@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
@copying
-Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
-Copyright @copyright{} 2015, 2016, 2017, 2019 Leo Famulari@*
-Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017, 2019, 2020 Leo Famulari@*
+Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
-Copyright @copyright{} 2016, 2017 ng0@*
-Copyright @copyright{} 2016, 2017, 2018, 2019 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
+Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2016, 2017, 2018, 2019 Christopher Baines@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017, 2018, 2019 Marius Bakke@*
-Copyright @copyright{} 2017, 2019 Hartmut Goebel@*
-Copyright @copyright{} 2017, 2019 Maxim Cournoyer@*
-Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@*
+Copyright @copyright{} 2017, 2018, 2019, 2020 Marius Bakke@*
+Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
+Copyright @copyright{} 2017, 2019, 2020 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2018, 2019, 2020 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
Copyright @copyright{} 2019 Josh Holland@*
-Copyright @copyright{} 2019 Diego Nicola Barbato@*
+Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
Copyright @copyright{} 2019 Jakob L. Kreuze@*
Copyright @copyright{} 2019 Kyle Andrews@*
Copyright @copyright{} 2019 Alex Griffin@*
Copyright @copyright{} 2019 Guillaume Le Vaillant@*
+Copyright @copyright{} 2020 Leo Prikler@*
+Copyright @copyright{} 2019, 2020 Simon Tournier@*
+Copyright @copyright{} 2020 Wiktor Żelazny@*
+Copyright @copyright{} 2020 Damien Cassou@*
+Copyright @copyright{} 2020 Jakub Kądziołka@*
+Copyright @copyright{} 2020 Jack Hill@*
+Copyright @copyright{} 2020 Naga Malleswari@*
+Copyright @copyright{} 2020 Brice Waegeneire@*
+Copyright @copyright{} 2020 R Veera Kumar@*
+Copyright @copyright{} 2020 Pierre Langlois@*
+Copyright @copyright{} 2020 pinoaffe@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Invoking guix environment:: Setting up development environments.
* Invoking guix pack:: Creating software bundles.
+* The GCC toolchain:: Working with languages supported by GCC.
Programming Interface
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
Defining Services
@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.
+user. As root, you can thus run this:
+
+@example
+cd /tmp
+wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
+chmod +x guix-install.sh
+./guix-install.sh
+@end example
@end quotation
Installing goes along these lines:
Do @emph{not} unpack the tarball on a working Guix system since that
would overwrite its own essential files.
-The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
+The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
not emit warnings about ``implausibly old time stamps'' (such
warnings were triggered by GNU@tie{}tar 1.26 and older; recent
versions are fine.)
~root/.config/guix/current
@end example
-Source @file{etc/profile} to augment @code{PATH} and other relevant
+Source @file{etc/profile} to augment @env{PATH} and other relevant
environment variables:
@example
@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 \
+# cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
+ ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
-# systemctl start guix-daemon && systemctl enable guix-daemon
+# systemctl enable --now gnu-store.mount guix-daemon
@end example
If your host distro uses the Upstart init system:
GNU Guix depends on the following packages:
@itemize
-@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x or
+2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
@itemize
@item
-@c Note: We need at least 0.10.2 for 'channel-send-eof'.
+@c Note: We need at least 0.12.0 for 'userauth-gssapi!'.
Support for build offloading (@pxref{Daemon Offload Setup}) and
@command{guix copy} (@pxref{Invoking guix copy}) depends on
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
-version 0.10.2 or later.
+version 0.12.0 or later.
@item
When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib
@command{guix-daemon} can use it to compress build logs.
@end itemize
-Unless @code{--disable-daemon} was passed to @command{configure}, the
+Unless @option{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:
@itemize
@cindex state directory
When configuring Guix on a system that already has a Guix installation,
be sure to specify the same state directory as the existing installation
-using the @code{--localstatedir} option of the @command{configure}
+using the @option{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
GNU Coding Standards}). Usually, this @var{localstatedir} option is
set to the value @file{/var}. The @command{configure} script protects
@end itemize
You can influence the directory where the daemon stores build trees
-@i{via} the @code{TMPDIR} environment variable. However, the build tree
+@i{via} the @env{TMPDIR} environment variable. However, the build tree
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
-This way, the value of @code{TMPDIR} does not leak inside build
+This way, the value of @env{TMPDIR} does not leak inside build
environments, which avoids discrepancies in cases where build processes
capture the name of their build tree.
@vindex http_proxy
-The daemon also honors the @code{http_proxy} environment variable for
-HTTP downloads it performs, be it for fixed-output derivations
-(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
+@vindex https_proxy
+The daemon also honors the @env{http_proxy} and @env{https_proxy}
+environment variables for HTTP and HTTPS downloads it performs, be it
+for fixed-output derivations (@pxref{Derivations}) or for substitutes
+(@pxref{Substitutes}).
If you are installing Guix as an unprivileged user, it is still possible
-to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
+to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
However, build processes will not be isolated from one another, and not
from the rest of the system. Thus, build processes may interfere with
each other, and may access programs, libraries, and other files
@command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
@example
-$ lsh-export-key --openssh < /etc/lsh/host-key.pub
+$ lsh-export-key --openssh < /etc/lsh/host-key.pub
ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
@end example
@cindex reproducible builds
By default, @command{guix-daemon} launches build processes under
different UIDs, taken from the build group specified with
-@code{--build-users-group}. In addition, each build process is run in a
+@option{--build-users-group}. In addition, each build process is run in a
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
-its @code{TMPDIR} environment variable. This directory is shared with
+its @env{TMPDIR} environment variable. This directory is shared with
the container for the duration of the build, though within the container,
the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).
-When the daemon runs with @code{--no-substitutes}, clients can still
+When the daemon runs with @option{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
as available.
The default value is @code{0}, but it may be overridden by clients, such
-as the @code{--cores} option of @command{guix build} (@pxref{Invoking
+as the @option{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
-The effect is to define the @code{NIX_BUILD_CORES} environment variable
+The effect is to define the @env{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
The default value is @code{0}, which disables the timeout.
The value specified here can be overridden by clients (@pxref{Common
-Build Options, @code{--max-silent-time}}).
+Build Options, @option{--max-silent-time}}).
@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
The default value is @code{0}, which disables the timeout.
The value specified here can be overridden by clients (@pxref{Common
-Build Options, @code{--timeout}}).
+Build Options, @option{--timeout}}).
@item --rounds=@var{N}
Build each derivation @var{n} times in a row, and raise an error if
Produce debugging output.
This is useful to debug daemon start-up issues, but then it may be
-overridden by clients, for example the @code{--verbosity} option of
+overridden by clients, for example the @option{--verbosity} option of
@command{guix build} (@pxref{Invoking guix build}).
@item --chroot-directory=@var{dir}
Compress build logs according to @var{type}, one of @code{gzip},
@code{bzip2}, or @code{none}.
-Unless @code{--lose-logs} is used, all the build logs are kept in the
+Unless @option{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}. To save space, the daemon automatically compresses
-them with bzip2 by default.
+them with Bzip2 by default.
@item --disable-deduplication
@cindex deduplication
@cindex GC roots
@cindex garbage collector roots
-When set to ``yes'', the GC will keep the outputs of any live derivation
-available in the store---the @code{.drv} files. The default is ``no'',
-meaning that derivation outputs are kept only if they are reachable from a GC
-root. @xref{Invoking guix gc}, for more on GC roots.
+When set to @code{yes}, the GC will keep the outputs of any live
+derivation available in the store---the @file{.drv} files. The default
+is @code{no}, meaning that derivation outputs are kept only if they are
+reachable from a GC root. @xref{Invoking guix gc}, for more on GC
+roots.
@item --gc-keep-derivations[=yes|no]
Tell whether the garbage collector (GC) must keep derivations
corresponding to live outputs.
-When set to ``yes'', as is the case by default, the GC keeps
-derivations---i.e., @code{.drv} files---as long as at least one of their
+When set to @code{yes}, as is the case by default, the GC keeps
+derivations---i.e., @file{.drv} files---as long as at least one of their
outputs is live. This allows users to keep track of the origins of
-items in their store. Setting it to ``no'' saves a bit of disk space.
-
-In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness
-to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to
-``yes'' causes liveness to flow from derivations to outputs. When both are
-set to ``yes'', the effect is to keep all the build prerequisites (the
-sources, compiler, libraries, and other build-time tools) of live objects in
-the store, regardless of whether these prerequisites are reachable from a GC
-root. This is convenient for developers since it saves rebuilds or downloads.
+items in their store. Setting it to @code{no} saves a bit of disk
+space.
+
+In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
+liveness to flow from outputs to derivations, and setting
+@option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
+derivations to outputs. When both are set to @code{yes}, the effect is
+to keep all the build prerequisites (the sources, compiler, libraries,
+and other build-time tools) of live objects in the store, regardless of
+whether these prerequisites are reachable from a GC root. This is
+convenient for developers since it saves rebuilds or downloads.
@item --impersonate-linux-2.6
On Linux-based systems, impersonate Linux 2.6. This means that the
-kernel's @code{uname} system call will report 2.6 as the release number.
+kernel's @command{uname} system call will report 2.6 as the release number.
This might be helpful to build programs that (usually wrongfully) depend
on the kernel version number.
@item --lose-logs
Do not keep build logs. By default they are kept under
-@code{@var{localstatedir}/guix/log}.
+@file{@var{localstatedir}/guix/log}.
@item --system=@var{system}
Assume @var{system} as the current system type. By default it is the
This option can be repeated multiple times, in which case
@command{guix-daemon} accepts connections on all the specified
endpoints. Users can tell client commands what endpoint to connect to
-by setting the @code{GUIX_DAEMON_SOCKET} environment variable
-(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).
+by setting the @env{GUIX_DAEMON_SOCKET} environment variable
+(@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
@quotation Note
The daemon protocol is @emph{unauthenticated and unencrypted}. Using
-@code{--listen=@var{host}} is suitable on local networks, such as
+@option{--listen=@var{host}} is suitable on local networks, such as
clusters, where only trusted nodes may connect to the build daemon. In
other cases where remote access to the daemon is needed, we recommend
using Unix-domain sockets along with SSH.
@end quotation
-When @code{--listen} is omitted, @command{guix-daemon} listens for
+When @option{--listen} is omitted, @command{guix-daemon} listens for
connections on the Unix-domain socket located at
@file{@var{localstatedir}/guix/daemon-socket/socket}.
@end table
@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the locale data of the
host system. Instead, you must first install one of the locale packages
-available with Guix and then define the @code{GUIX_LOCPATH} environment
+available with Guix and then define the @env{GUIX_LOCPATH} environment
variable:
@example
Note that the @code{glibc-locales} package contains data for all the
locales supported by the GNU@tie{}libc and weighs in at around
-110@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
+917@tie{}MiB. Alternatively, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
-The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
-(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
+The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
+(@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
Manual}). There are two important differences though:
@enumerate
@item
-@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
-provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
+@env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
+provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
to make sure the programs of the foreign distro will not end up loading
incompatible locale data.
@item
-libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
+libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
@code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
should your Guix profile contain a mixture of programs linked against
different libc version, each libc version will only try to load locale
by default. Thus, to allow graphical applications installed with Guix
to display fonts, you have to install fonts with Guix as well.
Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and
-@code{font-gnu-freefont-ttf}.
+@code{font-gnu-freefont}.
+
+@cindex @code{fc-cache}
+@cindex font cache
+Once you have installed or removed fonts, or when you notice an
+application that does not find fonts, you may need to install Fontconfig
+and to force an update of its font cache by running:
+
+@example
+guix install fontconfig
+fc-cache -rv
+@end example
To display text written in Chinese languages, Japanese, or Korean in
graphical applications, consider installing
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.
-@cindex @code{fc-cache}
-@cindex font cache
-After installing fonts you may have to refresh the font cache to use
-them in applications. The same applies when applications installed via
-Guix do not seem to find fonts. To force rebuilding of the font cache
-run @code{fc-cache -rv}. The @code{fc-cache} command is provided by
-the @code{fontconfig} package.
@subsection X.509 Certificates
@subsection Emacs Packages
@cindex @code{emacs}
-When you install Emacs packages with Guix, the elisp files may be placed
-either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in
-sub-directories of
-@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
-directory exists because potentially there may exist thousands of Emacs
-packages and storing all their files in a single directory may not be
-reliable (because of name conflicts). So we think using a separate
-directory for each package is a good idea. It is very similar to how
-the Emacs package system organizes the file structure (@pxref{Package
-Files,,, emacs, The GNU Emacs Manual}).
-
-By default, Emacs (installed with Guix) ``knows'' where these packages
-are placed, so you do not need to perform any configuration. If, for
-some reason, you want to avoid auto-loading Emacs packages installed
-with Guix, you can do so by running Emacs with @code{--no-site-file}
-option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
-
-@subsection The GCC toolchain
+When you install Emacs packages with Guix, the Elisp files are placed
+under the @file{share/emacs/site-lisp/} directory of the profile in
+which they are installed. The Elisp libraries are made available to
+Emacs through the @env{EMACSLOADPATH} environment variable, which is
+set when installing Emacs itself.
-@cindex GCC
-@cindex ld-wrapper
+Additionally, autoload definitions are automatically evaluated at the
+initialization of Emacs, by the Guix-specific
+@code{guix-emacs-autoload-packages} procedure. If, for some reason, you
+want to avoid auto-loading the Emacs packages installed with Guix, you
+can do so by running Emacs with the @option{--no-site-file} option
+(@pxref{Init File,,, emacs, The GNU Emacs Manual}).
-Guix offers individual compiler packages such as @code{gcc} but if you
-are in need of a complete toolchain for compiling and linking source
-code what you really want is the @code{gcc-toolchain} package. This
-package provides a complete GCC toolchain for C/C++ development,
-including GCC itself, the GNU C Library (headers and binaries, plus
-debugging symbols in the @code{debug} output), Binutils, and a linker
-wrapper.
-
-The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
-passed to the linker, add corresponding @code{-rpath} arguments, and
-invoke the actual linker with this new set of arguments. You can instruct the
-wrapper to refuse to link against libraries not in the store by setting the
-@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
@node Upgrading Guix
@section Upgrading Guix
link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
Info}. Hit @kbd{l} afterwards to come back here.
-Alternately, run @command{info info} in another tty to keep the manual
+Alternatively, run @command{info info} in another tty to keep the manual
available.
@end quotation
@end ifinfo
Once this is done, you should be able to reboot the system and boot from
the USB stick or DVD. The latter usually requires you to get in the
BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
+In order to boot from Libreboot, switch to the command mode by pressing
+the @kbd{c} key and type @command{search_grub usb}.
@xref{Installing Guix in a VM}, if, instead, you would like to install
Guix System in a virtual machine (VM).
@section Preparing for Installation
Once you have booted, you can use the guided graphical installer, which makes
-it easy to get started (@pxref{Guided Graphical Installation}). Alternately,
+it easy to get started (@pxref{Guided Graphical Installation}). Alternatively,
if you are already familiar with GNU/Linux and if you want more control than
what the graphical installer provides, you can choose the ``manual''
installation process (@pxref{Manual Installation}).
Setting up network access is almost always a requirement because the
image does not contain all the software and tools that may be needed.
+@cindex proxy, during system installation
+If you need HTTP and HTTPS access to go through a proxy, run the
+following command:
+
+@example
+herd set-http-proxy guix-daemon @var{URL}
+@end example
+
+@noindent
+where @var{URL} is the proxy URL, for example
+@code{http://example.org:8118}.
+
@cindex installing over SSH
If you want to, you can continue the installation remotely by starting
an SSH server:
Once you are done partitioning the target hard disk drive, you have to
create a file system on the relevant partition(s)@footnote{Currently
-Guix System only supports ext4 and btrfs file systems. In particular, code
-that reads file system UUIDs and labels only works for these file system
+Guix System only supports ext4, btrfs, and JFS file systems. In particular,
+code that reads file system UUIDs and labels only works for these file system
types.}. For the ESP, if you have one and assuming it is
@file{/dev/sda1}, run:
@quotation Note
@cindex sudo vs. @command{guix pull}
Note that @command{sudo guix} runs your user's @command{guix} command and
-@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To
+@emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
+
+The difference matters here, because @command{guix pull} updates
+the @command{guix} command and package definitions only for the user it is ran
+as. This means that if you choose to use @command{guix system reconfigure} in
+root's login shell, you'll need to @command{guix pull} separately.
@end quotation
Join us on @code{#guix} on the Freenode IRC network or on
For each user, a symlink to the user's default profile is automatically
created in @file{$HOME/.guix-profile}. This symlink always points to the
current generation of the user's default profile. Thus, users can add
-@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
+@file{$HOME/.guix-profile/bin} to their @env{PATH} environment
variable, and so on.
@cindex search paths
If you are not using Guix System, consider adding the
to (@pxref{Invoking guix gc}). That directory is normally
@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
-@code{--localstatedir}, and @var{user} is the user name. The
+@option{--localstatedir}, and @var{user} is the user name. The
@file{per-user} directory is created when @command{guix-daemon} is
started, and the @var{user} sub-directory is created by @command{guix
package}.
Besides, packages sometimes rely on the definition of environment
variables for their search paths (see explanation of
-@code{--search-paths} below). Any missing or possibly incorrect
+@option{--search-paths} below). Any missing or possibly incorrect
environment variable definitions are reported here.
@item --install-from-expression=@var{exp}
development snapshots and create reproducible development environments
(@pxref{Invoking guix environment}).
+The @var{file} may also contain a JSON representation of one or more
+package definitions. Running @code{guix package -f} on
+@file{hello.json} with the following contents would result in installing
+the package @code{greeter} after building @code{myhello}:
+
+@example
+@verbatiminclude package-hello.json
+@end example
+
@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.
-As for @code{--install}, each @var{package} may specify a version number
+As for @option{--install}, each @var{package} may specify a version number
and/or output name in addition to the package name. For instance,
-@code{-r glibc:debug} would remove the @code{debug} output of
+@samp{-r glibc:debug} would remove the @code{debug} output of
@code{glibc}.
@item --upgrade[=@var{regexp} @dots{}]
@cindex upgrading packages
Upgrade all the installed packages. If one or more @var{regexp}s are
specified, upgrade only installed packages whose name matches a
-@var{regexp}. Also see the @code{--do-not-upgrade} option below.
+@var{regexp}. Also see the @option{--do-not-upgrade} option below.
Note that this upgrades package to the latest version of packages found
in the distribution currently installed. To update your distribution,
pull}).
@item --do-not-upgrade[=@var{regexp} @dots{}]
-When used together with the @code{--upgrade} option, do @emph{not}
+When used together with the @option{--upgrade} option, do @emph{not}
upgrade any packages whose name matches a @var{regexp}. For example, to
upgrade all packages in the current profile except those containing the
substring ``emacs'':
several times, in which case the manifests are concatenated.
This allows you to @emph{declare} the profile's contents rather than
-constructing it through a sequence of @code{--install} and similar
+constructing it through a sequence of @option{--install} and similar
commands. The advantage is that @var{file} can be put under version
control, copied to different machines to reproduce the same profile, and
so on.
Roll back to the previous @dfn{generation} of the profile---i.e., undo
the last transaction.
-When combined with options such as @code{--install}, roll back occurs
+When combined with options such as @option{--install}, roll back occurs
before any other actions.
When rolling back from the first generation that actually contains
@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''. The latter means: move forward/backward by a
specified number of generations. For example, if you want to return to
-the latest generation after @code{--roll-back}, use
-@code{--switch-generation=+1}.
+the latest generation after @option{--roll-back}, use
+@option{--switch-generation=+1}.
-The difference between @code{--roll-back} and
-@code{--switch-generation=-1} is that @code{--switch-generation} will
+The difference between @option{--roll-back} and
+@option{--switch-generation=-1} is that @option{--switch-generation} will
not make a zeroth generation, so if a specified generation does not
exist, the current generation will not be changed.
variables are used to specify @dfn{search paths} for files used by some
of the installed packages.
-For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
+For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
environment variables to be defined so it can look for headers and
libraries in the user's profile (@pxref{Environment Variables,,, gcc,
Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
-library are installed in the profile, then @code{--search-paths} will
-suggest setting these variables to @code{@var{profile}/include} and
-@code{@var{profile}/lib}, respectively.
+library are installed in the profile, then @option{--search-paths} will
+suggest setting these variables to @file{@var{profile}/include} and
+@file{@var{profile}/lib}, respectively.
The typical use case is to define these environment variables in the
shell:
$ guix package -p foo -p bar --search-paths
@end example
-The last command above reports about the @code{GUILE_LOAD_PATH}
+The last command above reports about the @env{GUILE_LOAD_PATH}
variable, even though, taken individually, neither @file{foo} nor
@file{bar} would lead to that recommendation.
@item --search=@var{regexp}
@itemx -s @var{regexp}
+@anchor{guix-search}
@cindex searching for packages
List the available packages whose name, synopsis, or description matches
@var{regexp} (in a case-insensitive fashion), sorted by relevance.
@itemx -A [@var{regexp}]
List packages currently available in the distribution for this system
(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
-installed packages whose name matches @var{regexp}.
+available packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name,
its version string, the parts of the package (@pxref{Packages with
@itemize
@item @emph{Integers and comma-separated integers}. Both patterns denote
-generation numbers. For instance, @code{--list-generations=1} returns
+generation numbers. For instance, @option{--list-generations=1} returns
the first one.
-And @code{--list-generations=1,8,2} outputs three generations in the
+And @option{--list-generations=1,8,2} outputs three generations in the
specified order. Neither spaces nor trailing commas are allowed.
-@item @emph{Ranges}. @code{--list-generations=2..9} prints the
+@item @emph{Ranges}. @option{--list-generations=2..9} prints the
specified generations and everything in between. Note that the start of
a range must be smaller than its end.
It is also possible to omit the endpoint. For example,
-@code{--list-generations=2..}, returns all generations starting from the
+@option{--list-generations=2..}, returns all generations starting from the
second one.
@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
or months by passing an integer along with the first letter of the
-duration. For example, @code{--list-generations=20d} lists generations
+duration. For example, @option{--list-generations=20d} lists generations
that are up to 20 days old.
@end itemize
This command accepts the same patterns as @option{--list-generations}.
When @var{pattern} is specified, delete the matching generations. When
@var{pattern} specifies a duration, generations @emph{older} than the
-specified duration match. For instance, @code{--delete-generations=1m}
+specified duration match. For instance, @option{--delete-generations=1m}
deletes generations that are more than one month old.
If the current generation matches, it is @emph{not} deleted. Also, the
@option{--with-source} (@pxref{Package Transformation Options}).
However, note that package transformations are lost when upgrading; to
preserve transformations across upgrades, you should define your own
-package variant in a Guile module and add it to @code{GUIX_PACKAGE_PATH}
+package variant in a Guile module and add it to @env{GUIX_PACKAGE_PATH}
(@pxref{Defining Packages}).
@node Substitutes
@end example
@noindent
-This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and
-will be downloaded, when possible, for future builds.
+The text changed from ``The following derivations would be built'' to
+``112.3 MB would be downloaded''. This indicates that substitutes from
+@code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when
+possible, for future builds.
@cindex substitutes, how to disable
The substitute mechanism can be disabled globally by running
-@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
+@code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
guix-daemon}). It can also be disabled temporarily by passing the
-@code{--no-substitutes} option to @command{guix package}, @command{guix
-build}, and other command-line tools.
+@option{--no-substitutes} option to @command{guix package},
+@command{guix build}, and other command-line tools.
@node Substitute Authentication
@subsection Substitute Authentication
@noindent
@cindex reproducible builds
-If the ACL contains only the key for @code{b.example.org}, and if
-@code{a.example.org} happens to serve the @emph{exact same} substitutes,
-then Guix will download substitutes from @code{a.example.org} because it
+If the ACL contains only the key for @samp{b.example.org}, and if
+@samp{a.example.org} happens to serve the @emph{exact same} substitutes,
+then Guix will download substitutes from @samp{a.example.org} because it
comes first in the list and can be considered a mirror of
-@code{b.example.org}. In practice, independent build machines usually
+@samp{b.example.org}. In practice, independent build machines usually
produce the same binaries, thanks to bit-reproducible builds (see
below).
@subsection Proxy Settings
@vindex http_proxy
-Substitutes are downloaded over HTTP or HTTPS.
-The @code{http_proxy} environment
-variable can be set in the environment of @command{guix-daemon} and is
-honored for downloads of substitutes. Note that the value of
-@code{http_proxy} in the environment where @command{guix build},
-@command{guix package}, and other client commands are run has
-@emph{absolutely no effect}.
+@vindex https_proxy
+Substitutes are downloaded over HTTP or HTTPS. The @env{http_proxy} and
+@env{https_proxy} environment variables can be set in the environment of
+@command{guix-daemon} and are honored for downloads of substitutes.
+Note that the value of those environment variables in the environment
+where @command{guix build}, @command{guix package}, and other client
+commands are run has @emph{absolutely no effect}.
@node Substitution Failure
@subsection Substitution Failure
When substitutes are enabled and a substitute for a derivation is
available, but the substitution attempt fails, Guix will attempt to
build the derivation locally depending on whether or not
-@code{--fallback} was given (@pxref{fallback-option,, common build
-option @code{--fallback}}). Specifically, if @code{--fallback} was
+@option{--fallback} was given (@pxref{fallback-option,, common build
+option @option{--fallback}}). Specifically, if @option{--fallback} was
omitted, then no local build will be performed, and the derivation is
-considered to have failed. However, if @code{--fallback} was given,
+considered to have failed. However, if @option{--fallback} was given,
then Guix will attempt to build the derivation locally, and the success
or failure of the derivation depends on the success or failure of the
local build. Note that when substitutes are disabled or no substitute
is available for the derivation in question, a local build will
@emph{always} be performed, regardless of whether or not
-@code{--fallback} was given.
+@option{--fallback} was given.
To get an idea of how many substitutes are available right now, you can
try running the @command{guix weather} command (@pxref{Invoking guix
The @command{guix gc} command has three modes of operation: it can be
used to garbage-collect any dead files (the default), to delete specific
-files (the @code{--delete} option), to print garbage-collector
+files (the @option{--delete} option), to print garbage-collector
information, or for more advanced queries. The garbage collection
options are as follows:
@dfn{deduplication}.
The daemon performs deduplication after each successful build or archive
-import, unless it was started with @code{--disable-deduplication}
-(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
+import, unless it was started with @option{--disable-deduplication}
+(@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus,
this option is primarily useful when the daemon was running with
-@code{--disable-deduplication}.
+@option{--disable-deduplication}.
@end table
export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
@end example
-The @code{--list-generations} or @code{-l} option lists past generations
+The @option{--list-generations} or @option{-l} option lists past generations
produced by @command{guix pull}, along with details about their provenance:
@example
@var{pattern} may be either a generation number or a number prefixed
with ``+'' or ``-''. The latter means: move forward/backward by a
specified number of generations. For example, if you want to return to
-the latest generation after @code{--roll-back}, use
-@code{--switch-generation=+1}.
+the latest generation after @option{--roll-back}, use
+@option{--switch-generation=+1}.
@item --delete-generations[=@var{pattern}]
@itemx -d [@var{pattern}]
This command accepts the same patterns as @option{--list-generations}.
When @var{pattern} is specified, delete the matching generations. When
@var{pattern} specifies a duration, generations @emph{older} than the
-specified duration match. For instance, @code{--delete-generations=1m}
+specified duration match. For instance, @option{--delete-generations=1m}
deletes generations that are more than one month old.
If the current generation matches, it is @emph{not} deleted.
(channel
(name 'my-personal-packages)
(url "https://example.org/personal-packages.git")
- (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
+ (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
@end lisp
The @command{guix describe --format=channels} command can even generate this
@end example
where @var{command} and @var{arg}@dots{} are passed unmodified to the
-@command{guix} command if the specified revision. The @var{options} that define
+@command{guix} command of the specified revision. The @var{options} that define
this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
@table @code
@end example
will thus build the package @code{hello} as defined in the master branch,
-which is in general a newer revison of Guix than you have installed.
+which is in general a newer revision of Guix than you have installed.
Time travel works in both directions!
Note that @command{guix time-machine} can trigger builds of channels and
produce a list of channel specifications in Recutils format.
@end table
+@item --list-formats
+Display available formats for @option{--format} option.
+
@item --profile=@var{profile}
@itemx -p @var{profile}
Display information about @var{profile}.
@noindent
However, note that, in both examples, all of @code{emacs} and the
profile as well as all of their dependencies are transferred (due to
-@code{-r}), regardless of what is already available in the store on the
-target machine. The @code{--missing} option can help figure out which
-items are missing from the target store. The @command{guix copy}
+@option{-r}), regardless of what is already available in the store on
+the target machine. The @option{--missing} option can help figure out
+which items are missing from the target store. The @command{guix copy}
command simplifies and optimizes this whole process, so this is probably
what you should use in this case (@pxref{Invoking guix copy}).
resulting archive to the standard output.
Dependencies are @emph{not} included in the output, unless
-@code{--recursive} is passed.
+@option{--recursive} is passed.
@item -r
@itemx --recursive
-When combined with @code{--export}, this instructs @command{guix
-archive} to include dependencies of the given items in the archive.
-Thus, the resulting archive is self-contained: it contains the closure
-of the exported store items.
+When combined with @option{--export}, this instructs @command{guix archive}
+to include dependencies of the given items in the archive. Thus, the
+resulting archive is self-contained: it contains the closure of the
+exported store items.
@item --import
Read an archive from the standard input, and import the files listed
therein into the store. Abort if the archive has an invalid digital
signature, or if it is signed by a public key not among the authorized
-keys (see @code{--authorize} below.)
+keys (see @option{--authorize} below.)
@item --missing
Read a list of store file names from the standard input, one per line,
@item --generate-key[=@var{parameters}]
@cindex signing, archives
Generate a new key pair for the daemon. This is a prerequisite before
-archives can be exported with @code{--export}. Note that this operation
-usually takes time, because it needs to gather enough entropy to
-generate the key pair.
+archives can be exported with @option{--export}. Note that this
+operation usually takes time, because it needs to gather enough entropy
+to generate the key pair.
The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
@example
$ wget -O - \
- https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \
- | bunzip2 | guix archive -x /tmp/emacs
+ https://@value{SUBSTITUTE-SERVER}/nar/gzip/@dots{}-emacs-24.5 \
+ | gunzip | guix archive -x /tmp/emacs
@end example
Single-item archives are different from multiple-item archives produced
unsafe.
The primary purpose of this operation is to facilitate inspection of
-archive contents coming from possibly untrusted substitute servers.
+archive contents coming from possibly untrusted substitute servers
+(@pxref{Invoking guix challenge}).
@item --list
@itemx -t
easily distributed to users who do not run Guix.
@menu
-* Invoking guix environment:: Setting up development environments.
-* Invoking guix pack:: Creating software bundles.
+* Invoking guix environment:: Setting up development environments.
+* Invoking guix pack:: Creating software bundles.
+* The GCC toolchain:: Working with languages supported by GCC.
@end menu
@node Invoking guix environment
@end example
If the needed dependencies are not built yet, @command{guix environment}
-automatically builds them. The environment of the new shell is an augmented
-version of the environment that @command{guix environment} was run in.
-It contains the necessary search paths for building the given package
-added to the existing environment variables. To create a ``pure''
-environment, in which the original environment variables have been unset,
-use the @code{--pure} option@footnote{Users sometimes wrongfully augment
-environment variables such as @code{PATH} in their @file{~/.bashrc}
-file. As a consequence, when @code{guix environment} launches it, Bash
-may read @file{~/.bashrc}, thereby introducing ``impurities'' in these
-environment variables. It is an error to define such environment
-variables in @file{.bashrc}; instead, they should be defined in
-@file{.bash_profile}, which is sourced only by log-in shells.
-@xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for
-details on Bash start-up files.}.
+automatically builds them. The environment of the new shell is an
+augmented version of the environment that @command{guix environment} was
+run in. It contains the necessary search paths for building the given
+package added to the existing environment variables. To create
+a ``pure'' environment, in which the original environment variables have
+been unset, use the @option{--pure} option@footnote{Users sometimes
+wrongfully augment environment variables such as @env{PATH} in their
+@file{~/.bashrc} file. As a consequence, when @command{guix
+environment} launches it, Bash may read @file{~/.bashrc}, thereby
+introducing ``impurities'' in these environment variables. It is an
+error to define such environment variables in @file{.bashrc}; instead,
+they should be defined in @file{.bash_profile}, which is sourced only by
+log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
+Manual}, for details on Bash start-up files.}.
@vindex GUIX_ENVIRONMENT
-@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
+@command{guix environment} defines the @env{GUIX_ENVIRONMENT}
variable in the shell it spawns; its value is the file name of the
profile of this environment. This allows users to, say, define a
specific prompt for development environments in their @file{.bashrc}
Furthermore, one might want the dependencies of a package and also some
additional packages that are not build-time or runtime dependencies, but
are useful when developing nonetheless. Because of this, the
-@code{--ad-hoc} flag is positional. Packages appearing before
-@code{--ad-hoc} are interpreted as packages whose dependencies will be
+@option{--ad-hoc} flag is positional. Packages appearing before
+@option{--ad-hoc} are interpreted as packages whose dependencies will be
added to the environment. Packages appearing after are interpreted as
packages that will be added to the environment directly. For example,
the following command creates a Guix development environment that
additionally includes Git and strace:
@example
-guix environment guix --ad-hoc git strace
+guix environment --pure guix --ad-hoc git strace
@end example
+@cindex container
Sometimes it is desirable to isolate the environment as much as
possible, for maximal purity and reproducibility. In particular, when
using Guix on a host distro that is not Guix System, it is desirable to
@end example
@quotation Note
-The @code{--container} option requires Linux-libre 3.19 or newer.
+The @option{--container} option requires Linux-libre 3.19 or newer.
@end quotation
+@cindex certificates
+Another typical use case for containers is to run security-sensitive
+applications such as a web browser. To run Eolie, we must expose and
+share some files and directories; we include @code{nss-certs} and expose
+@file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
+the @env{DISPLAY} environment variable since containerized graphical
+applications won't display without it.
+
+@example
+guix environment --preserve='^DISPLAY$' --container --network \
+ --expose=/etc/machine-id \
+ --expose=/etc/ssl/certs/ \
+ --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
+ --ad-hoc eolie nss-certs dbus -- eolie
+@end example
+
The available options are summarized below.
@table @code
of @code{glib} (@pxref{Packages with Multiple Outputs}).
This option may be composed with the default behavior of @command{guix
-environment}. Packages appearing before @code{--ad-hoc} are interpreted
-as packages whose dependencies will be added to the environment, the
-default behavior. Packages appearing after are interpreted as packages
-that will be added to the environment directly.
+environment}. Packages appearing before @option{--ad-hoc} are
+interpreted as packages whose dependencies will be added to the
+environment, the default behavior. Packages appearing after are
+interpreted as packages that will be added to the environment directly.
@item --pure
Unset existing environment variables when building the new environment, except
@end example
This example runs @command{mpirun} in a context where the only environment
-variables defined are @code{PATH}, environment variables whose name starts
-with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME},
-@code{USER}, etc.)
+variables defined are @env{PATH}, environment variables whose name starts
+with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
+@env{USER}, etc.)
@item --search-paths
Display the environment variable definitions that make up the
@cindex container
Run @var{command} within an isolated container. The current working
directory outside the container is mapped inside the container.
-Additionally, unless overridden with @code{--user}, a dummy home
+Additionally, unless overridden with @option{--user}, a dummy home
directory is created that matches the current user's home directory, and
@file{/etc/passwd} is configured accordingly.
@item --link-profile
@itemx -P
-For containers, link the environment profile to
-@file{~/.guix-profile} within the container. This is equivalent to
-running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
-within the container. Linking will fail and abort the environment if
-the directory already exists, which will certainly be the case if
-@command{guix environment} was invoked in the user's home directory.
-
-Certain packages are configured to look in
-@code{~/.guix-profile} for configuration files and data;@footnote{For
-example, the @code{fontconfig} package inspects
-@file{~/.guix-profile/share/fonts} for additional fonts.}
-@code{--link-profile} allows these programs to behave as expected within
-the environment.
+For containers, link the environment profile to @file{~/.guix-profile}
+within the container. This is equivalent to running the command
+@samp{ln -s $GUIX_ENVIRONMENT ~/.guix-profile} within the container.
+Linking will fail and abort the environment if the directory already
+exists, which will certainly be the case if @command{guix environment}
+was invoked in the user's home directory.
+
+Certain packages are configured to look in @file{~/.guix-profile} for
+configuration files and data;@footnote{For example, the
+@code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
+for additional fonts.} @option{--link-profile} allows these programs to
+behave as expected within the environment.
@item --user=@var{user}
@itemx -u @var{user}
the UID and GID inside the container are 1000. @var{user}
need not exist on the system.
-Additionally, any shared or exposed path (see @code{--share} and
-@code{--expose} respectively) whose target is within the current user's
+Additionally, any shared or exposed path (see @option{--share} and
+@option{--expose} respectively) whose target is within the current user's
home directory will be remapped relative to @file{/home/USER}; this
includes the automatic mapping of the current working directory.
@item --no-cwd
For containers, the default behavior is to share the current working
directory with the isolated container and immediately change to that
-directory within the container. If this is undesirable, @code{--no-cwd}
-will cause the current working directory to @emph{not} be automatically
-shared and will change to the user's home directory within the container
-instead. See also @code{--user}.
+directory within the container. If this is undesirable,
+@option{--no-cwd} will cause the current working directory to @emph{not}
+be automatically shared and will change to the user's home directory
+within the container instead. See also @option{--user}.
@item --expose=@var{source}[=@var{target}]
-For containers, expose the file system @var{source} from the host system
-as the read-only file system @var{target} within the container. If
+@itemx --share=@var{source}[=@var{target}]
+For containers, @option{--expose} (resp. @option{--share}) exposes the
+file system @var{source} from the host system as the read-only
+(resp. writable) file system @var{target} within the container. If
@var{target} is not specified, @var{source} is used as the target mount
point in the container.
guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
@end example
-@item --share=@var{source}[=@var{target}]
-For containers, share the file system @var{source} from the host system
-as the writable file system @var{target} within the container. If
-@var{target} is not specified, @var{source} is used as the target mount
-point in the container.
-
-The example below spawns a Guile REPL in a container in which the user's
-home directory is accessible for both reading and writing via the
-@file{/exchange} directory:
-
-@example
-guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
-@end example
@end table
@command{guix environment}
@cindex relocatable binaries, with @command{guix pack}
What if the recipient of your pack does not have root privileges on
their machine, and thus cannot unpack it in the root file system? In
-that case, you will want to use the @code{--relocatable} option (see
+that case, you will want to use the @option{--relocatable} option (see
below). This option produces @dfn{relocatable binaries}, meaning they
they can be placed anywhere in the file system hierarchy: in the example
above, users can unpack your tarball in their home directory and
the following command:
@example
-guix pack -f docker guile emacs geiser
+guix pack -f docker -S /bin=bin guile guile-readline
@end example
@noindent
The result is a tarball that can be passed to the @command{docker load}
-command. See the
+command, followed by @code{docker run}:
+
+@example
+docker load < @var{file}
+docker run -ti guile-guile-readline /bin/guile
+@end example
+
+@noindent
+where @var{file} is the image returned by @var{guix pack}, and
+@code{guile-guile-readline} is its ``image tag''. See the
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
@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{https://singularity.lbl.gov, Singularity container execution
+@uref{https://www.sylabs.io/docs/, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
@dfn{user namespaces} in the kernel Linux; when passed
@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
PRoot support, can be thought of as the abbreviation of ``Really
-Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot
-if user namespaces are unavailable, and essentially work anywhere---see below
-for the implications.
+Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to
+other techniques if user namespaces are unavailable, and essentially
+work anywhere---see below for the implications.
For example, if you create a pack containing Bash with:
To produce relocatable binaries that work even in the absence of user
namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
-case, binaries will try user namespace support and fall back to PRoot if user
-namespaces are not supported.
+case, binaries will try user namespace support and fall back to another
+@dfn{execution engine} if user namespaces are not supported. The
+following execution engines are supported:
+
+@table @code
+@item default
+Try user namespaces and fall back to PRoot if user namespaces are not
+supported (see below).
+
+@item performance
+Try user namespaces and fall back to Fakechroot if user namespaces are
+not supported (see below).
-The @uref{https://proot-me.github.io/, PRoot} program provides the necessary
+@item userns
+Run the program through user namespaces and abort if they are not
+supported.
+
+@item proot
+Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program
+provides the necessary
support for file system virtualization. It achieves that by using the
@code{ptrace} system call on the running program. This approach has the
advantage to work without requiring special kernel support, but it incurs
run-time overhead every time a system call is made.
+
+@item fakechroot
+Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
+Fakechroot} virtualizes file system accesses by intercepting calls to C
+library functions such as @code{open}, @code{stat}, @code{exec}, and so
+on. Unlike PRoot, it incurs very little overhead. However, it does not
+always work: for example, some file system accesses made from within the
+C library are not intercepted, and file system accesses made @i{via}
+direct syscalls are not intercepted either, leading to erratic behavior.
+@end table
+
+@vindex GUIX_EXECUTION_ENGINE
+When running a wrapped program, you can explicitly request one of the
+execution engines listed above by setting the
+@code{GUIX_EXECUTION_ENGINE} environment variable accordingly.
@end quotation
@cindex entry point, for Docker images
Consider the package @var{expr} evaluates to.
This has the same purpose as the same-named option in @command{guix
-build} (@pxref{Additional Build Options, @code{--expression} in
+build} (@pxref{Additional Build Options, @option{--expression} in
@command{guix build}}).
@item --manifest=@var{file}
options (@pxref{Package Transformation Options}).
+@node The GCC toolchain
+@section The GCC toolchain
+
+@cindex GCC
+@cindex ld-wrapper
+@cindex linker wrapper
+@cindex toolchain, for C development
+@cindex toolchain, for Fortran development
+
+If you need a complete toolchain for compiling and linking C or C++
+source code, use the @code{gcc-toolchain} package. This package
+provides a complete GCC toolchain for C/C++ development, including GCC
+itself, the GNU C Library (headers and binaries, plus debugging symbols
+in the @code{debug} output), Binutils, and a linker wrapper.
+
+The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
+passed to the linker, add corresponding @code{-rpath} arguments, and
+invoke the actual linker with this new set of arguments. You can instruct the
+wrapper to refuse to link against libraries not in the store by setting the
+@env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
+
+The package @code{gfortran-toolchain} provides a complete GCC toolchain
+for Fortran development. For other languages, please use
+@samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}).
+
@c *********************************************************************
@node Programming Interface
@chapter Programming Interface
name and module name must match. For instance, the @code{(my-packages
emacs)} module must be stored in a @file{my-packages/emacs.scm} file
relative to the load path specified with @option{--load-path} or
-@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
+@env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
these package definitions visible to the user interfaces:
@item
By adding the directory containing your package modules to the search path
with the @code{-L} flag of @command{guix package} and other commands
-(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH}
+(@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
environment variable described below.
@item
channels.
@end enumerate
-@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
+@env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
@defvr {Environment Variable} GUIX_PACKAGE_PATH
This is a colon-separated list of directories to search for additional
The @code{arguments} field specifies options for the build system
(@pxref{Build Systems}). Here it is interpreted by
@var{gnu-build-system} as a request run @file{configure} with the
-@code{--enable-silent-rules} flag.
+@option{--enable-silent-rules} flag.
@cindex quote
@cindex quoting
Behind the scenes, a derivation corresponding to the @code{<package>}
object is first computed by the @code{package-derivation} procedure.
-That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
+That derivation is stored in a @file{.drv} file under @file{/gnu/store}.
The build actions it prescribes may then be realized by using the
@code{build-derivations} procedure (@pxref{The Store}).
@item @code{home-page}
The URL to the home-page of the package, as a string.
-@item @code{supported-systems} (default: @var{%supported-systems})
+@item @code{supported-systems} (default: @code{%supported-systems})
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.
@end table
@item @code{sha256}
-A bytevector containing the SHA-256 hash of the source. Typically the
-@code{base32} form is used here to generate the bytevector from a
-base-32 string.
+A bytevector containing the SHA-256 hash of the source. This is
+equivalent to providing a @code{content-hash} SHA256 object in the
+@code{hash} field described below.
+
+@item @code{hash}
+The @code{content-hash} object of the source---see below for how to use
+@code{content-hash}.
You can obtain this information using @code{guix download}
(@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
@end table
@end deftp
+@deftp {Data Type} content-hash @var{value} [@var{algorithm}]
+Construct a content hash object for the given @var{algorithm}, and with
+@var{value} as its hash value. When @var{algorithm} is omitted, assume
+it is @code{sha256}.
+
+@var{value} can be a literal string, in which case it is base32-decoded,
+or it can be a bytevector.
+
+The following forms are all equivalent:
+
+@lisp
+(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
+(content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
+ sha256)
+(content-hash (base32
+ "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
+(content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
+ sha256)
+@end lisp
+
+Technically, @code{content-hash} is currently implemented as a macro.
+It performs sanity checks at macro-expansion time, when possible, such
+as ensuring that @var{value} has the right size for @var{algorithm}.
+@end deftp
@node Build Systems
@section Build Systems
evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
by the daemon (@pxref{Derivations}).
-The main build system is @var{gnu-build-system}, which implements the
+The main build system is @code{gnu-build-system}, which implements the
standard build procedure for GNU and many other packages. It
is provided by the @code{(guix build-system gnu)} module.
@defvr {Scheme Variable} gnu-build-system
-@var{gnu-build-system} represents the GNU Build System, and variants
+@code{gnu-build-system} represents the GNU Build System, and variants
thereof (@pxref{Configuration, configuration and makefile conventions,,
standards, GNU Coding Standards}).
@item configure
Run the @file{configure} script with a number of default options, such
-as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
+as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
by the @code{#:configure-flags} argument.
@item build
@vindex %standard-phases
The build-side module @code{(guix build gnu-build-system)} defines
-@var{%standard-phases} as the default list of build phases.
-@var{%standard-phases} is a list of symbol/procedure pairs, where the
+@code{%standard-phases} as the default list of build phases.
+@code{%standard-phases} is a list of symbol/procedure pairs, where the
procedure implements the actual phase.
The list of phases used for a particular package can be changed with the
Other @code{<build-system>} objects are defined to support other
conventions and tools used by free software packages. They inherit most
-of @var{gnu-build-system}, and differ mainly in the set of inputs
+of @code{gnu-build-system}, and differ mainly in the set of inputs
implicitly added to the build process, and in the list of phases
executed. Some of these build systems are listed below.
archive. In this case the parameter @code{#:source-dir} can be used to
specify the source sub-directory, defaulting to ``src''.
-The @code{#:main-class} parameter can be used with the minimal ant
-buildfile to specify the main class of the resulting jar. This makes the
-jar file executable. The @code{#:test-include} parameter can be used to
+The @code{#:main-class} parameter can be used with the minimal ant
+buildfile to specify the main class of the resulting jar. This makes the
+jar file executable. The @code{#:test-include} parameter can be used to
specify the list of junit tests to run. It defaults to
@code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
disable some tests. It defaults to @code{(list "**/Abstract*.java")},
packages using a Guix-specific build process.
The build system assumes that packages install their public interface
-(header) files to the subdirectory "include" of the "out" output and
-their libraries to the subdirectory "lib" of the "out" output.
+(header) files to the subdirectory @file{include} of the @code{out} output and
+their libraries to the subdirectory @file{lib} the @code{out} output.
It's also assumed that the union of all the dependencies of a package
has no conflicting files.
resulting image. @code{build-program} requires a list of Common Lisp
expressions to be passed as the @code{#:entry-program} argument.
-If the system is not defined within its own @code{.asd} file of the same
+If the system is not defined within its own @file{.asd} file of the same
name, then the @code{#:asd-file} parameter should be used to specify
which file the system is defined in. Furthermore, if the package
defines a system for its tests in a separate file, it will be loaded
if they are defined by the crate.
@end defvr
+
+@defvr {Scheme Variable} copy-build-system
+This variable is exported by @code{(guix build-system copy)}. It
+supports builds of simple packages that don't require much compiling,
+mostly just moving files around.
+
+It adds much of the @code{gnu-build-system} packages to the set of
+inputs. Because of this, the @code{copy-build-system} does not require
+all the boilerplate code often needed for the
+@code{trivial-build-system}.
+
+To further simplify the file installation process, an
+@code{#:install-plan} argument is exposed to let the packager specify
+which files go where. The install plan is a list of @code{(@var{source}
+@var{target} [@var{filters}])}. @var{filters} are optional.
+
+@itemize
+@item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
+@itemize
+@item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
+@item Otherwise install @var{source} as @var{target}.
+@end itemize
+
+@item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
+the trailing slash of @var{target} is implied with the same meaning
+as above.
+@itemize
+@item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
+@item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
+@code{#:exclude-regexp}, only select files are installed depending on
+the filters. Each filters is specified by a list of strings.
+@itemize
+@item With @code{#:include}, install all the files which the path suffix matches
+at least one of the elements in the given list.
+@item With @code{#:include-regexp}, install all the files which the
+subpaths match at least one of the regular expressions in the given
+list.
+@item The @code{#:exclude} and @code{#:exclude-regexp} filters
+are the complement of their inclusion counterpart. Without @code{#:include} flags,
+install all files but those matching the exclusion filters.
+If both inclusions and exclusions are specified, the exclusions are done
+on top of the inclusions.
+@end itemize
+@end itemize
+In all cases, the paths relative to @var{source} are preserved within
+@var{target}.
+@end itemize
+
+Examples:
+
+@itemize
+@item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
+@item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
+@item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
+e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
+@item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
+@file{share/my-app/sub/file}.
+@item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
+@file{share/my-app/file}.
+@end itemize
+@end defvr
+
+
@cindex Clojure (programming language)
@cindex simple Clojure build system
@defvr {Scheme Variable} clojure-build-system
with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
Other parameters are documented below.
-This build system is an extension of @var{ant-build-system}, but with the
+This build system is an extension of @code{ant-build-system}, but with the
following phases changed:
@table @code
@item install-doc
This phase installs all top-level files with base name matching
-@var{%doc-regex}. A different regex can be specified with the
+@code{%doc-regex}. A different regex can be specified with the
@code{#:doc-regex} parameter. All files (recursively) inside the documentation
directories specified in @code{#:doc-dirs} are installed as well.
@end table
is intended for use with packages making use of GLib or GTK+.
This build system adds the following two phases to the ones defined by
-@var{gnu-build-system}:
+@code{gnu-build-system}:
@table @code
@item glib-or-gtk-wrap
@file{bin/} are able to find GLib ``schemas'' and
@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
modules}. This is achieved by wrapping the programs in launch scripts
-that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
+that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
environment variables.
It is possible to exclude specific package outputs from that wrapping
installs the @file{.scm} and @file{.go} files in the right place. It also
installs documentation.
-This build system supports cross-compilation by using the @code{--target}
-option of @command{guild compile}.
+This build system supports cross-compilation by using the
+@option{--target} option of @samp{guild compile}.
Packages built with @code{guile-build-system} must provide a Guile package in
their @code{native-inputs} field.
@end defvr
@defvr {Scheme Variable} julia-build-system
-This variable is exported by @code{(guix build-system julia)}. It implements
-the build procedure used by @uref{https://julialang.org/, julia} packages,
-which essentially is similar to running @command{julia -e 'using Pkg;
-Pkg.add(package)'} in an environment where @code{JULIA_LOAD_PATH} contains the
-paths to all Julia package inputs. Tests are run not run.
+This variable is exported by @code{(guix build-system julia)}. It
+implements the build procedure used by @uref{https://julialang.org/,
+julia} packages, which essentially is similar to running @samp{julia -e
+'using Pkg; Pkg.add(package)'} in an environment where
+@env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
+Tests are run not run.
Julia packages require the source @code{file-name} to be the real name of the
package, correctly capitalized.
directory as OCaml, which is not what we want in guix. In particular, they
will install @file{.so} files in their module's directory, which is usually
fine because it is in the OCaml compiler directory. In guix though, these
-libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
+libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
@file{.so} libraries should be installed.
@end defvr
then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
For packages that install stand-alone Python programs under @code{bin/},
-it takes care of wrapping these programs so that their @code{PYTHONPATH}
+it takes care of wrapping these programs so that their @env{PYTHONPATH}
environment variable points to all the Python libraries they depend on.
Which Python package is used to perform the build can be specified with
This variable is exported by @code{(guix build-system qt)}. It
is intended for use with applications using Qt or KDE.
-This build system adds the phase @code{qt-wrap} to the ones defined by
-@var{cmake-build-system}, after the @code{install} phase.
+This build system adds the following two phases to the ones defined by
+@code{cmake-build-system}:
-This phase searches for Qt5 plugin paths, QML paths and some XDG in the inputs
+@table @code
+@item check-setup
+The phase @code{check-setup} prepares the environment for running
+the checks as commonly used by Qt test programs.
+For now this only sets some environment variables:
+@code{QT_QPA_PLATFORM=offscreen},
+@code{DBUS_FATAL_WARNINGS=0} and
+@code{CTEST_OUTPUT_ON_FAILURE=1}.
+
+This phase is added before the @code{check} phase.
+It's a separate phase to ease adjusting if necessary.
+
+@item qt-wrap
+The phase @code{qt-wrap}
+searches for Qt5 plugin paths, QML paths and some XDG in the inputs
and output. In case some path is found, all programs in the output's
@file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
are wrapped in scripts defining the necessary environment variables.
This is useful when an output is known not to contain any Qt binaries, and
where wrapping would gratuitously add a dependency of that output on Qt, KDE,
or such.
+
+This phase is added after the @code{install} phase.
+@end table
@end defvr
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
implements the build procedure used by @uref{https://r-project.org, R}
-packages, which essentially is little more than running @code{R CMD
+packages, which essentially is little more than running @samp{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
-@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
-are run after installation using the R function
+@env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
+run after installation using the R function
@code{tools::testInstalledPackage}.
@end defvr
@defvr {Scheme Variable} texlive-build-system
This variable is exported by @code{(guix build-system texlive)}. It is
used to build TeX packages in batch mode with a specified engine. The
-build system sets the @code{TEXINPUTS} variable to find all TeX source
+build system sets the @env{TEXINPUTS} variable to find all TeX source
files in the inputs.
By default it runs @code{luatex} on all files ending on @code{ins}. A
implements an installation procedure similar to the packaging system
of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
-It first creates the @code{@var{package}-autoloads.el} file, then it
+It first creates the @code{@code{package}-autoloads.el} file, then it
byte compiles all Emacs Lisp files. Differently from the Emacs
packaging system, the Info documentation files are moved to the standard
-documentation directory and the @file{dir} file is deleted. Each
-package is installed in its own directory under
-@file{share/emacs/site-lisp/guix.d}.
+documentation directory and the @file{dir} file is deleted. The Elisp
+package files are installed directly under @file{share/emacs/site-lisp}.
@end defvr
@defvr {Scheme Variable} font-build-system
@code{meson-for-build}, which is special because it doesn't clear the
@code{RUNPATH} of binaries and libraries when they are installed.
-This build system is an extension of @var{gnu-build-system}, but with the
+This build system is an extension of @code{gnu-build-system}, but with the
following phases changed to some specific for Meson:
@table @code
@item configure
The phase runs @code{meson} with the flags specified in
-@code{#:configure-flags}. The flag @code{--build-type} is always set to
-@code{plain} unless something else is specified in @code{#:build-type}.
+@code{#:configure-flags}. The flag @option{--buildtype} is always set to
+@code{debugoptimized} unless something else is specified in
+@code{#:build-type}.
@item build
The phase runs @code{ninja} to build the package in parallel by default, but
@end defvr
@defvr {Scheme Variable} linux-module-build-system
-@var{linux-module-build-system} allows building Linux kernel modules.
+@code{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
+This build system is an extension of @code{gnu-build-system}, but with the
following phases changed:
@table @code
@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).
+the module (in the @code{arguments} form of a package using the
+@code{linux-module-build-system}, use the key @code{#:linux} to specify it).
@end defvr
@defvr {Scheme Variable} node-build-system
This variable is exported by @code{(guix build-system node)}. It
-implements the build procedure used by @uref{http://nodejs.org,
+implements the build procedure used by @uref{https://nodejs.org,
Node.js}, which implements an approximation of the @code{npm install}
command, followed by an @code{npm test} command.
daemon, and to perform RPCs. These are described below. By default,
@code{open-connection}, and thus all the @command{guix} commands,
connect to the local daemon or to the URI specified by the
-@code{GUIX_DAEMON_SOCKET} environment variable.
+@env{GUIX_DAEMON_SOCKET} environment variable.
@defvr {Environment Variable} GUIX_DAEMON_SOCKET
When set, the value of this variable should be a file name or a URI
trusted nodes may connect to the build daemon at
@code{master.guix.example.org}.
-The @code{--listen} option of @command{guix-daemon} can be used to
+The @option{--listen} option of @command{guix-daemon} can be used to
instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
-@code{--listen}}).
+@option{--listen}}).
@item ssh
@cindex SSH access to build daemons
-These URIs allow you to connect to a remote daemon over
-SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}.
-A typical URL might look like this:
+These URIs allow you to connect to a remote daemon over SSH. This
+feature requires Guile-SSH (@pxref{Requirements}) and a working
+@command{guile} binary in @env{PATH} on the destination machine. It
+supports public key and GSSAPI authentication. A typical URL might look
+like this:
@example
ssh://charlie@@guix.example.org:22
Derivations allow clients of the daemon to communicate build actions to
the store. They exist in two forms: as an in-memory representation,
both on the client- and daemon-side, and as files in the store whose
-name end in @code{.drv}---these files are referred to as @dfn{derivation
+name end in @file{.drv}---these files are referred to as @dfn{derivation
paths}. Derivations paths can be passed to the @code{build-derivations}
procedure to perform the build actions they prescribe (@pxref{The
Store}).
@result{} 3
@end lisp
-When ``run'' through @var{%state-monad}, we obtain that additional state
+When ``run'' through @code{%state-monad}, we obtain that additional state
value, which is the number of @code{square} calls.
@end defvr
store)} module, is as follows.
@defvr {Scheme Variable} %store-monad
-The store monad---an alias for @var{%state-monad}.
+The store monad---an alias for @code{%state-monad}.
Values in the store monad encapsulate accesses to the store. When its
effect is needed, a value of the store monad must be ``evaluated'' by
directory of @var{package}. When @var{file} is omitted, return the name
of the @var{output} directory of @var{package}. When @var{target} is
true, use it as a cross-compilation target triplet.
+
+Note that this procedure does @emph{not} build @var{package}. Thus, the
+result might or might not designate an existing file. We recommend not
+using this procedure unless you know what you are doing.
@end deffn
@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
[#:system (%current-system)] [#:target #f] [#:graft? #t] @
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
- [#:module-path @var{%load-path}] @
+ [#:module-path @code{%load-path}] @
[#:effective-version "2.2"] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @
or a subset thereof.
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
+ [#:splice? #f] [#:set-load-path? #t]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.
@dots{})} expression to construct the file name @emph{at run time}.
@end deffn
+@deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
+@deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
+Bind @var{system} to the currently targeted system---e.g.,
+@code{"x86_64-linux"}---within @var{body}.
+
+In the second case, additionally bind @var{target} to the current
+cross-compilation target---a GNU triplet such as
+@code{"arm-linux-gnueabihf"}---or @code{#f} if we are not
+cross-compiling.
+
+@code{let-system} is useful in the occasional case where the object
+spliced into the gexp depends on the target system, as in this example:
+
+@example
+#~(system*
+ #+(let-system system
+ (cond ((string-prefix? "armhf-" system)
+ (file-append qemu "/bin/qemu-system-arm"))
+ ((string-prefix? "x86_64-" system)
+ (file-append qemu "/bin/qemu-system-x86_64"))
+ (else
+ (error "dunno!"))))
+ "-net" "user" #$image)
+@end example
+@end deffn
+
+@deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
+This macro is similar to the @code{parameterize} form for
+dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
+Guile Reference Manual}). The key difference is that it takes effect
+when the file-like object returned by @var{exp} is lowered to a
+derivation or store item.
+
+A typical use of @code{with-parameters} is to force the system in effect
+for a given object:
+
+@lisp
+(with-parameters ((%current-system "i686-linux"))
+ coreutils)
+@end lisp
+
+The example above returns an object that corresponds to the i686 build
+of Coreutils, regardless of the current value of @code{%current-system}.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
[#:target #f]
-Return as a value in @var{%store-monad} the derivation or store item
+Return as a value in @code{%store-monad} the derivation or store item
corresponding to @var{obj} for @var{system}, cross-compiling for
@var{target} if @var{target} is true. @var{obj} must be an object that
has an associated gexp compiler, such as a @code{<package>}.
@item --listen=unix:/tmp/socket
Accept connections on the Unix-domain socket @file{/tmp/socket}.
@end table
+
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tool.
+
+@item -q
+Inhibit loading of the @file{~/.guile} file. By default, that
+configuration file is loaded when spawning a @code{guile} REPL.
@end table
@c *********************************************************************
package with the corresponding name (and optionally version) is searched
for among the GNU distribution modules (@pxref{Package Modules}).
-Alternatively, the @code{--expression} option may be used to specify a
+Alternatively, the @option{--expression} option may be used to specify a
Scheme expression that evaluates to a package; this is useful when
disambiguating among several same-named packages or package variants is
needed.
This option implies @option{--no-offload}, and it has no effect when
connecting to a remote daemon with a @code{guix://} URI (@pxref{The
-Store, the @code{GUIX_DAEMON_SOCKET} variable}).
+Store, the @env{GUIX_DAEMON_SOCKET} variable}).
@item --keep-going
@itemx -k
@var{seconds}, terminate it and report a build failure.
By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--max-silent-time}}).
+guix-daemon, @option{--max-silent-time}}).
@item --timeout=@var{seconds}
Likewise, when the build or substitution process lasts for more than
@var{seconds}, terminate it and report a build failure.
By default, the daemon's setting is honored (@pxref{Invoking
-guix-daemon, @code{--timeout}}).
+guix-daemon, @option{--timeout}}).
@c Note: This option is actually not part of %standard-build-options but
@c most programs honor it.
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. @xref{Invoking
-guix-daemon, @code{--max-jobs}}, for details about this option and the
+guix-daemon, @option{--max-jobs}}, for details about this option and the
equivalent @command{guix-daemon} option.
@item --debug=@var{level}
In addition to options explicitly passed on the command line,
@command{guix build} and other @command{guix} commands that support
-building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
@defvr {Environment Variable} GUIX_BUILD_OPTIONS
Users can define this variable to a list of command line options that
guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
@end example
-As a developer, @code{--with-source} makes it easy to test release
+As a developer, @option{--with-source} makes it easy to test release
candidates:
@example
procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
@item --with-graft=@var{package}=@var{replacement}
-This is similar to @code{--with-input} but with an important difference:
+This is similar to @option{--with-input} but with an important difference:
instead of rebuilding the whole dependency chain, @var{replacement} is
built and then @dfn{grafted} onto the binaries that were initially
referring to @var{package}. @xref{Security Updates}, for more
--with-git-url=python=https://github.com/python/cpython
@end example
-This option can also be combined with @code{--with-branch} or
-@code{--with-commit} (see below).
+This option can also be combined with @option{--with-branch} or
+@option{--with-commit} (see below).
@cindex continuous integration
Obviously, since it uses the latest commit of the given branch, the result of
@code{source} field of @var{package} is an origin with the @code{git-fetch}
method (@pxref{origin Reference}) or a @code{git-checkout} object, the
repository URL is taken from that @code{source}. Otherwise you have to use
-@code{--with-git-url} to specify the URL of the Git repository.
+@option{--with-git-url} to specify the URL of the Git repository.
For instance, the following command builds @code{guile-sqlite3} from the
latest commit of its @code{master} branch, and then builds @code{guix} (which
@end example
@item --with-commit=@var{package}=@var{commit}
-This is similar to @code{--with-branch}, except that it builds from
+This is similar to @option{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
Git commit SHA1 identifier or a tag.
@end table
@item --quiet
@itemx -q
Build quietly, without displaying the build log; this is equivalent to
-@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
+@option{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
(or similar) and can always be retrieved using the @option{--log-file} option.
@item --file=@var{file}
@include package-hello.scm
@end lisp
+The @var{file} may also contain a JSON representation of one or more
+package definitions. Running @code{guix build -f} on @file{hello.json}
+with the following contents would result in building the packages
+@code{myhello} and @code{greeter}:
+
+@example
+@verbatiminclude package-hello.json
+@end example
+
+@item --manifest=@var{manifest}
+@itemx -m @var{manifest}
+Build all packages listed in the given @var{manifest}
+(@pxref{profile-manifest, @option{--manifest}}).
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.
dependencies, recursively. This is a handy way to obtain a local copy
of all the source code needed to build @var{packages}, allowing you to
eventually build them even without network access. It is an extension
-of the @code{--source} option and can accept one of the following
+of the @option{--source} option and can accept one of the following
optional argument values:
@table @code
@item package
-This value causes the @code{--sources} option to behave in the same way
-as the @code{--source} option.
+This value causes the @option{--sources} option to behave in the same way
+as the @option{--source} option.
@item all
Build the source derivations of all packages, including any source that
specified systems; other commands ignore extraneous @option{-s} options.
@quotation Note
-The @code{--system} flag is for @emph{native} compilation and must not
-be confused with cross-compilation. See @code{--target} below for
+The @option{--system} flag is for @emph{native} compilation and must not
+be confused with cross-compilation. See @option{--target} below for
information on cross-compilation.
@end quotation
An example use of this is on Linux-based systems, which can emulate
different personalities. For instance, passing
-@code{--system=i686-linux} on an @code{x86_64-linux} system or
-@code{--system=armhf-linux} on an @code{aarch64-linux} system allows you
-to build packages in a complete 32-bit environment.
+@option{--system=i686-linux} on an @code{x86_64-linux} system or
+@option{--system=armhf-linux} on an @code{aarch64-linux} system allows
+you to build packages in a complete 32-bit environment.
@quotation Note
Building for an @code{armhf-linux} system is unconditionally enabled on
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
-If a log is unavailable locally, and unless @code{--no-substitutes} is
+If a log is unavailable locally, and unless @option{--no-substitutes} is
passed, the command looks for a corresponding log on one of the
-substitute servers (as specified with @code{--substitute-urls}.)
+substitute servers (as specified with @option{--substitute-urls}.)
So for instance, imagine you want to see the build log of GDB on MIPS,
but you are actually on an @code{x86_64} machine:
To that end, the first thing to do is to use the @option{--keep-failed}
or @option{-K} option of @command{guix build}, which will keep the
failed build tree in @file{/tmp} or whatever directory you specified as
-@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}).
+@env{TMPDIR} (@pxref{Invoking guix build, @option{--keep-failed}}).
From there on, you can @command{cd} to the failed build tree and source
the @file{environment-variables} file, which contains all the
Here, @command{guix environment -C} creates a container and spawns a new
shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
strace gdb} part adds the @command{strace} and @command{gdb} commands to
-the container, which would may find handy while debugging. The
+the container, which you may find handy while debugging. The
@option{--no-grafts} option makes sure we get the exact same
environment, with ungrafted packages (@pxref{Security Updates}, for more
info on grafts).
@end example
@noindent
-launches the program specified in the @code{VISUAL} or in the
-@code{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
+launches the program specified in the @env{VISUAL} or in the
+@env{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
and that of Vim.
If you are using a Guix Git checkout (@pxref{Building from Git}), or
-have created your own packages on @code{GUIX_PACKAGE_PATH}
+have created your own packages on @env{GUIX_PACKAGE_PATH}
(@pxref{Package Modules}), you will be able to edit the package
recipes. In other cases, you will be able to examine the read-only recipes
for packages currently in the store.
+Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
+@option{--load-path=@var{directory}} (or in short @option{-L
+@var{directory}}) allows you to add @var{directory} to the front of the
+package module search path and so make your own packages visible.
@node Invoking guix download
@section Invoking @command{guix download}
@command{guix download} verifies HTTPS server certificates by loading
the certificates of X.509 authorities from the directory pointed to by
-the @code{SSL_CERT_DIR} environment variable (@pxref{X.509
+the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
Certificates}), unless @option{--no-check-certificate} is used.
The following options are available:
@table @code
+@item --hash=@var{algorithm}
+@itemx -H @var{algorithm}
+Compute a hash using the specified @var{algorithm}. @xref{Invoking guix
+hash}, for more information.
+
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}. For more
@table @code
+@item --hash=@var{algorithm}
+@itemx -H @var{algorithm}
+Compute a hash using the specified @var{algorithm}, @code{sha256} by
+default.
+
+@var{algorithm} must the name of a cryptographic hash algorithm
+supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
+@code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
+Reference Manual}).
+
@item --format=@var{fmt}
@itemx -f @var{fmt}
Write the hash in the format specified by @var{fmt}.
-Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
+Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
(@code{hex} and @code{hexadecimal} can be used as well).
If the @option{--format} option is not specified, @command{guix hash}
@table @code
@item --key-download=@var{policy}
-As for @code{guix refresh}, specify the policy to handle missing OpenPGP
-keys when verifying the package signature. @xref{Invoking guix
-refresh, @code{--key-download}}.
+As for @command{guix refresh}, specify the policy to handle missing
+OpenPGP keys when verifying the package signature. @xref{Invoking guix
+refresh, @option{--key-download}}.
@end table
@item pypi
@code{corelist} utility will be used to filter core modules out of the
list of dependencies.
-The command command below imports metadata for the @code{Acme::Boolean}
-Perl module:
+The command command below imports metadata for the Acme::Boolean Perl
+module:
@example
guix import cpan Acme::Boolean
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.
+Information is extracted from the @file{DESCRIPTION} file of the package.
-The command command below imports metadata for the @code{Cairo}
-R package:
+The command command below imports metadata for the Cairo R package:
@example
guix import cran Cairo
@end example
-When @code{--recursive} is added, the importer will traverse the
+When @option{--recursive} is added, the importer will traverse the
dependency graph of the given upstream package recursively and generate
package expressions for all those packages that are not yet in Guix.
-When @code{--archive=bioconductor} is added, metadata is imported from
+When @option{--archive=bioconductor} is added, metadata is imported from
@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
packages for for the analysis and comprehension of high-throughput
genomic data in bioinformatics.
-Information is extracted from the @code{DESCRIPTION} file contained in the
+Information is extracted from the @file{DESCRIPTION} file contained in the
package archive.
-The command below imports metadata for the @code{GenomicRanges}
-R package:
+The command below imports metadata for the GenomicRanges R package:
@example
guix import cran --archive=bioconductor GenomicRanges
Finally, you can also import R packages that have not yet been published on
CRAN or Bioconductor as long as they are in a git repository. Use
-@code{--archive=git} followed by the URL of the git repository:
+@option{--archive=git} followed by the URL of the git repository:
@example
guix import cran --archive=git https://github.com/immunogenomics/harmony
guix import texlive fontspec
@end example
-When @code{--archive=DIRECTORY} is added, the source code is downloaded
-not from the @file{latex} sub-directory of the @file{texmf-dist/source}
-tree in the TeX Live SVN repository, but from the specified sibling
-directory under the same root.
+When @option{--archive=@var{directory}} is added, the source code is
+downloaded not from the @file{latex} sub-directory of the
+@file{texmf-dist/source} tree in the TeX Live SVN repository, but from
+the specified sibling @var{directory} under the same root.
The command below imports metadata for the @code{ifxetex} package from
CTAN while fetching the sources from the directory
@end table
The command below imports metadata for the latest version of the
-@code{HTTP} Haskell package without including test dependencies and
+HTTP Haskell package without including test dependencies and
specifying the value of the flag @samp{network-uri} as @code{false}:
@example
in Guix.
@end table
-The command below imports metadata for the @code{HTTP} Haskell package
+The command below imports metadata for the HTTP Haskell package
included in the LTS Stackage release version 7.18:
@example
gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
@end example
-Alternately, one can specify packages to consider, in which case a
+Alternatively, one can specify packages to consider, in which case a
warning is emitted for packages that lack an updater:
@example
(properties '((upstream-name . "NetworkManager")))))
@end lisp
-When passed @code{--update}, it modifies distribution source files to
+When passed @option{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those package
recipes (@pxref{Defining Packages}). This is achieved by downloading
each package's latest source tarball and its associated OpenPGP
@noindent
The command above specifically updates the @code{emacs} and
-@code{idutils} packages. The @code{--select} option would have no
+@code{idutils} packages. The @option{--select} option would have no
effect in this case.
When considering whether to upgrade a package, it is sometimes
@end table
-Be aware that the @code{--list-dependent} option only
+Be aware that the @option{--list-dependent} option only
@emph{approximates} the rebuilds that would be required as a result of
an upgrade. More rebuilds might be required under some circumstances.
@item --key-server=@var{host}
Use @var{host} as the OpenPGP key server when importing a public key.
+@item --load-path=@var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
+
@end table
The @code{github} updater uses the
default 60 API requests per hour are allowed, and a full refresh on all
GitHub packages in Guix requires more than this. Authentication with
GitHub through the use of an API token alleviates these limits. To use
-an API token, set the environment variable @code{GUIX_GITHUB_TOKEN} to a
+an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
token procured from @uref{https://github.com/settings/tokens} or
otherwise.
common errors and use a consistent style. It runs a number of checks on
a given set of packages in order to find common mistakes in their
definitions. Available @dfn{checkers} include (see
-@code{--list-checkers} for a complete list):
+@option{--list-checkers} for a complete list):
@table @code
@item synopsis
@item --checkers
@itemx -c
Only enable the checkers specified in a comma-separated list using the
-names returned by @code{--list-checkers}.
+names returned by @option{--list-checkers}.
@item --load-path=@var{directory}
@itemx -L @var{directory}
102.3@tie{}MiB in total, which is much less than the sum of each closure
since they have a lot of dependencies in common.
+When looking at the profile returned by @command{guix size}, you may
+find yourself wondering why a given package shows up in the profile at
+all. To understand it, you can use @command{guix graph --path -t
+references} to display the shortest path between the two packages
+(@pxref{Invoking guix graph}).
+
The available options are:
@table @option
@itemx -s @var{system}
Consider packages for @var{system}---e.g., @code{x86_64-linux}.
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
@node Invoking guix graph
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{https://www.opencypher.org/, openCypher} query language.
-The general syntax is:
+the @uref{https://www.opencypher.org/, openCypher} query language. With
+@option{--path}, it simply displays the shortest path between two
+packages. The general syntax is:
@example
guix graph @var{options} @var{package}@dots{}
Nice little graph, no?
+You may find it more pleasant to navigate the graph interactively with
+@command{xdot} (from the @code{xdot} package):
+
+@example
+guix graph coreutils | xdot -
+@end example
+
But there is more than one graph! The one above is concise: it is the
graph of package objects, omitting implicit inputs such as GCC, libc,
grep, etc. It is often useful to have such a concise graph, but
For instance, the following command:
@example
-guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
+guix graph --type=bag-emerged coreutils
@end example
...@: yields this bigger graph:
module that defines the @code{guile} package:
@example
-guix graph -t module guile | dot -Tpdf > module-graph.pdf
+guix graph -t module guile | xdot -
@end example
@end table
@end table
+@cindex shortest path, between packages
+Often, the graph of the package you are interested in does not fit on
+your screen, and anyway all you want to know is @emph{why} that package
+actually depends on some seemingly unrelated package. The
+@option{--path} option instructs @command{guix graph} to display the
+shortest path between two packages (or derivations, or store items,
+etc.):
+
+@example
+$ guix graph --path emacs libunistring
+emacs@@26.3
+mailutils@@3.9
+libunistring@@0.9.10
+$ guix graph --path -t derivation emacs libunistring
+/gnu/store/@dots{}-emacs-26.3.drv
+/gnu/store/@dots{}-mailutils-3.9.drv
+/gnu/store/@dots{}-libunistring-0.9.10.drv
+$ guix graph --path -t references emacs libunistring
+/gnu/store/@dots{}-emacs-26.3
+/gnu/store/@dots{}-libidn2-2.2.0
+/gnu/store/@dots{}-libunistring-0.9.10
+@end example
+
The available options are the following:
@table @option
Currently, the available backends are Graphviz and d3.js.
+@item --path
+Display the shortest path between two nodes of the type specified by
+@option{--type}. The example below shows the shortest path between
+@code{libreoffice} and @code{llvm} according to the references of
+@code{libreoffice}:
+
+@example
+$ guix graph --path -t references libreoffice llvm
+/gnu/store/@dots{}-libreoffice-6.4.2.2
+/gnu/store/@dots{}-libepoxy-1.5.4
+/gnu/store/@dots{}-mesa-19.3.4
+/gnu/store/@dots{}-llvm-9.0.1
+@end example
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
The package dependency graph is largely architecture-independent, but there
are some architecture-dependent bits that this option allows you to visualize.
+
+@item --load-path=@var{directory}
+@itemx -L @var{directory}
+Add @var{directory} to the front of the package module search path
+(@pxref{Package Modules}).
+
+This allows users to define their own packages and make them visible to
+the command-line tools.
@end table
On top of that, @command{guix graph} supports all the usual package
their authenticity and integrity (@pxref{Substitutes}). Because
@command{guix publish} uses the signing key of the system, which is only
readable by the system administrator, it must be started as root; the
-@code{--user} option makes it drop root privileges early on.
+@option{--user} option makes it drop root privileges early on.
The signing key pair must be generated before @command{guix publish} is
launched, using @command{guix archive --generate-key} (@pxref{Invoking
as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
URLs return the compressed log as-is, with an appropriate
@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
-running @command{guix-daemon} with @code{--log-compression=gzip} since
+running @command{guix-daemon} with @option{--log-compression=gzip} since
Web browsers can automatically decompress it, which is not the case with
-bzip2 compression.
+Bzip2 compression.
The following options are available:
This automatically invokes @command{diffoscope}, which displays detailed
information about files that differ.
-Alternately, we can do something along these lines (@pxref{Invoking guix
+Alternatively, we can do something along these lines (@pxref{Invoking guix
archive}):
@example
-$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \
- | guix archive -x /tmp/git
+$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/lzip/@dots{}-git-2.5.0 \
+ | lzip -d | guix archive -x /tmp/git
$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
@end example
Do not show further details about the differences.
@end table
-Thus, unless @code{--diff=none} is passed, @command{guix challenge}
+Thus, unless @option{--diff=none} is passed, @command{guix challenge}
downloads the store items from the given substitute servers so that it
can compare them.
When @var{packages} is omitted, @command{guix weather} checks the availability
of substitutes for @emph{all} the packages, or for those specified with
@option{--manifest}; otherwise it only considers the specified packages. It
-is also possible to query specific system types with @option{--system}. The
-available options are listed below.
+is also possible to query specific system types with @option{--system}.
+@command{guix weather} exits with a non-zero code when the fraction of
+available substitutes is below 100%.
+
+The available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
with the @code{-m} option of @command{guix package} (@pxref{Invoking
guix package}).
+This option can be repeated several times, in which case the manifests
+are concatenated.
+
@item --coverage[=@var{count}]
@itemx -c [@var{count}]
Report on substitute coverage for packages: list packages with at least
If you are a Guix developer, or if you are taking care of this build farm,
you'll probably want to have a closer look at these packages: they may simply
fail to build.
+
+@item --display-missing
+Display the list of store items for which substitutes are missing.
@end table
@node Invoking guix processes
@vindex %base-packages
The @code{packages} field lists packages that will be globally visible
-on the system, for all user accounts---i.e., in every user's @code{PATH}
+on the system, for all user accounts---i.e., in every user's @env{PATH}
environment variable---in addition to the per-user profiles
(@pxref{Invoking guix package}). The @code{%base-packages} variable
provides all the tools one would expect for basic user and administrator
configuration (@pxref{Using the Configuration System}).
@table @asis
-@item @code{kernel} (default: @var{linux-libre})
+@item @code{kernel} (default: @code{linux-libre})
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{'("quiet")})
+@item @code{kernel-loadable-modules} (default: '())
+A list of objects (usually packages) to collect loadable kernel modules
+from--e.g. @code{(list ddcci-driver-linux)}.
+
+@item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
Linux @dfn{pluggable authentication module} (PAM) services.
@c FIXME: Add xref to PAM services section.
-@item @code{setuid-programs} (default: @var{%setuid-programs})
+@item @code{setuid-programs} (default: @code{%setuid-programs})
List of string-valued G-expressions denoting setuid programs.
@xref{Setuid Programs}.
-@item @code{sudoers-file} (default: @var{%sudoers-specification})
+@item @code{sudoers-file} (default: @code{%sudoers-specification})
@cindex sudoers file
The contents of the @file{/etc/sudoers} file as a file-like object
(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
Manual}, for more information on these flags.
@item @code{options} (default: @code{#f})
-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.
+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. Note that the
+@code{file-system-options->alist} and @code{alist->file-system-options}
+procedures from @code{(gnu system file-systems)} can be used to convert
+file system options given as an association list to the string
+representation, and vice-versa.
@item @code{mount?} (default: @code{#t})
This value indicates whether to automatically mount the file system when
@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
-such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
+such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
below.) Operating system declarations should always contain at least
these.
@end defvr
@code{fuse.ko} kernel module to be loaded.
@end defvr
+@node Btrfs file system
+@subsection Btrfs file system
+
+The Btrfs has special features, such as subvolumes, that merit being
+explained in more details. The following section attempts to cover
+basic as well as complex uses of a Btrfs file system with the Guix
+System.
+
+In its simplest usage, a Btrfs file system can be described, for
+example, by:
+
+@lisp
+(file-system
+ (mount-point "/home")
+ (type "btrfs")
+ (device (file-system-label "my-home")))
+@end lisp
+
+The example below is more complex, as it makes use of a Btrfs
+subvolume, named @code{rootfs}. The parent Btrfs file system is labeled
+@code{my-btrfs-pool}, and is located on an encrypted device (hence the
+dependency on @code{mapped-devices}):
+
+@lisp
+(file-system
+ (device (file-system-label "my-btrfs-pool"))
+ (mount-point "/")
+ (type "btrfs")
+ (options "subvol=rootfs")
+ (dependencies mapped-devices))
+@end lisp
+
+Some bootloaders, for example GRUB, only mount a Btrfs partition at its
+top level during the early boot, and rely on their configuration to
+refer to the correct subvolume path within that top level. The
+bootloaders operating in this way typically produce their configuration
+on a running system where the Btrfs partitions are already mounted and
+where the subvolume information is readily available. As an example,
+@command{grub-mkconfig}, the configuration generator command shipped
+with GRUB, reads @file{/proc/self/mountinfo} to determine the top-level
+path of a subvolume.
+
+The Guix System produces a bootloader configuration using the operating
+system configuration as its sole input; it is therefore necessary to
+extract the subvolume name on which @file{/gnu/store} lives (if any)
+from that operating system configuration. To better illustrate,
+consider a subvolume named 'rootfs' which contains the root file system
+data. In such situation, the GRUB bootloader would only see the top
+level of the root Btrfs partition, e.g.:
+
+@example
+/ (top level)
+├── rootfs (subvolume directory)
+ ├── gnu (normal directory)
+ ├── store (normal directory)
+[...]
+@end example
+
+Thus, the subvolume name must be prepended to the @file{/gnu/store} path
+of the kernel, initrd binaries and any other files referred to in the
+GRUB configuration that must be found during the early boot.
+
+The next example shows a nested hierarchy of subvolumes and
+directories:
+
+@example
+/ (top level)
+├── rootfs (subvolume)
+ ├── gnu (normal directory)
+ ├── store (subvolume)
+[...]
+@end example
+
+This scenario would work without mounting the 'store' subvolume.
+Mounting 'rootfs' is sufficient, since the subvolume name matches its
+intended mount point in the file system hierarchy. Alternatively, the
+'store' subvolume could be referred to by setting the @code{subvol}
+option to either @code{/rootfs/gnu/store} or @code{rootfs/gnu/store}.
+
+Finally, a more contrived example of nested subvolumes:
+
+@example
+/ (top level)
+├── root-snapshots (subvolume)
+ ├── root-current (subvolume)
+ ├── guix-store (subvolume)
+[...]
+@end example
+
+Here, the 'guix-store' subvolume doesn't match its intended mount point,
+so it is necessary to mount it. The subvolume must be fully specified,
+by passing its file name to the @code{subvol} option. To illustrate,
+the 'guix-store' subvolume could be mounted on @file{/gnu/store} by using
+a file system declaration such as:
+
+@lisp
+(file-system
+ (device (file-system-label "btrfs-pool-1"))
+ (mount-point "/gnu/store")
+ (type "btrfs")
+ (options "subvol=root-snapshots/root-current/guix-store,\
+compress-force=zstd,space_cache=v2"))
+@end lisp
+
@node Mapped Devices
@section Mapped Devices
;; The Catalan layout.
(keyboard-layout "es" "cat")
+;; Arabic layout with "Alt-Shift" to switch to US layout.
+(keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
+
;; The Latin American Spanish layout. In addition, the
;; "Caps Lock" key is used as an additional "Ctrl" key,
;; and the "Menu" key is used as a "Compose" key to enter
@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
version, which is the default location where the GNU@tie{}libc provided
by Guix looks for locale data. This can be overridden using the
-@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
-@code{LOCPATH} and locale packages}).
+@env{LOCPATH} environment variable (@pxref{locales-and-locpath,
+@env{LOCPATH} and locale packages}).
The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module. Details are given below.
data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
the incompatible locale data, which is already an improvement.}.
Similarly, a program linked against libc 2.22 can read most, but not
-all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
+all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
data is incompatible); thus calls to @code{setlocale} may fail, but
programs will not abort.
used to build the system-wide locale data.
Fortunately, unprivileged users can also install their own locale data
-and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
-@code{GUIX_LOCPATH} and locale packages}).
+and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
+@env{GUIX_LOCPATH} and locale packages}).
Still, it is best if the system-wide locale data at
@file{/run/current-system/locale} is built for all the libc versions
* Game Services:: Game servers.
* PAM Mount Service:: Service to mount volumes when logging in.
* Guix Services:: Services relating specifically to Guix.
+* Linux Services:: Services tied to the Linux kernel.
* Miscellaneous Services:: Other services.
@end menu
Return a service that sets the host name to @var{name}.
@end deffn
+@defvr {Scheme Variable} console-font-service-type
+Install the given fonts on the specified ttys (fonts are per
+virtual console on the kernel Linux). The value of this service is a list of
+tty/font pairs. The font can be the name of a font provided by the @code{kbd}
+package or any valid argument to @command{setfont}, as in this example:
+
+@lisp
+`(("tty1" . "LatGrkCyr-8x16")
+ ("tty2" . ,(file-append
+ font-tamzen
+ "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
+ ("tty3" . ,(file-append
+ font-terminus
+ "/share/consolefonts/ter-132n"))) ; for HDPI
+@end lisp
+@end defvr
+
@deffn {Scheme Procedure} login-service @var{config}
Return a service to run login according to @var{config}, a
@code{<login-configuration>} object, which specifies the message of the day,
@item @code{tty}
The name of the console this agetty runs on, as a string---e.g.,
-@code{"ttyS0"}. This argument is optional, it will default to
+@code{"ttyS0"}. This argument is optional, it will default to
a reasonable default serial port used by the kernel Linux.
For this, if there is a value for an option @code{agetty.tty} in the kernel
descending order.
@item @code{term} (default: @code{#f})
-A string containing the value used for the @code{TERM} environment
+A string containing the value used for the @env{TERM} environment
variable.
@item @code{eight-bits?} (default: @code{#f})
When @code{#t}, don't reset terminal cflags (control modes).
@item @code{host} (default: @code{#f})
-This accepts a string containing the "login_host", which will be written
+This accepts a string containing the ``login_host'', which will be written
into the @file{/var/run/utmpx} file.
@item @code{remote?} (default: @code{#f})
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 user
+This option accepts a string that should be interpreted to mean ``ignore
+all previous characters'' (also called a ``kill'' character) when the user
types their login name.
@item @code{chdir} (default: @code{#f})
@command{login} program.
@item @code{extra-options} (default: @code{'()})
-This option provides an "escape hatch" for the user to provide arbitrary
+This option provides an ``escape hatch'' for the user to provide arbitrary
command-line arguments to @command{agetty} as a list of strings.
@end table
@defvr {Scheme Variable} %nscd-default-configuration
This is the default @code{<nscd-configuration>} value (see below) used
by @code{nscd-service}. It uses the caches defined by
-@var{%nscd-default-caches}; see below.
+@code{%nscd-default-caches}; see below.
@end defvr
@deftp {Data Type} nscd-configuration
Integer denoting the debugging levels. Higher numbers mean that more
debugging output is logged.
-@item @code{caches} (default: @var{%nscd-default-caches})
+@item @code{caches} (default: @code{%nscd-default-caches})
List of @code{<nscd-cache>} objects denoting things to be cached; see
below.
File where @command{guix-daemon}'s standard output and standard error
are written.
+@cindex HTTP proxy, for @code{guix-daemon}
+@cindex proxy, for @code{guix-daemon} HTTP access
@item @code{http-proxy} (default: @code{#f})
-The HTTP proxy used for downloading fixed-output derivations and
-substitutes.
+The URL of the HTTP and HTTPS proxy used for downloading fixed-output
+derivations and substitutes.
+
+It is also possible to change the daemon's proxy at run time through the
+@code{set-http-proxy} action, which restarts it:
+
+@example
+herd set-http-proxy guix-daemon http://localhost:8118
+@end example
+
+To clear the proxy settings, run:
+
+@example
+herd set-http-proxy guix-daemon
+@end example
@item @code{tmpdir} (default: @code{#f})
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 @code{udev-rule} and @code{file->udev-rule} from
-@code{(gnu services base)} simplify the creation of such rule files.
+variable. The procedures @code{udev-rule}, @code{udev-rules-service}
+and @code{file->udev-rule} from @code{(gnu services base)} simplify the
+creation of such rule files.
+
+The @command{herd rules udev} command, as root, returns the name of the
+directory containing all the active udev rules.
@end deffn
@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
"ATTR@{product@}==\"Example\", "
"RUN+=\"/path/to/script\"")))
@end lisp
-
-The @command{herd rules udev} command, as root, returns the name of the
-directory containing all the active udev rules.
@end deffn
-Here we show how the default @var{udev-service} can be extended with it.
+@deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @
+ [#:groups @var{groups}]
+Return a service that extends @code{udev-service-type } with @var{rules}
+and @code{account-service-type} with @var{groups} as system groups.
+This works by creating a singleton service type
+@code{@var{name}-udev-rules}, of which the returned service is an
+instance.
+
+Here we show how it can be used to extend @code{udev-service-type} with the
+previously defined rule @code{%example-udev-rule}.
@lisp
(operating-system
;; @dots{}
(services
- (modify-services %desktop-services
- (udev-service-type config =>
- (udev-configuration (inherit config)
- (rules (append (udev-configuration-rules config)
- (list %example-udev-rule))))))))
+ (cons (udev-rules-service 'usb-thing %example-udev-rule)
+ %desktop-services)))
@end lisp
+@end deffn
@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
Return a udev file named @var{file-name} containing the rules defined
package so that the Android tool @command{adb} can detect devices
without root privileges. It also details how to create the
@code{adbusers} group, which is required for the proper functioning of
-the rules defined within the @var{android-udev-rules} package. To
+the rules defined within the @code{android-udev-rules} package. To
create such a group, we must define it both as part of the
-@var{supplementary-groups} of our @var{user-account} declaration, as
-well as in the @var{groups} field of the @var{operating-system} record.
+@code{supplementary-groups} of our @code{user-account} declaration, as
+well as in the @var{groups} of the @code{udev-rules-service} procedure.
@lisp
(use-modules (gnu packages android) ;for android-udev-rules
(operating-system
;; @dots{}
- (users (cons (user-acount
+ (users (cons (user-account
;; @dots{}
(supplementary-groups
'("adbusers" ;for adb
"wheel" "netdev" "audio" "video")))))
-
- (groups (cons (user-group (system? #t) (name "adbusers"))
- %base-groups))
-
;; @dots{}
-
(services
- (modify-services %desktop-services
- (udev-service-type
- config =>
- (udev-configuration (inherit config)
- (rules (cons android-udev-rules
- (udev-configuration-rules config))))))))
+ (cons (udev-rules-service 'android android-udev-rules
+ #:groups '("adbusers"))
+ %desktop-services)))
@end lisp
@defvr {Scheme Variable} urandom-seed-service-type
-Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
+Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
when rebooting. It also tries to seed @file{/dev/urandom} from
@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
readable.
@item @code{nar-path} (default: @code{"nar"})
The URL path at which ``nars'' can be fetched. @xref{Invoking guix
-publish, @code{--nar-path}}, for details.
+publish, @option{--nar-path}}, for details.
@item @code{cache} (default: @code{#f})
When it is @code{#f}, disable caching and instead generate archives on
services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
-The example below defines an operating system that provides log rotation
-with the default settings, for commonly encountered log files.
+This service is part of @code{%base-services}, and thus enabled by
+default, with the default settings, for commonly encountered log files.
+The example below shows how to extend it with an additional
+@dfn{rotation}, should you need to do that (usually, services that
+produce log files already take care of that):
@lisp
(use-modules (guix) (gnu))
-(use-service-modules admin mcron)
-(use-package-modules base idutils)
+(use-service-modules admin)
+
+(define my-log-files
+ ;; Log files that I want to rotate.
+ '("/var/log/something.log" "/var/log/another.log"))
(operating-system
;; @dots{}
- (services (cons (service rottlog-service-type)
+ (services (cons (simple-service 'rotate-my-stuff
+ rottlog-service-type
+ (list (log-rotation
+ (frequency 'daily)
+ (files my-log-files))))
%base-services)))
@end lisp
@end deftp
@defvr {Scheme Variable} %default-rotations
-Specifies weekly rotation of @var{%rotated-files} and of
+Specifies weekly rotation of @code{%rotated-files} and of
@file{/var/log/guix-daemon.log}.
@end defvr
@defvr {Scheme Variable} usb-modeswitch-service-type
This is the service type for the
-@uref{http://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
+@uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
value for this service type is a @code{usb-modeswitch-configuration} record.
When plugged in, some USB modems (and other USB devices) initially present
@end table
@end deftp
+@cindex hostapd service, for Wi-Fi access points
+@cindex Wi-Fi access points, hostapd service
+@defvr {Scheme Variable} hostapd-service-type
+This is the service type to run the @uref{https://w1.fi/hostapd/,
+hostapd} daemon to set up WiFi (IEEE 802.11) access points and
+authentication servers. Its associated value must be a
+@code{hostapd-configuration} as shown below:
+
+@lisp
+;; Use wlan1 to run the access point for "My Network".
+(service hostapd-service-type
+ (hostapd-configuration
+ (interface "wlan1")
+ (ssid "My Network")
+ (channel 12)))
+@end lisp
+@end defvr
+
+@deftp {Data Type} hostapd-configuration
+This data type represents the configuration of the hostapd service, with
+the following fields:
+
+@table @asis
+@item @code{package} (default: @code{hostapd})
+The hostapd package to use.
+
+@item @code{interface} (default: @code{"wlan0"})
+The network interface to run the WiFi access point.
+
+@item @code{ssid}
+The SSID (@dfn{service set identifier}), a string that identifies this
+network.
+
+@item @code{broadcast-ssid?} (default: @code{#t})
+Whether to broadcast this SSID.
+
+@item @code{channel} (default: @code{1})
+The WiFi channel to use.
+
+@item @code{driver} (default: @code{"nl80211"})
+The driver interface type. @code{"nl80211"} is used with all Linux
+mac80211 drivers. Use @code{"none"} if building hostapd as a standalone
+RADIUS server that does # not control any wireless/wired driver.
+
+@item @code{extra-settings} (default: @code{""})
+Extra settings to append as-is to the hostapd configuration file. See
+@uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
+configuration file reference.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} simulated-wifi-service-type
+This is the type of a service to simulate WiFi networking, which can be
+useful in virtual machines for testing purposes. The service loads the
+Linux kernel
+@uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
+@code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
+network that can be seen on @code{wlan0}, by default.
+
+The service's value is a @code{hostapd-configuration} record.
+@end defvr
+
@cindex iptables
@defvr {Scheme Variable} iptables-service-type
This is the service type to set up an iptables configuration. iptables is a
@cindex ntpd, service for the Network Time Protocol daemon
@cindex real time clock
@defvr {Scheme Variable} ntp-service-type
-This is the type of the service running the @uref{http://www.ntp.org,
+This is the type of the service running the @uref{https://www.ntp.org,
Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
system clock synchronized with that of the specified NTP servers.
@defvr {Scheme Variable} %openntpd-servers
This variable is a list of the server addresses defined in
-@var{%ntp-servers}.
+@code{%ntp-servers}.
@end defvr
@deftp {Data Type} openntpd-configuration
information.
@item @code{server} (default: @code{'()})
Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
-@item @code{servers} (default: @var{%openntp-servers})
+@item @code{servers} (default: @code{%openntp-servers})
Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
@item @code{constraint-from} (default: @code{'()})
@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
subsystem request.
The command @command{internal-sftp} implements an in-process SFTP
-server. Alternately, one can specify the @command{sftp-server} command:
+server. Alternatively, one can specify the @command{sftp-server} command:
@lisp
(service openssh-service-type
(openssh-configuration
Each string gets on its own line. See the @code{AcceptEnv} option in
@code{man sshd_config}.
-This example allows ssh-clients to export the @code{COLORTERM} variable.
+This example allows ssh-clients to export the @env{COLORTERM} variable.
It is set by terminal emulators, which support colors. You can use it in
-your shell's ressource file to enable colors for the prompt and commands
+your shell's resource file to enable colors for the prompt and commands
if this variable is set.
@lisp
@end table
@end deftp
+@cindex AutoSSH
+@deffn {Scheme Variable} autossh-service-type
+This is the type for the @uref{https://www.harding.motd.ca/autossh,
+AutoSSH} program that runs a copy of @command{ssh} and monitors it,
+restarting it as necessary should it die or stop passing traffic.
+AutoSSH can be run manually from the command-line by passing arguments
+to the binary @command{autossh} from the package @code{autossh}, but it
+can also be run as a Guix service. This latter use case is documented
+here.
+
+AutoSSH can be used to forward local traffic to a remote machine using
+an SSH tunnel, and it respects the @file{~/.ssh/config} of the user it
+is run as.
+
+For example, to specify a service running autossh as the user
+@code{pino} and forwarding all local connections to port @code{8081} to
+@code{remote:8081} using an SSH tunnel, add this call to the operating
+system's @code{services} field:
+
+@lisp
+(service autossh-service-type
+ (autossh-configuration
+ (user "pino")
+ (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
+@end lisp
+@end deffn
+
+@deftp {Data Type} autossh-configuration
+This data type represents the configuration of an AutoSSH service.
+
+@table @asis
+
+@item @code{user} (default @code{"autossh"})
+The user as which the AutoSSH service is to be run.
+This assumes that the specified user exists.
+
+@item @code{poll} (default @code{600})
+Specifies the connection poll time in seconds.
+
+@item @code{first-poll} (default @code{#f})
+Specifies how many seconds AutoSSH waits before the first connection
+test. After this first test, polling is resumed at the pace defined in
+@code{poll}. When set to @code{#f}, the first poll is not treated
+specially and will also use the connection poll specified in
+@code{poll}.
+
+@item @code{gate-time} (default @code{30})
+Specifies how many seconds an SSH connection must be active before it is
+considered successful.
+
+@item @code{log-level} (default @code{1})
+The log level, corresponding to the levels used by syslog---so @code{0}
+is the most silent while @code{7} is the chattiest.
+
+@item @code{max-start} (default @code{#f})
+The maximum number of times SSH may be (re)started before AutoSSH exits.
+When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely.
+
+@item @code{message} (default @code{""})
+The message to append to the echo message sent when testing connections.
+
+@item @code{port} (default @code{"0"})
+The ports used for monitoring the connection. When set to @code{"0"},
+monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
+a positive integer, ports @var{n} and @var{n}+1 are used for
+monitoring the connection, such that port @var{n} is the base
+monitoring port and @code{n+1} is the echo port. When set to
+@code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
+integers, the ports @var{n} and @var{n}+1 are used for monitoring the
+connection, such that port @var{n} is the base monitoring port and
+@var{m} is the echo port.
+
+@item @code{ssh-options} (default @code{'()})
+The list of command-line arguments to pass to @command{ssh} when it is
+run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
+may cause undefined behaviour.
+
+@end table
+@end deftp
+
@defvr {Scheme Variable} %facebook-host-aliases
This variable contains a string for use in @file{/etc/hosts}
(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
This service extends the name service cache daemon (nscd) so that it can
resolve @code{.local} host names using
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
+@uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
Service Switch}, for information on host name resolution.
Additionally, add the @var{avahi} package to the system profile so that
@defvr {Scheme Variable} pagekite-service-type
This is the service type for the @uref{https://pagekite.net, PageKite} service,
a tunneling solution for making localhost servers publicly visible, even from
-behind NAT or restrictive firewalls. The value for this service type is a
-@code{pagekite-configuration} record.
+behind restrictive firewalls or NAT without forwarded ports. The value for
+this service type is a @code{pagekite-configuration} record.
Here's an example exposing the local HTTP and SSH daemons:
@deftp {Data Type} sddm-configuration
-This is the data type representing the sddm service configuration.
+This is the data type representing the SDDM service configuration.
@table @asis
@item @code{display-server} (default: "x11")
-Select display server to use for the greeter. Valid values are "x11"
-or "wayland".
+Select display server to use for the greeter. Valid values are
+@samp{"x11"} or @samp{"wayland"}.
@item @code{numlock} (default: "on")
-Valid values are "on", "off" or "none".
+Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
Command to run when halting.
Command to run when rebooting.
@item @code{theme} (default "maldives")
-Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
+Theme to use. Default themes provided by SDDM are @samp{"elarun"},
+@samp{"maldives"} or @samp{"maya"}.
@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
Directory to look for themes.
@cindex X11 login
@defvr {Scheme Variable} sddm-service-type
This is the type of the service to run the
-@uref{https://github.com/sddm/sddm,SSDM display manager}. Its value
+@uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
must be a @code{sddm-configuration} record (see below).
Here's an example use:
@deftypevr {@code{files-configuration} parameter} file-name server-keychain
Specifies the location of TLS certificates and private keys. CUPS will
-look for public and private keys in this directory: a @code{.crt} files
-for PEM-encoded certificates and corresponding @code{.key} files for
+look for public and private keys in this directory: @file{.crt} files
+for PEM-encoded certificates and corresponding @file{.key} files for
PEM-encoded private keys.
Defaults to @samp{"/etc/cups/ssl"}.
@deftypevr {@code{cups-configuration} parameter} string classification
Specifies the security classification of the server. Any valid banner
-name can be used, including "classified", "confidential", "secret",
-"topsecret", and "unclassified", or the banner can be omitted to disable
-secure printing functions.
+name can be used, including @samp{"classified"}, @samp{"confidential"},
+@samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
+banner can be omitted to disable secure printing functions.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
Access control directives, as a list of strings. Each string should be
-one directive, such as "Order allow,deny".
+one directive, such as @samp{"Order allow,deny"}.
Defaults to @samp{()}.
@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
Specifies the maximum time a job may take to print before it is
-canceled, in seconds. Set to 0 to disable cancellation of "stuck" jobs.
+canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
Defaults to @samp{10800}.
@end deftypevr
metapackage to the system profile. ``Adding Enlightenment'' means that
@code{dbus} is extended appropriately, and several of Enlightenment's binaries
are set as setuid, allowing Enlightenment's screen locker and other
-functionality to work as expetected.
+functionality to work as expected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
means that all users are allowed.
@end deffn
+@cindex scanner access
+@deffn {Scheme Procedure} sane-service-type
+This service provides access to scanners @i{via}
+@uref{http://www.sane-project.org, SANE} by installing the necessary udev
+rules.
+@end deffn
+
@defvr {Scheme Variable} %standard-geoclue-applications
The standard list of well-known GeoClue application configurations,
granting authority to the GNOME date-and-time utility to ask for the
@item @code{pulseaudio?} (default: @var{#t})
Whether ALSA applications should transparently be made to use the
-@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
+@uref{https://www.pulseaudio.org/, PulseAudio} sound server.
Using PulseAudio allows you to run several sound-producing applications
at the same time and to individual control them @i{via}
See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
details.
+@deffn {Scheme Variable} pulseaudio-service-type
+This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
+sound server. It exists to allow system overrides of the default settings
+via @code{pulseaudio-configuration}, see below.
+
+@quotation Warning
+This service overrides per-user configuration files. If you want
+PulseAudio to honor configuraton files in @file{~/.config/pulse} you
+have to unset the environment variables @env{PULSE_CONFIG} and
+@env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
+@end quotation
+
+@quotation Warning
+This service on its own does not ensure, that the @code{pulseaudio} package
+exists on your machine. It merely adds configuration files for it, as
+detailed below. In the (admittedly unlikely) case, that you find yourself
+without a @code{pulseaudio} package, consider enabling it through the
+@code{alsa-service-type} above.
+@end quotation
+@end deffn
+
+@deftp {Data Type} pulseaudio-configuration
+Data type representing the configuration for @code{pulseaudio-service}.
+
+@table @asis
+@item @var{client-conf} (default: @code{'()})
+List of settings to set in @file{client.conf}.
+Accepts a list of strings or a symbol-value pairs. A string will be
+inserted as-is with a newline added. A pair will be formatted as
+``key = value'', again with a newline added.
+
+@item @var{daemon-conf} (default: @code{'((flat-volumes . no))})
+List of settings to set in @file{daemon.conf}, formatted just like
+@var{client-conf}.
+
+@item @var{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
+Script file to use as as @file{default.pa}.
+
+@item @var{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
+Script file to use as as @file{system.pa}.
+@end table
+@end deftp
+
+@deffn {Scheme Variable} ladspa-service-type
+This service sets the @var{LADSPA_PATH} variable, so that programs, which
+respect it, e.g. PulseAudio, can load LADSPA plugins.
+
+The following example will setup the service to enable modules from the
+@code{swh-plugins} package:
+
+@lisp
+(service ladspa-service-type
+ (ladspa-configuration (plugins (list swh-plugins))))
+@end lisp
+
+See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
+details.
+
+@end deffn
@node Database Services
@subsection Database Services
Dovecot the full location.
If you're using mbox, giving a path to the INBOX
-file (e.g.@: /var/mail/%u) isn't enough. You'll also need to tell Dovecot
-where the other mailboxes are kept. This is called the "root mail
-directory", and it must be the first path given in the
+file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
+where the other mailboxes are kept. This is called the @emph{root mail
+directory}, and it must be the first path given in the
@samp{mail-location} setting.
-There are a few special variables you can use, eg.:
+There are a few special variables you can use, e.g.:
@table @samp
@item %u
@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
Group to enable temporarily for privileged operations. Currently
this is used only with INBOX when either its initial creation or
-dotlocking fails. Typically this is set to "mail" to give access to
-/var/mail.
+dotlocking fails. Typically this is set to @samp{"mail"} to give access to
+@file{/var/mail}.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
Grant access to these supplementary groups for mail processes.
Typically these are used to set up access to shared mailboxes. Note
-that it may be dangerous to set these if users can create
-symlinks (e.g.@: if "mail" group is set here, ln -s /var/mail ~/mail/var
-could allow a user to delete others' mailboxes, or ln -s
-/secret/shared/box ~/mail/mybox would allow reading it).
-Defaults to @samp{""}.
+that it may be dangerous to set these if users can create symlinks
+(e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
+could allow a user to delete others' mailboxes, or @code{ln -s
+/secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
+@samp{""}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
Allow full file system access to clients. There's no access checks
other than what the operating system does for the active UID/GID. It
works with both maildir and mboxes, allowing you to prefix mailboxes
-names with e.g.@: /path/ or ~user/.
+names with e.g.@: @file{/path/} or @file{~user/}.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
-Don't use mmap() at all. This is required if you store indexes to
+Don't use @code{mmap()} at all. This is required if you store indexes to
shared file systems (NFS or clustered file system).
Defaults to @samp{#f}.
@end deftypevr
@item optimized
Whenever necessary to avoid losing important data
@item always
-Useful with e.g.@: NFS when write()s are delayed
+Useful with e.g.@: NFS when @code{write()}s are delayed
@item never
Never use it (best performance, but crashes can lose data).
@end table
@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
List of directories under which chrooting is allowed for mail
-processes (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar
+processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
too). This setting doesn't affect @samp{login-chroot}
@samp{mail-chroot} or auth chroot settings. If this setting is empty,
-"/./" in home dirs are ignored. WARNING: Never add directories here
+@samp{/./} in home dirs are ignored. WARNING: Never add directories here
which local users can modify, that may lead to root exploit. Usually
this should be done only if you don't allow shell access for users.
<doc/wiki/Chrooting.txt>.
@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
Default chroot directory for mail processes. This can be overridden
-for specific users in user database by giving /./ in user's home
-directory (e.g.@: /home/./user chroots into /home). Note that usually
+for specific users in user database by giving @samp{/./} in user's home
+directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
there is no real need to do chrooting, Dovecot doesn't allow users to
access files outside their mail directory anyway. If your home
-directories are prefixed with the chroot directory, append "/."@: to
+directories are prefixed with the chroot directory, append @samp{/.} to
@samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
Defaults to @samp{""}.
@end deftypevr
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string server
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string username
-Space separated list of arguments to the userdb driver.
+Username to login to the mail server with.
Defaults to @samp{unset}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
-Space separated list of arguments to the userdb driver.
+Port number to connect to.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
-PEM-formatted key file to use for the TLS negotiation
+PEM-formatted key file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
-PEM-formatted certificate file to use for the TLS negotiation
+PEM-formatted certificate file to use for the TLS negotiation.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
-CA certificates to use
+CA certificates to use.
Defaults to @samp{""}.
@end deftypevr
@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
-Extra retriever parameters
+Extra retriever parameters.
Defaults to @samp{()}.
If true, getmail will record a log of its actions using the system
logger.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
the reason for not retrieving them, as well as starting and ending
information lines.
-Defaults to @samp{#t}.
+Defaults to @samp{#f}.
@end deftypevr
@lisp
(service prosody-service-type
(prosody-configuration
- (modules-enabled (cons "groups" "mam" %default-modules-enabled))
+ (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
(int-components
(list
(int-component-configuration
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
-A list of "extra" verification options.
+A list of ``extra'' verification options.
@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string password
@samp{"john.smith@@example.com"} then you need to add a host
@samp{"example.com"}. All options in this list will apply only to this host.
-Note: the name "virtual" host is used in configuration to avoid confusion with
+Note: the name @emph{virtual} host is used in configuration to avoid confusion with
the actual physical host that Prosody is installed on. A single Prosody
instance can serve many domains, each one defined as a VirtualHost entry in
Prosody's configuration. Conversely a server that hosts a single domain would
hosted chatrooms/conferences for XMPP users.
General information on setting up and using multi-user chatrooms can be found
-in the "Chatrooms" documentation (@url{https://prosody.im/doc/chatrooms}),
+in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
which you should read if you are new to XMPP chatrooms.
See also @url{https://prosody.im/doc/modules/mod_muc}.
@deftypevr {@code{nslcd-configuration} parameter} log-option log
This option controls the way logging is done via a list containing
-SCHEME and LEVEL. The SCHEME argument may either be the symbols "none"
-or "syslog", or an absolute file name. The LEVEL argument is optional
-and specifies the log level. The log level may be one of the following
-symbols: "crit", "error", "warning", "notice", "info" or "debug". All
-messages with the specified log level or higher are logged.
+SCHEME and LEVEL. The SCHEME argument may either be the symbols
+@samp{none} or @samp{syslog}, or an absolute file name. The LEVEL
+argument is optional and specifies the log level. The log level may be
+one of the following symbols: @samp{crit}, @samp{error}, @samp{warning},
+@samp{notice}, @samp{info} or @samp{debug}. All messages with the
+specified log level or higher are logged.
Defaults to @samp{("/var/log/nslcd" info)}.
request scheme, hostname and port that the server uses to identify
itself.
-This doesn't need to be set in the server config, and can be specifyed
+This doesn't need to be set in the server config, and can be specified
in virtual hosts. The default is @code{#f} to not specify a
@code{ServerName}.
/etc/nginx/modules/ngx_http_accept_language_module.so")))
@end lisp
+@item @code{global-directives} (default: @code{'((events . ()))})
+Association list of global directives for the top level of the nginx
+configuration. Values may themselves be association lists.
+
+@lisp
+(global-directives
+ `((worker_processes . 16)
+ (pcre_jit . on)
+ (events . ((worker_connections . 1024)))))
+@end lisp
+
@item @code{extra-content} (default: @code{""})
Extra content for the @code{http} block. Should be string or a string
valued G-expression.
VCL syntax.
@c Varnish does not support HTTPS, so keep this URL to avoid confusion.
-For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you
+For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
can do something along these lines:
@lisp
@end table
@end deftp
+@subsubheading Mumi
+
+@cindex Mumi, Debbugs Web interface
+@cindex Debbugs, Mumi Web interface
+@uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
+Web interface to the Debbugs bug tracker, by default for
+@uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server,
+but it also fetches and indexes mail retrieved from Debbugs.
+
+@defvr {Scheme Variable} mumi-service-type
+This is the service type for Mumi.
+@end defvr
+
+@deftp {Data Type} mumi-configuration
+Data type representing the Mumi service configuration. This type has the
+following fields:
+
+@table @asis
+@item @code{mumi} (default: @code{mumi})
+The Mumi package to use.
+
+@item @code{mailer?} (default: @code{#true})
+Whether to enable or disable the mailer component.
+
+@item @code{mumi-configuration-sender}
+The email address used as the sender for comments.
+
+@item @code{mumi-configuration-smtp}
+A URI to configure the SMTP settings for Mailutils. This could be
+something like @code{sendmail:///path/to/bin/msmtp} or any other URI
+supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
+mailutils, GNU@tie{}Mailutils}.
+
+@end table
+@end deftp
+
+
@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
@end deftp
-@deffn {Scheme Procedure} nginx-php-fpm-location @
+@deffn {Scheme Procedure} nginx-php-location @
[#:nginx-package nginx] @
[socket (string-append "/var/run/php" @
(version-major (package-version php)) @
Mandatory email used for registration, recovery contact, and important
account notifications.
+@item @code{server} (default: @code{#f})
+Optional URL of ACME server. Setting this overrides certbot's default,
+which is the Let's Encrypt server.
+
@item @code{rsa-key-size} (default: @code{2048})
Size of the RSA key.
@end deftp
@deftp {Data Type} zone-entry
-Data type represnting a record entry in a zone file.
+Data type representing a record entry in a zone file.
This type has the following parameters:
@table @asis
@item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
The configuration string of the backend. An example for the PKCS#11 is:
@code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
-For the pem backend, the string reprensents a path in the file system.
+For the pem backend, the string represents a path in the file system.
@end table
@end deftp
@item @code{servers} (default: @code{'()})
Specify IP address of upstream servers directly.
+@item @code{addresses} (default: @code{'()})
+For each entry, specify an IP address to return for any host in the
+given domains. Queries in the domains are never forwarded and always
+replied to with the specified IP address.
+
+This is useful for redirecting hosts locally, for example:
+
+@lisp
+(service dnsmasq-service-type
+ (dnsmasq-configuration
+ (addresses
+ '(; Redirect to a local web-server.
+ "/example.org/127.0.0.1"
+ ; Redirect subdomain to a specific IP.
+ "/subdomain.example.org/192.168.1.42"))))
+@end lisp
+
+Note that rules in @file{/etc/hosts} take precedence over this.
+
@item @code{cache-size} (default: @code{150})
Set the size of dnsmasq's cache. Setting the cache size to zero
disables caching.
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
Verbosity level.
@end deftypevr
+@deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
+Authenticate with server using username/password. The option is a file
+containing username/password on 2 lines. Do not use a file-like object as it
+would be added to the store and readable by any user.
+
+Defaults to @samp{'disabled}.
+@end deftypevr
+
@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
Whether to check the server certificate has server usage extension.
@end deftypevr
+@deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
+(Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
+poll/epoll/select prior to the write operation.
+
+Defaults to @samp{#f}.
+@end deftypevr
+
@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
Verbosity level.
which are most commonly used in relation to mounting or exporting
directory trees as @dfn{network file systems} (NFS).
+While it is possible to use the individual components that together make
+up a Network File System service, we recommended to configure an NFS
+server with the @code{nfs-service-type}.
+
+@subsubheading NFS Service
+@cindex NFS, server
+
+The NFS service takes care of setting up all NFS component services,
+kernel configuration file systems, and installs configuration files in
+the locations that NFS expects.
+
+@defvr {Scheme Variable} nfs-service-type
+A service type for a complete NFS server.
+@end defvr
+
+@deftp {Data Type} nfs-configuration
+This data type represents the configuration of the NFS service and all
+of its subsystems.
+
+It has the following parameters:
+@table @asis
+@item @code{nfs-utils} (default: @code{nfs-utils})
+The nfs-utils package to use.
+
+@item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
+If a list of string values is provided, the @command{rpc.nfsd} daemon
+will be limited to supporting the given versions of the NFS protocol.
+
+@item @code{exports} (default: @code{'()})
+This is a list of directories the NFS server should export. Each entry
+is a list consisting of two elements: a directory name and a string
+containing all options. This is an example in which the directory
+@file{/export} is served to all NFS clients as a read-only share:
+
+@lisp
+(nfs-configuration
+ (exports
+ '(("/export"
+ "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
+@end lisp
+
+@item @code{rpcmountd-port} (default: @code{#f})
+The network port that the @command{rpc.mountd} daemon should use.
+
+@item @code{rpcstatd-port} (default: @code{#f})
+The network port that the @command{rpc.statd} daemon should use.
+
+@item @code{rpcbind} (default: @code{rpcbind})
+The rpcbind package to use.
+
+@item @code{idmap-domain} (default: @code{"localdomain"})
+The local NFSv4 domain name.
+
+@item @code{nfsd-port} (default: @code{2049})
+The network port that the @command{nfsd} daemon should use.
+
+@item @code{nfsd-threads} (default: @code{8})
+The number of threads used by the @command{nfsd} daemon.
+
+@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
+The directory where the pipefs file system is mounted.
+
+@item @code{debug} (default: @code{'()"})
+A list of subsystems for which debugging output should be enabled. This
+is a list of symbols. Any of these symbols are valid: @code{nfsd},
+@code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
+@end table
+@end deftp
+
+If you don't need a complete NFS service or prefer to build it yourself
+you can use the individual component services that are documented below.
+
@subsubheading RPC Bind Service
@cindex rpcbind
This must be a string or @code{#f}.
If it is @code{#f} then the daemon will use the host's fully qualified domain name.
+@item @code{verbosity} (default: @code{0})
+The verbosity level of the daemon.
+
@end table
@end deftp
configuration. Here is an example of a service that polls the Guix repository
and builds the packages from a manifest. Some of the packages are defined in
the @code{"custom-packages"} input, which is the equivalent of
-@code{GUIX_PACKAGE_PATH}.
+@env{GUIX_PACKAGE_PATH}.
@lisp
(define %cuirass-specs
When substituting a pre-built binary fails, fall back to building
packages locally.
+@item @code{extra-options} (default: @code{'()})
+Extra options to pass when running the Cuirass processes.
+
@item @code{cuirass} (default: @code{cuirass})
The Cuirass package to use.
@end table
@deftypevr {@code{libvirt-configuration} parameter} string tls-priority
Override the compile time default TLS priority string. The default is
-usually "NORMAL" unless overridden at build time. Only set this is it
+usually @samp{"NORMAL"} unless overridden at build time. Only set this is it
is desired for libvirt to deviate from the global default settings.
Defaults to @samp{"NORMAL"}.
where @code{name} is a string which is matched against the category
given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
-file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
-be a substring of the full category name, in order to match multiple
-similar categories), the optional "+" prefix tells libvirt to log stack
-trace for each message matching name, and @code{x} is the minimal level
-where matching messages should be logged:
+file, e.g., @samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"} (the
+name in the filter can be a substring of the full category name, in
+order to match multiple similar categories), the optional @samp{"+"}
+prefix tells libvirt to log stack trace for each message matching name,
+and @code{x} is the minimal level where matching messages should be
+logged:
@itemize @bullet
@item
@item @code{guix-support?} (default: @code{#f})
When it is true, QEMU and all its dependencies are added to the build
environment of @command{guix-daemon} (@pxref{Invoking guix-daemon,
-@code{--chroot-directory} option}). This allows the @code{binfmt_misc}
+@option{--chroot-directory} option}). This allows the @code{binfmt_misc}
handlers to be used within the build environment, which in turn means
that you can transparently build programs for another architecture.
The optional @var{config} argument should be a
@code{<git-daemon-configuration>} object, by default it allows read-only
access to exported@footnote{By creating the magic file
-"git-daemon-export-ok" in the repository directory.} repositories under
+@file{git-daemon-export-ok} in the repository directory.} repositories under
@file{/srv/git}.
@end deffn
over HTTP.
@deftp {Data Type} git-http-configuration
-Data type representing the configuration for @code{git-http-service}.
+Data type representing the configuration for a future
+@code{git-http-service-type}; can currently be used to configure Nginx
+trough @code{git-http-nginx-location-configuration}.
@table @asis
@item @code{package} (default: @var{git})
@deftypevr {@code{cgit-configuration} parameter} string root-readme
The content of the file specified with this option will be included
-verbatim below thef "about" link on the repository index page.
+verbatim below the ``about'' link on the repository index page.
Defaults to @samp{""}.
If set to @samp{#t} and repository-directory is enabled,
repository-directory will recurse into directories whose name starts
with a period. Otherwise, repository-directory will stay away from such
-directories, considered as "hidden". Note that this does not apply to
-the ".git" directory in non-bare repos.
+directories, considered as ``hidden''. Note that this does not apply to
+the @file{.git} directory in non-bare repos.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{cgit-configuration} parameter} integer summary-branches
-Specifies the number of branches to display in the repository "summary"
+Specifies the number of branches to display in the repository ``summary''
view.
Defaults to @samp{10}.
@deftypevr {@code{cgit-configuration} parameter} integer summary-log
Specifies the number of log entries to display in the repository
-"summary" view.
+``summary'' view.
Defaults to @samp{10}.
@end deftypevr
@deftypevr {@code{cgit-configuration} parameter} integer summary-tags
-Specifies the number of tags to display in the repository "summary"
+Specifies the number of tags to display in the repository ``summary''
view.
Defaults to @samp{10}.
@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
The name of the default branch for this repository. If no such branch
exists in the repository, the first branch name (when sorted) is used as
-default instead. By default branch pointed to by HEAD, or "master" if
+default instead. By default branch pointed to by HEAD, or ``master'' if
there is no suitable HEAD.
Defaults to @samp{""}.
@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
A path (relative to repo) which specifies a file to include verbatim as
-the "About" page for this repo.
+the ``About'' page for this repo.
Defaults to @samp{""}.
like cgit or gitweb.
@item @code{git-config-keys} (default: @code{""})
-Gitolite allows you to set git config values using the "config" keyword. This
+Gitolite allows you to set git config values using the @samp{config} keyword. This
setting allows control over the config keys to accept.
@item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
Some @code{volume} elements must be added to automatically mount volumes
at login. Here's an example allowing the user @code{alice} to mount her
-encrypted @code{HOME} directory and allowing the user @code{bob} to mount
+encrypted @env{HOME} directory and allowing the user @code{bob} to mount
the partition where he stores his data:
@lisp
which to configure getmail to fetch mail from the guix-commits mailing
list.
+@item @code{extra-options} (default: @var{'()})
+Extra command line options for @code{guix-data-service}.
+
+@item @code{extra-process-jobs-options} (default: @var{'()})
+Extra command line options for @code{guix-data-service-process-jobs}.
+
+@end table
+@end deftp
+
+@node Linux Services
+@subsection Linux Services
+
+@cindex oom
+@cindex out of memory killer
+@cindex earlyoom
+@cindex early out of memory daemon
+@subsubheading Early OOM Service
+
+@uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
+Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
+space and provides a more responsive and configurable alternative to the
+in-kernel OOM killer. It is useful to prevent the system from becoming
+unresponsive when it runs out of memory.
+
+@deffn {Scheme Variable} earlyoom-service-type
+The service type for running @command{earlyoom}, the Early OOM daemon.
+Its value must be a @code{earlyoom-configuration} object, described
+below. The service can be instantiated in its default configuration
+with:
+
+@lisp
+(service earlyoom-service-type)
+@end lisp
+@end deffn
+
+@deftp {Data Type} earlyoom-configuration
+This is the configuration record for the @code{earlyoom-service-type}.
+
+@table @asis
+@item @code{earlyoom} (default: @var{earlyoom})
+The Earlyoom package to use.
+
+@item @code{minimum-available-memory} (default: @code{10})
+The threshold for the minimum @emph{available} memory, in percentages.
+
+@item @code{minimum-free-swap} (default: @code{10})
+The threshold for the minimum free swap memory, in percentages.
+
+@item @code{prefer-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should be preferably killed.
+
+@item @code{avoid-regexp} (default: @code{#f})
+A regular expression (as a string) to match the names of the processes
+that should @emph{not} be killed.
+
+@item @code{memory-report-interval} (default: @code{0})
+The interval in seconds at which a memory report is printed. It is
+disabled by default.
+
+@item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
+A boolean indicating whether the positive adjustments set in
+@file{/proc/*/oom_score_adj}.
+
+@item @code{show-debug-messages?} (default: @code{#f})
+A boolean indicating whether debug messages should be printed. The logs
+are saved at @file{/var/log/earlyoom.log}.
+
+@item @code{send-notification-command} (default: @code{#f})
+This can be used to provide a custom command used for sending
+notifications.
@end table
@end deftp
+@cindex modprobe
+@cindex kernel module loader
+@subsubheading Kernel Module Loader Service
+
+The kernel module loader service allows one to load loadable kernel
+modules at boot. This is especially useful for modules that don't
+autoload and need to be manually loaded, as it's the case with
+@code{ddcci}.
+
+@deffn {Scheme Variable} kernel-module-loader-service-type
+The service type for loading loadable kernel modules at boot with
+@command{modprobe}. Its value must be a list of strings representing
+module names. For example loading the drivers provided by
+@code{ddcci-driver-linux}, in debugging mode by passing some module
+parameters, can be done as follow:
+
+@lisp
+(use-modules (gnu) (gnu services))
+(use-package-modules linux)
+(use-service-modules linux)
+
+(define ddcci-config
+ (plain-file "ddcci.conf"
+ "options ddcci dyndbg delay=120"))
+
+(operating-system
+ ...
+ (services (cons* (service kernel-module-loader-service-type
+ '("ddcci" "ddcci_backlight"))
+ (simple-service 'ddcci-config etc-service-type
+ (list `("modprobe.d/ddcci.conf"
+ ,ddcci-config)))
+ %base-services))
+ (kernel-loadable-modules (list ddcci-driver-linux)))
+@end lisp
+@end deffn
@node Miscellaneous Services
@subsection Miscellaneous Services
@end table
@end deftp
-@subsection Dictionary Services
+@subsubheading Dictionary Service
@cindex dictionary
The @code{(gnu services dict)} module provides the following service:
+@defvr {Scheme Variable} dicod-service-type
+This is the type of the service that runs the @command{dicod} daemon, an
+implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
+@end defvr
+
@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
Return a service that runs the @command{dicod} daemon, an implementation
of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
The optional @var{config} argument specifies the configuration for
@command{dicod}, which should be a @code{<dicod-configuration>} object, by
-default it serves the GNU Collaborative International Dictonary of English.
+default it serves the GNU Collaborative International Dictionary of English.
You can add @command{open localhost} to your @file{~/.dico} file to make
@code{localhost} the default server for @command{dico} client
can also install their own certificate package in
their profile. A number of environment variables need to be defined so
that applications and libraries know where to find them. Namely, the
-OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
+OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
variables. Some applications add their own environment variables; for
instance, the Git version control system honors the certificate bundle
-pointed to by the @code{GIT_SSL_CAINFO} environment variable. Thus, you
+pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
would typically run something like:
@example
-$ 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"
+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"
@end example
-As another example, R requires the @code{CURL_CA_BUNDLE} environment
+As another example, R requires the @env{CURL_CA_BUNDLE} environment
variable to point to a certificate bundle, so you would have to run
something like this:
@example
-$ guix install nss-certs
-$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
+guix install nss-certs
+export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
@end example
For other applications you may want to look up the required environment
@cindex nss-mdns
@cindex .local, host name lookup
As an example, the declaration below configures the NSS to use the
-@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
+@uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
back-end}, which supports host name lookups over multicast DNS (mDNS)
for host names ending in @code{.local}:
initialization system.
@item --root=@var{root}
-Mount @var{root} as the root file system. @var{root} can be a
-device name like @code{/dev/sda1}, a file system label, or a file system
-UUID.
+Mount @var{root} as the root file system. @var{root} can be a device
+name like @code{/dev/sda1}, a file system label, or a file system UUID.
+When unspecified, the device name from the root file system of the
+operating system declaration is used.
@item --system=@var{system}
Have @file{/run/booted-system} and @file{/run/current-system} point to
[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
Return a derivation that builds a raw initrd. @var{file-systems} is
a list of file systems to be mounted by the initrd, possibly in addition to
-the root file system specified on the kernel command line via @code{--root}.
+the root file system specified on the kernel command line via @option{--root}.
@var{linux-modules} is a list of kernel modules to be loaded at boot time.
@var{mapped-devices} is a list of device mappings to realize before
@var{file-systems} are mounted (@pxref{Mapped Devices}).
Return as a file-like object a generic initrd, with kernel
modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
mounted by the initrd, possibly in addition to the root file system specified
-on the kernel command line via @code{--root}. @var{mapped-devices} is a list of device
+on the kernel command line via @option{--root}. @var{mapped-devices} is a list of device
mappings to realize before @var{file-systems} are mounted.
When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
program to run in that initrd.
@deffn {Scheme Procedure} expression->initrd @var{exp} @
- [#:guile %guile-static-stripped] [#:name "guile-initrd"]
+ [#:guile %guile-3.0-static-stripped] [#:name "guile-initrd"]
Return as a file-like object a Linux initrd (a gzipped cpio archive)
containing @var{guile} and that evaluates @var{exp}, a G-expression,
upon booting. All the derivations referenced by @var{exp} are
@end table
@end deftp
+@cindex HDPI
+@cindex HiDPI
+@cindex resolution
@c FIXME: Write documentation once it's stable.
-For now only GRUB has theme support. GRUB themes are created using
-the @code{grub-theme} form, which is not documented yet.
+For now only GRUB has theme support. GRUB themes are created using
+the @code{grub-theme} form, which is not fully documented yet.
-@defvr {Scheme Variable} %default-theme
-This is the default GRUB theme used by the operating system if no
+@deftp {Data Type} grub-theme
+Data type representing the configuration of the GRUB theme.
+
+@table @asis
+@item @code{gfxmode} (default: @code{'("auto")})
+The GRUB @code{gfxmode} to set (a list of screen resolution strings, see
+@pxref{gfxmode,,, grub, GNU GRUB manual}).
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} grub-theme
+Return the default GRUB theme used by the operating system if no
@code{theme} field is specified in @code{bootloader-configuration}
record.
It comes with a fancy background image displaying the GNU and Guix
logos.
-@end defvr
+@end deffn
+For example, to override the default resolution, you may use something
+like
+
+@lisp
+(bootloader
+ (bootloader-configuration
+ ;; @dots{}
+ (theme (grub-theme
+ (inherit (grub-theme))
+ (gfxmode '("1024x786x32" "auto"))))))
+@end lisp
@node Invoking guix system
@section Invoking @code{guix system}
Display available service type definitions that match the given regular
expressions, sorted by relevance:
+@cindex HDPI
+@cindex HiDPI
+@cindex resolution
@example
-$ guix system search console font
+$ guix system search console
name: console-fonts
-location: gnu/services/base.scm:729:2
+location: gnu/services/base.scm:806:2
extends: shepherd-root
-description: Install the given fonts on the specified ttys (fonts are
-+ per virtual console on GNU/Linux). The value of this service is a list
-+ of tty/font pairs like:
-+
-+ '(("tty1" . "LatGrkCyr-8x16"))
-relevance: 20
+description: Install the given fonts on the specified ttys (fonts are per
++ virtual console on GNU/Linux). The value of this service is a list of
++ tty/font pairs. The font can be the name of a font provided by the `kbd'
++ package or any valid argument to `setfont', as in this example:
++
++ '(("tty1" . "LatGrkCyr-8x16")
++ ("tty2" . (file-append
++ font-tamzen
++ "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
++ ("tty3" . (file-append
++ font-terminus
++ "/share/consolefonts/ter-132n"))) ; for HDPI
+relevance: 9
name: mingetty
-location: gnu/services/base.scm:1048:2
+location: gnu/services/base.scm:1190:2
extends: shepherd-root
description: Provide console login using the `mingetty' program.
relevance: 2
name: login
-location: gnu/services/base.scm:775:2
+location: gnu/services/base.scm:860:2
extends: pam
description: Provide a console log-in service as specified by its
+ configuration value, a `login-configuration' object.
switches the system profile to the specified system generation. It
also rearranges the system's existing bootloader menu entries. It
makes the menu entry for the specified system generation the default,
-and it moves the entries for the other generatiors to a submenu, if
+and it moves the entries for the other generations to a submenu, if
supported by the bootloader being used. The next time the system
boots, it will use the specified system generation.
(@pxref{Invoking guix gc}, for information on how to run the ``garbage
collector'').
-This works in the same way as @command{guix package --delete-generations}
-(@pxref{Invoking guix package, @code{--delete-generations}}). With no
+This works in the same way as @samp{guix package --delete-generations}
+(@pxref{Invoking guix package, @option{--delete-generations}}). With no
arguments, all system generations but the current one are deleted:
@example
The VM shares its store with the host system.
Additional file systems can be shared between the host and the VM using
-the @code{--share} and @code{--expose} command-line options: the former
+the @option{--share} and @option{--expose} command-line options: the former
specifies a directory to be shared with write access, while the latter
provides read-only access to the shared directory.
the advantage of requiring only a very tiny root disk image since the
store of the host can then be mounted.
-The @code{--full-boot} option forces a complete boot sequence, starting
+The @option{--full-boot} option forces a complete boot sequence, starting
with the bootloader. This requires more disk space since a root image
containing at least the kernel, initrd, and bootloader data files must
-be created. The @code{--image-size} option can be used to specify the
+be created. The @option{--image-size} option can be used to specify the
size of the image.
@cindex System images, creation in various formats
container, you may need to pass the @option{--privileged} option to
@code{docker create}.
+Last, the @option{--network} option applies to @command{guix system
+docker-image}: it produces an image where network is supposedly shared
+with the host, and thus without services like nscd or NetworkManager.
+
@item container
Return a script to run the operating system declared in @var{file}
within a container. Containers are a set of lightweight isolation
@cindex ISO-9660 format
@cindex CD image format
@cindex DVD image format
-@code{--file-system-type=iso9660} produces an ISO-9660 image, suitable
+@option{--file-system-type=iso9660} produces an ISO-9660 image, suitable
for burning on CDs and DVDs.
@item --image-size=@var{size}
The command:
@example
-$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf
+$ guix system extension-graph @var{file} | xdot -
@end example
-produces a PDF file showing the extension relations among services.
+shows the extension relations among services.
@anchor{system-shepherd-graph}
@item shepherd-graph
The file should evaluate to a list of @var{machine} objects. This example,
upon being deployed, will create a new generation on the remote system
-realizing the @code{operating-system} declaration @var{%system}.
-@var{environment} and @var{configuration} specify how the machine should be
+realizing the @code{operating-system} declaration @code{%system}.
+@code{environment} and @code{configuration} specify how the machine should be
provisioned---that is, how the computing resources should be created and
managed. The above example does not create any resources, as a
@code{'managed-host} is a machine that is already running the Guix system and
@command{guix deploy} can log in as an unprivileged user and employ
@code{sudo} to escalate privileges. This will only work if @code{sudo} is
currently installed on the remote and can be invoked non-interactively as
-@code{user}. That is: the line in @code{sudoers} granting @code{user} the
-ability to use @code{sudo} must contain the @code{NOPASSWD} tag.
+@code{user}. That is, the line in @code{sudoers} granting @code{user} the
+ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
+be accomplished with the following operating system configuration snippet:
+
+@lisp
+(use-modules ...
+ (gnu system)) ;for %sudoers-specification
+
+(define %user "username")
+
+(operating-system
+ ...
+ (sudoers-file
+ (plain-file "sudoers"
+ (string-append (plain-file-content %sudoers-specification)
+ (format #f "~a ALL = NOPASSWD: ALL~%"
+ %user)))))
+
+@end lisp
+
+For more information regarding the format of the @file{sudoers} file,
+consult @command{man sudoers}.
@deftp {Data Type} machine
This is the data type representing a single machine in a heterogeneous Guix
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}).
+as @file{/run/current-system/configuration.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
name=com.redhat.spice.0
@end example
-You'll also need to add the @pxref{Miscellaneous Services, Spice service}.
+You'll also need to add the @code{(spice-vdagent-service)} to your
+system definition (@pxref{Miscellaneous Services, Spice service}).
@node Defining Services
@section Defining Services
@end example
From there on, GDB will pick up debugging information from the
-@code{.debug} files under @file{~/.guix-profile/lib/debug}.
+@file{.debug} files under @file{~/.guix-profile/lib/debug}.
In addition, you will most likely want GDB to be able to show the source
code being debugged. To do that, you will have to unpack the source
@dfn{bootstrap binaries}.
These bootstrap binaries are ``taken for granted'', though we can also
-re-create them if needed (more on that later).
-
-For @code{i686-linux} and @code{x86_64-linux} the Guix bootstrap process is
-more elaborate, @pxref{Reduced Binary Seed Bootstrap}.
+re-create them if needed (@pxref{Preparing to Use the Bootstrap
+Binaries}).
@menu
* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
``taken for granted.''
-Taking these binaries for granted means that we consider them to be a correct
-and trustworthy `seed' for building the complete system. Therein lies a
-problem: the current combined size of these bootstrap binaries is about 250MB
-(@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing or even inspecting
-these is next to impossible.
+Taking the bootstrap binaries for granted means that we consider them to
+be a correct and trustworthy ``seed'' for building the complete system.
+Therein lies a problem: the combined size of these bootstrap binaries is
+about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing
+or even inspecting these is next to impossible.
-For @code{i686-linux} and @code{x86_64-linux}, Guix now features a ``Reduced
-Binary Seed'' bootstrap @footnote{We would like to say: ``Full Source
-Bootstrap'' and while we are working towards that goal it would be hyperbole
-to use that term for what we do now.}.
+For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
+``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
+Source Bootstrap'' and while we are working towards that goal it would
+be hyperbole to use that term for what we do now.}.
The Reduced Binary Seed bootstrap removes the most critical tools---from a
trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
-written in Scheme and the Mes C Library, built for TinyCC and for GCC). Using
-these new binary seeds and a new set of
-@c
-packages@footnote{@c
-nyacc-boot,
-mes-boot,
-tcc-boot0,
-tcc-boot,
-make-mesboot0,
-diffutils-mesboot,
-binutils-mesboot0,
-gcc-core-mesboot,
-mesboot-headers,
-glibc-mesboot0,
-gcc-mesboot0,
-binutils-mesboot,
-make-mesboot,
-gcc-mesboot1,
-gcc-mesboot1-wrapper,
-glibc-headers-mesboot,
-glibc-mesboot,
-gcc-mesboot,
-and
-gcc-mesboot-wrapper.
-}
-@c
-the ``missing'' Binutils, GCC, and the GNU C Library are built from source.
-From here on the more traditional bootstrap process resumes. This approach
-has reduced the bootstrap binaries in size to about 130MB. Work is ongoing to
-reduce this further. If you are interested, join us on @code{#bootstrappable}
-on the Freenode IRC network.
-
-@c ./pre-inst-env guix graph --type=bag -e '(begin (use-modules (guix packages)) (%current-system "i686-linux") (@@ (gnu packages commencement) gcc-mesboot))' > doc/images/gcc-mesboot-bag-graph.dot
-@c dot -T png doc/images/gcc-mesboot-bag-graph.dot > doc/images/gcc-mesboot-bag-graph.png
-
-Below is the generated dependency graph for @code{gcc-mesboot}, the bootstrap
-compiler used to build the rest of GuixSD.
-
-@image{images/gcc-mesboot-bag-graph,6in,,Dependency graph of the gcc-mesboot}
+written in Scheme and the Mes C Library, built for TinyCC and for GCC).
+
+Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
+C Library are built from source. From here on the more traditional
+bootstrap process resumes. This approach has reduced the bootstrap
+binaries in size to about 145MB in Guix v1.1.
+
+The next step that Guix has taken is to replace the shell and all its
+utilities with implementations in Guile Scheme, the @emph{Scheme-only
+bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a
+POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
+which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
+Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
+removed are now built from source.
+
+Building the GNU System from source is currently only possibly by adding
+some historical GNU packages as intermediate steps@footnote{Packages
+such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
+@code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
+@file{gnu/packages/commencement.scm}.}. As Gash and Gash Utils mature,
+and GNU packages become more bootstrappable again (e.g., new releases of
+GNU Sed will also ship as gzipped tarballs again, as alternative to the
+hard to bootstrap @code{xz}-compression), this set of added packages can
+hopefully be reduced again.
+
+The graph below shows the resulting dependency graph for
+@code{gcc-core-mesboot0}, the bootstrap compiler used for the
+traditional bootstrap of the rest of the Guix System.
+
+@c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot
+@image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
+
+The only significant binary bootstrap seeds that remain@footnote{
+Ignoring the 68KB @code{mescc-tools}; that will be removed later,
+together with @code{mes}.} are a Scheme intepreter and a Scheme
+compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
+static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
+to get Guile running.}.
+
+This further reduction has brought down the size of the binary seed to
+about 60MB for @code{i686-linux} and @code{x86_64-linux}.
+
+Work is ongoing to remove all binary blobs from our free software
+bootstrap stack, working towards a Full Source Bootstrap. Also ongoing
+is work to bring these bootstraps to the @code{arm-linux} and
+@code{aarch64-linux} architectures and to the Hurd.
+
+If you are interested, join us on @samp{#bootstrappable} on the Freenode
+IRC network or discuss on @email{bug-mes@@gnu.org} or
+@email{gash-devel@@nongnu.org}.
@node Preparing to Use the Bootstrap Binaries
@section Preparing to Use the Bootstrap Binaries
| dot -Tps > gcc.ps
@end example
-or, for the Reduced Binary Seed bootstrap
+or, for the further Reduced Binary Seed bootstrap
@example
guix graph -t derivation \
Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
Guile that can be used to run subsequent build programs. Its first task
is to download tarballs containing the other pre-built binaries---this
-is what the @code{.tar.xz.drv} derivations do. Guix modules such as
+is what the @file{.tar.xz.drv} derivations do. Guix modules such as
@code{ftp-client.scm} are used for this purpose. The
@code{module-import.drv} derivations import those modules in a directory
in the store, using the original layout. The
@example
guix graph -t bag \
-e '(@@@@ (gnu packages commencement)
- glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps
+ glibc-final-with-bootstrap-bash)' | xdot -
@end example
@noindent
-produces the dependency graph leading to the ``final'' C
+displays the dependency graph leading to the ``final'' C
library@footnote{You may notice the @code{glibc-intermediate} label,
suggesting that it is not @emph{quite} final, but as a good
approximation, we will consider it final.}, depicted below.
built.
Then come the first-stage Binutils and GCC, built as pseudo cross
-tools---i.e., with @code{--target} equal to @code{--host}. They are
+tools---i.e., with @option{--target} equal to @option{--host}. They are
used to build libc. Thanks to this cross-build trick, this libc is
guaranteed not to hold any reference to the initial tool chain.
-From there the final Binutils and GCC (not shown above) are built.
-GCC uses @code{ld}
-from the final Binutils, and links programs against the just-built libc.
-This tool chain is used to build the other packages used by Guix and by
-the GNU Build System: Guile, Bash, Coreutils, etc.
+From there the final Binutils and GCC (not shown above) are built. GCC
+uses @command{ld} from the final Binutils, and links programs against
+the just-built libc. This tool chain is used to build the other
+packages used by Guix and by the GNU Build System: Guile, Bash,
+Coreutils, etc.
And voilà! At this point we have the complete set of build tools that
the GNU Build System expects. These are in the @code{%final-inputs}
where Guix always gives us a source-to-binary mapping. Thus, our goal
is to reduce the set of bootstrap binaries to the bare minimum.
-The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists
+The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
on-going projects to do that. One of these is about replacing the
bootstrap GCC with a sequence of assemblers, interpreters, and compilers
of increasing complexity, which could be built from source starting from
In practice, there may be some complications. First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
above) is not recognized by all the GNU tools. Typically, glibc
-recognizes some of these, whereas GCC uses an extra @code{--with-abi}
+recognizes some of these, whereas GCC uses an extra @option{--with-abi}
configure flag (see @code{gcc.scm} for examples of how to handle this).
Second, some of the required packages could fail to build for that
platform. Lastly, the generated binaries could be broken for some