@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@*
@c TRANSLATORS: You can replace the following paragraph with information on
@c how to join your own translation team and how to report issues with the
@c translation.
-This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
-référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
-zu GNU Guix}). If you would like to translate it in your native language,
-consider joining the
+This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
+GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
+Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), and
+Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}). If you
+would like to translate it in your native language, consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.
@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
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.
@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 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}
@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}.
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
@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
@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
@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.
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})
@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
Configuration record for the GNOME desktop environment.
@table @asis
-@item @code{gnome} (default @code{gnome})
+@item @code{gnome} (default: @code{gnome})
The GNOME package to use.
@end table
@end deftp
Configuration record for the Xfce desktop environment.
@table @asis
-@item @code{xfce} (default @code{xfce})
+@item @code{xfce} (default: @code{xfce})
The Xfce package to use.
@end table
@end deftp
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
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
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).
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
@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
@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
@item @code{requirements} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.
+@cindex one-shot services, for the Shepherd
+@item @code{one-shot?} (default: @code{#f})
+Whether this service is @dfn{one-shot}. One-shot services stop immediately
+after their @code{start} action has completed. @xref{Slots of services,,,
+shepherd, The GNU Shepherd Manual}, for more info.
+
@item @code{respawn?} (default: @code{#t})
Whether to restart the service when it stops, for instance when the
underlying process dies.
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