X-Git-Url: https://git.hcoop.net/jackhill/guix/guix.git/blobdiff_plain/ce45eb4c385e3b473bc6746a8b58452865f69977..8462a03f2861a1b3ed33e99a6f5a886bb9093846:/doc/guix.texi

diff --git a/doc/guix.texi b/doc/guix.texi
index 50a7084fec..4269d4fa5f 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -83,6 +83,7 @@ package management tool written for the GNU system.
 Installation
 
 * Requirements::                Software needed to build and run Guix.
+* Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 
@@ -120,6 +121,7 @@ Utilities
 * Invoking guix refresh::       Updating package definitions.
 * Invoking guix lint::          Finding errors in package definitions.
 * Invoking guix environment::   Setting up development environments.
+* Invoking guix publish::       Sharing substitutes.
 
 GNU Distribution
 
@@ -153,15 +155,16 @@ Services
 * Base Services::               Essential system services.
 * Networking Services::         Network setup, SSH daemon, etc.
 * X Window::                    Graphical display.
+* Various Services::            Other services.
 
 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.
-* Python Modules::       Taming the snake.
-* Perl Modules::         Little pearls.
-* Fonts::                Fond of fonts.
+* Software Freedom::            What may go into the distribution.
+* Package Naming::              What's in a name?
+* Version Numbers::             When the name is not enough.
+* Python Modules::              Taming the snake.
+* Perl Modules::                Little pearls.
+* Fonts::                       Fond of fonts.
 
 @end detailmenu
 @end menu
@@ -233,19 +236,91 @@ manager, which can be done on top of a running GNU/Linux system.  If,
 instead, you want to install the complete GNU operating system,
 @pxref{System Installation}.
 
-The build procedure for Guix is the same as for other GNU software, and
-is not covered here.  Please see the files @file{README} and
-@file{INSTALL} in the Guix source tree for additional details.
-
 @menu
+* Binary Installation::         Getting Guix running in no time!
 * Requirements::                Software needed to build and run Guix.
+* Running the Test Suite::      Testing Guix.
 * Setting Up the Daemon::       Preparing the build daemon's environment.
 * Invoking guix-daemon::        Running the build daemon.
 @end menu
 
+@node Binary Installation
+@section Binary Installation
+
+This section describes how to install Guix on an arbitrary system from a
+self-contained tarball providing binaries for Guix and for all its
+dependencies.  This is often quicker than installing from source, which
+is described in the next sections.  The only requirement is to have
+GNU@tie{}tar and Xz.
+
+Installing goes along these lines:
+
+@enumerate
+@item
+Download the binary tarball from
+@code{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
+usual, make sure to download the associated @file{.sig} file and to
+verify the authenticity of the tarball against it!}, where @var{system}
+is @code{x86_64-linux} for an @code{x86_64} machine already running the
+kernel Linux, and so on.
+
+@item
+As @code{root}, run:
+
+@example
+# cd /
+# tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
+@end example
+
+This creates @file{/gnu/store} (@pxref{The Store}), @file{/var/guix},
+and @file{/root/.guix-profile}.  @file{/root/.guix-profile} is a
+ready-to-use profile for @code{root} where Guix is installed.
+
+Do @emph{not} unpack the tarball on a working Guix system since that
+would overwrite its own essential files.
+
+@item
+Set up the daemon as explained below (@pxref{Setting Up the Daemon}), and
+run it:
+
+@example
+# /root/.guix-profile/bin/guix-daemon --build-users-group=guix-builder
+@end example
+
+@item
+Make the @command{guix} command available to other users on the machine,
+for instance with:
+
+@example
+# mkdir -p /usr/local/bin
+# cd /usr/local/bin
+# ln -s /root/.guix-profile/bin/guix
+@end example
+@end enumerate
+
+And that's it!
+
+The @code{guix} package must remain available in @code{root}'s
+profile, or it would become subject to garbage collection---in which
+case you would find yourself badly handicapped by the lack of the
+@command{guix} command.
+
+The tarball in question can be (re)produced simply by running the
+following command in the Guix source tree:
+
+@example
+make guix-binary.@var{system}.tar.xz
+@end example
+
+
 @node Requirements
 @section Requirements
 
+This section lists requirements when building Guix from source.  The
+build procedure for Guix is the same as for other GNU software, and is
+not covered here.  Please see the files @file{README} and @file{INSTALL}
+in the Guix source tree for additional details.
+
 GNU Guix depends on the following packages:
 
 @itemize
@@ -295,6 +370,32 @@ located, among other things.  The default values for Nix are
 Note that @code{--disable-daemon} is not required if
 your goal is to share the store with Nix.
 
+@node Running the Test Suite
+@section Running the Test Suite
+
+After a successful @command{configure} and @code{make} run, it is a good
+idea to run the test suite.  It can help catch issues with the setup or
+environment, or bugs in Guix itself---and really, reporting test
+failures is a good way to help improve the software.  To run the test
+suite, type:
+
+@example
+make check
+@end example
+
+Test cases can run in parallel: you can use the @code{-j} option of
+GNU@tie{}make to speed things up.  The first run may take a few minutes
+on a recent machine; subsequent runs will be faster because the store
+that is created for test purposes will already have various things in
+cache.
+
+Upon failure, please email @email{bug-guix@@gnu.org} and attach the
+@file{test-suite.log} file.  When @file{tests/@var{something}.scm}
+fails, please also attach the @file{@var{something}.log} file available
+in the top-level build directory.  Please specify the Guix version being
+used as well as version numbers of the dependencies
+(@pxref{Requirements}) in your message.
+
 @node Setting Up the Daemon
 @section Setting Up the Daemon
 
@@ -308,7 +409,8 @@ goes through the daemon.  For instance, command-line tools such as
 daemon (@i{via} remote procedure calls) to instruct it what to do.
 
 The following sections explain how to prepare the build daemon's
-environment.
+environment.  Also @ref{Substitutes}, for information on how to allow
+the daemon to download pre-built binaries.
 
 @menu
 * Build Environment Setup::     Preparing the isolated build environment.
@@ -354,15 +456,6 @@ Bash syntax and the @code{shadow} commands):
   done
 @end example
 
-The @file{/gnu/store} directory (or whichever was specified with the
-@code{--with-store-dir} option) must have ownership and permissions as
-follows:
-
-@example
-# chgrp guix-builder /gnu/store
-# chmod 1775 /gnu/store
-@end example
-
 @noindent
 The @code{guix-daemon} program may then be run as @code{root} with:
 
@@ -870,7 +963,10 @@ Install the specified @var{package}s.
 
 Each @var{package} may specify either a simple package name, such as
 @code{guile}, or a package name followed by a hyphen and version number,
-such as @code{guile-1.8.8}.  If no version number is specified, the
+such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
+case, the newest version prefixed by @code{1.8} is selected.)
+
+If no version number is specified, the
 newest available version will be selected.  In addition, @var{package}
 may contain a colon, followed by the name of one of the outputs of the
 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
@@ -925,13 +1021,23 @@ and/or output name in addition to the package name.  For instance,
 @itemx -u [@var{regexp} @dots{}]
 Upgrade all the installed packages.  If one or more @var{regexp}s are
 specified, upgrade only installed packages whose name matches a
-@var{regexp}.
+@var{regexp}.  Also see the @code{--do-not-upgrade} option below.
 
 Note that this upgrades package to the latest version of packages found
 in the distribution currently installed.  To update your distribution,
 you should regularly run @command{guix pull} (@pxref{Invoking guix
 pull}).
 
+@item --do-not-upgrade[=@var{regexp} @dots{}]
+When used together with the @code{--upgrade} option, do @emph{not}
+upgrade any packages whose name matches a @var{regexp}.  For example, to
+upgrade all packages in the current profile except those containing the
+substring ``emacs'':
+
+@example
+$ guix package --upgrade . --do-not-upgrade emacs
+@end example
+
 @item --roll-back
 Roll back to the previous @dfn{generation} of the profile---i.e., undo
 the last transaction.
@@ -999,7 +1105,7 @@ availability of packages:
 
 @item --search=@var{regexp}
 @itemx -s @var{regexp}
-List the available packages whose synopsis or description matches
+List the available packages whose name, synopsis, or description matches
 @var{regexp}.  Print all the meta-data of matching packages in
 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
 GNU recutils manual}).
@@ -1065,7 +1171,7 @@ the store.
 
 @item --list-available[=@var{regexp}]
 @itemx -A [@var{regexp}]
-List packages currently available in the software distribution
+List packages currently available in the distribution for this system
 (@pxref{GNU Distribution}).  When @var{regexp} is specified, list only
 installed packages whose name matches @var{regexp}.
 
@@ -1121,9 +1227,8 @@ When @var{pattern} is specified, delete the matching generations.  When
 specified duration match.  For instance, @code{--delete-generations=1m}
 deletes generations that are more than one month old.
 
-If the current generation matches, it is deleted atomically---i.e., by
-switching to the previous available generation.  Note that the zeroth
-generation is never deleted.
+If the current generation matches, it is @emph{not} deleted.  Also, the
+zeroth generation is never deleted.
 
 Note that deleting generations prevents roll-back to them.
 Consequently, this command must be used with care.
@@ -1294,7 +1399,9 @@ guix package}).
 @cindex garbage collector
 Packages that are installed but not used may be @dfn{garbage-collected}.
 The @command{guix gc} command allows users to explicitly run the garbage
-collector to reclaim space from the @file{/gnu/store} directory.
+collector to reclaim space from the @file{/gnu/store} directory.  It is
+the @emph{only} way to remove files from @file{/gnu/store}---removing
+files or directories manually may break it beyond repair!
 
 The garbage collector has a set of known @dfn{roots}: any file under
 @file{/gnu/store} reachable from a root is considered @dfn{live} and
@@ -1894,12 +2001,20 @@ parameter.
 
 @defvr {Scheme Variable} perl-build-system
 This variable is exported by @code{(guix build-system perl)}.  It
-implements the standard build procedure for Perl packages, which
-consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
-followed by @code{make} and @code{make install}.
-
-The initial @code{perl Makefile.PL} invocation passes flags specified by
-the @code{#:make-maker-flags} parameter.
+implements the standard build procedure for Perl packages, which either
+consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
+followed by @code{Build} and @code{Build install}; or in running
+@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
+@code{make} and @code{make install}; depending on which of
+@code{Build.PL} or @code{Makefile.PL} is present in the package
+distribution.  Preference is given to the former if both @code{Build.PL}
+and @code{Makefile.PL} exist in the package distribution.  This
+preference can be reversed by specifying @code{#t} for the
+@code{#:make-maker?} parameter.
+
+The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
+passes flags specified by the @code{#:make-maker-flags} or
+@code{#:module-build-flags} parameter, respectively.
 
 Which Perl package is used can be specified with @code{#:perl}.
 @end defvr
@@ -1925,6 +2040,25 @@ Python package is used to run the script can be specified with the
 @code{#:python} parameter.
 @end defvr
 
+@defvr {Scheme Variable} haskell-build-system
+This variable is exported by @code{(guix build-system haskell)}.  It
+implements the Cabal build procedure used by Haskell packages, which
+involves running @code{runhaskell Setup.hs configure
+--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
+Instead of installing the package by running @code{runhaskell Setup.hs
+install}, to avoid trying to register libraries in the read-only
+compiler store directory, the build system uses @code{runhaskell
+Setup.hs copy}, followed by @code{runhaskell Setup.hs register}.  In
+addition, the build system generates the package documentation by
+running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
+is passed.  Optional Haddock parameters can be passed with the help of
+the @code{#:haddock-flags} parameter.  If the file @code{Setup.hs} is
+not found, the build system looks for @code{Setup.lhs} instead.
+
+Which Haskell compiler is used can be specified with the @code{#:haskell}
+parameter which defaults to @code{ghc}. 
+@end defvr
+
 Lastly, for packages that do not need anything as sophisticated, a
 ``trivial'' build system is provided.  It is trivial in the sense that
 it provides basically no support: it does not pull any implicit inputs,
@@ -2453,8 +2587,9 @@ Gexps are meant to be written to a file and run or manipulated by other
 processes.
 
 @item
-When a package or derivation is unquoted inside a gexp, the result is as
-if its output file name had been introduced.
+When a high-level object such as a package or derivation is unquoted
+inside a gexp, the result is as if its output file name had been
+introduced.
 
 @item
 Gexps carry information about the packages or derivations they refer to,
@@ -2462,6 +2597,14 @@ and these dependencies are automatically added as inputs to the build
 processes that use them.
 @end itemize
 
+Actually 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
+into gexps.  Another useful type of high-level object that can be
+inserted in a gexp is @dfn{local files}, which allows files from the
+local file system to be added to the store and referred to by
+derivations and such (see @code{local-file} below.)
+
 To illustrate the idea, here is an example of a gexp:
 
 @example
@@ -2469,7 +2612,7 @@ To illustrate the idea, here is an example of a gexp:
   #~(begin
       (mkdir #$output)
       (chdir #$output)
-      (symlink (string-append #$coreutils "/bin/ls") 
+      (symlink (string-append #$coreutils "/bin/ls")
                "list-files")))
 @end example
 
@@ -2521,24 +2664,24 @@ or more of the following forms:
 @table @code
 @item #$@var{obj}
 @itemx (ungexp @var{obj})
-Introduce a reference to @var{obj}.  @var{obj} may be a package or a
+Introduce a reference to @var{obj}.  @var{obj} may have one of the
+supported types, for example a package or a
 derivation, in which case the @code{ungexp} form is replaced by its
 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
 
-If @var{obj} is a list, it is traversed and any package or derivation
-references are substituted similarly.
+If @var{obj} is a list, it is traversed and references to supported
+objects are substituted similarly.
 
 If @var{obj} is another gexp, its contents are inserted and its
 dependencies are added to those of the containing gexp.
 
 If @var{obj} is another kind of object, it is inserted as is.
 
-@item #$@var{package-or-derivation}:@var{output}
-@itemx (ungexp @var{package-or-derivation} @var{output})
+@item #$@var{obj}:@var{output}
+@itemx (ungexp @var{obj} @var{output})
 This is like the form above, but referring explicitly to the
-@var{output} of @var{package-or-derivation}---this is useful when
-@var{package-or-derivation} produces multiple outputs (@pxref{Packages
-with Multiple Outputs}).
+@var{output} of @var{obj}---this is useful when @var{obj} produces
+multiple outputs (@pxref{Packages with Multiple Outputs}).
 
 @item #+@var{obj}
 @itemx #+@var{obj}:output
@@ -2623,6 +2766,20 @@ refer to.  Any reference to another store item will lead to a build error.
 The other arguments are as for @code{derivation} (@pxref{Derivations}).
 @end deffn
 
+@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
+   [#:recursive? #t]
+Return an object representing local file @var{file} to add to the store; this
+object can be used in a gexp.  @var{file} will be added to the store under @var{name}--by
+default the base name of @var{file}.
+
+When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
+designates a flat file and @var{recursive?} is true, its contents are added, and its
+permission bits are kept.
+
+This is the declarative counterpart of the @code{interned-file} monadic
+procedure (@pxref{The Store Monad, @code{interned-file}}).
+@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.
@@ -2660,8 +2817,9 @@ or a subset thereof.
 @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
-strings, packages, derivations, and store file names; the resulting
-store file holds references to all these.
+strings, objects of any type that can be used in a gexp: packages,
+derivations, local file objects, etc.  The resulting store file holds
+references to all these.
 
 This variant should be preferred over @code{text-file} anytime the file
 to create will reference items from the store.  This is typically the
@@ -2704,6 +2862,7 @@ programming interface of Guix in a convenient way.
 * Invoking guix refresh::       Updating package definitions.
 * Invoking guix lint::          Finding errors in package definitions.
 * Invoking guix environment::   Setting up development environments.
+* Invoking guix publish::       Sharing substitutes.
 @end menu
 
 @node Invoking guix build
@@ -3081,9 +3240,10 @@ guix import pypi itsdangerous
 Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
 Information is taken from the JSON-formatted meta-data provided through
 @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
-relevant information.  License information should be checked closely.
-Package dependencies are included but may in some cases needlessly
-include core Perl modules.
+relevant information, such as module dependencies.  License information
+should be checked closely.  If Perl is available in the store, then the
+@code{corelist} utility will be used to filter core modules out of the
+list of dependencies.
 
 The command command below imports meta-data for the @code{Acme::Boolean}
 Perl module:
@@ -3112,6 +3272,37 @@ bound to the @code{libreoffice} top-level attribute):
 @example
 guix import nix ~/path/to/nixpkgs libreoffice
 @end example
+
+@item hackage
+@cindex hackage
+Import meta-data from Haskell community's central package archive
+@uref{https://hackage.haskell.org/, Hackage}.  Information is taken from
+Cabal files and includes all the relevant information, including package
+dependencies.
+
+Specific command-line options are:
+
+@table @code
+@item --no-test-dependencies
+@itemx -t
+Do not include dependencies only required to run the test suite.
+@end table
+
+The command below imports meta-data for the latest version of the
+@code{HTTP} Haskell package without including test dependencies:
+
+@example
+guix import hackage -t HTTP
+@end example
+
+A specific package version may optionally be specified by following the
+package name by a hyphen and a version number as in the following example:
+
+@example
+guix import hackage mtl-2.1.3.1
+@end example
+
+Currently only indentation structured Cabal files are supported.
 @end table
 
 The structure of the @command{guix import} code is modular.  It would be
@@ -3178,7 +3369,7 @@ In addition, @command{guix refresh} can be passed one or more package
 names, as in this example:
 
 @example
-guix refresh -u emacs idutils
+guix refresh -u emacs idutils gcc-4.8.4
 @end example
 
 @noindent
@@ -3365,6 +3556,54 @@ environment.
 It also supports all of the common build options that @command{guix
 build} supports (@pxref{Invoking guix build, common build options}).
 
+@node Invoking guix publish
+@section Invoking @command{guix publish}
+
+The purpose of @command{guix publish} is to enable users to easily share
+their store with others.  When @command{guix publish} runs, it spawns an
+HTTP server which allows anyone with network access to obtain
+substitutes from it.  This means that any machine running Guix can also
+act as if it were a build farm, since the HTTP interface is
+Hydra-compatible.
+
+For security, each substitute is signed, allowing recipients to check
+their authenticity and integrity (@pxref{Substitutes}).  Because
+@command{guix publish} uses the system's signing key, which is only
+readable by the system administrator, it must run as root.
+
+The general syntax is:
+
+@example
+guix publish @var{options}@dots{}
+@end example
+
+Running @command{guix publish} without any additional arguments will
+spawn an HTTP server on port 8080:
+
+@example
+guix publish
+@end example
+
+Once a publishing server has been authorized (@pxref{Invoking guix
+archive}), the daemon may download substitutes from it:
+
+@example
+guix-daemon --substitute-urls=http://example.org:8080
+@end example
+
+The following options are available:
+
+@table @code
+@item --port=@var{port}
+@itemx -p @var{port}
+Listen for HTTP requests on @var{port}.
+
+@item --repl[=@var{port}]
+@itemx -r [@var{port}]
+Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
+Reference Manual}) on @var{port} (37146 by default).
+@end table
+
 @c *********************************************************************
 @node GNU Distribution
 @chapter GNU Distribution
@@ -3982,8 +4221,9 @@ variables.
 
 @defvr {Scheme Variable} %base-file-systems
 These are essential file systems that are required on normal systems,
-such as @var{%devtmpfs-file-system} (see below.)  Operating system
-declarations should always contain at least these.
+such as @var{%devtmpfs-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
@@ -4005,6 +4245,16 @@ memory sharing across processes (@pxref{Memory-mapped I/O,
 @code{shm_open},, libc, The GNU C Library Reference Manual}).
 @end defvr
 
+@defvr {Scheme Variable} %immutable-store
+This file system performs a read-only ``bind mount'' of
+@file{/gnu/store}, making it read-only for all the users including
+@code{root}.  This prevents against accidental modification by software
+running as @code{root} or by system administrators.
+
+The daemon itself is still able to write to the store: it remounts it
+read-write in its own ``name space.''
+@end defvr
+
 @defvr {Scheme Variable} %binary-format-file-system
 The @code{binfmt_misc} file system, which allows handling of arbitrary
 executable file types to be delegated to user space.  This requires the
@@ -4083,7 +4333,9 @@ command, from the same-named package.  This relies on the
 @node User Accounts
 @subsection User Accounts
 
-User accounts are specified with the @code{user-account} form:
+User accounts and groups are entirely managed through the
+@code{operating-system} declaration.  They are specified with the
+@code{user-account} and @code{user-group} forms:
 
 @example
 (user-account
@@ -4097,6 +4349,14 @@ User accounts are specified with the @code{user-account} form:
   (home-directory "/home/alice"))
 @end example
 
+When booting or upon completion of @command{guix system reconfigure},
+the system ensures that only the user accounts and groups specified in
+the @code{operating-system} declaration exist, and with the specified
+properties.  Thus, account or group creations or modifications made by
+directly invoking commands such as @command{useradd} are lost upon
+reconfiguration or reboot.  This ensures that the system remains exactly
+as declared.
+
 @deftp {Data Type} user-account
 Objects of this type represent user accounts.  The following members may
 be specified:
@@ -4136,7 +4396,9 @@ graphical login managers do not list them.
 @item @code{password} (default: @code{#f})
 You would normally leave this field to @code{#f}, initialize user
 passwords as @code{root} with the @command{passwd} command, and then let
-users change it with @command{passwd}.
+users change it with @command{passwd}.  Passwords set with
+@command{passwd} are of course preserved across reboot and
+reconfiguration.
 
 If you @emph{do} want to have a preset password for an account, then
 this field must contain the encrypted password, as a string.
@@ -4307,6 +4569,7 @@ declaration.
 * Base Services::               Essential system services.
 * Networking Services::         Network setup, SSH daemon, etc.
 * X Window::                    Graphical display.
+* Various Services::            Other services.
 @end menu
 
 @node Base Services
@@ -4363,7 +4626,8 @@ the ``message of the day''.
 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.
+name service switch (NSS) modules needed by nscd.  @xref{Name Service
+Switch}, for an example.
 @end deffn
 
 @defvr {Scheme Variable} %nscd-default-configuration
@@ -4444,8 +4708,9 @@ external name servers do not even need to be queried.
 @end defvr
 
 
-@deffn {Monadic Procedure} syslog-service
-Return a service that runs @code{syslogd} with reasonable default
+@deffn {Monadic 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
 
@@ -4538,7 +4803,7 @@ Furthermore, @code{(gnu services ssh)} provides the following service.
        [#:allow-empty-passwords? #f] [#:root-login? #f] @
        [#:syslog-output? #t] [#:x11-forwarding? #t] @
        [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
-       [#:public-key-authentication? #t] [#:initialize? #f]
+       [#:public-key-authentication? #t] [#:initialize? #t]
 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
 @var{host-key} must designate a file containing the host key, and readable
 only by root.
@@ -4609,8 +4874,7 @@ started by the @dfn{login manager}, currently SLiM.
 @deffn {Monadic 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}] @
-  [#:sessions @var{%default-sessions}]
+  [#:theme-name @var{%default-slim-theme-name}]
 Return a service that spawns the SLiM graphical login manager, which in
 turn starts the X display server with @var{startx}, a command as returned by
 @code{xorg-start-command}.
@@ -4623,27 +4887,8 @@ If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
 @var{theme} must be a gexp denoting the name of a directory containing the
 theme to use.  In that case, @var{theme-name} specifies the name of the
 theme.
-
-Last, @var{session} is a list of @code{<session-type>} objects denoting the
-available session types that can be chosen from the log-in screen.
 @end deffn
 
-@defvr {Scheme Variable} %default-sessions
-The list of default session types used by SLiM.
-@end defvr
-
-@defvr {Scheme Variable} %ratpoison-session-type
-Session type using the Ratpoison window manager.
-@end defvr
-
-@defvr {Scheme Variable} %windowmaker-session-type
-Session type using the WindowMaker window manager.
-@end defvr
-
-@defvr {Scheme Variable} %sawfish-session-type
-Session type using the Sawfish window manager.
-@end defvr
-
 @defvr {Scheme Variable} %default-theme
 @defvrx {Scheme Variable} %default-theme-name
 The G-Expression denoting the default SLiM theme and its name.
@@ -4663,6 +4908,56 @@ appropriate screen resolution; otherwise, it must be a list of
 resolutions---e.g., @code{((1024 768) (640 480))}.
 @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] @
+       [#:device #f] [#:driver #f] [#:config-file #f] @
+       [#:extra-options '()]
+Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
+decodes infrared signals from remote controls.
+
+Optionally, @var{device}, @var{driver} and @var{config-file}
+(configuration file name) may be specified.  See @command{lircd} manual
+for details.
+
+Finally, @var{extra-options} is a list of additional command-line options
+passed to @command{lircd}.
+@end deffn
+
+@code{(gnu services upower)} provides a power-management daemon:
+
+@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
+                         [#:watts-up-pro? #f] @
+                         [#:poll-batteries? #t] @
+                         [#:ignore-lid? #f] @
+                         [#:use-percentage-for-policy? #f] @
+                         [#:percentage-low 10] @
+                         [#:percentage-critical 3] @
+                         [#:percentage-action 2] @
+                         [#:time-low 1200] @
+                         [#:time-critical 300] @
+                         [#:time-action 120] @
+                         [#:critical-power-action 'hybrid-sleep]
+Return a service that runs @uref{http://upower.freedesktop.org/,
+@command{upowerd}}, a system-wide monitor for power consumption and battery
+levels, with the given configuration settings.  It implements the
+@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
+GNOME.
+@end deffn
+
+@code{(gnu services colord)} provides a color management service:
+
+@deffn {Monadic 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
+tool.  See @uref{http://www.freedesktop.org/software/colord/, the colord web
+site} for more information.
+@end deffn
+
 @node Setuid Programs
 @subsection Setuid Programs
 
@@ -4730,9 +5025,12 @@ next method in the list.  The NSS configuration is given in the
 @code{name-service-switch} field of @code{operating-system} declarations
 (@pxref{operating-system Reference, @code{name-service-switch}}).
 
-@c See <http://0pointer.de/lennart/projects/nss-mdns/>.
+@cindex nss-mdns
+@cindex .local, host name lookup
 As an example, the declaration below configures the NSS to use the
-@code{nss-mdns} back-end for host name lookups:
+@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
+back-end}, which supports host name lookups over multicast DNS (mDNS)
+for host names ending in @code{.local}:
 
 @example
 (name-service-switch
@@ -4758,6 +5056,34 @@ As an example, the declaration below configures the NSS to use the
                   (name "mdns")))))
 @end example
 
+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.
+
 The reference for name service switch configuration is given below.  It
 is a direct mapping of the C library's configuration file format, so
 please refer to the C library manual for more information (@pxref{NSS
@@ -5315,7 +5641,9 @@ facility is implemented in the @code{(gnu packages)} module.
 @cindex customization, of packages
 @cindex package module search path
 Users can store package definitions in modules with different
-names---e.g., @code{(my-packages emacs)}.  These package definitions
+names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
+name and module name must match.  @xref{Modules and the File System,,,
+guile, GNU Guile Reference Manual}, for details.}  These package definitions
 will not be visible by default.  Thus, users can invoke commands such as
 @command{guix package} and @command{guix build} have to be used with the
 @code{-e} option so that they know where to find the package, or use the
@@ -5403,12 +5731,12 @@ needed is to review and apply the patch.
 
 
 @menu
-* Software Freedom::     What may go into the distribution.
-* Package Naming::       What's in a name?
-* Version Numbers::      When the name is not enough.
-* Python Modules::       Taming the snake.
-* Perl Modules::         Little pearls.
-* Fonts::                Fond of fonts.
+* Software Freedom::            What may go into the distribution.
+* Package Naming::              What's in a name?
+* Version Numbers::             When the name is not enough.
+* Python Modules::              Taming the snake.
+* Perl Modules::                Little pearls.
+* Fonts::                       Fond of fonts.
 @end menu
 
 @node Software Freedom