@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
-@author Ludovic Courtès
-@author Andreas Enge
-@author Nikita Karetnikov
+@author The GNU Guix Developers
@page
@vskip 0pt plus 1filll
* Package Management: Emacs Package Management. Managing packages and generations.
* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
-* Completions: Emacs Completions. Completing @command{guix} shell command.
+* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
+* Completions: Emacs Completions. Completing @command{guix} shell command.
+* Development: Emacs Development. Tools for Guix developers.
Programming Interface
* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
+* Invoking guix challenge:: Challenging substitute servers.
GNU Distribution
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
+* Web Services:: Web servers.
* Various Services:: Other services.
+Defining Services
+
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Service Reference:: API reference.
+* dmd Services:: A particular type of service.
+
Packaging Guidelines
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
@cindex functional package management
The term @dfn{functional} refers to a specific package management
-discipline. In Guix, the package build and installation process is seen
+discipline pioneered by Nix (@pxref{Acknowledgments}).
+In Guix, the package build and installation process is seen
as a function, in the mathematical sense. That function takes inputs,
such as build scripts, a compiler, and libraries, and
returns an installed package. As a pure function, its result depends
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
+When this option is used, @command{guix gc --list-failures} can be used
+to query the set of store items marked as failed; @command{guix gc
+--clear-failures} removes store items from the set of cached failures.
+@xref{Invoking guix gc}.
+
@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
@node Application Setup
@section Application Setup
-When using Guix on top of GNU/Linux distribution other than GuixSD, a
-few additional steps are needed to get everything in place. Here are
-some of them.
+When using Guix on top of GNU/Linux distribution other than GuixSD---a
+so-called @dfn{foreign distro}---a few additional steps are needed to
+get everything in place. Here are some of them.
@subsection Locales
+@anchor{locales-and-locpath}
@cindex locales, when not on GuixSD
+@vindex LOCPATH
+@vindex GUIX_LOCPATH
Packages installed @i{via} Guix will not use the host system's locale
data. Instead, you must first install one of the locale packages
-available with Guix and then define the @code{LOCPATH} environment
-variable (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library
-Reference Manual}):
+available with Guix and then define the @code{GUIX_LOCPATH} environment
+variable:
@example
$ guix package -i glibc-locales
-$ export LOCPATH=$HOME/.guix-profile/lib/locale
+$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
@end example
Note that the @code{glibc-locales} package contains data for all the
110@tie{}MiB. Alternately, the @code{glibc-utf8-locales} is smaller but
limited to a few UTF-8 locales.
+The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}
+(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference
+Manual}). There are two important differences though:
+
+@enumerate
+@item
+@code{GUIX_LOCPATH} is honored only by Guix's libc, and not by the libc
+provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you
+to make sure the the foreign distro's programs will not end up loading
+incompatible locale data.
+
+@item
+libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where
+@code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
+should your Guix profile contain a mixture of programs linked against
+different libc version, each libc version will only try to load locale
+data in the right format.
+@end enumerate
+
+This is important because the locale data format used by different libc
+versions may be incompatible.
+
@subsection X11 Fonts
The majority of graphical applications use Fontconfig to locate and
(@pxref{Features}). In most cases, independent builds of a given
package or derivation should yield bit-identical results. Thus, through
a diverse set of independent package builds, we can strengthen the
-integrity of our systems.
+integrity of our systems. The @command{guix challenge} command aims to
+help users assess substitute servers, and to assist developers in
+finding out about non-deterministic package builds (@pxref{Invoking guix
+challenge}).
In the future, we want Guix to have support to publish and retrieve
binaries to/from other users, in a peer-to-peer fashion. If you would
arguments. This fails if some of the files are not in the store, or if
they are still live.
+@item --list-failures
+List store items corresponding to cached build failures.
+
+This prints nothing unless the daemon was started with
+@option{--cache-failures} (@pxref{Invoking guix-daemon,
+@option{--cache-failures}}).
+
+@item --clear-failures
+Remove the specified store items from the failed-build cache.
+
+Again, this option only makes sense when the daemon is started with
+@option{--cache-failures}. Otherwise, it does nothing.
+
@item --list-dead
Show the list of dead files and directories still present in the
store---i.e., files and directories no longer reachable from any root.
s-expressions''} and is structured as an access-control list in the
@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
+
+@item --extract=@var{directory}
+@itemx -x @var{directory}
+Read a single-item archive as served by substitute servers
+(@pxref{Substitutes}) and extract it to @var{directory}. This is a
+low-level operation needed in only very narrow use cases; see below.
+
+For example, the following command extracts the substitute for Emacs
+served by @code{hydra.gnu.org} to @file{/tmp/emacs}:
+
+@example
+$ wget -O - \
+ http://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
+ | bunzip2 | guix archive -x /tmp/emacs
+@end example
+
+Single-item archives are different from multiple-item archives produced
+by @command{guix archive --export}; they contain a single store item,
+and they do @emph{not} embed a signature. Thus this operation does
+@emph{no} signature verification and its output should be considered
+unsafe.
+
+The primary purpose of this operation is to facilitate inspection of
+archive contents coming from possibly untrusted substitute servers.
+
@end table
To export store files as an archive to the standard output, run:
(define-public hello
(package
(name "hello")
- (version "2.8")
+ (version "2.10")
(source (origin
- (method url-fetch)
- (uri (string-append "mirror://gnu/hello/hello-" version
- ".tar.gz"))
- (sha256
- (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
+ (method url-fetch)
+ (uri (string-append "mirror://gnu/hello/hello-" version
+ ".tar.gz"))
+ (sha256
+ (base32
+ "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
(build-system gnu-build-system)
(arguments `(#:configure-flags '("--enable-silent-rules")))
(inputs `(("gawk" ,gawk)))
implements the RubyGems build procedure used by Ruby packages, which
involves running @code{gem build} followed by @code{gem install}.
-The @code{source} field of a package that uses this build system is
-expected to reference a gem archive instead of a traditional tarball,
-since this is the format that all Ruby developers use when releasing
-their software. The build system unpacks the gem archive, potentially
-patches the source, runs the test suite, repackages the gem, and
-installs it.
+The @code{source} field of a package that uses this build system
+typically references a gem archive, since this is the format that Ruby
+developers use when releasing their software. The build system unpacks
+the gem archive, potentially patches the source, runs the test suite,
+repackages the gem, and installs it. Additionally, directories and
+tarballs may be referenced to allow building unreleased gems from Git or
+a traditional source release tarball.
Which Ruby package is used can be specified with the @code{#:ruby}
parameter. A list of additional flags to be passed to the @command{gem}
@end deffn
@cindex file-like objects
-The @code{local-file} and @code{plain-file} procedures below return
+The @code{local-file}, @code{plain-file}, @code{computed-file},
+@code{program-file}, and @code{scheme-file} procedures below return
@dfn{file-like objects}. That is, when unquoted in a G-expression,
these objects lead to a file in the store. Consider this G-expression:
This is the declarative counterpart of @code{text-file}.
@end deffn
+@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
+ [#:modules '()] [#:options '(#:local-build? #t)]
+Return an object representing the store item @var{name}, a file or
+directory computed by @var{gexp}. @var{modules} specifies the set of
+modules visible in the execution context of @var{gexp}. @var{options}
+is a list of additional arguments to pass to @code{gexp->derivation}.
+
+This is the declarative counterpart of @code{gexp->derivation}.
+@end deffn
+
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
Return an executable script @var{name} that runs @var{exp} using
@var{guile} with @var{modules} in its search path.
@end example
@end deffn
+@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
+ [#:modules '()] [#:guile #f]
+Return an object representing the executable store item @var{name} that
+runs @var{gexp}. @var{guile} is the Guile package used to execute that
+script, and @var{modules} is the list of modules visible to that script.
+
+This is the declarative counterpart of @code{gexp->script}.
+@end deffn
+
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
Return a derivation that builds a file @var{name} containing @var{exp}.
or a subset thereof.
@end deffn
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
+Return an object representing the Scheme file @var{name} that contains
+@var{exp}.
+
+This is the declarative counterpart of @code{gexp->file}.
+@end deffn
+
@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
Return as a monadic value a derivation that builds a text file
containing all of @var{text}. @var{text} may list, in addition to
preventing them from being garbage-collected during its lifetime.
@end deffn
+@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
+Return an object representing store file @var{name} containing
+@var{text}. @var{text} is a sequence of strings and file-like objects,
+as in:
+
+@example
+(mixed-text-file "profile"
+ "export PATH=" coreutils "/bin:" grep "/bin")
+@end example
+
+This is the declarative counterpart of @code{text-file*}.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
+* Invoking guix challenge:: Challenging substitute servers.
@end menu
@node Invoking guix build
@table @code
+@item --file=@var{file}
+@itemx -f @var{file}
+
+Build the package or derivation that the code within @var{file}
+evaluates to.
+
+As an example, @var{file} might contain a package definition like this
+(@pxref{Defining Packages}):
+
+@example
+@verbatiminclude package-hello.scm
+@end example
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Build the package or derivation @var{expr} evaluates to.
@end example
It does so by browsing each package's FTP directory and determining the
-highest version number of the source tarballs
-therein@footnote{Currently, this only works for GNU packages.}.
+highest version number of the source tarballs therein. The command
+knows how to update specific types of packages: GNU packages, ELPA
+packages, etc.---see the documentation for @option{--type} below. The
+are many packages, though, for which it lacks a method to determine
+whether a new upstream release is available. However, the mechanism is
+extensible, so feel free to get in touch with us to add a new method!
When passed @code{--update}, it modifies distribution source files to
update the version numbers and source tarball hashes of those packages'
@item --update
@itemx -u
-Update distribution source files (package recipes) in place.
+Update distribution source files (package recipes) in place. This is
+usually run from a checkout of the Guix source tree (@pxref{Running
+Guix Before It Is Installed}):
+
+@example
+$ ./pre-inst-env guix refresh -s non-core
+@end example
+
@xref{Defining Packages}, for more information on package definitions.
@item --select=[@var{subset}]
typically useful in cases where an update of the core packages would be
inconvenient.
+@item --type=@var{updater}
+@itemx -t @var{updater}
+Select only packages handled by @var{updater} (may be a comma-separated
+list of updaters). Currently, @var{updater} may be one of:
+
+@table @code
+@item gnu
+the updater for GNU packages;
+@item elpa
+the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
+@item cran
+the updater fro @uref{http://cran.r-project.org/, CRAN} packages.
+@end table
+
+For instance, the following commands only checks for updates of Emacs
+packages hosted at @code{elpa.gnu.org} and updates of CRAN packages:
+
+@example
+$ guix refresh --type=elpa,cran
+gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
+gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
+@end example
+
@end table
In addition, @command{guix refresh} can be passed one or more package
names, as in this example:
@example
-guix refresh -u emacs idutils gcc-4.8.4
+$ ./pre-inst-env guix refresh -u emacs idutils gcc-4.8.4
@end example
@noindent
@table @code
+@item --list-updaters
+@itemx -L
+List available updaters and exit (see @option{--type} above.)
+
@item --list-dependent
@itemx -l
List top-level dependent packages that would need to be rebuilt as a
@item source
@itemx home-page
+@itemx source-file-name
Probe @code{home-page} and @code{source} URLs and report those that are
-invalid.
+invalid. Check that the source file name is meaningful, e.g. is not
+just a version number or ``git-checkout'', and should not have a
+@code{file-name} declared (@pxref{origin Reference}).
@item formatting
Warn about obvious source code formatting issues: trailing white space,
guix environment guile emacs
@end example
-Sometimes an interactive shell session is not desired. The
-@code{--exec} option can be used to specify the command to run instead.
+Sometimes an interactive shell session is not desired. An arbitrary
+command may be invoked by placing the @code{--} token to separate the
+command from the rest of the arguments:
@example
-guix environment guile --exec=make
+guix environment guile -- make -j4
@end example
In other situations, it is more convenient to specify the list of
NumPy:
@example
-guix environment --ad-hoc python2-numpy python-2.7 -E python
+guix environment --ad-hoc python2-numpy python-2.7 -- python
+@end example
+
+Furthermore, one might want the dependencies of a package and also some
+additional packages that are not build-time or runtime dependencies, but
+are useful when developing nonetheless. Because of this, the
+@code{--ad-hoc} flag is positional. Packages appearing before
+@code{--ad-hoc} are interpreted as packages whose dependencies will be
+added to the environment. Packages appearing after are interpreted as
+packages that will be added to the environment directly. For example,
+the following command creates a Guix development environment that
+additionally includes Git and strace:
+
+@example
+guix environment guix --ad-hoc git strace
+@end example
+
+Sometimes it is desirable to isolate the environment as much as
+possible, for maximal purity and reproducibility. In particular, when
+using Guix on a host distro that is not GuixSD, it is desirable to
+prevent access to @file{/usr/bin} and other system-wide resources from
+the development environment. For example, the following command spawns
+a Guile REPL in a ``container'' where only the store and the current
+working directory are mounted:
+
+@example
+guix environment --ad-hoc --container guile -- guile
@end example
The available options are summarized below.
@table @code
@item --expression=@var{expr}
@itemx -e @var{expr}
-Create an environment for the package that @var{expr} evaluates to.
+Create an environment for the package or list of packages that
+@var{expr} evaluates to.
For example, running:
starts a shell with the environment for this specific variant of the
PETSc package.
+Running:
+
+@example
+guix environment --ad-hoc -e '(@ (gnu) %base-packages)'
+@end example
+
+starts a shell with all the GuixSD base packages available.
+
@item --load=@var{file}
@itemx -l @var{file}
-Create an environment for the package that the code within @var{file}
-evaluates to.
+Create an environment for the package or list of packages that the code
+within @var{file} evaluates to.
As an example, @var{file} might contain a definition like this
(@pxref{Defining Packages}):
@verbatiminclude environment-gdb.scm
@end example
-
-@item --exec=@var{command}
-@item -E @var{command}
-Execute @var{command} in the new environment.
-
@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs. This option is
For instance, the command:
@example
-guix environment --ad-hoc guile guile-sdl -E guile
+guix environment --ad-hoc guile guile-sdl -- guile
@end example
runs @command{guile} in an environment where Guile and Guile-SDL are
specific output---e.g., @code{glib:bin} asks for the @code{bin} output
of @code{glib} (@pxref{Packages with Multiple Outputs}).
+This option may be composed with the default behavior of @command{guix
+environment}. Packages appearing before @code{--ad-hoc} are interpreted
+as packages whose dependencies will be added to the environment, the
+default behavior. Packages appearing after are interpreted as packages
+that will be added to the environment directly.
+
@item --pure
Unset existing environment variables when building the new environment.
This has the effect of creating an environment in which search paths
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}.
+
+@item --container
+@itemx -C
+@cindex container
+Run @var{command} within an isolated container. The current working
+directory outside the container is mapped to @file{/env} inside the
+container. Additionally, the spawned process runs as the current user
+outside the container, but has root privileges in the context of the
+container.
+
+@item --network
+@itemx -N
+For containers, share the network namespace with the host system.
+Containers created without this flag only have access to the loopback
+device.
+
+@item --expose=@var{source}[=@var{target}]
+For containers, expose the file system @var{source} from the host system
+as the read-only file system @var{target} within the container. If
+@var{target} is not specified, @var{source} is used as the target mount
+point in the container.
+
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible read-only via the @file{/exchange}
+directory:
+
+@example
+guix environment --container --expose=$HOME=/exchange guile -- guile
+@end example
+
+@item --share
+For containers, share the file system @var{source} from the host system
+as the writable file system @var{target} within the container. If
+@var{target} is not specified, @var{source} is used as the target mount
+point in the container.
+
+The example below spawns a Guile REPL in a container in which the user's
+home directory is accessible for both reading and writing via the
+@file{/exchange} directory:
+
+@example
+guix environment --container --share=$HOME=/exchange guile -- guile
+@end example
@end table
It also supports all of the common build options that @command{guix
primarily for debugging a running @command{guix publish} server.
@end table
+
+@node Invoking guix challenge
+@section Invoking @command{guix challenge}
+
+@cindex reproducible builds
+@cindex verifiable builds
+
+Do the binaries provided by this server really correspond to the source
+code it claims to build? Is this package's build process deterministic?
+These are the questions the @command{guix challenge} command attempts to
+answer.
+
+The former is obviously an important question: Before using a substitute
+server (@pxref{Substitutes}), you'd rather @emph{verify} that it
+provides the right binaries, and thus @emph{challenge} it. The latter
+is what enables the former: If package builds are deterministic, then
+independent builds of the package should yield the exact same result,
+bit for bit; if a server provides a binary different from the one
+obtained locally, it may be either corrupt or malicious.
+
+We know that the hash that shows up in @file{/gnu/store} file names is
+the hash of all the inputs of the process that built the file or
+directory---compilers, libraries, build scripts,
+etc. (@pxref{Introduction}). Assuming deterministic build processes,
+one store file name should map to exactly one build output.
+@command{guix challenge} checks whether there is, indeed, a single
+mapping by comparing the build outputs of several independent builds of
+any given store item.
+
+The command's output looks like this:
+
+@smallexample
+$ guix challenge --substitute-urls="http://hydra.gnu.org http://guix.example.org"
+updating list of substitutes from 'http://hydra.gnu.org'... 100.0%
+updating list of substitutes from 'http://guix.example.org'... 100.0%
+/gnu/store/@dots{}-openssl-1.0.2d contents differ:
+ local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ http://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
+ http://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
+/gnu/store/@dots{}-git-2.5.0 contents differ:
+ local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
+ http://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
+ http://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
+/gnu/store/@dots{}-pius-2.1.1 contents differ:
+ local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ http://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
+ http://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
+@end smallexample
+
+@noindent
+In this example, @command{guix challenge} first scans the store to
+determine the set of locally-built derivations---as opposed to store
+items that were downloaded from a substitute server---and then queries
+all the substitute servers. It then reports those store items for which
+the servers obtained a result different from the local build.
+
+@cindex non-determinism, in package builds
+As an example, @code{guix.example.org} always gets a different answer.
+Conversely, @code{hydra.gnu.org} agrees with local builds, except in the
+case of Git. This might indicate that the build process of Git is
+non-deterministic, meaning that its output varies as a function of
+various things that Guix does not fully control, in spite of building
+packages in isolated environments (@pxref{Features}). Most common
+sources of non-determinism include the addition of timestamps in build
+results, the inclusion of random numbers, and directory listings sorted
+by inode number. See @uref{http://reproducible.debian.net/howto/}, for
+more information.
+
+To find out what's wrong with this Git binary, we can do something along
+these lines (@pxref{Invoking guix archive}):
+
+@example
+$ wget -q -O - http://hydra.gnu.org/nar/@dots{}-git-2.5.0 \
+ | guix archive -x /tmp/git
+$ diff -ur /gnu/store/@dots{}-git.2.5.0 /tmp/git
+@end example
+
+This command shows the difference between the files resulting from the
+local build, and the files resulting from the build on
+@code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,,
+diffutils, Comparing and Merging Files}). The @command{diff} command
+works great for text files. When binary files differ, a better option
+is @uref{http://diffoscope.org/, Diffoscope}, a tool that helps
+visualize differences for all kinds of files.
+
+Once you've done that work, you can tell whether the differences are due
+to a non-deterministic build process or to a malicious server. We try
+hard to remove sources of non-determinism in packages to make it easier
+to verify substitutes, but of course, this is a process, one that
+involves not just Guix but a large part of the free software community.
+In the meantime, @command{guix challenge} is one tool to help address
+the problem.
+
+If you are writing packages for Guix, you are encouraged to check
+whether @code{hydra.gnu.org} and other substitute servers obtain the
+same build result as you did with:
+
+@example
+$ guix challenge @var{package}
+@end example
+
+@noindent
+... where @var{package} is a package specification such as
+@code{guile-2.0} or @code{glibc:debug}.
+
+The general syntax is:
+
+@example
+guix challenge @var{options} [@var{packages}@dots{}]
+@end example
+
+The one option that matters is:
+
+@table @code
+
+@item --substitute-urls=@var{urls}
+Consider @var{urls} the whitespace-separated list of substitute source
+URLs to compare to.
+
+@end table
+
+
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
for basic user and administrator tasks---including the GNU Core
Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
editor, @command{find}, @command{grep}, etc. The example above adds
-Emacs to those, taken from the @code{(gnu packages emacs)} module
+tcpdump to those, taken from the @code{(gnu packages admin)} module
(@pxref{Package Modules}).
@vindex %base-services
available when the system starts (@pxref{Services}).
The @code{operating-system} declaration above specifies that, in
addition to the basic services, we want the @command{lshd} secure shell
-daemon listening on port 2222, and allowing remote @code{root} logins
-(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
+daemon listening on port 2222 (@pxref{Networking Services,
+@code{lsh-service}}). Under the hood,
@code{lsh-service} arranges so that @code{lshd} is started with the
right command-line options, possibly with supporting configuration files
-generated as needed (@pxref{Defining Services}). @xref{operating-system
-Reference}, for details about the available @code{operating-system}
-fields.
+generated as needed (@pxref{Defining Services}).
+
+@cindex customization, of services
+@findex modify-services
+Occasionally, instead of using the base services as is, you will want to
+customize them. For instance, to change the configuration of
+@code{guix-daemon} and Mingetty (the console log-in), you may write the
+following instead of @var{%base-services}:
+
+@lisp
+(modify-services %base-services
+ (guix-service-type config =>
+ (guix-configuration
+ (inherit config)
+ (use-substitutes? #f)
+ (extra-options '("--gc-keep-outputs"))))
+ (mingetty-service-type config =>
+ (mingetty-configuration
+ (inherit config)
+ (motd (plain-file "motd" "Hi there!")))))
+@end lisp
+
+@noindent
+The effect here is to change the options passed to @command{guix-daemon}
+when it is started, as well as the ``message of the day'' that appears
+when logging in at the console. @xref{Service Reference,
+@code{modify-services}}, for more on that.
The configuration for a typical ``desktop'' usage, with the X11 display
-server, a desktop environment, network management, an SSH server, and
+server, a desktop environment, network management, power management, and
more, would look like this:
@lisp
@xref{Desktop Services}, for the exact list of services provided by
@var{%desktop-services}. @xref{X.509 Certificates}, for background
information about the @code{nss-certs} package that is used here.
+@xref{operating-system Reference}, for details about all the available
+@code{operating-system} fields.
Assuming the above snippet is stored in the @file{my-system-config.scm}
file, the @command{guix system reconfigure my-system-config.scm} command
instantiates that configuration, and makes it the default GRUB boot
-entry (@pxref{Invoking guix system}). The normal way to change the
-system's configuration is by updating this file and re-running the
-@command{guix system} command.
+entry (@pxref{Invoking guix system}).
+
+The normal way to change the system's configuration is by updating this
+file and re-running @command{guix system reconfigure}. One should never
+have to touch files in @command{/etc} or to run commands that modify the
+system state such as @command{useradd} or @command{grub-install}. In
+fact, you must avoid that since that would not only void your warranty
+but also prevent you from rolling back to previous versions of your
+system, should you ever need to.
+
+@cindex roll-back, of the operating system
+Speaking of roll-back, each time you run @command{guix system
+reconfigure}, a new @dfn{generation} of the system is created---without
+modifying or deleting previous generations. Old system generations get
+an entry in the GRUB boot menu, allowing you to boot them in case
+something went wrong with the latest generation. Reassuring, no? The
+@command{guix system list-generations} command lists the system
+generations available on disk.
At the Scheme level, the bulk of an @code{operating-system} declaration
is instantiated with the following monadic procedure (@pxref{The Store
The list of locale definitions to be compiled and that may be used at
run time. @xref{Locales}.
+@item @code{locale-libcs} (default: @code{(list @var{glibc})})
+The list of GNU@tie{}libc packages whose locale data and tools are used
+to build the locale definitions. @xref{Locales}, for compatibility
+considerations that justify this option.
+
@item @code{name-service-switch} (default: @var{%default-nss})
Configuration of libc's name service switch (NSS)---a
@code{<name-service-switch>} object. @xref{Name Service Switch}, for
@defvr {Scheme Variable} %base-file-systems
These are essential file systems that are required on normal systems,
-such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
+such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
below.) Operating system declarations should always contain at least
these.
@end defvr
-@defvr {Scheme Variable} %devtmpfs-file-system
-The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
-requirement for udev (@pxref{Base Services, @code{udev-service}}).
-@end defvr
-
@defvr {Scheme Variable} %pseudo-terminal-file-system
This is the file system to be mounted as @file{/dev/pts}. It supports
@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
(charset "EUC-JP")))
@end example
+@vindex LOCPATH
+The compiled locale definitions are available at
+@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
+version, which is the default location where the GNU@tie{}libc provided
+by Guix looks for locale data. This can be overridden using the
+@code{LOCPATH} environment variable (@pxref{locales-and-locpath,
+@code{LOCPATH} and locale packages}).
+
The @code{locale-definition} form is provided by the @code{(gnu system
locale)} module. Details are given below.
@code{uk_UA.UTF-8}.
@end defvr
+@subsubsection Locale Data Compatibility Considerations
+
+@cindex incompatibility, of locale data
+@code{operating-system} declarations provide a @code{locale-libcs} field
+to specify the GNU@tie{}libc packages that are used to compile locale
+declarations (@pxref{operating-system Reference}). ``Why would I
+care?'', you may ask. Well, it turns out that the binary format of
+locale data is occasionally incompatible from one libc version to
+another.
+
+@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
+@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
+For instance, a program linked against libc version 2.21 is unable to
+read locale data produced with libc 2.22; worse, that program
+@emph{aborts} instead of simply ignoring the incompatible locale
+data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
+the incompatible locale data, which is already an improvement.}.
+Similarly, a program linked against libc 2.22 can read most, but not
+all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE}
+data is incompatible); thus calls to @code{setlocale} may fail, but
+programs will not abort.
+
+The ``problem'' in GuixSD is that users have a lot of freedom: They can
+choose whether and when to upgrade software in their profiles, and might
+be using a libc version different from the one the system administrator
+used to build the system-wide locale data.
+
+Fortunately, unprivileged users can also install their own locale data
+and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
+@code{GUIX_LOCPATH} and locale packages}).
+
+Still, it is best if the system-wide locale data at
+@file{/run/current-system/locale} is built for all the libc versions
+actually in use on the system, so that all the programs can access
+it---this is especially crucial on a multi-user system. To do that, the
+administrator can specify several libc packages in the
+@code{locale-libcs} field of @code{operating-system}:
+
+@example
+(use-package-modules base)
+
+(operating-system
+ ;; @dots{}
+ (locale-libcs (list glibc-2.21 (canonical-package glibc))))
+@end example
+
+This example would lead to a system containing locale definitions for
+both libc 2.21 and the current version of libc in
+@file{/run/current-system/locale}.
+
+
@node Services
@subsection Services
@end example
@end defvr
-@deffn {Monadic Procedure} host-name-service @var{name}
+@deffn {Scheme Procedure} host-name-service @var{name}
Return a service that sets the host name to @var{name}.
@end deffn
-@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
- [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
- [#:allow-empty-passwords? #f]
-Return a service to run mingetty on @var{tty}.
+@deffn {Scheme Procedure} mingetty-service @var{config}
+Return a service to run mingetty according to @var{config}, a
+@code{<mingetty-configuration>} object, which specifies the tty to run, among
+other things.
+@end deffn
+
+@deftp {Data Type} mingetty-configuration
+This is the data type representing the configuration of Mingetty, which
+implements console log-in.
-When @var{allow-empty-passwords?} is true, allow empty log-in password. When
-@var{auto-login} is true, it must be a user name under which to log-in
-automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
-@var{auto-login}, in which case the user will have to press a key before the
-login shell is launched.
+@table @asis
-When true, @var{login-program} is a gexp denoting the name
-of the log-in program (the default is the @code{login} program from the Shadow
-tool suite.)
+@item @code{tty}
+The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
-@var{motd} is a monadic value containing a text file to use as
-the ``message of the day''.
-@end deffn
+@item @code{motd}
+A file-like object containing the ``message of the day''.
+
+@item @code{auto-login} (default: @code{#f})
+When true, this field must be a string denoting the user name under
+which the the system automatically logs in. When it is @code{#f}, a
+user name and password must be entered to log in.
+
+@item @code{login-program} (default: @code{#f})
+This must be either @code{#f}, in which case the default log-in program
+is used (@command{login} from the Shadow tool suite), or a gexp denoting
+the name of the log-in program.
+
+@item @code{login-pause?} (default: @code{#f})
+When set to @code{#t} in conjunction with @var{auto-login}, the user
+will have to press a key before the log-in shell is launched.
+
+@item @code{mingetty} (default: @var{mingetty})
+The Mingetty package to use.
+
+@end table
+@end deftp
@cindex name service cache daemon
@cindex nscd
-@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
+@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
[#:name-services '()]
-Return a service that runs libc's name service cache daemon (nscd) with
-the given @var{config}---an @code{<nscd-configuration>} object.
-Optionally, @code{#:name-services} is a list of packages that provide
-name service switch (NSS) modules needed by nscd. @xref{Name Service
-Switch}, for an example.
+Return a service that runs libc's name service cache daemon (nscd) with the
+given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
+Service Switch}, for an example.
@end deffn
@defvr {Scheme Variable} %nscd-default-configuration
@table @asis
+@item @code{name-services} (default: @code{'()})
+List of packages denoting @dfn{name services} that must be visible to
+the nscd---e.g., @code{(list @var{nss-mdns})}.
+
+@item @code{glibc} (default: @var{glibc})
+Package object denoting the GNU C Library providing the @command{nscd}
+command.
+
@item @code{log-file} (default: @code{"/var/log/nscd.log"})
Name of nscd's log file. This is where debugging output goes when
@code{debug-level} is strictly positive.
@end defvr
-@deffn {Monadic Procedure} syslog-service [#:config-file #f]
+@deffn {Scheme Procedure} syslog-service [#:config-file #f]
Return a service that runs @code{syslogd}. If configuration file name
@var{config-file} is not specified, use some reasonable default
settings.
@end deffn
-@deffn {Monadic Procedure} guix-service [#:guix guix] @
- [#:builder-group "guixbuild"] [#:build-accounts 10] @
- [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
- [#:extra-options '()]
-Return a service that runs the build daemon from @var{guix}, and has
-@var{build-accounts} user accounts available under @var{builder-group}.
+@anchor{guix-configuration-type}
+@deftp {Data Type} guix-configuration
+This data type represents the configuration of the Guix build daemon.
+@xref{Invoking guix-daemon}, for more information.
-When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
-provided by @var{guix} is authorized upon activation, meaning that substitutes
-from @code{hydra.gnu.org} are used by default.
+@table @asis
+@item @code{guix} (default: @var{guix})
+The Guix package to use.
-If @var{use-substitutes?} is false, the daemon is run with
-@option{--no-substitutes} (@pxref{Invoking guix-daemon,
-@option{--no-substitutes}}).
+@item @code{build-group} (default: @code{"guixbuild"})
+Name of the group for build user accounts.
-Finally, @var{extra-options} is a list of additional command-line options
-passed to @command{guix-daemon}.
+@item @code{build-accounts} (default: @code{10})
+Number of build user accounts to create.
+
+@item @code{authorize-key?} (default: @code{#t})
+Whether to authorize the substitute key for @code{hydra.gnu.org}
+(@pxref{Substitutes}).
+
+@item @code{use-substitutes?} (default: @code{#t})
+Whether to use substitutes.
+
+@item @code{substitute-urls} (default: @var{%default-substitute-urls})
+The list of URLs where to look for substitutes by default.
+
+@item @code{extra-options} (default: @code{'()})
+List of extra command-line options for @command{guix-daemon}.
+
+@item @code{lsof} (default: @var{lsof})
+@itemx @code{lsh} (default: @var{lsh})
+The lsof and lsh packages to use.
+
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} guix-service @var{config}
+Return a service that runs the Guix build daemon according to
+@var{config}.
@end deffn
-@deffn {Monadic Procedure} udev-service [#:udev udev]
+@deffn {Scheme Procedure} udev-service [#:udev udev]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
@end deffn
-@deffn {Monadic Procedure} console-keymap-service @var{file}
+@deffn {Scheme Procedure} console-keymap-service @var{file}
Return a service to load console keymap from @var{file} using
@command{loadkeys} command.
@end deffn
the network interface.
@cindex DHCP, networking service
-@deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
+@deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
Return a service that runs @var{dhcp}, a Dynamic Host Configuration
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn
-@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
+@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
[#:gateway #f] [#:name-services @code{'()}]
Return a service that starts @var{interface} with address @var{ip}. If
@var{gateway} is true, it must be a string specifying the default network
@end deffn
@cindex wicd
-@deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
+@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
network manager that aims to simplify wired and wireless networking.
@end deffn
-@deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
+@deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @
[#:name-service @var{%ntp-servers}]
Return a service that runs the daemon from @var{ntp}, the
@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
List of host names used as the default NTP servers.
@end defvr
-@deffn {Monadic Procedure} tor-service [#:tor tor]
-Return a service to run the @uref{https://torproject.org,Tor} daemon.
+@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
+Return a service to run the @uref{https://torproject.org, Tor} anonymous
+networking daemon.
-The daemon runs with the default settings (in particular the default exit
-policy) as the @code{tor} unprivileged user.
+The daemon runs as the @code{tor} unprivileged user. It is passed
+@var{config-file}, a file-like object, with an additional @code{User tor}
+line. Run @command{man tor} for information about the configuration file.
@end deffn
-@deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
+@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
[#:interface "127.0.0.1"] [#:port 6667] @
[#:extra-settings ""]
Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
Furthermore, @code{(gnu services ssh)} provides the following service.
-@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
+@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
[#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
[#:allow-empty-passwords? #f] [#:root-login? #f] @
[#:syslog-output? #t] [#:x11-forwarding? #t] @
The @code{(gnu services avahi)} provides the following definition.
-@deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
+@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
[#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
[#:ipv6? #t] [#:wide-area? #f] @
[#:domains-to-browse '()]
Return a 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{http://avahi.org/}), and
+extends the name service cache daemon (nscd) so that it can resolve
+@code{.local} host names using
+@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}.
If @var{host-name} is different from @code{#f}, use that as the host name to
publish for this machine; otherwise, use the machine's actual host name.
there is no @code{xorg-service} procedure. Instead, the X server is
started by the @dfn{login manager}, currently SLiM.
-@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
+@deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @
[#:auto-login? #f] [#:default-user ""] [#:startx] @
[#:theme @var{%default-slim-theme}] @
[#:theme-name @var{%default-slim-theme-name}]
The G-Expression denoting the default SLiM theme and its name.
@end defvr
-@deffn {Monadic Procedure} xorg-start-command [#:guile] @
+@deffn {Scheme Procedure} xorg-start-command [#:guile] @
[#:configuration-file #f] [#:xorg-server @var{xorg-server}]
Return a derivation that builds a @var{guile} script to start the X server
from @var{xorg-server}. @var{configuration-file} is the server configuration
Usually the X server is started by a login manager.
@end deffn
-@deffn {Monadic Procedure} xorg-configuration-file @
+@deffn {Scheme Procedure} xorg-configuration-file @
[#:drivers '()] [#:resolutions '()] [#:extra-config '()]
Return a configuration file for the Xorg server containing search paths for
all the common drivers.
verbatim to the configuration file.
@end deffn
+@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}]
+Add @var{package}, a package for a screen-locker or screen-saver whose
+command is @var{program}, to the set of setuid programs and add a PAM entry
+for it. For example:
+
+@lisp
+(screen-locker-service xlockmore "xlock")
+@end lisp
+
+makes the good ol' XlockMore usable.
+@end deffn
+
+
@node Desktop Services
@subsubsection Desktop Services
adds or adjust services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
-@code{slim-service}}), a network management tool (@pxref{Networking
+@code{slim-service}}), screen lockers,
+a network management tool (@pxref{Networking
Services, @code{wicd-service}}), energy and color management services,
the @code{elogind} login and seat manager, the Polkit privilege service,
the GeoClue location service, an NTP client (@pxref{Networking
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-The actual service definitions provided by @code{(gnu services desktop)}
-are described below.
+The actual service definitions provided by @code{(gnu services dbus)}
+and @code{(gnu services desktop)} are described below.
-@deffn {Monadic Procedure} dbus-service @var{services} @
- [#:dbus @var{dbus}]
+@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.
@var{services} must be equal to @code{(list avahi)}.
@end deffn
-@deffn {Monadic Procedure} elogind-service @
- [#:elogind @var{elogind}] [#:config @var{config}]
+@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
Return a service that runs the @code{elogind} login and
seat management daemon. @uref{https://github.com/andywingo/elogind,
Elogind} exposes a D-Bus interface that can be used to know which users
@end table
@end deffn
-@deffn {Monadic Procedure} polkit-service @
+@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the Polkit privilege manager.
@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows
users active.
@end deffn
-@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
+@deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
[#:watts-up-pro? #f] @
[#:poll-batteries? #t] @
[#:ignore-lid? #f] @
GNOME.
@end deffn
-@deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
+@deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
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
know the user's location.
@end defvr
-@deffn {Monadic Procedure} geoclue-service [#:colord @var{colord}] @
+@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
[#:whitelist '()] @
[#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
[#:submit-data? #f]
The @code{(gnu services databases)} module provides the following service.
-@deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
+@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
[#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
Return a service that runs @var{postgresql}, the PostgreSQL database
server.
The @code{(gnu services web)} module provides the following service:
-@deffn {Monadic Procedure} nginx-service [#:nginx nginx] @
+@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
[#:log-directory ``/var/log/nginx''] @
[#:run-directory ``/var/run/nginx''] @
[#:config-file]
The @code{(gnu services lirc)} module provides the following service.
-@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
+@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
[#:device #f] [#:driver #f] [#:config-file #f] @
[#:extra-options '()]
Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
-@code{nscd-service} must be told where to find the @code{nss-mdns}
-shared library (@pxref{Base Services, @code{nscd-service}}). Since the
-@code{nscd} service is part of @var{%base-services}, you may want to
-customize it by adding this snippet in the operating system
-configuration file:
-
-@example
-(use-modules (guix) (gnu))
-
-(define %my-base-services
- ;; Replace the default nscd service with one that knows
- ;; about nss-mdns.
- (map (lambda (mservice)
- ;; "Bind" the MSERVICE monadic value to inspect it.
- (mlet %store-monad ((service mservice))
- (if (member 'nscd (service-provision service))
- (nscd-service (nscd-configuration)
- #:name-services (list nss-mdns))
- mservice)))
- %base-services))
-@end example
-
-@noindent
-@dots{} and then refer to @var{%my-base-services} instead of
-@var{%base-services} in the @code{operating-system} declaration.
-Lastly, this relies on the availability of the Avahi service
-(@pxref{Networking Services, @code{avahi-service}}).
+you also need to use @code{avahi-service} (@pxref{Networking Services,
+@code{avahi-service}}), or @var{%desktop-services}, which includes it
+(@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
+to the name service cache daemon (@pxref{Base Services,
+@code{nscd-service}}).
For convenience, the following variables provide typical NSS
configurations.
@item reconfigure
Build the operating system described in @var{file}, activate it, and
switch to it@footnote{This action is usable only on systems already
-running GNU.}.
+running GuixSD.}.
This effects all the configuration specified in @var{file}: user
accounts, system services, global package list, setuid programs, etc.
@item vm
@cindex virtual machine
@cindex VM
+@anchor{guix system vm}
Build a virtual machine that contain the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
Arguments given to the script are passed as is to QEMU.
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example
+@item container
+Return a script to run the operating system declared in @var{file}
+within a container. Containers are a set of lightweight isolation
+mechanisms provided by the kernel Linux-libre. Containers are
+substantially less resource-demanding than full virtual machines since
+the kernel, shared objects, and other resources can be shared with the
+host system; this also means they provide thinner isolation.
+
+Currently, the script must be run as root in order to support more than
+a single user and group. The container shares its store with the host
+system.
+
+As with the @code{vm} action (@pxref{guix system vm}), additional file
+systems to be shared between the host and container can be specified
+using the @option{--share} and @option{--expose} options:
+
+@example
+guix system container my-config.scm \
+ --expose=$HOME --share=$HOME/tmp=/exchange
+@end example
+
@end table
@var{options} can contain any of the common build options provided by
Attempt to build for @var{system} instead of the host's system type.
This works as per @command{guix build} (@pxref{Invoking guix build}).
+@item --derivation
+@itemx -d
+Return the derivation file name of the given operating system without
+building anything.
+
@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}. @var{size} may be a number of bytes, or it may
must exist and be readable and writable by the user and by the daemon's
build users.
+Once you have built, configured, re-configured, and re-re-configured
+your GuixSD installation, you may find it useful to list the operating
+system generations available on disk---and that you can choose from the
+GRUB boot menu:
+
+@table @code
+
+@item list-generations
+List a summary of each generation of the operating system available on
+disk, in a human-readable way. This is similar to the
+@option{--list-generations} option of @command{guix package}
+(@pxref{Invoking guix package}).
+
+Optionally, one can specify a pattern, with the same syntax that is used
+in @command{guix package --list-generations}, to restrict the list of
+generations displayed. For instance, the following command displays
+generations up to 10-day old:
+
+@example
+$ guix system list-generations 10d
+@end example
+
+@end table
+
+The @command{guix system} command has even more to offer! The following
+sub-commands allow you to visualize how your system services relate to
+each other:
+
+@anchor{system-extension-graph}
+@table @code
+
+@item extension-graph
+Emit in Dot/Graphviz format to standard output the @dfn{service
+extension graph} of the operating system defined in @var{file}
+(@pxref{Service Composition}, for more information on service
+extensions.)
+
+The command:
+
+@example
+$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf
+@end example
+
+produces a PDF file showing the extension relations among services.
+
+@anchor{system-dmd-graph}
+@item dmd-graph
+Emit in Dot/Graphviz format to standard output the @dfn{dependency
+graph} of dmd services of the operating system defined in @var{file}.
+@xref{dmd Services}, for more information and for an example graph.
+
+@end table
+
+
@node Defining Services
@subsection Defining Services
-The @code{(gnu services @dots{})} modules define several procedures that allow
-users to declare the operating system's services (@pxref{Using the
-Configuration System}). These procedures are @emph{monadic
-procedures}---i.e., procedures that return a monadic value in the store
-monad (@pxref{The Store Monad}). For examples of such procedures,
-@xref{Services}.
-
-@cindex service definition
-The monadic value returned by those procedures is a @dfn{service
-definition}---a structure as returned by the @code{service} form.
-Service definitions specifies the inputs the service depends on, and an
-expression to start and stop the service. Behind the scenes, service
-definitions are ``translated'' into the form suitable for the
-configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
-dmd Manual}).
-
-As an example, here is what the @code{nscd-service} procedure looks
-like:
+The previous sections show the available services and how one can combine
+them in an @code{operating-system} declaration. But how do we define
+them in the first place? And what is a service anyway?
-@lisp
-(define (nscd-service)
- (with-monad %store-monad
- (return (service
- (documentation "Run libc's name service cache daemon.")
- (provision '(nscd))
- (activate #~(begin
- (use-modules (guix build utils))
- (mkdir-p "/var/run/nscd")))
- (start #~(make-forkexec-constructor
- (string-append #$glibc "/sbin/nscd")
- "-f" "/dev/null" "--foreground"))
- (stop #~(make-kill-destructor))
- (respawn? #f)))))
-@end lisp
+@menu
+* Service Composition:: The model for composing services.
+* Service Types and Services:: Types and services.
+* Service Reference:: API reference.
+* dmd Services:: A particular type of service.
+@end menu
+
+@node Service Composition
+@subsubsection Service Composition
+
+@cindex services
+@cindex daemons
+Here we define a @dfn{service} as, broadly, something that extends the
+operating system's functionality. Often a service is a process---a
+@dfn{daemon}---started when the system boots: a secure shell server, a
+Web server, the Guix build daemon, etc. Sometimes a service is a daemon
+whose execution can be triggered by another daemon---e.g., an FTP server
+started by @command{inetd} or a D-Bus service activated by
+@command{dbus-daemon}. Occasionally, a service does not map to a
+daemon. For instance, the ``account'' service collects user accounts
+and makes sure they exist when the system runs; the ``udev'' service
+collects device management rules and makes them available to the eudev
+daemon; the @file{/etc} service populates the system's @file{/etc}
+directory.
+
+@cindex service extensions
+GuixSD services are connected by @dfn{extensions}. For instance, the
+secure shell service @emph{extends} dmd---GuixSD's initialization system,
+running as PID@tie{}1---by giving it the command lines to start and stop
+the secure shell daemon (@pxref{Networking Services,
+@code{lsh-service}}); the UPower service extends the D-Bus service by
+passing it its @file{.service} specification, and extends the udev
+service by passing it device management rules (@pxref{Desktop Services,
+@code{upower-service}}); the Guix daemon service extends dmd by passing
+it the command lines to start and stop the daemon, and extends the
+account service by passing it a list of required build user accounts
+(@pxref{Base Services}).
+
+All in all, services and their ``extends'' relations form a directed
+acyclic graph (DAG). If we represent services as boxes and extensions
+as arrows, a typical system might provide something like this:
+
+@image{images/service-graph,,5in,Typical service extension graph.}
+
+At the bottom, we see the @dfn{boot service}, which produces the boot
+script that is executed at boot time from the initial RAM disk.
+@xref{system-extension-graph, the @command{guix system extension-graph}
+command}, for information on how to generate this representation for a
+particular operating system definition.
+
+@cindex service types
+Technically, developers can define @dfn{service types} to express these
+relations. There can be any number of services of a given type on the
+system---for instance, a system running two instances of the GNU secure
+shell server (lsh) has two instances of @var{lsh-service-type}, with
+different parameters.
+
+The following section describes the programming interface for service
+types and services.
+
+@node Service Types and Services
+@subsubsection Service Types and Services
+
+A @dfn{service type} is a node in the DAG described above. Let us start
+with a simple example, the service type for the Guix build daemon
+(@pxref{Invoking guix-daemon}):
+
+@example
+(define guix-service-type
+ (service-type
+ (name 'guix)
+ (extensions
+ (list (service-extension dmd-root-service-type guix-dmd-service)
+ (service-extension account-service-type guix-accounts)
+ (service-extension activation-service-type guix-activation)))))
+@end example
@noindent
-The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
-(@pxref{G-Expressions}). The @code{activate} field contains a script to
-run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
-directory exists before @command{nscd} is started.
+It defines a two things:
+
+@enumerate
+@item
+A name, whose sole purpose is to make inspection and debugging easier.
+
+@item
+A list of @dfn{service extensions}, where each extension designates the
+target service type and a procedure that, given the service's
+parameters, returns a list of object to extend the service of that type.
+
+Every service type has at least one service extension. The only
+exception is the @dfn{boot service type}, which is the ultimate service.
+@end enumerate
+
+In this example, @var{guix-service-type} extends three services:
+
+@table @var
+@item dmd-root-service-type
+The @var{guix-dmd-service} procedure defines how the dmd service is
+extended. Namely, it returns a @code{<dmd-service>} object that defines
+how @command{guix-daemon} is started and stopped (@pxref{dmd Services}).
+
+@item account-service-type
+This extension for this service is computed by @var{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
+a code snippet to run at ``activation time''---e.g., when the service is
+booted.
+@end table
+
+A service of this type is instantiated like this:
+
+@example
+(service guix-service-type
+ (guix-configuration
+ (build-accounts 5)
+ (use-substitutes? #f)))
+@end example
+
+The second argument to the @code{service} form is a value representing
+the parameters of this specific service instance.
+@xref{guix-configuration-type, @code{guix-configuration}}, for
+information about the @code{guix-configuration} data type.
+
+@var{guix-service-type} is quite simple because it extends other
+services but is not extensible itself.
+
+@c @subsubsubsection Extensible Service Types
+
+The service type for an @emph{extensible} service looks like this:
+
+@example
+(define udev-service-type
+ (service-type (name 'udev)
+ (extensions
+ (list (service-extension dmd-root-service-type
+ udev-dmd-service)))
+
+ (compose concatenate) ;concatenate the list of rules
+ (extend (lambda (config rules)
+ (match config
+ (($ <udev-configuration> udev initial-rules)
+ (udev-configuration
+ (udev udev) ;the udev package to use
+ (rules (append initial-rules rules)))))))))
+@end example
+
+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{dmd-root-service-type}, we see two new fields:
+
+@table @code
+@item compose
+This is the procedure to @dfn{compose} the list of extensions to
+services of this type.
+
+Services can extend the udev service by passing it lists of rules; we
+compose those extensions simply by concatenating them.
+
+@item extend
+This procedure defines how the service's value is @dfn{extended} with
+the composition of the extensions.
+
+Udev extensions are composed into a list of rules, but the udev service
+value is itself a @code{<udev-configuration>} record. So here, we
+extend that record by appending the list of rules is contains to the
+list of contributed rules.
+@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{service-extension} specifications would be ambiguous.
+
+Still here? The next section provides a reference of the programming
+interface for services.
+@node Service Reference
+@subsubsection Service Reference
+
+We have seen an overview of service types (@pxref{Service Types and
+Services}). This section provides a reference on how to manipulate
+services and service types. This interface is provided by the
+@code{(gnu services)} module.
+
+@deffn {Scheme Procedure} service @var{type} @var{value}
+Return a new service of @var{type}, a @code{<service-type>} object (see
+below.) @var{value} can be any object; it represents the parameters of
+this particular service instance.
+@end deffn
+
+@deffn {Scheme Procedure} service? @var{obj}
+Return true if @var{obj} is a service.
+@end deffn
+
+@deffn {Scheme Procedure} service-kind @var{service}
+Return the type of @var{service}---i.e., a @code{<service-type>} object.
+@end deffn
+
+@deffn {Scheme Procedure} service-parameters @var{service}
+Return the value associated with @var{service}. It represents its
+parameters.
+@end deffn
+
+Here is an example of how a service is created and manipulated:
+
+@example
+(define s
+ (service nginx-service-type
+ (nginx-configuration
+ (nginx nginx)
+ (log-directory log-directory)
+ (run-directory run-directory)
+ (file config-file))))
+
+(service? s)
+@result{} #t
+
+(eq? (service-kind s) nginx-service-type)
+@result{} #t
+@end example
+
+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}}). 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}); @code{modify-services} simply
+provides a more concise form for this common pattern.
+
+@deffn {Scheme Syntax} modify-services @var{services} @
+ (@var{type} @var{variable} => @var{body}) @dots{}
+
+Modify the services listed in @var{services} according to the given
+clauses. Each clause has the form:
+
+@example
+(@var{type} @var{variable} => @var{body})
+@end example
+
+where @var{type} is a service type, such as @var{guix-service-type}, and
+@var{variable} is an identifier that is bound within @var{body} to the
+value of the service of that @var{type}. @xref{Using the Configuration
+System}, for an example.
+
+This is a shorthand for:
+
+@example
+(map (lambda (service) @dots{}) @var{services})
+@end example
+@end deffn
+
+Next comes the programming interface for service types. This is
+something you want to know when writing new service definitions, but not
+necessarily when simply looking for ways to customize your
+@code{operating-system} declaration.
+
+@deftp {Data Type} service-type
+@cindex service type
+This is the representation of a @dfn{service type} (@pxref{Service Types
+and Services}).
+
+@table @asis
+@item @code{name}
+This is a symbol, used only to simplify inspection and debugging.
+
+@item @code{extensions}
+A non-empty list of @code{<service-extension>} objects (see below.)
+
+@item @code{compose} (default: @code{#f})
+If this is @code{#f}, then the service type denotes services that cannot
+be extended---i.e., services that do not receive ``values'' from other
+services.
+
+Otherwise, it must be a one-argument procedure. The procedure is called
+by @code{fold-services} and is passed a list of values collected from
+extensions. It must return a value that is a valid parameter value for
+the service instance.
+
+@item @code{extend} (default: @code{#f})
+If this is @code{#f}, services of this type cannot be extended.
+
+Otherwise, it must be a two-argument procedure: @code{fold-services}
+calls it, passing it the service's initial value as the first argument
+and the result of applying @code{compose} to the extension values as the
+second argument.
+@end table
+
+@xref{Service Types and Services}, for examples.
+@end deftp
+
+@deffn {Scheme Procedure} service-extension @var{target-type} @
+ @var{compute}
+Return a new extension for services of type @var{target-type}.
+@var{compute} must be a one-argument procedure: @code{fold-services}
+calls it, passing it the value associated with the service that provides
+the extension; it must return a valid value for the target service.
+@end deffn
+
+@deffn {Scheme Procedure} service-extension? @var{obj}
+Return true if @var{obj} is a service extension.
+@end deffn
+
+At the core of the service abstraction lies the @code{fold-services}
+procedure, which is responsible for ``compiling'' a list of services
+down to a single boot script. In essence, it propagates service
+extensions down the service graph, updating each node parameters on the
+way, until it reaches the root node.
+
+@deffn {Scheme Procedure} fold-services @var{services} @
+ [#:target-type @var{boot-service-type}]
+Fold @var{services} by propagating their extensions down to the root of
+type @var{target-type}; return the root service adjusted accordingly.
+@end deffn
+
+Lastly, the @code{(gnu services)} module also defines several essential
+service types, some of which are listed below.
+
+@defvr {Scheme Variable} boot-service-type
+The type of the ``boot service'', which is the root of the service
+graph.
+@end defvr
+
+@defvr {Scheme Variable} etc-service-type
+The type of the @file{/etc} service. This service can be extended by
+passing it name/file tuples such as:
+
+@example
+(list `("issue" ,(plain-file "issue" "Welcome!\n")))
+@end example
+
+In this example, the effect would be to add an @file{/etc/issue} file
+pointing to the given file.
+@end defvr
+
+@defvr {Scheme Variable} setuid-program-service-type
+Type for the ``setuid-program service''. This service collects lists of
+executable file names, passed as gexps, and adds them to the set of
+setuid-root programs on the system (@pxref{Setuid Programs}).
+@end defvr
+
+
+@node dmd Services
+@subsubsection dmd Services
+
+@cindex PID 1
+@cindex init system
+The @code{(gnu services dmd)} provides a way to define services managed
+by GNU@tie{}dmd, which is GuixSD initialization system---the first
+process that is started when the system boots, aka. PID@tie{}1
+(@pxref{Introduction,,, dmd, GNU dmd Manual}).
+
+Services in dmd can depend on each other. For instance, the SSH daemon
+may need to be started after the syslog daemon has been started, which
+in turn can only happen once all the file systems have been mounted.
+The simple operating system defined earlier (@pxref{Using the
+Configuration System}) results in a service graph like this:
+
+@image{images/dmd-graph,,5in,Typical dmd service graph.}
+
+You can actually generate such a graph for any operating system
+definition using the @command{guix system dmd-graph} command
+(@pxref{system-dmd-graph, @command{guix system dmd-graph}}).
+
+The @var{%dmd-root-service} is a service object representing PID@tie{}1,
+of type @var{dmd-root-service-type}; it can be extended by passing it
+lists of @code{<dmd-service>} objects.
+
+@deftp {Data Type} dmd-service
+The data type representing a service managed by dmd.
+
+@table @asis
+@item @code{provision}
+This is a list of symbols denoting what the service provides.
+
+These are the names that may be passed to @command{deco start},
+@command{deco status}, and similar commands (@pxref{Invoking deco,,,
+dmd, GNU dmd Manual}). @xref{Slots of services, the @code{provides}
+slot,, dmd, GNU dmd Manual}, for details.
+
+@item @code{requirements} (default: @code{'()})
+List of symbols denoting the dmd services this one depends on.
+
+@item @code{respawn?} (default: @code{#t})
+Whether to restart the service when it stops, for instance when the
+underlying process dies.
+
+@item @code{start}
+@itemx @code{stop} (default: @code{#~(const #f)})
The @code{start} and @code{stop} fields refer to dmd's facilities to
start and stop processes (@pxref{Service De- and Constructors,,, dmd,
-GNU dmd Manual}). The @code{provision} field specifies the name under
-which this service is known to dmd, and @code{documentation} specifies
-on-line documentation. Thus, the commands @command{deco start ncsd},
-@command{deco stop nscd}, and @command{deco doc nscd} will do what you
-would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
+GNU dmd Manual}). They are given as G-expressions that get expanded in
+the dmd configuration file (@pxref{G-Expressions}).
+
+@item @code{documentation}
+A documentation string, as shown when running:
+
+@example
+deco doc @var{service-name}
+@end example
+
+where @var{service-name} is one of the symbols in @var{provision}
+(@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} dmd-root-service-type
+The service type for the dmd ``root service''---i.e., PID@tie{}1.
+
+This is the service type that extensions target when they want to create
+dmd services (@pxref{Service Types and Services}, for an example). Each
+extension must pass a list of @code{<dmd-service>}.
+@end defvr
+
+@defvr {Scheme Variable} %dmd-root-service
+This service represents PID@tie{}1.
+@end defvr
@node Installing Debugging Files
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
+* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
@example
(define-public gtk+
(package
- (name "gtk+")
- (version "3.9.12")
- ...))
+ (name "gtk+")
+ (version "3.9.12")
+ ...))
(define-public gtk+-2
(package
- (name "gtk+")
- (version "2.24.20")
- ...))
+ (name "gtk+")
+ (version "2.24.20")
+ ...))
@end example
If we also wanted GTK+ 3.8.2, this would be packaged as
@example
(define-public gtk+-3.8
(package
- (name "gtk+")
- (version "3.8.2")
- ...))
+ (name "gtk+")
+ (version "3.8.2")
+ ...))
+@end example
+
+@node Synopses and Descriptions
+@subsection Synopses and Descriptions
+
+As we have seen before, each package in GNU@tie{}Guix includes a
+synopsis and a description (@pxref{Defining Packages}). Synopses and
+descriptions are important: They are what @command{guix package
+--search} searches, and a crucial piece of information to help users
+determine whether a given package suits their needs. Consequently,
+packagers should pay attention to what goes into them.
+
+Synopses must start with a capital letter and must not end with a
+period. They must not start with ``a'' or ``the'', which usually does
+not bring anything; for instance, prefer ``File-frobbing tool'' over ``A
+tool that frobs files''. The synopsis should say what the package
+is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is
+used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines
+matching a pattern''.
+
+Keep in mind that the synopsis must be meaningful for a very wide
+audience. For example, ``Manipulate alignments in the SAM format''
+might make sense for a seasoned bioinformatics researcher, but might be
+fairly unhelpful or even misleading to a non-specialized audience. It
+is a good idea to come up with a synopsis that gives an idea of the
+application domain of the package. In this example, this might give
+something like ``Manipulate nucleotide sequence alignments'', which
+hopefully gives the user a better idea of whether this is what they are
+looking for.
+
+@cindex Texinfo markup, in package descriptions
+Descriptions should take between five and ten lines. Use full
+sentences, and avoid using acronyms without first introducing them.
+Descriptions can include Texinfo markup, which is useful to introduce
+ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or
+hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you
+should be careful when using some characters for example @samp{@@} and
+curly braces which are the basic special characters in Texinfo
+(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces
+such as @command{guix package --show} take care of rendering it
+appropriately.
+
+Synopses and descriptions are translated by volunteers
+@uref{http://translationproject.org/domain/guix-packages.html, at the
+Translation Project} so that as many users as possible can read them in
+their native language. User interfaces search them and display them in
+the language specified by the current locale.
+
+Translation is a lot of work so, as a packager, please pay even more
+attention to your synopses and descriptions as every change may entail
+additional work for translators. In order to help them, it is possible
+to make recommendations or instructions visible to them by inserting
+special comments like this (@pxref{xgettext Invocation,,, gettext, GNU
+Gettext}):
+
+@example
+;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
+(description "ARandR is designed to provide a simple visual front end
+for the X11 resize-and-rotate (RandR) extension. @dots{}")
@end example
@node Acknowledgments
@chapter Acknowledgments
-Guix is based on the Nix package manager, which was designed and
+Guix is based on the @uref{http://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
management, and promoted unprecedented features, such as transactional