@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
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
+* Emacs Interface:: Using Guix from Emacs.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* GNU Distribution:: Software for your friendly GNU system.
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
-* Emacs Interface:: Package management from Emacs.
* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Invoking guix archive:: Exporting and importing store files.
+Emacs Interface
+
+* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
+* 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.
+* 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
* Defining Packages:: Defining new packages.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
+* 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
By default, files added to the store are automatically ``deduplicated'':
if a newly added file is identical to another one found in the store,
the daemon makes the new file a hard link to the other file. This can
-noticeably reduce disk usage, at the expense of slightly increasde
+noticeably reduce disk usage, at the expense of slightly increased
input/output load at the end of a build process. This option disables
this optimization.
@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 uses Fontconfig to locate and
+The majority of graphical applications use Fontconfig to locate and
load fonts and perform X11-client-side rendering. Guix's
@code{fontconfig} package looks for fonts in @file{$HOME/.guix-profile}
by default. Thus, to allow graphical applications installed with Guix
This chapter describes the main features of Guix, as well as the package
management tools it provides. Two user interfaces are provided for
-routine package management tasks: a command-line interface
-(@pxref{Invoking guix package, @code{guix package}}), and a visual user
-interface in Emacs (@pxref{Emacs Interface}).
+routine package management tasks: A command-line interface described below
+(@pxref{Invoking guix package, @code{guix package}}), as well as a visual user
+interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}).
@menu
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
-* Emacs Interface:: Package management from Emacs.
* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
package, which may be insufficient when needing a specific output of a
multiple-output package.
+@item --install-from-file=@var{file}
+@itemx -f @var{file}
+Install the package that the code within @var{file} evaluates to.
+
+As an example, @var{file} might contain a definition like this
+(@pxref{Defining Packages}):
+
+@example
+@verbatiminclude package-hello.scm
+@end example
+
+Developers may find it useful to include such a @file{package.scm} file
+in the root of their project's source tree that can be used to test
+development snapshots and create reproducible development environments
+(@pxref{Invoking guix environment}).
+
@item --remove=@var{package} @dots{}
@itemx -r @var{package} @dots{}
Remove the specified @var{package}s.
processes, it supports all the common build options that @command{guix
build} supports (@pxref{Invoking guix build, common build options}).
-@include emacs.texi
-
@node Substitutes
@section Substitutes
(@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
output, whereas the GUIs are in a separate output. This allows users
who do not need the GUIs to save space. The @command{guix size} command
can help find out about such situations (@pxref{Invoking guix size}).
+@command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
There are several such multiple-output packages in the GNU distribution.
Other conventional output names include @code{lib} for libraries and
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.
@dfn{transitive closure} of the store files.
@xref{Invoking guix size}, for a tool to profile the size of an
-element's closure.
+element's closure. @xref{Invoking guix graph}, for a tool to visualize
+the graph of references.
@end table
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:
same options that can be passed to the @command{guix build} command
(@pxref{Invoking guix build, common build options}).
+@c *********************************************************************
+@include emacs.texi
@c *********************************************************************
@node Programming Interface
#:use-module (guix packages)
#:use-module (guix download)
#:use-module (guix build-system gnu)
- #:use-module (guix licenses))
+ #:use-module (guix licenses)
+ #:use-module (gnu packages gawk))
(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)))
Which Perl package is used can be specified with @code{#:perl}.
@end defvr
+@defvr {Scheme Variable} r-build-system
+This variable is exported by @code{(guix build-system r)}. It
+implements the build procedure used by @uref{http://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
+are run after installation using the R function
+@code{tools::testInstalledPackage}.
+@end defvr
+
@defvr {Scheme Variable} ruby-build-system
This variable is exported by @code{(guix build-system ruby)}. It
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
+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}
command can be specified with the @code{#:gem-flags} parameter.
Conceptually, the @dfn{store} is where derivations that have been
successfully built are stored---by default, under @file{/gnu/store}.
Sub-directories in the store are referred to as @dfn{store paths}. The
-store has an associated database that contains information such has the
+store has an associated database that contains information such as the
store paths referred to by each store path, and the list of @emph{valid}
store paths---paths that result from a successful build.
processes that use them.
@end itemize
+@cindex lowering, of high-level objects in gexps
This mechanism is not limited to package and derivation
objects: @dfn{compilers} able to ``lower'' other high-level objects to
-derivations can be defined, such that these objects can also be inserted
+derivations or files in the store can be defined,
+such that these objects can also be inserted
into gexps. For example, a useful type of high-level object that can be
inserted in a gexp is ``file-like objects'', which make it easy to
add files to the store and refer to them in
[#:module-path @var{%load-path}] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:leaked-env-vars #f] @
+ [#:script-name (string-append @var{name} "-builder")] @
[#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
Return a derivation @var{name} that runs @var{exp} (a gexp) with
-@var{guile-for-build} (a derivation) on @var{system}. When @var{target}
-is true, it is used as the cross-compilation target triplet for packages
-referred to by @var{exp}.
+@var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
+stored in a file called @var{script-name}. When @var{target} is true,
+it is used as the cross-compilation target triplet for packages referred
+to by @var{exp}.
Make @var{modules} available in the evaluation context of @var{exp};
@var{modules} is a list of names of Guile modules searched in
@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
@code{(guix build @dots{})} name space.
+@cindex lowering, of high-level objects in gexps
+Internally, high-level objects are @dfn{lowered}, using their compiler,
+to either derivations or store items. For instance, lowering a package
+yields a derivation, and lowering a @code{plain-file} yields a store
+item. This is achieved using the @code{lower-object} monadic procedure.
+
+@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
+ [#:target #f]
+Return as a value in @var{%store-monad} the derivation or store item
+corresponding to @var{obj} for @var{system}, cross-compiling for
+@var{target} if @var{target} is true. @var{obj} must be an object that
+has an associated gexp compiler, such as a @code{<package>}.
+@end deffn
+
@c *********************************************************************
@node Utilities
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
+* 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.
collector root.
@item --log-file
-Return the build log file names for the given
+Return the build log file names or URLs for the given
@var{package-or-derivation}s, or raise an error if build logs are
missing.
guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
@end example
+If a log is unavailable locally, and unless @code{--no-substitutes} is
+passed, the command looks for a corresponding log on one of the
+substitute servers (as specified with @code{--substitute-urls}.)
+
+So for instance, let's say you want to see the build log of GDB on MIPS
+but you're actually on an @code{x86_64} machine:
+
+@example
+$ guix build --log-file gdb -s mips64el-linux
+http://hydra.gnu.org/log/@dots{}-gdb-7.10
+@end example
+You can freely access a huge library of build logs!
@end table
@cindex common build options
guix import pypi itsdangerous
@end example
+@item gem
+@cindex gem
+Import meta-data from @uref{https://rubygems.org/,
+RubyGems}@footnote{This functionality requires Guile-JSON to be
+installed. @xref{Requirements}.}. Information is taken from the
+JSON-formatted description available at @code{rubygems.org} and includes
+most relevant information, including runtime dependencies. There are
+some caveats, however. The meta-data doesn't distinguish between
+synopses and descriptions, so the same string is used for both fields.
+Additionally, the details of non-Ruby dependencies required to build
+native extensions is unavailable and left as an exercise to the
+packager.
+
+The command below imports meta-data for the @code{rails} Ruby package:
+
+@example
+guix import gem rails
+@end example
+
@item cpan
@cindex CPAN
Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
guix import cpan Acme::Boolean
@end example
+@item cran
+@cindex CRAN
+Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the
+central repository for the @uref{http://r-project.org, GNU@tie{}R
+statistical and graphical environment}.
+
+Information is extracted from the HTML package description.
+
+The command command below imports meta-data for the @code{Cairo}
+R package:
+
+@example
+guix import cran Cairo
+@end example
+
@item nix
Import meta-data from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
@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,
+use of tabulations, etc.
@end table
The general syntax is:
@end table
+@node Invoking guix graph
+@section Invoking @command{guix graph}
+
+@cindex DAG
+Packages and their dependencies form a @dfn{graph}, specifically a
+directed acyclic graph (DAG). It can quickly become difficult to have a
+mental model of the package DAG, so the @command{guix graph} command is
+here to provide a visual representation of the DAG. @command{guix
+graph} emits a DAG representation in the input format of
+@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+directly to Graphviz's @command{dot} command, for instance. The general
+syntax is:
+
+@example
+guix graph @var{options} @var{package}@dots{}
+@end example
+
+For example, the following command generates a PDF file representing the
+package DAG for the GNU@tie{}Core Utilities, showing its build-time
+dependencies:
+
+@example
+guix graph coreutils | dot -Tpdf > dag.pdf
+@end example
+
+The output looks like this:
+
+@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
+
+Nice little graph, no?
+
+But there's more than one graph! The one above is concise: it's the
+graph of package objects, omitting implicit inputs such as GCC, libc,
+grep, etc. It's often useful to have such a concise graph, but
+sometimes you want to see more details. @command{guix graph} supports
+several types of graphs, allowing you to choose the level of details:
+
+@table @code
+@item package
+This is the default type, the one we used above. It shows the DAG of
+package objects, excluding implicit dependencies. It is concise, but
+filters out many details.
+
+@item bag-emerged
+This is the package DAG, @emph{including} implicit inputs.
+
+For instance, the following command:
+
+@example
+guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
+@end example
+
+... yields this bigger graph:
+
+@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
+
+At the bottom of the graph, we see all the implicit inputs of
+@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
+
+Now, note that the dependencies of those implicit inputs---that is, the
+@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
+here, for conciseness.
+
+@item bag
+Similar to @code{bag-emerged}, but this time including all the bootstrap
+dependencies.
+
+@item derivations
+This is the most detailed representation: It shows the DAG of
+derivations (@pxref{Derivations}) and plain store items. Compared to
+the above representation, many additional nodes are visible, including
+builds scripts, patches, Guile modules, etc.
+
+@end table
+
+All the above types correspond to @emph{build-time dependencies}. The
+following graph type represents the @emph{run-time dependencies}:
+
+@table @code
+@item references
+This is the graph of @dfn{references} of a package output, as returned
+by @command{guix gc --references} (@pxref{Invoking guix gc}).
+
+If the given package output is not available in the store, @command{guix
+graph} attempts to obtain dependency information from substitutes.
+@end table
+
+The available options are the following:
+
+@table @option
+@item --type=@var{type}
+@itemx -t @var{type}
+Produce a graph output of @var{type}, where @var{type} must be one of
+the values listed above.
+
+@item --list-types
+List the supported graph types.
+
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the package @var{expr} evaluates to.
+
+This is useful to precisely refer to a package, as in this example:
+
+@example
+guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
+@end example
+@end table
+
+
@node Invoking guix environment
@section Invoking @command{guix environment}
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
A @dfn{locale} defines cultural conventions for a particular language
and region of the world (@pxref{Locales,,, libc, The GNU C Library
Reference Manual}). Each locale has a name that typically has the form
-@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
+@code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
@code{fr_LU.utf8} designates the locale for the French language, with
cultural conventions from Luxembourg, and using the UTF-8 encoding.
(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.
@end deftp
@defvr {Scheme Variable} %default-locale-definitions
-An arbitrary list of commonly used locales, used as the default value of
-the @code{locale-definitions} field of @code{operating-system}
+An arbitrary list of commonly used UTF-8 locales, used as the default
+value of the @code{locale-definitions} field of @code{operating-system}
declarations.
+
+@cindex locale name
+@cindex normalized codeset in locale names
+These locale definitions use the @dfn{normalized codeset} for the part
+that follows the dot in the name (@pxref{Using gettextized software,
+normalized codeset,, libc, The GNU C Library Reference Manual}). So for
+instance it has @code{uk_UA.utf8} but @emph{not}, say,
+@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
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
+* Web Services:: Web servers.
* Various Services:: Other services.
@end menu
@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 or a monadic 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.
+
+@table @asis
+@item @code{guix} (default: @var{guix})
+The Guix package to use.
-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.
+@item @code{build-group} (default: @code{"guixbuild"})
+Name of the group for build user accounts.
-If @var{use-substitutes?} is false, the daemon is run with
-@option{--no-substitutes} (@pxref{Invoking guix-daemon,
-@option{--no-substitutes}}).
+@item @code{build-accounts} (default: @code{10})
+Number of build user accounts to create.
-Finally, @var{extra-options} is a list of additional command-line options
-passed to @command{guix-daemon}.
+@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,
-an NTP client (@pxref{Networking Services}), the Avahi
-daemon, and has the name service switch service configured to be able to
-use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
+the @code{elogind} login and seat manager, the Polkit privilege service,
+the GeoClue location service, an NTP client (@pxref{Networking
+Services}), the Avahi daemon, and has the name service switch service
+configured to be able to use @code{nss-mdns} (@pxref{Name Service
+Switch, mDNS}).
@end defvr
The @var{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-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} upower-service [#:upower @var{upower}] @
+@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
+are logged in, know what kind of sessions they have open, suspend the
+system, inhibit system suspend, reboot the system, and other tasks.
+
+Elogind handles most system-level power events for a computer, for
+example suspending the system when a lid is closed, or shutting it down
+when the power button is pressed.
+
+The @var{config} keyword argument specifies the configuration for
+elogind, and should be the result of a @code{(elogind-configuration
+(@var{parameter} @var{value})...)} invocation. Available parameters and
+their default values are:
+
+@table @code
+@item kill-user-processes?
+@code{#f}
+@item kill-only-users
+@code{()}
+@item kill-exclude-users
+@code{("root")}
+@item inhibit-delay-max-seconds
+@code{5}
+@item handle-power-key
+@code{poweroff}
+@item handle-suspend-key
+@code{suspend}
+@item handle-hibernate-key
+@code{hibernate}
+@item handle-lid-switch
+@code{suspend}
+@item handle-lid-switch-docked
+@code{ignore}
+@item power-key-ignore-inhibited?
+@code{#f}
+@item suspend-key-ignore-inhibited?
+@code{#f}
+@item hibernate-key-ignore-inhibited?
+@code{#f}
+@item lid-switch-ignore-inhibited?
+@code{#t}
+@item holdoff-timeout-seconds
+@code{30}
+@item idle-action
+@code{ignore}
+@item idle-action-seconds
+@code{(* 30 60)}
+@item runtime-directory-size-percent
+@code{10}
+@item runtime-directory-size
+@code{#f}
+@item remove-ipc?
+@code{#t}
+@item suspend-state
+@code{("mem" "standby" "freeze")}
+@item suspend-mode
+@code{()}
+@item hibernate-state
+@code{("disk")}
+@item hibernate-mode
+@code{("platform" "shutdown")}
+@item hybrid-sleep-state
+@code{("disk")}
+@item hybrid-sleep-mode
+@code{("suspend" "platform" "shutdown")}
+@end table
+@end deffn
+
+@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
+system administrators to grant access to privileged operations in a
+structured way. For example, polkit rules can allow a logged-in user
+whose session is active to shut down the machine, if there are no other
+users active.
+@end deffn
+
+@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
site} for more information.
@end deffn
+@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
+Return an configuration allowing an application to access GeoClue
+location data. @var{name} is the Desktop ID of the application, without
+the @code{.desktop} part. If @var{allowed?} is true, the application
+will have access to location information by default. The boolean
+@var{system?} value indicates that an application is a system component
+or not. Finally @var{users} is a list of UIDs of all users for which
+this application is allowed location info access. An empty users list
+means that all users are allowed.
+@end deffn
+
+@defvr {Scheme Variable} %standard-geoclue-applications
+The standard list of well-known GeoClue application configurations,
+granting authority to GNOME's date-and-time utility to ask for the
+current location in order to set the time zone, and allowing the Firefox
+(IceCat) and Epiphany web browsers to request location information.
+Firefox and Epiphany both query the user before allowing a web page to
+know the user's location.
+@end defvr
+
+@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
+ [#:whitelist '()] @
+ [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
+ [#:submit-data? #f]
+ [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
+ [#:submission-nick "geoclue"] @
+ [#:applications %standard-geoclue-applications]
+Return a service that runs the GeoClue location service. This service
+provides a D-Bus interface to allow applications to request access to a
+user's physical location, and optionally to add information to online
+location databases. See
+@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
+web site} for more information.
+@end deffn
+
@node Database Services
@subsubsection Database Services
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.
@var{data-directory}.
@end deffn
+@node Web Services
+@subsubsection Web Services
+
+The @code{(gnu services web)} module provides the following service:
+
+@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
+ [#:log-directory ``/var/log/nginx''] @
+ [#:run-directory ``/var/run/nginx''] @
+ [#:config-file]
+
+Return a service that runs @var{nginx}, the nginx web server.
+
+The nginx daemon loads its runtime configuration from @var{config-file}.
+Log files are written to @var{log-directory} and temporary runtime data
+files are written to @var{run-directory}. For proper operation, these
+arguments should match what is in @var{config-file} to ensure that the
+directories are created when the service is activated.
+
+@end deffn
+
@node Various Services
@subsubsection Various Services
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
HCoop / jackhill / guix / guix.git / blobdiff