@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@set KEY-SERVER pool.sks-keyservers.net
+@c Base URL for downloads.
+@set BASE-URL https://ftp.gnu.org/gnu/guix
+
@c The official substitute server used by default.
-@set SUBSTITUTE-SERVER ci.guix.info
+@set SUBSTITUTE-SERVER ci.guix.gnu.org
+@set SUBSTITUTE-URL https://@value{SUBSTITUTE-SERVER}
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
Copyright @copyright{} 2018 Gábor Boskovits@*
-Copyright @copyright{} 2018 Florian Pelz@*
+Copyright @copyright{} 2018, 2019 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
+Copyright @copyright{} 2019 Josh Holland@*
+Copyright @copyright{} 2019 Diego Nicola Barbato@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
-This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
-référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
-zu GNU Guix}). If you would like to translate it in your native language,
-consider joining the
+This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
+GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
+Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
+Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
+Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
+would like to translate it in your native language, consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.
@cindex Guix System
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
+@url{https://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
@example
and Linux-Libre kernel.
@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
+n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
+supported; in particular, the project's build farms no longer provide
+substitutes for this architecture.
@end table
is described in the next sections. The only requirement is to have
GNU@tie{}tar and Xz.
+@c Note duplicated from the ``Installation'' node.
+@quotation Note
+We recommend the use of this
+@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
+shell installer script}. The script automates the download, installation, and
+initial configuration steps described below. It should be run as the root
+user.
+@end quotation
+
Installing goes along these lines:
@enumerate
@item
@cindex downloading Guix binary
Download the binary tarball from
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
+@indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz},
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
authenticity of the tarball against it, along these lines:
@example
-$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
+$ wget @value{BASE-URL}/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
@end example
@c files into place.
@c
@c See this thread for more information:
-@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
+@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
@example
# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
the root profile:
@example
-# guix package -i hello
+# guix install hello
@end example
-The @code{guix} package must remain available in @code{root}'s profile,
-or it would become subject to garbage collection---in which case you
-would find yourself badly handicapped by the lack of the @command{guix}
-command. In other words, do not remove @code{guix} by running
-@code{guix package -r guix}.
-
The binary installation tarball can be (re)produced and verified simply
by running the following command in the Guix source tree:
GNU Guix depends on the following packages:
@itemize
-@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
-@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
+@uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
@item
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
2017 or later;
@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON};
-@item @url{http://zlib.net, zlib};
-@item @url{http://www.gnu.org/software/make/, GNU Make}.
+@item @url{https://zlib.net, zlib};
+@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
following packages are also needed:
@itemize
-@item @url{http://gnupg.org/, GNU libgcrypt};
-@item @url{http://sqlite.org, SQLite 3};
-@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
+@item @url{https://gnupg.org/, GNU libgcrypt};
+@item @url{https://sqlite.org, SQLite 3};
+@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
inadvertently corrupt your store (@pxref{The Store}).
@cindex Nix, compatibility
-When a working installation of @url{http://nixos.org/nix/, the Nix package
+When a working installation of @url{https://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nix replaces the three dependencies above.
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
-@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
+@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
variable:
@example
-$ guix package -i glibc-locales
+$ guix install glibc-locales
$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example
for Chinese languages:
@example
-guix package -i font-adobe-source-han-sans:cn
+guix install font-adobe-source-han-sans:cn
@end example
@cindex @code{xterm}
@node Limitations
@section Limitations
-As of version @value{VERSION}, Guix System is
-not production-ready. It may contain bugs and lack important
-features. Thus, if you are looking for a stable production system that
-respects your freedom as a computer user, a good solution at this point
-is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
-the more established GNU/Linux distributions}. We hope you can soon switch
-to the Guix System without fear, of course. In the meantime, you can
-also keep using your distribution and try out the package manager on top
-of it (@pxref{Installation}).
+We consider Guix System to be ready for a wide range of ``desktop'' and server
+use cases. The reliability guarantees it provides---transactional upgrades
+and rollbacks, reproducibility---make it a solid foundation.
-Before you proceed with the installation, be aware of the following
-noteworthy limitations applicable to version @value{VERSION}:
+Nevertheless, before you proceed with the installation, be aware of the
+following noteworthy limitations applicable to version @value{VERSION}:
@itemize
-@item
-The installation process does not include a graphical user interface and
-requires familiarity with GNU/Linux (see the following subsections to
-get a feel of what that means.)
-
@item
Support for the Logical Volume Manager (LVM) is missing.
More and more system services are provided (@pxref{Services}), but some
may be missing.
-@item
-More than 8,500 packages are available, but you might
-occasionally find that a useful package is missing.
-
@item
GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
-as well as a number of X11 window managers. However, some graphical
-applications may be missing, as well as KDE.
+as well as a number of X11 window managers. However, KDE is currently
+missing.
@end itemize
-You have been warned! But more than a disclaimer, this is an invitation
-to report issues (and success stories!), and to join us in improving it.
-@xref{Contributing}, for more info.
+More than a disclaimer, this is an invitation to report issues (and success
+stories!), and to join us in improving it. @xref{Contributing}, for more
+info.
@node Hardware Considerations
driver, and those using Broadcom/AirForce chips (BCM43xx with
Wireless-Core Revision 5), which corresponds to the @code{b43-open}
Linux-libre driver. Free firmware exists for both and is available
-out-of-the-box on Guix System, as part of @var{%base-firmware}
+out-of-the-box on Guix System, as part of @code{%base-firmware}
(@pxref{operating-system Reference, @code{firmware}}).
@cindex RYF, Respects Your Freedom
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
+@indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz},
where @var{system} is one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
+$ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig
@end example
ip a
@end example
-@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
Wired interfaces have a name starting with @samp{e}; for example, the
interface corresponding to the first on-board Ethernet controller is
called @samp{eno1}. Wireless interfaces have a name starting with
virtual private server (VPS) rather than on your beloved machine, this
section is for you.
-To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a
+To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
disk image, follow these steps:
@enumerate
@section Building the Installation Image for ARM Boards
Many ARM boards require a specific variant of the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
If you build a disk image and the bootloader is not available otherwise
(on another boot drive etc), it's advisable to build an image that
with it):
@example
-guix package -i emacs-guix
+guix install emacs-guix
@end example
@menu
@example
guix package @var{options}
@end example
+
@cindex transactions
Primarily, @var{options} specifies the operations to be performed during
the transaction. Upon completion, a new profile is created, but
guix package -r lua -i guile guile-cairo
@end example
+@cindex aliases, for @command{guix package}
+For your convenience, we also provide the following aliases:
+
+@itemize
+@item
+@command{guix search} is an alias for @command{guix package -s},
+@item
+@command{guix install} is an alias for @command{guix package -i},
+@item
+@command{guix remove} is an alias for @command{guix package -r},
+@item
+and @command{guix upgrade} is an alias for @command{guix package -u}.
+@end itemize
+
+These aliases are less expressive than @command{guix package} and provide
+fewer options, so in some cases you'll probably want to use @command{guix
+package} directly.
+
@command{guix package} also supports a @dfn{declarative approach}
whereby the user specifies the exact set of packages to be available and
passes it @i{via} the @option{--manifest} option
@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
variable, and so on.
@cindex search paths
-If you are not using the Guix System Distribution, consider adding the
+If you are not using Guix System, consider adding the
following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
shells get all the right environment variable definitions:
@dots{}
@end example
-It is also possible to refine search results using several @code{-s}
-flags. For example, the following command returns a list of board
-games:
+It is also possible to refine search results using several @code{-s} flags to
+@command{guix package}, or several arguments to @command{guix search}. For
+example, the following command returns a list of board games (this time using
+the @command{guix search} alias):
@example
-$ guix package -s '\<board\>' -s game | recsel -p name
+$ guix search '\<board\>' game | recsel -p name
name: gnubg
@dots{}
@end example
libraries, and prints the name and synopsis of the matching packages:
@example
-$ guix package -s crypto -s library | \
+$ guix search crypto library | \
recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
@end example
your system has unpatched security vulnerabilities.
Substitutes from the official build farm are enabled by default when
-using the Guix System Distribution (@pxref{GNU Distribution}). However,
+using Guix System (@pxref{GNU Distribution}). However,
they are disabled by default when using Guix on a foreign distribution,
unless you have explicitly enabled them via one of the recommended
installation steps (@pxref{Installation}). The following paragraphs
Often, packages defined in Guix have a single @dfn{output}---i.e., the
source package leads to exactly one directory in the store. When running
-@command{guix package -i glibc}, one installs the default output of the
+@command{guix install glibc}, one installs the default output of the
GNU libc package; the default output is called @code{out}, but its name
can be omitted as shown in this command. In this particular case, the
default output of @code{glibc} contains all the C header files, shared
which contains everything but the documentation, one would run:
@example
-guix package -i glib
+guix install glib
@end example
@cindex documentation
The command to install its documentation is:
@example
-guix package -i glib:doc
+guix install glib:doc
@end example
Some packages install programs with different ``dependency footprints''.
includes default user profiles; by default, the symlinks under
@file{/var/guix/gcroots} represent these GC roots. New GC roots can be
added with @command{guix build --root}, for example (@pxref{Invoking
-guix build}).
+guix build}). The @command{guix gc --list-roots} command lists them.
Prior to running @code{guix gc --collect-garbage} to make space, it is
often useful to remove old generations from user profiles; that way, old
When @var{free} or more is already available in @file{/gnu/store}, do
nothing and exit immediately.
+@item --delete-generations[=@var{duration}]
+@itemx -d [@var{duration}]
+Before starting the garbage collection process, delete all the generations
+older than @var{duration}, for all the user profiles; when run as root, this
+applies to all the profiles @emph{of all the users}.
+
+For example, this command deletes all the generations of all your profiles
+that are older than 2 months (except generations that are current), and then
+proceeds to free space until at least 10 GiB are available:
+
+@example
+guix gc -d 2m -F 10G
+@end example
+
@item --delete
-@itemx -d
+@itemx -D
Attempt to delete all the store files and directories specified as
arguments. This fails if some of the files are not in the store, or if
they are still live.
@option{--cache-failures} (@pxref{Invoking guix-daemon,
@option{--cache-failures}}).
+@item --list-roots
+List the GC roots owned by the user; when run as root, list @emph{all} the GC
+roots.
+
@item --clear-failures
Remove the specified store items from the failed-build cache.
69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
@end example
-@ref{Invoking guix describe, @command{guix describe}}, for other ways to
+@xref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.
This @code{~/.config/guix/current} profile works like any other profile
@item --url=@var{url}
@itemx --commit=@var{commit}
@itemx --branch=@var{branch}
-Download code from the specified @var{url}, at the given @var{commit} (a valid
-Git commit ID represented as a hexadecimal string), or @var{branch}.
+Download code for the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
@cindex @file{channels.scm}, configuration file
@cindex configuration file for channels
evaluates to a list of channel objects. @xref{Channels}, for more
information.
+@item --news
+@itemx -N
+Display the list of packages added or upgraded since the previous generation.
+
+This is the same information as displayed upon @command{guix pull} completion,
+but without ellipses; it is also similar to the output of @command{guix pull
+-l} for the last generation (see below).
+
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).
-@ref{Invoking guix describe}, for a way to display information about the
+@xref{Invoking guix describe}, for a way to display information about the
current generation only.
@item --profile=@var{profile}
The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}. The file contains
-@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
-@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@item --extract=@var{directory}
directory outside the container is mapped inside the container.
Additionally, unless overridden with @code{--user}, a dummy home
directory is created that matches the current user's home directory, and
-@file{/etc/passwd} is configured accordingly. The spawned process runs
-as the current user outside the container, but has root privileges in
-the context of the container.
+@file{/etc/passwd} is configured accordingly.
+
+The spawned process runs as the current user outside the container. Inside
+the container, it has the same UID and GID as the current user, unless
+@option{--user} is passed (see below.)
@item --network
@itemx -N
@itemx -u @var{user}
For containers, use the username @var{user} in place of the current
user. The generated @file{/etc/passwd} entry within the container will
-contain the name @var{user}; the home directory will be
-@file{/home/USER}; and no user GECOS data will be copied. @var{user}
+contain the name @var{user}, the home directory will be
+@file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
+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
@noindent
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
-@uref{http://singularity.lbl.gov, Singularity container execution
+@uref{https://singularity.lbl.gov, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
Recording such ``silent'' metadata in the output thus potentially breaks the
source-to-binary bitwise reproducibility property.
+@item --root=@var{file}
+@itemx -r @var{file}
+@cindex garbage collector root, for packs
+Make @var{file} a symlink to the resulting pack, and register it as a garbage
+collector root.
+
@item --localstatedir
@itemx --profile-name=@var{name}
Include the ``local state directory'', @file{/var/guix}, in the resulting
The @code{(gnu packages @dots{})} module name space is
automatically scanned for packages by the command-line tools. For
-instance, when running @code{guix package -i emacs}, all the @code{(gnu
+instance, when running @code{guix install emacs}, all the @code{(gnu
packages @dots{})} modules are scanned until one that exports a package
object whose name is @code{emacs} is found. This package search
facility is implemented in the @code{(gnu packages)} module.
(inputs `(("gawk" ,gawk)))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
- (home-page "http://www.gnu.org/software/hello/")
+ (home-page "https://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
-(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
-Configure and Build System}).
+(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
@end deffn
@cindex package transformations
library code they depend on at run time, run-time dependencies must be
listed in @code{propagated-inputs} rather than @code{inputs}.
-@item @code{self-native-input?} (default: @code{#f})
-This is a Boolean field telling whether the package should use itself as
-a native input when cross-compiling.
-
@item @code{outputs} (default: @code{'("out")})
The list of output names of the package. @xref{Packages with Multiple
Outputs}, for typical uses of additional outputs.
@end table
@end deftp
+@deffn {Scheme Syntax} this-package
+When used in the @emph{lexical scope} of a package field definition, this
+identifier resolves to the package being defined.
+
+The example below shows how to add a package as a native input of itself when
+cross-compiling:
+
+@example
+(package
+ (name "guile")
+ ;; ...
+
+ ;; When cross-compiled, Guile, for example, depends on
+ ;; a native version of itself. Add it here.
+ (native-inputs (if (%current-target-system)
+ `(("self" ,this-package))
+ '())))
+@end example
+
+It is an error to refer to @code{this-package} outside a package definition.
+@end deffn
@node origin Reference
@subsection @code{origin} Reference
@defvr {Scheme Variable} ant-build-system
This variable is exported by @code{(guix build-system ant)}. It
implements the build procedure for Java packages that can be built with
-@url{http://ant.apache.org/, Ant build tool}.
+@url{https://ant.apache.org/, Ant build tool}.
It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
provided by the @code{icedtea} package to the set of inputs. Different
@uref{https://www.rust-lang.org, Rust programming language}.
In its @code{configure} phase, this build system replaces dependencies
-specified in the @file{Carto.toml} file with inputs to the Guix package.
+specified in the @file{Cargo.toml} file with inputs to the Guix package.
The @code{install} phase installs the binaries, and it also installs the
source code and @file{Cargo.toml} file.
@end defvr
@defvr {Scheme Variable} cmake-build-system
This variable is exported by @code{(guix build-system cmake)}. It
implements the build procedure for packages using the
-@url{http://www.cmake.org, CMake build tool}.
+@url{https://www.cmake.org, CMake build tool}.
It automatically adds the @code{cmake} package to the set of inputs.
Which package is used can be specified with the @code{#:cmake}
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
-implements the build procedure used by @uref{http://r-project.org, R}
+implements the build procedure used by @uref{https://r-project.org, R}
packages, which essentially is little more than running @code{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
@end defvr
@defvr {Scheme Variable} rakudo-build-system
-This variable is exported by @code{(guix build-system rakudo)} It
+This variable is exported by @code{(guix build-system rakudo)}. It
implements the build procedure used by @uref{https://rakudo.org/,
Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
@defvr {Scheme Variable} meson-build-system
This variable is exported by @code{(guix build-system meson)}. It
implements the build procedure for packages that use
-@url{http://mesonbuild.com, Meson} as their build system.
+@url{https://mesonbuild.com, Meson} as their build system.
It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
of inputs, and they can be changed with the parameters @code{#:meson}
@end table
@end defvr
+@defvr {Scheme Variable} linux-module-build-system
+@var{linux-module-build-system} allows building Linux kernel modules.
+
+@cindex build phases
+This build system is an extension of @var{gnu-build-system}, but with the
+following phases changed:
+
+@table @code
+
+@item configure
+This phase configures the environment so that the Linux kernel's Makefile
+can be used to build the external kernel module.
+
+@item build
+This phase uses the Linux kernel's Makefile in order to build the external
+kernel module.
+
+@item install
+This phase uses the Linux kernel's Makefile in order to install the external
+kernel module.
+@end table
+
+It is possible and useful to specify the Linux kernel to use for building
+the module (in the "arguments" form of a package using the
+linux-module-build-system, use the key #:linux to specify it).
+@end defvr
+
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
it provides basically no support: it does not pull any implicit inputs,
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
-the system type of the build host.
+the system type of the build host. The @command{guix build} command allows
+you to repeat this option several times, in which case it builds for all the
+specified systems; other commands ignore extraneous @option{-s} options.
@quotation Note
The @code{--system} flag is for @emph{native} compilation and must not
@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
configuration triplets,, autoconf, Autoconf}).
@anchor{build-check}
@cindex CRAN
@cindex Bioconductor
Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
-central repository for the @uref{http://r-project.org, GNU@tie{}R
+central repository for the @uref{https://r-project.org, GNU@tie{}R
statistical and graphical environment}.
Information is extracted from the @code{DESCRIPTION} file of the package.
@item texlive
@cindex TeX Live
@cindex CTAN
-Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+Import metadata from @uref{https://www.ctan.org/, CTAN}, the
comprehensive TeX archive network for TeX packages that are part of the
@uref{https://www.tug.org/texlive/, TeX Live distribution}.
@item nix
Import metadata from a local copy of the source of the
-@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
-@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code. This
command only imports the high-level package structure that is written in
the Nix language. It normally includes all the basic fields of a
are:
@itemize -
@item
-@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
identifier. This is the default.
Packages from @code{elpa.gnu.org} are signed with one of the keys
signatures,, emacs, The GNU Emacs Manual}).
@item
-@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
+@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.
@item
-@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
+@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
@item kernel.org
the updater for packages hosted on kernel.org;
@item elpa
-the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
+the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
-the updater for @uref{http://www.cpan.org/, CPAN} packages;
+the updater for @uref{https://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
(cpe-version . "2.3")))
@end example
-@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Some entries in the CVE database do not specify which version of a
package they apply to, and would thus ``stick around'' forever. Package
developers who found CVE alerts and verified they can be ignored can
produced by @command{guix size}}
This option requires that
-@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path. When that is not
the case, @command{guix size} fails as it tries to load it.
mental model of the package DAG, so the @command{guix graph} command
provides a visual representation of the DAG. By default,
@command{guix graph} emits a DAG representation in the input format of
-@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
emit Cypher queries to construct a graph in a graph database supporting
-the @uref{http://www.opencypher.org/, openCypher} query language.
+the @uref{https://www.opencypher.org/, openCypher} query language.
The general syntax is:
@example
innocuous since the command only gathers statistics and cannot install
those substitutes.
-Among other things, it is possible to query specific system types and
-specific package sets. The available options are listed below.
+The general syntax is:
+
+@example
+guix weather @var{options}@dots{} [@var{packages}@dots{}]
+@end example
+
+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.
@table @code
@item --substitute-urls=@var{urls}
@var{b} usually lacks substitutes as well. The result looks like this:
@example
-$ guix weather --substitute-urls=https://ci.guix.info -c 10
+$ guix weather --substitute-urls=@value{SUBSTITUTE-URL} -c 10
computing 8,983 package derivations for x86_64-linux...
-looking for 9,343 store items on https://ci.guix.info...
-updating substitutes from 'https://ci.guix.info'... 100.0%
-https://ci.guix.info
+looking for 9,343 store items on @value{SUBSTITUTE-URL}...
+updating substitutes from '@value{SUBSTITUTE-URL}'... 100.0%
+@value{SUBSTITUTE-URL}
64.7% substitutes available (6,047 out of 9,343)
@dots{}
-2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which:
+2502 packages are missing from '@value{SUBSTITUTE-URL}' for 'x86_64-linux', among which:
58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
@chapter System Configuration
@cindex system configuration
-The Guix System Distribution supports a consistent whole-system configuration
+Guix System supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
only the Linux-libre kernel is supported. In the future, it will be
possible to use the GNU@tie{}Hurd.}.
-@item @code{kernel-arguments} (default: @code{'()})
+@item @code{kernel-arguments} (default: @code{'("quiet")})
List of strings or gexps representing additional arguments to pass on
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
@item @code{bootloader}
The system bootloader configuration object. @xref{Bootloader Configuration}.
+@item @code{label}
+This is the label (a string) as it appears in the bootloader's menu entry.
+The default label includes the kernel name and version.
+
@item @code{keyboard-layout} (default: @code{#f})
This field specifies the keyboard layout to use in the console. It can be
either @code{#f}, in which case the default keyboard layout is used (usually
@code{sudo}.
@end table
+
+@deffn {Scheme Syntax} this-operating-system
+When used in the @emph{lexical scope} of an operating system field definition,
+this identifier resolves to the operating system being defined.
+
+The example below shows how to refer to the operating system being defined in
+the definition of the @code{label} field:
+
+@example
+(use-modules (gnu) (guix))
+
+(operating-system
+ ;; ...
+ (label (package-full-name
+ (operating-system-kernel this-operating-system))))
+@end example
+
+It is an error to refer to @code{this-operating-system} outside an operating
+system definition.
+@end deffn
+
@end deftp
@node File Systems
This is a list of symbols denoting mount flags. Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
access to special files), @code{no-suid} (ignore setuid and setgid
-bits), and @code{no-exec} (disallow program execution.)
+bits), @code{no-atime} (do not update file access times), and @code{no-exec}
+(disallow program execution). @xref{Mount-Unmount-Remount,,, libc, The GNU C
+Library Reference Manual}, for more information on these flags.
@item @code{options} (default: @code{#f})
-This is either @code{#f}, or a string denoting mount options.
+This is either @code{#f}, or a string denoting mount options passed to the
+file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C Library
+Reference Manual}, for details and run @command{man 8 mount} for options for
+various file systems.
@item @code{mount?} (default: @code{#t})
This value indicates whether to automatically mount the file system when
@node Keyboard Layout
@section Keyboard Layout
+@cindex keyboard layout
+@cindex keymap
To specify what each key of your keyboard does, you need to tell the operating
system what @dfn{keyboard layout} you want to use. The default, when nothing
is specified, is the US English QWERTY layout for 105-key PC keyboards.
your system---bootloader, console, and Xorg. Here's what your system
configuration would look like:
+@findex set-xorg-configuration
@lisp
;; Using the Turkish layout for the bootloader, the console,
;; and for Xorg.
(bootloader grub-efi-bootloader)
(target "/boot/efi")
(keyboard-layout keyboard-layout))) ;for GRUB
- (services (modify-services %desktop-services
- (slim-service-type config =>
- (slim-configuration
- (inherit config)
- (xorg-configuration
+ (services (cons (set-xorg-configuration
(xorg-configuration ;for Xorg
- (keyboard-layout keyboard-layout))))))))
+ (keyboard-layout keyboard-layout)))
+ %desktop-services)))
@end lisp
In the example above, for GRUB and for Xorg, we just refer to the
@code{keyboard-layout} field defined above, but we could just as well refer to
-a different layout.
+a different layout. The @code{set-xorg-configuration} procedure communicates
+the desired Xorg configuration to the graphical log-in manager, by default
+GDM.
+
+We've discussed how to specify the @emph{default} keyboard layout of your
+system when it starts, but you can also adjust it at run time:
+
+@itemize
+@item
+If you're using GNOME, its settings panel has a ``Region & Language'' entry
+where you can select one or more keyboard layouts.
+
+@item
+Under Xorg, the @command{setxkbmap} command (from the same-named package)
+allows you to change the current layout. For example, this is how you would
+change the layout to US Dvorak:
+
+@example
+setxkbmap us dvorak
+@end example
+
+@item
+The @code{loadkeys} command changes the keyboard layout in effect in the Linux
+console. However, note that @code{loadkeys} does @emph{not} use the XKB
+keyboard layout categorization described above. The command below loads the
+French bépo layout:
+
+@example
+loadkeys fr-bepo
+@end example
+@end itemize
@node Locales
@section Locales
@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
-@uref{http://www.iana.org/assignments/character-sets, as defined by
+@uref{https://www.iana.org/assignments/character-sets, as defined by
IANA}.
@end table
@item @code{kill-characters} (default: @code{#f})
This option accepts a string that should be interpreted to mean "ignore
-all previous characters" (also called a "kill" character) when the types
-their login name.
+all previous characters" (also called a "kill" character) when the user
+types their login name.
@item @code{chdir} (default: @code{#f})
This option accepts, as a string, a directory path that will be changed
@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
-variable. The procedures @var{udev-rule} and @var{file->udev-rule} from
+variable. The procedures @code{udev-rule} and @code{file->udev-rule} from
@code{(gnu services base)} simplify the creation of such rule files.
@end deffn
It defaults to @file{/var/lib/random-seed}.
@end defvr
-@cindex keymap
-@cindex keyboard
-@deffn {Scheme Procedure} console-keymap-service @var{files} ...
-@cindex keyboard layout
-Return a service to load console keymaps from @var{files} using
-@command{loadkeys} command. Most likely, you want to load some default
-keymap, which can be done like this:
-
-@example
-(console-keymap-service "dvorak")
-@end example
-
-Or, for example, for a Swedish keyboard, you may need to combine
-the following keymaps:
-@example
-(console-keymap-service "se-lat6" "se-fi-lat6")
-@end example
-
-Also you can specify a full file name (or file names) of your keymap(s).
-See @code{man loadkeys} for details.
-
-@end deffn
-
@cindex mouse
@cindex gpm
@defvr {Scheme Variable} gpm-service-type
The package that provides the DHCP daemon. This package is expected to
provide the daemon at @file{sbin/dhcpd} relative to its output
directory. The default package is the
-@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}.
+@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}.
@item @code{config-file} (default: @code{#f})
The configuration file to use. This is required. It will be passed to
@code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
A list of local IP address the ntpd daemon should use for outgoing queries.
@item @code{sensor} (default: @code{'()})
Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
-will listen to each sensor that acutally exists and ignore non-existant ones.
+will listen to each sensor that actually exists and ignore non-existent ones.
See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
@item @code{server} (default: @var{%ntp-servers})
files.
@deffn {Scheme Variable} rsync-service-type
-This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
+This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
+The value for this service type is a
@command{rsync-configuration} record as in this example:
@example
@defvr {Scheme Variable} avahi-service-type
This is the service that runs @command{avahi-daemon}, a system-wide
mDNS/DNS-SD responder that allows for service discovery and
-``zero-configuration'' host name lookups (see @uref{http://avahi.org/}).
+``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
Its value must be a @code{zero-configuration} record---see below.
This service extends the name service cache daemon (nscd) so that it can
@end deftp
@deffn {Scheme Variable} openvswitch-service-type
-This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
+This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
service, whose value should be an @code{openvswitch-configuration}
object.
@end deffn
Support for the X Window graphical display system---specifically
Xorg---is provided by the @code{(gnu services xorg)} module. Note that
there is no @code{xorg-service} procedure. Instead, the X server is
-started by the @dfn{login manager}, by default SLiM.
+started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
+
+@cindex GDM
+@cindex GNOME, login manager
+GDM of course allows users to log in into window managers and desktop
+environments other than GNOME; for those using GNOME, GDM is required for
+features such as automatic screen locking.
@cindex window manager
To use X11, you must install at least one @dfn{window manager}---for
by adding it to the @code{packages} field of your operating system
definition (@pxref{operating-system Reference, system-wide packages}).
-@defvr {Scheme Variable} slim-service-type
-This is the type for the SLiM graphical login manager for X11.
+@defvr {Scheme Variable} gdm-service-type
+This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
+Desktop Manager} (GDM), a program that manages graphical display servers and
+handles graphical user logins. Its value must be a @code{gdm-configuration}
+(see below.)
@cindex session types (X11)
@cindex X11 session types
-SLiM looks for @dfn{session types} described by the @file{.desktop} files in
-@file{/run/current-system/profile/share/xsessions} and allows users to
-choose a session from the log-in screen using @kbd{F1}. Packages such
-as @code{xfce}, @code{sawfish}, and @code{ratpoison} provide
-@file{.desktop} files; adding them to the system-wide set of packages
-automatically makes them available at the log-in screen.
+GDM looks for @dfn{session types} described by the @file{.desktop} files in
+@file{/run/current-system/profile/share/xsessions} and allows users to choose
+a session from the log-in screen. Packages such as @code{gnome}, @code{xfce},
+and @code{i3} provide @file{.desktop} files; adding them to the system-wide
+set of packages automatically makes them available at the log-in screen.
In addition, @file{~/.xsession} files are honored. When available,
@file{~/.xsession} must be an executable that starts a window manager
and/or other X clients.
@end defvr
+@deftp {Data Type} gdm-configuration
+@table @asis
+@item @code{auto-login?} (default: @code{#f})
+@itemx @code{default-user} (default: @code{#f})
+When @code{auto-login?} is false, GDM presents a log-in screen.
+
+When @code{auto-login?} is true, GDM logs in directly as
+@code{default-user}.
+
+@item @code{gnome-shell-assets} (default: ...)
+List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
+
+@item @code{xorg-configuration} (default: @code{(xorg-configuration)})
+Configuration of the Xorg graphical server.
+
+@item @code{xsession} (default: @code{(xinitrc)})
+Script to run before starting a X session.
+
+@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
+File name of the @code{dbus-daemon} executable.
+
+@item @code{gdm} (default: @code{gdm})
+The GDM package to use.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} slim-service-type
+This is the type for the SLiM graphical login manager for X11.
+
+Like GDM, SLiM looks for session types described by @file{.desktop} files and
+allows users to choose a session from the log-in screen using @kbd{F1}. It
+also honors @file{~/.xsession} files.
+
+Unlike GDM, SLiM does not spawn the user session on a different VT after
+logging in, which means that you can only start one graphical session. If you
+want to be able to run multiple graphical sessions at the same time you have
+to add multiple SLiM services to your system services. The following example
+shows how to replace the default GDM service with two SLiM services on tty7
+and tty8.
+
+@lisp
+(use-modules (gnu services)
+ (gnu services desktop)
+ (gnu services xorg)
+ (srfi srfi-1)) ;for 'remove'
+
+(operating-system
+ ;; ...
+ (services (cons* (service slim-service-type (slim-configuration
+ (display ":0")
+ (vt "vt7")))
+ (service slim-service-type (slim-configuration
+ (display ":1")
+ (vt "vt8")))
+ (remove (lambda (service)
+ (eq? (service-kind service) gdm-service-type))
+ %desktop-services))))
+@end lisp
+
+@end defvr
+
@deftp {Data Type} slim-configuration
Data type representing the configuration of @code{slim-service-type}.
@item @code{xorg-configuration} (default @code{(xorg-configuration)})
Configuration of the Xorg graphical server.
+@item @code{display} (default @code{":0"})
+The display on which to start the Xorg graphical server.
+
+@item @code{vt} (default @code{"vt7"})
+The VT on which to start the Xorg graphical server.
+
@item @code{xauth} (default: @code{xauth})
The XAuth package to use.
@item @code{default-path} (default "/run/current-system/profile/bin")
Default PATH to use.
-@item @code{minimum-uid} (default 1000)
-Minimum UID to display in SDDM.
+@item @code{minimum-uid} (default: 1000)
+Minimum UID displayed in SDDM and allowed for log-in.
-@item @code{maximum-uid} (default 2000)
-Maximum UID to display in SDDM
+@item @code{maximum-uid} (default: 2000)
+Maximum UID to display in SDDM.
@item @code{remember-last-user?} (default #t)
Remember last user.
@end table
@end deftp
+@deffn {Scheme Procedure} set-xorg-configuration @var{config} @
+ [@var{login-manager-service-type}]
+Tell the log-in manager (of type @var{login-manager-service-type}) to use
+@var{config}, an @code{<xorg-configuration>} record.
+
+Since the Xorg configuration is embedded in the log-in manager's
+configuration---e.g., @code{gdm-configuration}---this procedure provides a
+shorthand to set the Xorg configuration.
+@end deffn
+
@deffn {Scheme Procedure} xorg-start-command [@var{config}]
Return a @code{startx} script in which the modules, fonts, etc. specified
in @var{config}, are available. The result should be used in place of
@deftypevr {@code{files-configuration} parameter} log-location error-log
Defines the error log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+error log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
@deftypevr {@code{files-configuration} parameter} log-location page-log
Defines the page log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+page log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
usually useful in the context of a ``desktop'' setup---that is, on a
machine running a graphical display server, possibly with graphical user
interfaces, etc. It also defines services that provide specific desktop
-environments like GNOME, XFCE or MATE.
+environments like GNOME, Xfce or MATE.
To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
adds or adjusts services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), screen lockers, a network management tool
-(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
-management services, the @code{elogind} login and seat manager, the
-Polkit privilege service, the GeoClue location service, the
-AccountsService daemon that allows authorized users change system
-passwords, an NTP client (@pxref{Networking Services}), the Avahi
-daemon, and has the name service switch service configured to be able to
-use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
+@code{gdm-service-type}}), screen lockers, a network management tool
+(@pxref{Networking Services, @code{network-manager-service-type}}) with modem
+support (@pxref{Networking Services, @code{modem-manager-service-type}}),
+energy and color management services, the @code{elogind} login and seat
+manager, the Polkit privilege service, the GeoClue location service, the
+AccountsService daemon that allows authorized users change system passwords,
+an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the
+name service switch service configured to be able to use @code{nss-mdns}
+(@pxref{Name Service Switch, mDNS}).
@end defvr
The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-Additionally, the @code{gnome-desktop-service},
+Additionally, the @code{gnome-desktop-service-type},
@code{xfce-desktop-service}, @code{mate-desktop-service-type} and
-@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
+@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, MATE
and/or Enlightenment to a system. To ``add GNOME'' means that system-level
services like the backlight adjustment helpers and the power management
utilities are added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
-adding a service made by @code{gnome-desktop-service} adds the GNOME
-metapackage to the system profile. Likewise, adding the XFCE service
+adding a service made by @code{gnome-desktop-service-type} adds the GNOME
+metapackage to the system profile. Likewise, adding the Xfce service
not only adds the @code{xfce} metapackage to the system profile, but it
also gives the Thunar file manager the ability to open a ``root-mode''
file management window, if the user authenticates using the
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
-called Wayland, you need to use the @code{sddm-service} instead of the
-@code{slim-service} for the graphical login manager. You should then
+called Wayland, you need to use the @code{sddm-service} instead of
+GDM as the graphical login manager. You should then
select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
also try starting GNOME on Wayland manually from a TTY with the
command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
gnome-session``. Currently only GNOME has support for Wayland.
-@deffn {Scheme Procedure} gnome-desktop-service
-Return a service that adds the @code{gnome} package to the system
-profile, and extends polkit with the actions from
-@code{gnome-settings-daemon}.
-@end deffn
+@defvr {Scheme Variable} gnome-desktop-service-type
+This is the type of the service that adds the @uref{https://www.gnome.org,
+GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
+object (see below.)
-@deffn {Scheme Procedure} xfce-desktop-service
-Return a service that adds the @code{xfce} package to the system profile,
-and extends polkit with the ability for @code{thunar} to manipulate the
-file system as root from within a user session, after the user has
-authenticated with the administrator's password.
-@end deffn
+This service adds the @code{gnome} package to the system profile, and extends
+polkit with the actions from @code{gnome-settings-daemon}.
+@end defvr
+
+@deftp {Data Type} gnome-desktop-configuration
+Configuration record for the GNOME desktop environment.
+
+@table @asis
+@item @code{gnome} (default: @code{gnome})
+The GNOME package to use.
+@end table
+@end deftp
+
+@defvr {Scheme Variable} xfce-desktop-service-type
+This is the type of a service to run the @uref{Xfce, https://xfce.org/}
+desktop environment. Its value is an @code{xfce-desktop-configuration} object
+(see below.)
+
+This service adds the @code{xfce} package to the system profile, and
+extends polkit with the ability for @code{thunar} to manipulate the file
+system as root from within a user session, after the user has authenticated
+with the administrator's password.
+@end defvr
+
+@deftp {Data Type} xfce-desktop-configuration
+Configuration record for the Xfce desktop environment.
+
+@table @asis
+@item @code{xfce} (default: @code{xfce})
+The Xfce package to use.
+@end table
+@end deftp
@deffn {Scheme Variable} mate-desktop-service-type
This is the type of the service that runs the @uref{https://mate-desktop.org/,
Configuration record for the MATE desktop environment.
@table @asis
-@item @code{mate} (default @code{mate})
+@item @code{mate} (default: @code{mate})
The MATE package to use.
@end table
@end deftp
@deftp {Data Type} enlightenment-desktop-service-configuration
@table @asis
-@item @code{enlightenment} (default @code{enlightenment})
+@item @code{enlightenment} (default: @code{enlightenment})
The enlightenment package to use.
@end table
@end deftp
-Because the GNOME, XFCE and MATE desktop services pull in so many packages,
+Because the GNOME, Xfce and MATE desktop services pull in so many packages,
the default @code{%desktop-services} variable doesn't include any of
-them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
+them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
(operating-system
...
;; cons* adds items to the list given as its last argument.
- (services (cons* (gnome-desktop-service)
- (xfce-desktop-service)
+ (services (cons* (service gnome-desktop-service-type)
+ (service xfce-desktop-service)
%desktop-services))
...)
@end example
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.
-@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
+@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility. Its system bus is used to allow system services to communicate
and to be notified of system-wide events.
@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the
-@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
+@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
management service}, which allows system administrators to grant access to
privileged operations in a structured way. By querying the Polkit service, a
privileged system component can know when it should grant additional
@end deffn
@defvr {Scheme Variable} upower-service-type
-Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a
+Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
configuration settings.
@end deftp
@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
-Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
+Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
UDisks}, a @dfn{disk management} daemon that provides user interfaces with
notifications and ways to mount/unmount disks. Programs that talk to UDisks
include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners. It is notably used by the GNOME Color Manager graphical
-tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
+tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
site} for more information.
@end deffn
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
+@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
In case of password mismatches, log the attempted password. Valid
values are no, plain and sha1. sha1 can be useful for detecting brute
force password attempts vs. user simply trying the same password over
and over again. You can also truncate the value to n chars by appending
":n" (e.g.@: sha1:6).
-Defaults to @samp{#f}.
+Defaults to @samp{"no"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
the @code{postmaster} mail to @code{bob} (which subsequently would
deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
+@subsubheading GNU Mailutils IMAP4 Daemon
+@cindex GNU Mailutils IMAP4 Daemon
+
+@deffn {Scheme Variable} imap4d-service-type
+This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
+mailutils, GNU Mailutils Manual}), whose value should be an
+@code{imap4d-configuration} object as in this example:
+
+@example
+(service imap4d-service-type
+ (imap4d-configuration
+ (config-file (local-file "imap4d.conf"))))
+@end example
+@end deffn
+
+@deftp {Data Type} imap4d-configuration
+Data type representing the configuration of @command{imap4d}.
+
+@table @asis
+@item @code{package} (default: @code{mailutils})
+The package that provides @command{imap4d}.
+
+@item @code{config-file} (default: @code{%default-imap4d-config-file})
+File-like object of the configuration file to use, by default it will listen
+on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
+Mailutils Manual}, for details.
+
+@end table
+@end deftp
+
@node Messaging Services
@subsection Messaging Services
@cindex IRC (Internet Relay Chat)
@cindex IRC gateway
-@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
interface to a variety of messaging protocols such as XMPP.
@defvr {Scheme Variable} bitlbee-service-type
-This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
gateway daemon. Its value is a @code{bitlbee-configuration} (see
below).
Maximum size in bytes that a user can send in one image message.
@item @code{cert-required?} (default: @code{#f})
-If it is set to @code{#t} clients that use weak password authentification
+If it is set to @code{#t} clients that use weak password authentication
will not be accepted. Users must have completed the certificate wizard to join.
@item @code{remember-channel?} (default: @code{#f})
The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
Only the most commonly used ones are described here.
For a full list, and more detailed explanation of each, see the MIT
-@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
+@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
documentation.
@end defvr
@deftp {Data Type} pam-krb5-configuration
-Data type representing the configuration of the Kerberos 5 PAM module
+Data type representing the configuration of the Kerberos 5 PAM module.
This type has the following parameters:
@table @asis
@item @code{pam-krb5} (default: @code{pam-krb5})
The first domain provided will be the subject CN of the certificate, and
all domains will be Subject Alternative Names on the certificate.
+@item @code{challenge} (default: @code{#f})
+The challenge type that has to be run by certbot. If @code{#f} is specified,
+default to the HTTP challenge. If a value is specified, defaults to the
+manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
+the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}).
+
+@item @code{authentication-hook} (default: @code{#f})
+Command to be run in a shell once for each certificate challenge to be
+answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
+will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
+contains the validation string and @code{$CERTBOT_TOKEN} contains the
+file name of the resource requested when performing an HTTP-01 challenge.
+
+@item @code{cleanup-hook} (default: @code{#f})
+Command to be run in a shell once for each certificate challenge that
+have been answered by the @code{auth-hook}. For this command, the shell
+variables available in the @code{auth-hook} script are still available, and
+additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
+of the @code{auth-hook} script.
+
@item @code{deploy-hook} (default: @code{#f})
Command to be run in a shell once for each successfully issued
certificate. For this command, the shell variable
The delay between a modification in memory and on disk. 0 means immediate
synchronization.
+@item @code{zonefile-load} (default: @code{#f})
+The way the zone file contents are applied during zone load. Possible values
+are:
+
+@itemize
+@item @code{#f} for using the default value from Knot,
+@item @code{'none} for not using the zone file at all,
+@item @code{'difference} for computing the difference between already available
+contents and zone contents and applying it to the current zone contents,
+@item @code{'difference-no-serial} for the same as @code{'difference}, but
+ignoring the SOA serial in the zone file, while the server takes care of it
+automatically.
+@item @code{'whole} for loading zone contents from the zone file.
+@end itemize
+
+@item @code{journal-content} (default: @code{#f})
+The way the journal is used to store zone and its changes. Possible values
+are @code{'none} to not use it at all, @code{'changes} to store changes and
+@code{'all} to store contents. @code{#f} does not set this option, so the
+default value from Knot is used.
+
+@item @code{max-journal-usage} (default: @code{#f})
+The maximum size for the journal on disk. @code{#f} does not set this option,
+so the default value from Knot is used.
+
+@item @code{max-journal-depth} (default: @code{#f})
+The maximum size of the history. @code{#f} does not set this option, so the
+default value from Knot is used.
+
+@item @code{max-zone-size} (default: @code{#f})
+The maximum size of the zone file. This limit is enforced for incoming
+transfer and updates. @code{#f} does not set this option, so the default
+value from Knot is used.
+
+@item @code{dnssec-policy} (default: @code{#f})
+A reference to a @code{knot-policy-configuration} record, or the special
+name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
+on this zone.
+
@item @code{serial-policy} (default: @code{'increment})
A policy between @code{'increment} and @code{'unixtime}.
@item @code{run-directory} (default: @code{"/var/run/knot"})
The run directory. This directory will be used for pid file and sockets.
+@item @code{includes} (default: @code{'()})
+A list of strings or file-like objects denoting other files that must be
+included at the top of the configuration file.
+
+@cindex secrets, Knot service
+This can be used to manage secrets out-of-band. For example, secret
+keys may be stored in an out-of-band file not managed by Guix, and
+thus not visible in @file{/gnu/store}---e.g., you could store secret
+key configuration in @file{/etc/knot/secrets.conf} and add this file
+to the @code{includes} list.
+
+It can also be used to add configuration not supported by this interface.
+
@item @code{listen-v4} (default: @code{"0.0.0.0"})
An ip address on which to listen.
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for
-your machine to connect to a VPN, and a @emph{servire} service for your machine
+your machine to connect to a VPN, and a @emph{server} service for your machine
to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}.
@deffn {Scheme Procedure} openvpn-client-service @
Contrary to @code{upower-service}, it is not a passive,
monitoring tool, as it will apply custom settings each time a new power
source is detected. More information can be found at
-@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}.
+@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
@deffn {Scheme Variable} tlp-service-type
The service type for the TLP tool. Its value should be a valid
@deftypevr {@code{libvirt-configuration} parameter} string log-outputs
Logging outputs.
-An output is one of the places to save logging information The format
+An output is one of the places to save logging information. The format
for an output can be:
@table @code
@cindex Gitolite service
@cindex Git, hosting
-@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
+@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
repositories on a central server.
Gitolite can handle multiple repositories and users, and supports flexible
@cindex fingerprint
@subsubheading Fingerprint Service
-The @code{(gnu services fingerprint)} module provides a DBus service to
+The @code{(gnu services authentication)} module provides a DBus service to
read and identify fingerprints via a fingerprint sensor.
@defvr {Scheme Variable} fprintd-service-type
The @code{(gnu services spice)} module provides the following service.
@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
-Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon
+Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
that enables sharing the clipboard with a vm and setting the guest display
resolution when the graphical console window resizes.
@end deffn
@defvr {Scheme Variable} docker-service-type
-This is the type of the service that runs @url{http://www.docker.com,Docker},
+This is the type of the service that runs @url{https://www.docker.com,Docker},
a daemon that can execute application bundles (sometimes referred to as
``containers'') in isolated environments.
would typically run something like:
@example
-$ guix package -i nss-certs
+$ guix install nss-certs
$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
$ export GIT_SSL_CAINFO="$SSL_CERT_FILE"
something like this:
@example
-$ guix package -i nss-certs
+$ guix install nss-certs
$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
@end example
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
@item @code{target}
This is a string denoting the target onto which to install the
is provided, some bootloaders might use a default theme, that's true
for GRUB.
-@item @code{terminal-outputs} (default: @code{'gfxterm})
+@item @code{terminal-outputs} (default: @code{'(gfxterm)})
The output terminals used for the bootloader boot menu, as a list of
symbols. GRUB accepts the values: @code{console}, @code{serial},
@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
@end deftp
@c FIXME: Write documentation once it's stable.
-Fow now only GRUB has theme support. GRUB themes are created using
+For now only GRUB has theme support. GRUB themes are created using
the @code{grub-theme} form, which is not documented yet.
@defvr {Scheme Variable} %default-theme
@quotation Note
@c The paragraph below refers to the problem discussed at
-@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+@c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invoking
guix pull}). Failing to do that you would see an older version of Guix
Docker container using commands like the following:
@example
-image_id="$(docker load < guix-system-docker-image.tar.gz)"
-docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
- --entrypoint /var/guix/profiles/system/profile/bin/guile \\
- $image_id /var/guix/profiles/system/boot
+image_id="`docker load < guix-system-docker-image.tar.gz`"
+container_id="`docker create $image_id`"
+docker start $container_id
@end example
This command starts a new Docker container from the specified image. It
will boot the Guix system in the usual manner, which means it will
start any services you have defined in the operating system
-configuration. Depending on what you run in the Docker container, it
+configuration. You can get an interactive shell running in the container
+using @command{docker exec}:
+
+@example
+docker exec -ti $container_id /run/current-system/profile/bin/bash --login
+@end example
+
+Depending on what you run in the Docker container, it
may be necessary to give the container additional permissions. For
example, if you intend to build software using Guix inside of the Docker
container, you may need to pass the @option{--privileged} option to
-@code{docker run}.
+@code{docker create}.
@item container
Return a script to run the operating system declared in @var{file}
of the image size as a function of the size of the system declared in
@var{file}.
+@item --network
+@itemx -N
+For the @code{container} action, allow containers to access the host network,
+that is, do not create a network namespace.
+
@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
@section Running Guix in a Virtual Machine
@cindex virtual machine
-To run Guix in a virtual machine (VM), one can either use the
-pre-built Guix VM image distributed at
-@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz}
-, or build their own virtual machine image using @command{guix system
-vm-image} (@pxref{Invoking guix system}). The returned image is in
-qcow2 format, which the @uref{http://qemu.org/, QEMU emulator} can
-efficiently use.
+To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
+distributed at
+@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
+This image is a compressed image in QCOW format. You will first need to
+decompress with @command{xz -d}, and then you can pass it to an emulator such
+as QEMU (see below for details).
+
+This image boots the Xfce graphical environment and it contains some
+commonly-used tools. You can install more software in the image by running
+@command{guix package} in a terminal (@pxref{Invoking guix package}). You can
+also reconfigure the system based on its initial configuration file available
+as @file{/etc/config.scm} (@pxref{Using the Configuration System}).
+
+Instead of using this pre-built image, one can also build their own virtual
+machine image using @command{guix system vm-image} (@pxref{Invoking guix
+system}). The returned image is in qcow2 format, which the
+@uref{https://qemu.org/, QEMU emulator} can efficiently use.
@cindex QEMU
If you built your own image, you must copy it out of the store
@example
$ qemu-system-x86_64 \
-net user -net nic,model=virtio \
- -enable-kvm -m 256 /tmp/qemu-image
+ -enable-kvm -m 512 \
+ -device virtio-blk,drive=myhd \
+ -drive if=none,file=/tmp/qemu-image,id=myhd
@end example
Here is what each of these options means:
virtual machine support (KVM) of the Linux kernel will make things run
faster.
-@item -m 256
+@c To run Xfce + 'guix pull', we need at least 1G of RAM.
+@item -m 1024
RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
which may be insufficient for some operations.
-@item /tmp/qemu-image
-The file name of the qcow2 image.
+@item -device virtio-blk,drive=myhd
+Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
+``paravirtualization'' mechanism for block devices that allows QEMU to achieve
+better performance than if it were emulating a complete disk drive. See the
+QEMU and KVM documentation for more info.
+
+@item -drive if=none,file=/tmp/qemu-image,id=myhd
+Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing store the
+the ``myhd'' drive.
@end table
The default @command{run-vm.sh} script that is returned by an invocation of
@cindex SSH
@cindex SSH server
-To enable SSH inside a VM you need to add a SSH server like @code{(dropbear-service)}
-or @code{(lsh-service)} to your VM. The @code{(lsh-service}) doesn't currently
-boot unsupervised. It requires you to type some characters to initialize the
-randomness generator. In addition you need to forward the SSH port, 22 by
-default, to the host. You can do this with
+To enable SSH inside a VM you need to add an SSH server like
+@code{openssh-service-type} to your VM (@pxref{Networking Services,
+@code{openssh-service-type}}). In addition you need to forward the SSH port,
+22 by default, to the host. You can do this with
@example
`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22
Optionally, a default value for instances of this type.
@end enumerate
-In this example, @var{guix-service-type} extends three services:
+In this example, @code{guix-service-type} extends three services:
-@table @var
+@table @code
@item shepherd-root-service-type
-The @var{guix-shepherd-service} procedure defines how the Shepherd
+The @code{guix-shepherd-service} procedure defines how the Shepherd
service is extended. Namely, it returns a @code{<shepherd-service>}
object that defines how @command{guix-daemon} is started and stopped
(@pxref{Shepherd Services}).
@item account-service-type
-This extension for this service is computed by @var{guix-accounts},
+This extension for this service is computed by @code{guix-accounts},
which returns a list of @code{user-group} and @code{user-account}
objects representing the build user accounts (@pxref{Invoking
guix-daemon}).
@item activation-service-type
-Here @var{guix-activation} is a procedure that returns a gexp, which is
+Here @code{guix-activation} is a procedure that returns a gexp, which is
a code snippet to run at ``activation time''---e.g., when the service is
booted.
@end table
(service guix-service-type)
@end example
-@var{guix-service-type} is quite simple because it extends other
+@code{guix-service-type} is quite simple because it extends other
services but is not extensible itself.
@c @subsubsubsection Extensible Service Types
This is the service type for the
@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
management daemon}. Compared to the previous example, in addition to an
-extension of @var{shepherd-root-service-type}, we see two new fields:
+extension of @code{shepherd-root-service-type}, we see two new fields:
@table @code
@item compose
@end table
There can be only one instance of an extensible service type such as
-@var{udev-service-type}. If there were more, the
+@code{udev-service-type}. If there were more, the
@code{service-extension} specifications would be ambiguous.
Still here? The next section provides a reference of the programming
The @code{modify-services} form provides a handy way to change the
parameters of some of the services of a list such as
-@var{%base-services} (@pxref{Base Services, @code{%base-services}}). It
+@code{%base-services} (@pxref{Base Services, @code{%base-services}}). It
evaluates to a list of services. Of course, you could always use
standard list combinators such as @code{map} and @code{fold} to do that
(@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
definition using the @command{guix system shepherd-graph} command
(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
-The @var{%shepherd-root-service} is a service object representing
-PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended
+The @code{%shepherd-root-service} is a service object representing
+PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
by passing it lists of @code{<shepherd-service>} objects.
@deftp {Data Type} shepherd-service
shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
-@item @code{requirements} (default: @code{'()})
+@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.
+@cindex one-shot services, for the Shepherd
+@item @code{one-shot?} (default: @code{#f})
+Whether this service is @dfn{one-shot}. One-shot services stop immediately
+after their @code{start} action has completed. @xref{Slots of services,,,
+shepherd, The GNU Shepherd Manual}, for more info.
+
@item @code{respawn?} (default: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example
+@item @code{auto-start?} (default: @code{#t})
+Whether this service should be started automatically by the Shepherd. If it
+is @code{#f} the service has to be started manually with @code{herd start}.
+
@item @code{documentation}
A documentation string, as shown when running:
herd doc @var{service-name}
@end example
-where @var{service-name} is one of the symbols in @var{provision}
+where @var{service-name} is one of the symbols in @code{provision}
(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
-@item @code{modules} (default: @var{%default-modules})
+@item @code{modules} (default: @code{%default-modules})
This is the list of modules that must be in scope when @code{start} and
@code{stop} are evaluated.
Guile:
@example
-guix package -i glibc:debug guile:debug
+guix install glibc:debug guile:debug
@end example
GDB must then be told to look for debug files in the user's profile, by
@cindex replacements of packages, for grafts
For instance, suppose a security update needs to be applied to Bash.
Guix developers will provide a package definition for the ``fixed''
-Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
+Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
Packages}). Then, the original package definition is augmented with a
@code{replacement} field pointing to the package containing the bug fix:
From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invoking guix
gc})---that is installed is automatically ``rewritten'' to refer to
-@var{bash-fixed} instead of @var{bash}. This grafting process takes
+@code{bash-fixed} instead of @code{bash}. This grafting process takes
time proportional to the size of the package, usually less than a
minute for an ``average'' package on a recent machine. Grafting is
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.
Currently, the length of the name and version of the graft and that of
-the package it replaces (@var{bash-fixed} and @var{bash} in the example
+the package it replaces (@code{bash-fixed} and @code{bash} in the example
above) must be equal. This restriction mostly comes from the fact that
grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
@image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
-@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
+@c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
The first tool that gets built with the bootstrap binaries is
GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
for all the following packages. From there Findutils and Diffutils get
@node Acknowledgments
@chapter Acknowledgments
-Guix is based on the @uref{http://nixos.org/nix/, Nix package manager},
+Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
which was designed and
implemented by Eelco Dolstra, with contributions from other people (see
the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
HCoop / jackhill / guix / guix.git / blobdiff