X-Git-Url: http://git.hcoop.net/jackhill/guix/guix.git/blobdiff_plain/3a665637afc32a142dc24a77ce7ce9235eb6a3af..24f2d488f23c9c0205b485b943d6ebbd276d62b0:/doc/guix.texi?ds=sidebyside diff --git a/doc/guix.texi b/doc/guix.texi index 1c82579afc..8f43ade09f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -13,8 +13,12 @@ @set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 @set KEY-SERVER pool.sks-keyservers.net +@c Base URL for downloads. +@set BASE-URL https://ftp.gnu.org/gnu/guix + @c The official substitute server used by default. -@set SUBSTITUTE-SERVER ci.guix.info +@set SUBSTITUTE-SERVER ci.guix.gnu.org +@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER} @copying Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@* @@ -108,10 +112,11 @@ package management tool written for the GNU system. @c TRANSLATORS: You can replace the following paragraph with information on @c how to join your own translation team and how to report issues with the @c translation. -This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de -référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch -zu GNU Guix}). If you would like to translate it in your native language, -consider joining the +This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN, +GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU +Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), and +Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}). If you +would like to translate it in your native language, consider joining the @uref{https://translationproject.org/domain/guix-manual.html, Translation Project}. @@ -393,7 +398,7 @@ garbage collection of packages (@pxref{Features}). @cindex Guix System Guix comes with a distribution of the GNU system consisting entirely of free software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to +@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to users of that software}.}. The distribution can be installed on its own (@pxref{System Installation}), but it is also possible to install Guix as a package manager on top of @@ -404,7 +409,7 @@ Guix@tie{}System. The distribution provides core GNU packages such as GNU libc, GCC, and Binutils, as well as many GNU and non-GNU applications. The complete list of available packages can be browsed -@url{http://www.gnu.org/software/guix/packages,on-line} or by +@url{https://www.gnu.org/software/guix/packages,on-line} or by running @command{guix package} (@pxref{Invoking guix package}): @example @@ -514,13 +519,22 @@ dependencies. This is often quicker than installing from source, which is described in the next sections. The only requirement is to have GNU@tie{}tar and Xz. +@c Note duplicated from the ``Installation'' node. +@quotation Note +We recommend the use of this +@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, +shell installer script}. The script automates the download, installation, and +initial configuration steps described below. It should be run as the root +user. +@end quotation + Installing goes along these lines: @enumerate @item @cindex downloading Guix binary Download the binary tarball from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}, +@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz}, where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine already running the kernel Linux, and so on. @@ -529,7 +543,7 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the tarball against it, along these lines: @example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig +$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig @end example @@ -606,7 +620,7 @@ with these commands: @c files into place. @c @c See this thread for more information: -@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html +@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html @example # cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ @@ -676,15 +690,9 @@ You can confirm that Guix is working by installing a sample package into the root profile: @example -# guix package -i hello +# guix install hello @end example -The @code{guix} package must remain available in @code{root}'s profile, -or it would become subject to garbage collection---in which case you -would find yourself badly handicapped by the lack of the @command{guix} -command. In other words, do not remove @code{guix} by running -@code{guix package -r guix}. - The binary installation tarball can be (re)produced and verified simply by running the following command in the Guix source tree: @@ -717,11 +725,11 @@ GNU Guix is available for download from its website at GNU Guix depends on the following packages: @itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; +@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x; @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version 0.1.0 or later; @item -@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings +@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings (@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}); @item @@ -732,8 +740,8 @@ or later; @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 or later; @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; -@item @url{http://zlib.net, zlib}; -@item @url{http://www.gnu.org/software/make/, GNU Make}. +@item @url{https://zlib.net, zlib}; +@item @url{https://www.gnu.org/software/make/, GNU Make}. @end itemize The following dependencies are optional: @@ -755,9 +763,9 @@ Unless @code{--disable-daemon} was passed to @command{configure}, the following packages are also needed: @itemize -@item @url{http://gnupg.org/, GNU libgcrypt}; -@item @url{http://sqlite.org, SQLite 3}; -@item @url{http://gcc.gnu.org, GCC's g++}, with support for the +@item @url{https://gnupg.org/, GNU libgcrypt}; +@item @url{https://sqlite.org, SQLite 3}; +@item @url{https://gcc.gnu.org, GCC's g++}, with support for the C++11 standard. @end itemize @@ -771,7 +779,7 @@ unintended misconfiguration of @var{localstatedir} so you do not inadvertently corrupt your store (@pxref{The Store}). @cindex Nix, compatibility -When a working installation of @url{http://nixos.org/nix/, the Nix package +When a working installation of @url{https://nixos.org/nix/, the Nix package manager} is available, you can instead configure Guix with @code{--disable-daemon}. In that case, Nix replaces the three dependencies above. @@ -900,7 +908,7 @@ regarded as pure functions (@pxref{Introduction}). On a GNU/Linux system, a build user pool may be created like this (using Bash syntax and the @code{shadow} commands): -@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html +@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html @c for why `-G' is needed. @example # groupadd --system guixbuild @@ -1570,7 +1578,7 @@ available with Guix and then define the @code{GUIX_LOCPATH} environment variable: @example -$ guix package -i glibc-locales +$ guix install glibc-locales $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale @end example @@ -1670,7 +1678,7 @@ Multiple Outputs}). For instance, the following command installs fonts for Chinese languages: @example -guix package -i font-adobe-source-han-sans:cn +guix install font-adobe-source-han-sans:cn @end example @cindex @code{xterm} @@ -1795,25 +1803,14 @@ available. @node Limitations @section Limitations -As of version @value{VERSION}, Guix System is -not production-ready. It may contain bugs and lack important -features. Thus, if you are looking for a stable production system that -respects your freedom as a computer user, a good solution at this point -is to consider @url{http://www.gnu.org/distros/free-distros.html, one of -the more established GNU/Linux distributions}. We hope you can soon switch -to the Guix System without fear, of course. In the meantime, you can -also keep using your distribution and try out the package manager on top -of it (@pxref{Installation}). +We consider Guix System to be ready for a wide range of ``desktop'' and server +use cases. The reliability guarantees it provides---transactional upgrades +and rollbacks, reproducibility---make it a solid foundation. -Before you proceed with the installation, be aware of the following -noteworthy limitations applicable to version @value{VERSION}: +Nevertheless, before you proceed with the installation, be aware of the +following noteworthy limitations applicable to version @value{VERSION}: @itemize -@item -The installation process does not include a graphical user interface and -requires familiarity with GNU/Linux (see the following subsections to -get a feel of what that means.) - @item Support for the Logical Volume Manager (LVM) is missing. @@ -1821,19 +1818,15 @@ Support for the Logical Volume Manager (LVM) is missing. More and more system services are provided (@pxref{Services}), but some may be missing. -@item -More than 8,500 packages are available, but you might -occasionally find that a useful package is missing. - @item GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, some graphical -applications may be missing, as well as KDE. +as well as a number of X11 window managers. However, KDE is currently +missing. @end itemize -You have been warned! But more than a disclaimer, this is an invitation -to report issues (and success stories!), and to join us in improving it. -@xref{Contributing}, for more info. +More than a disclaimer, this is an invitation to report issues (and success +stories!), and to join us in improving it. @xref{Contributing}, for more +info. @node Hardware Considerations @@ -1856,7 +1849,7 @@ devices. WiFi devices known to work include those using Atheros chips driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. Free firmware exists for both and is available -out-of-the-box on Guix System, as part of @var{%base-firmware} +out-of-the-box on Guix System, as part of @code{%base-firmware} (@pxref{operating-system Reference, @code{firmware}}). @cindex RYF, Respects Your Freedom @@ -1876,7 +1869,7 @@ about their support in GNU/Linux. An ISO-9660 installation image that can be written to a USB stick or burnt to a DVD can be downloaded from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, +@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, where @var{system} is one of: @table @code @@ -1892,7 +1885,7 @@ Make sure to download the associated @file{.sig} file and to verify the authenticity of the image against it, along these lines: @example -$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig +$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig $ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig @end example @@ -2081,7 +2074,7 @@ ifconfig -a ip a @end example -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 +@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 Wired interfaces have a name starting with @samp{e}; for example, the interface corresponding to the first on-board Ethernet controller is called @samp{eno1}. Wireless interfaces have a name starting with @@ -2405,7 +2398,7 @@ If you'd like to install Guix System in a virtual machine (VM) or on a virtual private server (VPS) rather than on your beloved machine, this section is for you. -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a +To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a disk image, follow these steps: @enumerate @@ -2468,7 +2461,7 @@ about the installation image. @section Building the Installation Image for ARM Boards Many ARM boards require a specific variant of the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. +@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. If you build a disk image and the bootloader is not available otherwise (on another boot drive etc), it's advisable to build an image that @@ -2500,7 +2493,7 @@ emacs-guix, The Emacs-Guix Reference Manual}), after installing with it): @example -guix package -i emacs-guix +guix install emacs-guix @end example @menu @@ -2618,6 +2611,7 @@ is: @example guix package @var{options} @end example + @cindex transactions Primarily, @var{options} specifies the operations to be performed during the transaction. Upon completion, a new profile is created, but @@ -2631,6 +2625,24 @@ For example, to remove @code{lua} and install @code{guile} and guix package -r lua -i guile guile-cairo @end example +@cindex aliases, for @command{guix package} +For your convenience, we also provide the following aliases: + +@itemize +@item +@command{guix search} is an alias for @command{guix package -s}, +@item +@command{guix install} is an alias for @command{guix package -i}, +@item +@command{guix remove} is an alias for @command{guix package -r}, +@item +and @command{guix upgrade} is an alias for @command{guix package -u}. +@end itemize + +These aliases are less expressive than @command{guix package} and provide +fewer options, so in some cases you'll probably want to use @command{guix +package} directly. + @command{guix package} also supports a @dfn{declarative approach} whereby the user specifies the exact set of packages to be available and passes it @i{via} the @option{--manifest} option @@ -2643,7 +2655,7 @@ current generation of the user's default profile. Thus, users can add @file{$HOME/.guix-profile/bin} to their @code{PATH} environment variable, and so on. @cindex search paths -If you are not using the Guix System Distribution, consider adding the +If you are not using Guix System, consider adding the following lines to your @file{~/.bash_profile} (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned shells get all the right environment variable definitions: @@ -2943,12 +2955,13 @@ name: gmp @dots{} @end example -It is also possible to refine search results using several @code{-s} -flags. For example, the following command returns a list of board -games: +It is also possible to refine search results using several @code{-s} flags to +@command{guix package}, or several arguments to @command{guix search}. For +example, the following command returns a list of board games (this time using +the @command{guix search} alias): @example -$ guix package -s '\' -s game | recsel -p name +$ guix search '\' game | recsel -p name name: gnubg @dots{} @end example @@ -2963,7 +2976,7 @@ for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby libraries, and prints the name and synopsis of the matching packages: @example -$ guix package -s crypto -s library | \ +$ guix search crypto library | \ recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis @end example @@ -3130,7 +3143,7 @@ could use the information gathered to determine, for instance, whether your system has unpatched security vulnerabilities. Substitutes from the official build farm are enabled by default when -using the Guix System Distribution (@pxref{GNU Distribution}). However, +using Guix System (@pxref{GNU Distribution}). However, they are disabled by default when using Guix on a foreign distribution, unless you have explicitly enabled them via one of the recommended installation steps (@pxref{Installation}). The following paragraphs @@ -3320,7 +3333,7 @@ like to discuss this project, join us on @email{guix-devel@@gnu.org}. Often, packages defined in Guix have a single @dfn{output}---i.e., the source package leads to exactly one directory in the store. When running -@command{guix package -i glibc}, one installs the default output of the +@command{guix install glibc}, one installs the default output of the GNU libc package; the default output is called @code{out}, but its name can be omitted as shown in this command. In this particular case, the default output of @code{glibc} contains all the C header files, shared @@ -3336,14 +3349,14 @@ separate output, called @code{doc}. To install the main GLib output, which contains everything but the documentation, one would run: @example -guix package -i glib +guix install glib @end example @cindex documentation The command to install its documentation is: @example -guix package -i glib:doc +guix install glib:doc @end example Some packages install programs with different ``dependency footprints''. @@ -3385,7 +3398,7 @@ deleted. The set of garbage collector roots (``GC roots'' for short) includes default user profiles; by default, the symlinks under @file{/var/guix/gcroots} represent these GC roots. New GC roots can be added with @command{guix build --root}, for example (@pxref{Invoking -guix build}). +guix build}). The @command{guix gc --list-roots} command lists them. Prior to running @code{guix gc --collect-garbage} to make space, it is often useful to remove old generations from user profiles; that way, old @@ -3438,8 +3451,22 @@ as @code{500MiB}, as described above. When @var{free} or more is already available in @file{/gnu/store}, do nothing and exit immediately. +@item --delete-generations[=@var{duration}] +@itemx -d [@var{duration}] +Before starting the garbage collection process, delete all the generations +older than @var{duration}, for all the user profiles; when run as root, this +applies to all the profiles @emph{of all the users}. + +For example, this command deletes all the generations of all your profiles +that are older than 2 months (except generations that are current), and then +proceeds to free space until at least 10 GiB are available: + +@example +guix gc -d 2m -F 10G +@end example + @item --delete -@itemx -d +@itemx -D Attempt to delete all the store files and directories specified as arguments. This fails if some of the files are not in the store, or if they are still live. @@ -3451,6 +3478,10 @@ This prints nothing unless the daemon was started with @option{--cache-failures} (@pxref{Invoking guix-daemon, @option{--cache-failures}}). +@item --list-roots +List the GC roots owned by the user; when run as root, list @emph{all} the GC +roots. + @item --clear-failures Remove the specified store items from the failed-build cache. @@ -3643,8 +3674,9 @@ but it supports the following options: @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} -Download code from the specified @var{url}, at the given @var{commit} (a valid -Git commit ID represented as a hexadecimal string), or @var{branch}. +Download code for the @code{guix} channel from the specified @var{url}, at the +given @var{commit} (a valid Git commit ID represented as a hexadecimal +string), or @var{branch}. @cindex @file{channels.scm}, configuration file @cindex configuration file for channels @@ -3659,6 +3691,14 @@ Read the list of channels from @var{file} instead of evaluates to a list of channel objects. @xref{Channels}, for more information. +@item --news +@itemx -N +Display the list of packages added or upgraded since the previous generation. + +This is the same information as displayed upon @command{guix pull} completion, +but without ellipses; it is also similar to the output of @command{guix pull +-l} for the last generation (see below). + @item --list-generations[=@var{pattern}] @itemx -l [@var{pattern}] List all the generations of @file{~/.config/guix/current} or, if @var{pattern} @@ -4254,9 +4294,9 @@ same format as the @file{signing-key.pub} file. The list of authorized keys is kept in the human-editable file @file{/etc/guix/acl}. The file contains -@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format +@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format s-expressions''} and is structured as an access-control list in the -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure +@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure (SPKI)}. @item --extract=@var{directory} @@ -4735,7 +4775,7 @@ guix pack -f squashfs guile emacs geiser @noindent The result is a SquashFS file system image that can either be mounted or directly be used as a file system container image with the -@uref{http://singularity.lbl.gov, Singularity container execution +@uref{https://singularity.lbl.gov, Singularity container execution environment}, using commands like @command{singularity shell} or @command{singularity exec}. @@ -4967,7 +5007,7 @@ module exports a variable named @code{emacs}, which is bound to a The @code{(gnu packages @dots{})} module name space is automatically scanned for packages by the command-line tools. For -instance, when running @code{guix package -i emacs}, all the @code{(gnu +instance, when running @code{guix install emacs}, all the @code{(gnu packages @dots{})} modules are scanned until one that exports a package object whose name is @code{emacs} is found. This package search facility is implemented in the @code{(gnu packages)} module. @@ -5044,7 +5084,7 @@ package looks like this: (inputs `(("gawk" ,gawk))) (synopsis "Hello, GNU world: An example GNU package") (description "Guess what GNU Hello prints!") - (home-page "http://www.gnu.org/software/hello/") + (home-page "https://www.gnu.org/software/hello/") (license gpl3+))) @end example @@ -5202,8 +5242,7 @@ Return the @code{} object of @var{package} cross-built from @var{target} must be a valid GNU triplet denoting the target hardware and operating system, such as @code{"mips64el-linux-gnu"} -(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU -Configure and Build System}). +(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}). @end deffn @cindex package transformations @@ -5406,6 +5445,27 @@ automatically corrected. @end table @end deftp +@deffn {Scheme Syntax} this-package +When used in the @emph{lexical scope} of a package field definition, this +identifier resolves to the package being defined. + +The example below shows how to add a package as a native input of itself when +cross-compiling: + +@example +(package + (name "guile") + ;; ... + + ;; When cross-compiled, Guile, for example, depends on + ;; a native version of itself. Add it here. + (native-inputs (if (%current-target-system) + `(("self" ,this-package)) + '()))) +@end example + +It is an error to refer to @code{this-package} outside a package definition. +@end deffn @node origin Reference @subsection @code{origin} Reference @@ -5613,7 +5673,7 @@ executed. Some of these build systems are listed below. @defvr {Scheme Variable} ant-build-system This variable is exported by @code{(guix build-system ant)}. It implements the build procedure for Java packages that can be built with -@url{http://ant.apache.org/, Ant build tool}. +@url{https://ant.apache.org/, Ant build tool}. It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided by the @code{icedtea} package to the set of inputs. Different @@ -5783,7 +5843,7 @@ directories specified in @code{#:doc-dirs} are installed as well. @defvr {Scheme Variable} cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the -@url{http://www.cmake.org, CMake build tool}. +@url{https://www.cmake.org, CMake build tool}. It automatically adds the @code{cmake} package to the set of inputs. Which package is used can be specified with the @code{#:cmake} @@ -5999,7 +6059,7 @@ Which Perl package is used can be specified with @code{#:perl}. @defvr {Scheme Variable} r-build-system This variable is exported by @code{(guix build-system r)}. It -implements the build procedure used by @uref{http://r-project.org, R} +implements the build procedure used by @uref{https://r-project.org, R} packages, which essentially is little more than running @code{R CMD INSTALL --library=/gnu/store/@dots{}} in an environment where @code{R_LIBS_SITE} contains the paths to all R package inputs. Tests @@ -6008,7 +6068,7 @@ are run after installation using the R function @end defvr @defvr {Scheme Variable} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It +This variable is exported by @code{(guix build-system rakudo)}. It implements the build procedure used by @uref{https://rakudo.org/, Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and @@ -6140,7 +6200,7 @@ locations in the output directory. @defvr {Scheme Variable} meson-build-system This variable is exported by @code{(guix build-system meson)}. It implements the build procedure for packages that use -@url{http://mesonbuild.com, Meson} as their build system. +@url{https://mesonbuild.com, Meson} as their build system. It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of inputs, and they can be changed with the parameters @code{#:meson} @@ -6192,6 +6252,33 @@ is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. @end table @end defvr +@defvr {Scheme Variable} linux-module-build-system +@var{linux-module-build-system} allows building Linux kernel modules. + +@cindex build phases +This build system is an extension of @var{gnu-build-system}, but with the +following phases changed: + +@table @code + +@item configure +This phase configures the environment so that the Linux kernel's Makefile +can be used to build the external kernel module. + +@item build +This phase uses the Linux kernel's Makefile in order to build the external +kernel module. + +@item install +This phase uses the Linux kernel's Makefile in order to install the external +kernel module. +@end table + +It is possible and useful to specify the Linux kernel to use for building +the module (in the "arguments" form of a package using the +linux-module-build-system, use the key #:linux to specify it). +@end defvr + Lastly, for packages that do not need anything as sophisticated, a ``trivial'' build system is provided. It is trivial in the sense that it provides basically no support: it does not pull any implicit inputs, @@ -7978,7 +8065,9 @@ The following derivations will be built: @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of -the system type of the build host. +the system type of the build host. The @command{guix build} command allows +you to repeat this option several times, in which case it builds for all the +specified systems; other commands ignore extraneous @option{-s} options. @quotation Note The @code{--system} flag is for @emph{native} compilation and must not @@ -8010,7 +8099,7 @@ also be offloaded to a remote machine of the right architecture. @item --target=@var{triplet} @cindex cross-compilation Cross-build for @var{triplet}, which must be a valid GNU triplet, such -as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU +as @code{"mips64el-linux-gnu"} (@pxref{Specifying Target Triplets, GNU configuration triplets,, autoconf, Autoconf}). @anchor{build-check} @@ -8428,7 +8517,7 @@ guix import cpan Acme::Boolean @cindex CRAN @cindex Bioconductor Import metadata from @uref{https://cran.r-project.org/, CRAN}, the -central repository for the @uref{http://r-project.org, GNU@tie{}R +central repository for the @uref{https://r-project.org, GNU@tie{}R statistical and graphical environment}. Information is extracted from the @code{DESCRIPTION} file of the package. @@ -8462,7 +8551,7 @@ guix import cran --archive=bioconductor GenomicRanges @item texlive @cindex TeX Live @cindex CTAN -Import metadata from @uref{http://www.ctan.org/, CTAN}, the +Import metadata from @uref{https://www.ctan.org/, CTAN}, the comprehensive TeX archive network for TeX packages that are part of the @uref{https://www.tug.org/texlive/, TeX Live distribution}. @@ -8541,9 +8630,9 @@ guix import json hello.json @item nix Import metadata from a local copy of the source of the -@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This +@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies on the @command{nix-instantiate} command of -@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are +@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are typically written in a mixture of Nix-language and Bash code. This command only imports the high-level package structure that is written in the Nix language. It normally includes all the basic fields of a @@ -8665,7 +8754,7 @@ information. Currently the supported repositories and their identifiers are: @itemize - @item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} +@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} identifier. This is the default. Packages from @code{elpa.gnu.org} are signed with one of the keys @@ -8675,11 +8764,11 @@ contained in the GnuPG keyring at signatures,, emacs, The GNU Emacs Manual}). @item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the +@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the @code{melpa-stable} identifier. @item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} +@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa} identifier. @end itemize @@ -8845,13 +8934,13 @@ the updater for X.org packages; @item kernel.org the updater for packages hosted on kernel.org; @item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; +the updater for @uref{https://elpa.gnu.org/, ELPA} packages; @item cran the updater for @uref{https://cran.r-project.org/, CRAN} packages; @item bioconductor the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages; @item cpan -the updater for @uref{http://www.cpan.org/, CPAN} packages; +the updater for @uref{https://www.cpan.org/, CPAN} packages; @item pypi the updater for @uref{https://pypi.python.org, PyPI} packages. @item gem @@ -9089,7 +9178,7 @@ that Guix uses, as in this example: (cpe-version . "2.3"))) @end example -@c See . +@c See . Some entries in the CVE database do not specify which version of a package they apply to, and would thus ``stick around'' forever. Package developers who found CVE alerts and verified they can be ignored can @@ -9247,7 +9336,7 @@ For the example above, the map looks like this: produced by @command{guix size}} This option requires that -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be +@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be installed and visible in Guile's module search path. When that is not the case, @command{guix size} fails as it tries to load it. @@ -9268,12 +9357,12 @@ directed acyclic graph (DAG). It can quickly become difficult to have a mental model of the package DAG, so the @command{guix graph} command provides a visual representation of the DAG. By default, @command{guix graph} emits a DAG representation in the input format of -@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed +@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed directly to the @command{dot} command of Graphviz. It can also emit an HTML page with embedded JavaScript code to display a ``chord diagram'' in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct a graph in a graph database supporting -the @uref{http://www.opencypher.org/, openCypher} query language. +the @uref{https://www.opencypher.org/, openCypher} query language. The general syntax is: @example @@ -10021,14 +10110,14 @@ on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though @var{b} usually lacks substitutes as well. The result looks like this: @example -$ guix weather --substitute-urls=https://ci.guix.info -c 10 +$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10 computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.info... -updating substitutes from 'https://ci.guix.info'... 100.0% -https://ci.guix.info +looking for 9,343 store items on @value{SUBSTITUTE-URL}... +updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0% +@value{SUBSTITUTE-URL} 64.7% substitutes available (6,047 out of 9,343) @dots{} -2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which: +2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which: 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 @@ -10105,7 +10194,7 @@ ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} @chapter System Configuration @cindex system configuration -The Guix System Distribution supports a consistent whole-system configuration +Guix System supports a consistent whole-system configuration mechanism. By that we mean that all aspects of the global system configuration---such as the available system services, timezone and locale settings, user accounts---are declared in a single place. Such @@ -10399,13 +10488,17 @@ The package object of the operating system kernel to use@footnote{Currently only the Linux-libre kernel is supported. In the future, it will be possible to use the GNU@tie{}Hurd.}. -@item @code{kernel-arguments} (default: @code{'()}) +@item @code{kernel-arguments} (default: @code{'("quiet")}) List of strings or gexps representing additional arguments to pass on the command-line of the kernel---e.g., @code{("console=ttyS0")}. @item @code{bootloader} The system bootloader configuration object. @xref{Bootloader Configuration}. +@item @code{label} +This is the label (a string) as it appears in the bootloader's menu entry. +The default label includes the kernel name and version. + @item @code{keyboard-layout} (default: @code{#f}) This field specifies the keyboard layout to use in the console. It can be either @code{#f}, in which case the default keyboard layout is used (usually @@ -10558,6 +10651,27 @@ is that only @code{root} and members of the @code{wheel} group may use @code{sudo}. @end table + +@deffn {Scheme Syntax} this-operating-system +When used in the @emph{lexical scope} of an operating system field definition, +this identifier resolves to the operating system being defined. + +The example below shows how to refer to the operating system being defined in +the definition of the @code{label} field: + +@example +(use-modules (gnu) (guix)) + +(operating-system + ;; ... + (label (package-full-name + (operating-system-kernel this-operating-system)))) +@end example + +It is an error to refer to @code{this-operating-system} outside an operating +system definition. +@end deffn + @end deftp @node File Systems @@ -10641,10 +10755,15 @@ corresponding device mapping established. This is a list of symbols denoting mount flags. Recognized flags include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to special files), @code{no-suid} (ignore setuid and setgid -bits), and @code{no-exec} (disallow program execution.) +bits), @code{no-atime} (do not update file access times), and @code{no-exec} +(disallow program execution). @xref{Mount-Unmount-Remount,,, libc, The GNU C +Library Reference Manual}, for more information on these flags. @item @code{options} (default: @code{#f}) -This is either @code{#f}, or a string denoting mount options. +This is either @code{#f}, or a string denoting mount options passed to the +file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C Library +Reference Manual}, for details and run @command{man 8 mount} for options for +various file systems. @item @code{mount?} (default: @code{#t}) This value indicates whether to automatically mount the file system when @@ -11200,7 +11319,7 @@ The name of the source for that locale. This is typically the @item @code{charset} (default: @code{"UTF-8"}) The ``character set'' or ``code set'' for that locale, -@uref{http://www.iana.org/assignments/character-sets, as defined by +@uref{https://www.iana.org/assignments/character-sets, as defined by IANA}. @end table @@ -11638,8 +11757,8 @@ interpreted as backspace when the user types their login name. @item @code{kill-characters} (default: @code{#f}) This option accepts a string that should be interpreted to mean "ignore -all previous characters" (also called a "kill" character) when the types -their login name. +all previous characters" (also called a "kill" character) when the user +types their login name. @item @code{chdir} (default: @code{#f}) This option accepts, as a string, a directory path that will be changed @@ -11904,7 +12023,7 @@ A directory path where the @command{guix-daemon} will perform builds. @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}] Run @var{udev}, which populates the @file{/dev} directory dynamically. udev rules can be provided as a list of files through the @var{rules} -variable. The procedures @var{udev-rule} and @var{file->udev-rule} from +variable. The procedures @code{udev-rule} and @code{file->udev-rule} from @code{(gnu services base)} simplify the creation of such rule files. @end deffn @@ -12378,7 +12497,7 @@ For example: The package that provides the DHCP daemon. This package is expected to provide the daemon at @file{sbin/dhcpd} relative to its output directory. The default package is the -@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}. +@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}. @item @code{config-file} (default: @code{#f}) The configuration file to use. This is required. It will be passed to @code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' @@ -12686,7 +12805,7 @@ A list of local IP addresses or hostnames the ntpd daemon should listen on. A list of local IP address the ntpd daemon should use for outgoing queries. @item @code{sensor} (default: @code{'()}) Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} -will listen to each sensor that acutally exists and ignore non-existant ones. +will listen to each sensor that actually exists and ignore non-existent ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more information. @item @code{server} (default: @var{%ntp-servers}) @@ -13227,7 +13346,7 @@ The @code{(gnu services avahi)} provides the following definition. @defvr {Scheme Variable} avahi-service-type This is the service that runs @command{avahi-daemon}, a system-wide mDNS/DNS-SD responder that allows for service discovery and -``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). +``zero-configuration'' host name lookups (see @uref{https://avahi.org/}). Its value must be a @code{zero-configuration} record---see below. This service extends the name service cache daemon (nscd) so that it can @@ -13274,7 +13393,7 @@ This is a list of domains to browse. @end deftp @deffn {Scheme Variable} openvswitch-service-type -This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} +This is the type of the @uref{https://www.openvswitch.org, Open vSwitch} service, whose value should be an @code{openvswitch-configuration} object. @end deffn @@ -14523,7 +14642,7 @@ polkit with the actions from @code{gnome-settings-daemon}. Configuration record for the GNOME desktop environment. @table @asis -@item @code{gnome} (default @code{gnome}) +@item @code{gnome} (default: @code{gnome}) The GNOME package to use. @end table @end deftp @@ -14543,7 +14662,7 @@ with the administrator's password. Configuration record for the Xfce desktop environment. @table @asis -@item @code{xfce} (default @code{xfce}) +@item @code{xfce} (default: @code{xfce}) The Xfce package to use. @end table @end deftp @@ -14562,7 +14681,7 @@ profile, and extends polkit with the actions from Configuration record for the MATE desktop environment. @table @asis -@item @code{mate} (default @code{mate}) +@item @code{mate} (default: @code{mate}) The MATE package to use. @end table @end deftp @@ -14574,7 +14693,7 @@ profile, and extends dbus with actions from @code{efl}. @deftp {Data Type} enlightenment-desktop-service-configuration @table @asis -@item @code{enlightenment} (default @code{enlightenment}) +@item @code{enlightenment} (default: @code{enlightenment}) The enlightenment package to use. @end table @end deftp @@ -14608,7 +14727,7 @@ are described below. Return a service that runs the ``system bus'', using @var{dbus}, with support for @var{services}. -@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication +@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication facility. Its system bus is used to allow system services to communicate and to be notified of system-wide events. @@ -14704,7 +14823,7 @@ package to expose as a service. @deffn {Scheme Procedure} polkit-service @ [#:polkit @var{polkit}] Return a service that runs the -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege +@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege management service}, which allows system administrators to grant access to privileged operations in a structured way. By querying the Polkit service, a privileged system component can know when it should grant additional @@ -14713,7 +14832,7 @@ the capability to suspend the system if the user is logged in locally. @end deffn @defvr {Scheme Variable} upower-service-type -Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a +Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a system-wide monitor for power consumption and battery levels, with the given configuration settings. @@ -14787,7 +14906,7 @@ Possible values are: @end deftp @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, +Return a service for @uref{https://udisks.freedesktop.org/docs/latest/, UDisks}, a @dfn{disk management} daemon that provides user interfaces with notifications and ways to mount/unmount disks. Programs that talk to UDisks include the @command{udisksctl} command, part of UDisks, and GNOME Disks. @@ -14797,7 +14916,7 @@ include the @command{udisksctl} command, part of UDisks, and GNOME Disks. Return a service that runs @command{colord}, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners. It is notably used by the GNOME Color Manager graphical -tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web +tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web site} for more information. @end deffn @@ -16559,6 +16678,36 @@ the @code{operating-system}'s @code{user-accounts} in order to deliver the @code{postmaster} mail to @code{bob} (which subsequently would deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). +@subsubheading GNU Mailutils IMAP4 Daemon +@cindex GNU Mailutils IMAP4 Daemon + +@deffn {Scheme Variable} imap4d-service-type +This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, +mailutils, GNU Mailutils Manual}), whose value should be an +@code{imap4d-configuration} object as in this example: + +@example +(service imap4d-service-type + (imap4d-configuration + (config-file (local-file "imap4d.conf")))) +@end example +@end deffn + +@deftp {Data Type} imap4d-configuration +Data type representing the configuration of @command{imap4d}. + +@table @asis +@item @code{package} (default: @code{mailutils}) +The package that provides @command{imap4d}. + +@item @code{config-file} (default: @code{%default-imap4d-config-file}) +File-like object of the configuration file to use, by default it will listen +on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU +Mailutils Manual}, for details. + +@end table +@end deftp + @node Messaging Services @subsection Messaging Services @@ -16989,11 +17138,11 @@ string, you could instantiate a prosody service like this: @cindex IRC (Internet Relay Chat) @cindex IRC gateway -@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC +@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC interface to a variety of messaging protocols such as XMPP. @defvr {Scheme Variable} bitlbee-service-type -This is the service type for the @url{http://bitlbee.org,BitlBee} IRC +This is the service type for the @url{https://bitlbee.org,BitlBee} IRC gateway daemon. Its value is a @code{bitlbee-configuration} (see below). @@ -17825,7 +17974,7 @@ specified by clients; The @code{krb5-realm} and @code{krb5-configuration} types have many fields. Only the most commonly used ones are described here. For a full list, and more detailed explanation of each, see the MIT -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} +@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} documentation. @@ -17884,7 +18033,7 @@ A service type for the Kerberos 5 PAM module. @end defvr @deftp {Data Type} pam-krb5-configuration -Data type representing the configuration of the Kerberos 5 PAM module +Data type representing the configuration of the Kerberos 5 PAM module. This type has the following parameters: @table @asis @item @code{pam-krb5} (default: @code{pam-krb5}) @@ -19307,6 +19456,26 @@ Its default is the first provided domain. The first domain provided will be the subject CN of the certificate, and all domains will be Subject Alternative Names on the certificate. +@item @code{challenge} (default: @code{#f}) +The challenge type that has to be run by certbot. If @code{#f} is specified, +default to the HTTP challenge. If a value is specified, defaults to the +manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and +the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}). + +@item @code{authentication-hook} (default: @code{#f}) +Command to be run in a shell once for each certificate challenge to be +answered. For this command, the shell variable @code{$CERTBOT_DOMAIN} +will contain the domain being authenticated, @code{$CERTBOT_VALIDATION} +contains the validation string and @code{$CERTBOT_TOKEN} contains the +file name of the resource requested when performing an HTTP-01 challenge. + +@item @code{cleanup-hook} (default: @code{#f}) +Command to be run in a shell once for each certificate challenge that +have been answered by the @code{auth-hook}. For this command, the shell +variables available in the @code{auth-hook} script are still available, and +additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output +of the @code{auth-hook} script. + @item @code{deploy-hook} (default: @code{#f}) Command to be run in a shell once for each successfully issued certificate. For this command, the shell variable @@ -19688,6 +19857,45 @@ When set, this forbids queries of the ANY type. The delay between a modification in memory and on disk. 0 means immediate synchronization. +@item @code{zonefile-load} (default: @code{#f}) +The way the zone file contents are applied during zone load. Possible values +are: + +@itemize +@item @code{#f} for using the default value from Knot, +@item @code{'none} for not using the zone file at all, +@item @code{'difference} for computing the difference between already available +contents and zone contents and applying it to the current zone contents, +@item @code{'difference-no-serial} for the same as @code{'difference}, but +ignoring the SOA serial in the zone file, while the server takes care of it +automatically. +@item @code{'whole} for loading zone contents from the zone file. +@end itemize + +@item @code{journal-content} (default: @code{#f}) +The way the journal is used to store zone and its changes. Possible values +are @code{'none} to not use it at all, @code{'changes} to store changes and +@code{'all} to store contents. @code{#f} does not set this option, so the +default value from Knot is used. + +@item @code{max-journal-usage} (default: @code{#f}) +The maximum size for the journal on disk. @code{#f} does not set this option, +so the default value from Knot is used. + +@item @code{max-journal-depth} (default: @code{#f}) +The maximum size of the history. @code{#f} does not set this option, so the +default value from Knot is used. + +@item @code{max-zone-size} (default: @code{#f}) +The maximum size of the zone file. This limit is enforced for incoming +transfer and updates. @code{#f} does not set this option, so the default +value from Knot is used. + +@item @code{dnssec-policy} (default: @code{#f}) +A reference to a @code{knot-policy-configuration} record, or the special +name @code{"default"}. If the value is @code{#f}, there is no dnssec signing +on this zone. + @item @code{serial-policy} (default: @code{'increment}) A policy between @code{'increment} and @code{'unixtime}. @@ -19705,6 +19913,19 @@ The Knot package. @item @code{run-directory} (default: @code{"/var/run/knot"}) The run directory. This directory will be used for pid file and sockets. +@item @code{includes} (default: @code{'()}) +A list of strings or file-like objects denoting other files that must be +included at the top of the configuration file. + +@cindex secrets, Knot service +This can be used to manage secrets out-of-band. For example, secret +keys may be stored in an out-of-band file not managed by Guix, and +thus not visible in @file{/gnu/store}---e.g., you could store secret +key configuration in @file{/etc/knot/secrets.conf} and add this file +to the @code{includes} list. + +It can also be used to add configuration not supported by this interface. + @item @code{listen-v4} (default: @code{"0.0.0.0"}) An ip address on which to listen. @@ -19898,7 +20119,7 @@ Defaults to @samp{()}. The @code{(gnu services vpn)} module provides services related to @dfn{virtual private networks} (VPNs). It provides a @emph{client} service for -your machine to connect to a VPN, and a @emph{servire} service for your machine +your machine to connect to a VPN, and a @emph{server} service for your machine to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}. @deffn {Scheme Procedure} openvpn-client-service @ @@ -20495,7 +20716,7 @@ TLP enables various powersaving modes in userspace and kernel. Contrary to @code{upower-service}, it is not a passive, monitoring tool, as it will apply custom settings each time a new power source is detected. More information can be found at -@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}. +@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}. @deffn {Scheme Variable} tlp-service-type The service type for the TLP tool. Its value should be a valid @@ -21495,7 +21716,7 @@ Defaults to @samp{"3:remote 4:event"}. @deftypevr {@code{libvirt-configuration} parameter} string log-outputs Logging outputs. -An output is one of the places to save logging information The format +An output is one of the places to save logging information. The format for an output can be: @table @code @@ -22964,7 +23185,7 @@ could instantiate a cgit service like this: @cindex Gitolite service @cindex Git, hosting -@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git +@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git repositories on a central server. Gitolite can handle multiple repositories and users, and supports flexible @@ -23092,7 +23313,7 @@ The port to bind the server to. @cindex fingerprint @subsubheading Fingerprint Service -The @code{(gnu services fingerprint)} module provides a DBus service to +The @code{(gnu services authentication)} module provides a DBus service to read and identify fingerprints via a fingerprint sensor. @defvr {Scheme Variable} fprintd-service-type @@ -23190,7 +23411,7 @@ passed to @command{lircd}. The @code{(gnu services spice)} module provides the following service. @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon +Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon that enables sharing the clipboard with a vm and setting the guest display resolution when the graphical console window resizes. @end deffn @@ -23328,7 +23549,7 @@ The @code{(gnu services docker)} module provides the following service. @defvr {Scheme Variable} docker-service-type -This is the type of the service that runs @url{http://www.docker.com,Docker}, +This is the type of the service that runs @url{https://www.docker.com,Docker}, a daemon that can execute application bundles (sometimes referred to as ``containers'') in isolated environments. @@ -23438,7 +23659,7 @@ pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you would typically run something like: @example -$ guix package -i nss-certs +$ guix install nss-certs $ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" $ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" $ export GIT_SSL_CAINFO="$SSL_CERT_FILE" @@ -23449,7 +23670,7 @@ variable to point to a certificate bundle, so you would have to run something like this: @example -$ guix package -i nss-certs +$ guix install nss-certs $ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" @end example @@ -23814,7 +24035,7 @@ in ``legacy'' BIOS mode. Available bootloaders are described in @code{(gnu bootloader @dots{})} modules. In particular, @code{(gnu bootloader u-boot)} contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. +@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. @item @code{target} This is a string denoting the target onto which to install the @@ -23953,7 +24174,7 @@ must @emph{not} be an OS device name such as @file{/dev/sda1}. @end deftp @c FIXME: Write documentation once it's stable. -Fow now only GRUB has theme support. GRUB themes are created using +For now only GRUB has theme support. GRUB themes are created using the @code{grub-theme} form, which is not documented yet. @defvr {Scheme Variable} %default-theme @@ -24045,7 +24266,7 @@ an older system generation at boot time should you need it. @quotation Note @c The paragraph below refers to the problem discussed at -@c . +@c . It is highly recommended to run @command{guix pull} once before you run @command{guix system reconfigure} for the first time (@pxref{Invoking guix pull}). Failing to do that you would see an older version of Guix @@ -24425,13 +24646,23 @@ example graph. @section Running Guix in a Virtual Machine @cindex virtual machine -To run Guix in a virtual machine (VM), one can either use the -pre-built Guix VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Invoking guix system}). The returned image is in -qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can -efficiently use. +To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image +distributed at +@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz} +This image is a compressed image in QCOW format. You will first need to +decompress with @command{xz -d}, and then you can pass it to an emulator such +as QEMU (see below for details). + +This image boots the Xfce graphical environment and it contains some +commonly-used tools. You can install more software in the image by running +@command{guix package} in a terminal (@pxref{Invoking guix package}). You can +also reconfigure the system based on its initial configuration file available +as @file{/etc/config.scm} (@pxref{Using the Configuration System}). + +Instead of using this pre-built image, one can also build their own virtual +machine image using @command{guix system vm-image} (@pxref{Invoking guix +system}). The returned image is in qcow2 format, which the +@uref{https://qemu.org/, QEMU emulator} can efficiently use. @cindex QEMU If you built your own image, you must copy it out of the store @@ -24444,7 +24675,9 @@ vm-image} on x86_64 hardware: @example $ qemu-system-x86_64 \ -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image + -enable-kvm -m 512 \ + -device virtio-blk,drive=myhd \ + -drive if=none,file=/tmp/qemu-image,id=myhd @end example Here is what each of these options means: @@ -24470,12 +24703,20 @@ If your system has hardware virtualization extensions, enabling the virtual machine support (KVM) of the Linux kernel will make things run faster. -@item -m 256 +@c To run Xfce + 'guix pull', we need at least 1G of RAM. +@item -m 1024 RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB, which may be insufficient for some operations. -@item /tmp/qemu-image -The file name of the qcow2 image. +@item -device virtio-blk,drive=myhd +Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a +``paravirtualization'' mechanism for block devices that allows QEMU to achieve +better performance than if it were emulating a complete disk drive. See the +QEMU and KVM documentation for more info. + +@item -drive if=none,file=/tmp/qemu-image,id=myhd +Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the +the ``myhd'' drive. @end table The default @command{run-vm.sh} script that is returned by an invocation of @@ -24491,11 +24732,10 @@ network connectivity, for example @command{guix download}. @cindex SSH @cindex SSH server -To enable SSH inside a VM you need to add a SSH server like @code{(dropbear-service)} -or @code{(lsh-service)} to your VM. The @code{(lsh-service}) doesn't currently -boot unsupervised. It requires you to type some characters to initialize the -randomness generator. In addition you need to forward the SSH port, 22 by -default, to the host. You can do this with +To enable SSH inside a VM you need to add an SSH server like +@code{openssh-service-type} to your VM (@pxref{Networking Services, +@code{openssh-service-type}}). In addition you need to forward the SSH port, +22 by default, to the host. You can do this with @example `guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 @@ -24639,23 +24879,23 @@ exception is the @dfn{boot service type}, which is the ultimate service. Optionally, a default value for instances of this type. @end enumerate -In this example, @var{guix-service-type} extends three services: +In this example, @code{guix-service-type} extends three services: -@table @var +@table @code @item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd +The @code{guix-shepherd-service} procedure defines how the Shepherd service is extended. Namely, it returns a @code{} object that defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd Services}). @item account-service-type -This extension for this service is computed by @var{guix-accounts}, +This extension for this service is computed by @code{guix-accounts}, which returns a list of @code{user-group} and @code{user-account} objects representing the build user accounts (@pxref{Invoking guix-daemon}). @item activation-service-type -Here @var{guix-activation} is a procedure that returns a gexp, which is +Here @code{guix-activation} is a procedure that returns a gexp, which is a code snippet to run at ``activation time''---e.g., when the service is booted. @end table @@ -24680,7 +24920,7 @@ value is omitted, the default value specified by (service guix-service-type) @end example -@var{guix-service-type} is quite simple because it extends other +@code{guix-service-type} is quite simple because it extends other services but is not extensible itself. @c @subsubsubsection Extensible Service Types @@ -24706,7 +24946,7 @@ The service type for an @emph{extensible} service looks like this: This is the service type for the @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management daemon}. Compared to the previous example, in addition to an -extension of @var{shepherd-root-service-type}, we see two new fields: +extension of @code{shepherd-root-service-type}, we see two new fields: @table @code @item compose @@ -24733,7 +24973,7 @@ them (@pxref{Invoking guix system}). @end table There can be only one instance of an extensible service type such as -@var{udev-service-type}. If there were more, the +@code{udev-service-type}. If there were more, the @code{service-extension} specifications would be ambiguous. Still here? The next section provides a reference of the programming @@ -24807,7 +25047,7 @@ Here is an example of how a service is created and manipulated: The @code{modify-services} form provides a handy way to change the parameters of some of the services of a list such as -@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It +@code{%base-services} (@pxref{Base Services, @code{%base-services}}). It evaluates to a list of services. Of course, you could always use standard list combinators such as @code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual}); @@ -24988,8 +25228,8 @@ You can actually generate such a graph for any operating system definition using the @command{guix system shepherd-graph} command (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). -The @var{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended +The @code{%shepherd-root-service} is a service object representing +PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by passing it lists of @code{} objects. @deftp {Data Type} shepherd-service @@ -25007,6 +25247,12 @@ shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the @item @code{requirements} (default: @code{'()}) List of symbols denoting the Shepherd services this one depends on. +@cindex one-shot services, for the Shepherd +@item @code{one-shot?} (default: @code{#f}) +Whether this service is @dfn{one-shot}. One-shot services stop immediately +after their @code{start} action has completed. @xref{Slots of services,,, +shepherd, The GNU Shepherd Manual}, for more info. + @item @code{respawn?} (default: @code{#t}) Whether to restart the service when it stops, for instance when the underlying process dies. @@ -25037,10 +25283,10 @@ A documentation string, as shown when running: herd doc @var{service-name} @end example -where @var{service-name} is one of the symbols in @var{provision} +where @var{service-name} is one of the symbols in @code{provision} (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). -@item @code{modules} (default: @var{%default-modules}) +@item @code{modules} (default: @code{%default-modules}) This is the list of modules that must be in scope when @code{start} and @code{stop} are evaluated. @@ -25206,7 +25452,7 @@ installs the debugging information for the GNU C Library and for GNU Guile: @example -guix package -i glibc:debug guile:debug +guix install glibc:debug guile:debug @end example GDB must then be told to look for debug files in the user's profile, by @@ -25287,7 +25533,7 @@ order of magnitudes lower than a full rebuild of the dependency chain. @cindex replacements of packages, for grafts For instance, suppose a security update needs to be applied to Bash. Guix developers will provide a package definition for the ``fixed'' -Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining +Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining Packages}). Then, the original package definition is augmented with a @code{replacement} field pointing to the package containing the bug fix: @@ -25302,14 +25548,14 @@ Packages}). Then, the original package definition is augmented with a From there on, any package depending directly or indirectly on Bash---as reported by @command{guix gc --requisites} (@pxref{Invoking guix gc})---that is installed is automatically ``rewritten'' to refer to -@var{bash-fixed} instead of @var{bash}. This grafting process takes +@code{bash-fixed} instead of @code{bash}. This grafting process takes time proportional to the size of the package, usually less than a minute for an ``average'' package on a recent machine. Grafting is recursive: when an indirect dependency requires grafting, then grafting ``propagates'' up to the package that the user is installing. Currently, the length of the name and version of the graft and that of -the package it replaces (@var{bash-fixed} and @var{bash} in the example +the package it replaces (@code{bash-fixed} and @code{bash} in the example above) must be equal. This restriction mostly comes from the fact that grafting works by patching files, including binary files, directly. Other restrictions may apply: for instance, when adding a graft to a @@ -25470,7 +25716,7 @@ approximation, we will consider it final.}, depicted below. @image{images/bootstrap-packages,6in,,Dependency graph of the early packages} -@c See . +@c See . The first tool that gets built with the bootstrap binaries is GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite for all the following packages. From there Findutils and Diffutils get @@ -25593,7 +25839,7 @@ reason. @node Acknowledgments @chapter Acknowledgments -Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, +Guix is based on the @uref{https://nixos.org/nix/, Nix package manager}, which was designed and implemented by Eelco Dolstra, with contributions from other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package