@include version.texi
@copying
-Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov
* GNU Free Documentation License:: The license of this manual.
* Concept Index:: Concepts.
* Programming Index:: Data types, functions, and variables.
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+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.
+
+Setting Up the Daemon
+
+* Build Environment Setup:: Preparing the isolated build environment.
+* Daemon Offload Setup:: Offloading builds to remote machines.
+
+Package Management
+
+* 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.
+
+Programming Interface
+
+* Defining Packages:: Defining new packages.
+* Build Systems:: Specifying how packages are built.
+* The Store:: Manipulating the package store.
+* Derivations:: Low-level interface to package derivations.
+* The Store Monad:: Purely functional interface to the store.
+* G-Expressions:: Manipulating build expressions.
+
+Utilities
+
+* Invoking guix build:: Building packages from the command line.
+* Invoking guix download:: Downloading a file and printing its hash.
+* Invoking guix hash:: Computing the cryptographic hash of a file.
+* Invoking guix import:: Importing package definitions.
+* 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
+
+* System Installation:: Installing the whole operating system.
+* System Configuration:: Configuring the operating system.
+* Installing Debugging Files:: Feeding the debugger.
+* Security Updates:: Deploying security fixes quickly.
+* Package Modules:: Packages from the programmer's viewpoint.
+* Packaging Guidelines:: Growing the distribution.
+* Bootstrapping:: GNU/Linux built from scratch.
+* Porting:: Targeting another platform or kernel.
+
+System Configuration
+
+* Using the Configuration System:: Customizing your GNU system.
+* operating-system Reference:: Detail of operating-system declarations.
+* File Systems:: Configuring file system mounts.
+* Mapped Devices:: Block device extra processing.
+* User Accounts:: Specifying user accounts.
+* Locales:: Language and cultural convention settings.
+* Services:: Specifying system services.
+* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
+* Initial RAM Disk:: Linux-Libre bootstrapping.
+* GRUB Configuration:: Configuring the boot loader.
+* Invoking guix system:: Instantiating a system configuration.
+* Defining Services:: Adding new service definitions.
+
+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.
+
+@end detailmenu
@end menu
@c *********************************************************************
Guix has a command-line interface, which allows users to build, install,
upgrade, and remove packages, as well as a Scheme programming interface.
+@cindex Guix System Distribution
+@cindex GSD
Last but not least, Guix is used to build a distribution of the GNU
-system, with many GNU and non-GNU free software packages. @xref{GNU
-Distribution}.
+system, with many GNU and non-GNU free software packages. The Guix
+System Distribution, or GNU@tie{}GSD, takes advantage of the core
+properties of Guix at the system level. With GNU@tie{}GSD, users
+@emph{declare} all aspects of the operating system configuration, and
+Guix takes care of instantiating that configuration in a reproducible,
+stateless fashion. @xref{GNU Distribution}.
@c *********************************************************************
@node Installation
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
+Create the group and user accounts for build users as explained below
+(@pxref{Build Environment Setup}), and run the daemon:
+
+@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
+
+@item
+To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
+authorize them:
+
+@example
+# guix archive --authorize < /root/.guix-profile/share/guix/hydra.gnu.org.pub
+@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 and verified 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
@item
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
allow you to access @code{https} URLs with the @command{guix download}
-command (@pxref{Invoking guix download}) and the @command{guix import
-pypi} command. This is primarily of interest to developers.
-@xref{Guile Preparations, how to install the GnuTLS bindings for Guile,,
-gnutls-guile, GnuTLS-Guile}.
+command (@pxref{Invoking guix download}), the @command{guix import pypi}
+command, and the @command{guix import cpan} command. This is primarily
+of interest to developers. @xref{Guile Preparations, how to install the
+GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
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
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.
a separate mount name space, its own PID name space, network name space,
etc. This helps achieve reproducible builds (@pxref{Features}).
+When the daemon performs a build on behalf of the user, it creates a
+build directory under @file{/tmp} or under the directory specified by
+its @code{TMPDIR} environment variable; this directory is shared with
+the container for the duration of the build. Be aware that using a
+directory other than @file{/tmp} can affect build results---for example,
+with a longer directory name, a build process that uses Unix-domain
+sockets might hit the name length limitation for @code{sun_path}, which
+it would otherwise not hit.
+
+The build directory is automatically deleted upon completion, unless the
+build failed and the client specified @option{--keep-failed}
+(@pxref{Invoking guix build, @option{--keep-failed}}).
+
The following command-line options are supported:
@table @code
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.
-The default value is @code{1}, but it may be overridden by clients, such
+The default value is @code{0}, but it may be overridden by clients, such
as the @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. The default value is
-@code{1}.
+@code{1}. Setting it to @code{0} means that no builds will be performed
+locally; instead, the daemon will offload builds (@pxref{Daemon Offload
+Setup}), or simply fail.
@item --debug
Produce debugging output.
@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
variable, and so on.
-In a multi-user setup, user profiles must be stored in a place
-registered as a @dfn{garbage-collector root}, which
-@file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
-directory is normally
+In a multi-user setup, user profiles are stored in a place registered as
+a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
+to (@pxref{Invoking guix gc}). That directory is normally
@code{@var{localstatedir}/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
-@code{--localstatedir}, and @var{user} is the user name. It must be
-created by @code{root}, with @var{user} as the owner. When it does not
-exist, or is not owned by @var{user}, @command{guix package} emits an
-error about it.
+@code{--localstatedir}, and @var{user} is the user name. The
+@file{per-user} directory is created when @command{guix-daemon} is
+started, and the @var{user} sub-directory is created by @command{guix
+package}.
The @var{options} can be among the following:
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}
@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.
@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}).
@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}.
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.
@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
package to a machine connected over SSH, one would run:
@example
-guix archive --export emacs | ssh the-machine guix archive --import
+guix archive --export -r emacs | ssh the-machine guix archive --import
@end example
@noindent
-However, note that, in this example, all of @code{emacs} and its
-dependencies are transferred, regardless of what is already available in
-the target machine's store. The @code{--missing} option can help figure
-out which items are missing from the target's store.
+Similarly, a complete user profile may be transferred from one machine
+to another like this:
+
+@example
+guix archive --export -r $(readlink -f ~/.guix-profile) | \
+ ssh the-machine guix-archive --import
+@end example
+
+@noindent
+However, note that, in both examples, all of @code{emacs} and the
+profile as well as all of their dependencies are transferred (due to
+@code{-r}), regardless of what is already available in the target
+machine's store. The @code{--missing} option can help figure out which
+items are missing from the target's store.
Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
comparable in spirit to `tar', but with a few noteworthy differences
Export the specified store files or packages (see below.) Write the
resulting archive to the standard output.
+Dependencies are @emph{not} included in the output, unless
+@code{--recursive} is passed.
+
+@item -r
+@itemx --recursive
+When combined with @code{--export}, this instructs @command{guix
+archive} to include dependencies of the given items in the archive.
+Thus, the resulting archive is self-contained: it contains the closure
+of the exported store items.
+
@item --import
Read an archive from the standard input, and import the files listed
therein into the store. Abort if the archive has an invalid digital
The generated key pair is typically stored under @file{/etc/guix}, in
@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
-key, which must be kept secret.) When @var{parameters} is omitted, it
-is a 4096-bit RSA key. Alternately, @var{parameters} can specify
+key, which must be kept secret.) When @var{parameters} is omitted,
+an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
+versions before 1.6.0, it is a 4096-bit RSA key.
+Alternately, @var{parameters} can specify
@code{genkey} parameters suitable for Libgcrypt (@pxref{General
public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
Libgcrypt Reference Manual}).
that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
environment variables.
+It is possible to exclude specific package outputs from that wrapping
+process by listing their names in the
+@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
+when an output is known not to contain any GLib or GTK+ binaries, and
+where wrapping would gratuitously add a dependency of that output on
+GLib and GTK+.
+
@item glib-or-gtk-compile-schemas
The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
@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
parameter.
@end defvr
+@defvr {Scheme Variable} waf-build-system
+This variable is exported by @code{(guix build-system waf)}. It
+implements a build procedure around the @code{waf} script. The common
+phases---@code{configure}, @code{build}, and @code{install}---are
+implemented by passing their names as arguments to the @code{waf}
+script.
+
+The @code{waf} script is executed by the Python interpreter. Which
+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,
@var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
[#:system (%current-system)] [#:references-graphs #f] @
- [#:allowed-references #f] [#:local-build? #f]
+ [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
Build a derivation with the given arguments, and return the resulting
@code{<derivation>} object.
When @var{allowed-references} is true, it must be a list of store items
or outputs that the derivation's output may refer to.
+When @var{leaked-env-vars} is true, it must be a list of strings
+denoting environment variables that are allowed to ``leak'' from the
+daemon's environment to the build environment. This is only applicable
+to fixed-output derivations---i.e., when @var{hash} is true. The main
+use is to allow variables such as @code{http_proxy} to be passed to
+derivations that download files.
+
When @var{local-build?} is true, declare that the derivation is not a
good candidate for offloading and should rather be built locally
(@pxref{Daemon Offload Setup}). This is the case for small derivations
useful monad for our uses, the @dfn{store monad}. Monads are a
construct that allows two things: associating ``context'' with values
(in our case, the context is the store), and building sequences of
-computations (here computations includes accesses to the store.) Values
+computations (here computations include accesses to the store.) Values
in a monad---values that carry this additional context---are called
@dfn{monadic values}; procedures that return such values are called
@dfn{monadic procedures}.
@code{derivation->output-path}---is @dfn{bound} using @code{mlet}
instead of plain @code{let}.
-Calling the monadic @code{profile.sh} has no effect. To get the desired
+Calling the monadic @code{sh-symlink} has no effect. To get the desired
effect, one must use @code{run-with-store}:
@example
-(run-with-store (open-connection) (profile.sh))
-@result{} /gnu/store/...-profile.sh
+(run-with-store (open-connection) (sh-symlink))
+@result{} /gnu/store/...-sh-symlink
@end example
Note that the @code{(guix monad-repl)} module extends Guile's REPL with
Note that non-monadic values cannot be returned in the
@code{store-monad} REPL.
-The main syntactic forms to deal with monads in general are described
-below.
+The main syntactic forms to deal with monads in general are provided by
+the @code{(guix monads)} module and are described below.
@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
@code{begin}, but applied to monadic expressions.
@end deffn
-The interface to the store monad provided by @code{(guix monads)} is as
-follows.
+@cindex state monad
+The @code{(guix monads)} module provides the @dfn{state monad}, which
+allows an additional value---the state---to be @emph{threaded} through
+monadic procedure calls.
-@defvr {Scheme Variable} %store-monad
-The store monad. Values in the store monad encapsulate accesses to the
-store. When its effect is needed, a value of the store monad must be
-``evaluated'' by passing it to the @code{run-with-store} procedure (see
-below.)
+@defvr {Scheme Variable} %state-monad
+The state monad. Procedures in the state monad can access and change
+the state that is threaded.
+
+Consider the example below. The @code{square} procedure returns a value
+in the state monad. It returns the square of its argument, but also
+increments the current state value:
+
+@example
+(define (square x)
+ (mlet %state-monad ((count (current-state)))
+ (mbegin %state-monad
+ (set-current-state (+ 1 count))
+ (return (* x x)))))
+
+(run-with-state (sequence %state-monad (map square (iota 3))) 0)
+@result{} (0 1 4)
+@result{} 3
+@end example
+
+When ``run'' through @var{%state-monad}, we obtain that additional state
+value, which is the number of @code{square} calls.
@end defvr
-@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
-Run @var{mval}, a monadic value in the store monad, in @var{store}, an
-open store connection.
+@deffn {Monadic Procedure} current-state
+Return the current state as a monadic value.
@end deffn
-@deffn {Monadic Procedure} text-file @var{name} @var{text}
-Return as a monadic value the absolute file name in the store of the file
-containing @var{text}, a string.
+@deffn {Monadic Procedure} set-current-state @var{value}
+Set the current state to @var{value} and return the previous state as a
+monadic value.
@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
-strings, packages, derivations, and store file names; the resulting
-store file holds references to all these.
+@deffn {Monadic Procedure} state-push @var{value}
+Push @var{value} to the current state, which is assumed to be a list,
+and return the previous state as a monadic value.
+@end deffn
-This variant should be preferred over @code{text-file} anytime the file
-to create will reference items from the store. This is typically the
-case when building a configuration file that embeds store file names,
-like this:
+@deffn {Monadic Procedure} state-pop
+Pop a value from the current state and return it as a monadic value.
+The state is assumed to be a list.
+@end deffn
-@example
-(define (profile.sh)
- ;; Return the name of a shell script in the store that
- ;; initializes the 'PATH' environment variable.
- (text-file* "profile.sh"
- "export PATH=" coreutils "/bin:"
- grep "/bin:" sed "/bin\n"))
-@end example
+@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
+Run monadic value @var{mval} starting with @var{state} as the initial
+state. Return two values: the resulting value, and the resulting state.
+@end deffn
-In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
-will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
-preventing them from being garbage-collected during its lifetime.
+The main interface to the store monad, provided by the @code{(guix
+store)} module, is as follows.
+
+@defvr {Scheme Variable} %store-monad
+The store monad---an alias for @var{%state-monad}.
+
+Values in the store monad encapsulate accesses to the store. When its
+effect is needed, a value of the store monad must be ``evaluated'' by
+passing it to the @code{run-with-store} procedure (see below.)
+@end defvr
+
+@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
+Run @var{mval}, a monadic value in the store monad, in @var{store}, an
+open store connection.
+@end deffn
+
+@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
+Return as a monadic value the absolute file name in the store of the file
+containing @var{text}, a string. @var{references} is a list of store items that the
+resulting text file refers to; it defaults to the empty list.
@end deffn
@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
@end deffn
+The @code{(guix packages)} module exports the following package-related
+monadic procedures:
+
@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
[#:system (%current-system)] [#:target #f] @
[#:output "out"] Return as a monadic
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,
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
#~(begin
(mkdir #$output)
(chdir #$output)
- (symlink (string-append #$coreutils "/bin/ls")
+ (symlink (string-append #$coreutils "/bin/ls")
"list-files")))
@end example
@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
information about monads.)
@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
- [#:system (%current-system)] [#:target #f] [#:inputs '()] @
+ [#:system (%current-system)] [#:target #f] [#:graft? #t] @
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:module-path @var{%load-path}] @
- [#:references-graphs #f] [#:local-build? #f] @
- [#:guile-for-build #f]
+ [#:references-graphs #f] [#:allowed-references #f] @
+ [#:leaked-env-vars #f] @
+ [#:local-build? #f] [#: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}.
-Make @var{modules} available in the evaluation context of @var{EXP};
-@var{MODULES} is a list of names of Guile modules searched in
-@var{MODULE-PATH} to be copied in the store, compiled, and made available in
+Make @var{modules} available in the evaluation context of @var{exp};
+@var{modules} is a list of names of Guile modules searched in
+@var{module-path} to be copied in the store, compiled, and made available in
the load path during the execution of @var{exp}---e.g., @code{((guix
build utils) (guix build gnu-build-system))}.
+@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
+applicable.
+
When @var{references-graphs} is true, it must be a list of tuples of one of the
following forms:
@var{file-name} contains the reference graph of the corresponding item, in a simple
text format.
+@var{allowed-references} must be either @code{#f} or a list of output names and packages.
+In the latter case, the list denotes store items that the result is allowed to
+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.
or a subset thereof.
@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
+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
+case when building a configuration file that embeds store file names,
+like this:
+
+@example
+(define (profile.sh)
+ ;; Return the name of a shell script in the store that
+ ;; initializes the 'PATH' environment variable.
+ (text-file* "profile.sh"
+ "export PATH=" coreutils "/bin:"
+ grep "/bin:" sed "/bin\n"))
+@end example
+
+In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
+will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
+preventing them from being garbage-collected during its lifetime.
+@end deffn
+
Of course, in addition to gexps embedded in ``host'' code, there are
also modules containing build tools. To make it clear that they are
meant to be used in the build stratum, these modules are kept in the
* Invoking guix 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
code snippets specified in the package's @code{origin} (@pxref{Defining
Packages}).
+@item --sources
+Fetch and return the source of @var{package-or-derivation} and all their
+dependencies, recursively. This is a handy way to obtain a local copy
+of all the source code needed to build @var{packages}, allowing you to
+eventually build them even without network access. It is an extension
+of the @code{--source} option and can accept one of the following
+optional argument values:
+
+@table @code
+@item package
+This value causes the @code{--sources} option to behave in the same way
+as the @code{--source} option.
+
+@item all
+Build all packages' source derivations, including any source that might
+be listed as @code{inputs}. This is the default value.
+
+@example
+$ guix build --sources tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+@end example
+
+@item transitive
+Build all packages' source derivations, as well as all source
+derivations for packages' transitive inputs. This can be used e.g. to
+prefetch package source for later offline building.
+
+@example
+$ guix build --sources=transitive tzdata
+The following derivations will be built:
+ /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
+ /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
+ /gnu/store/@dots{}-grep-2.21.tar.xz.drv
+ /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
+ /gnu/store/@dots{}-make-4.1.tar.xz.drv
+ /gnu/store/@dots{}-bash-4.3.tar.xz.drv
+@dots{}
+@end example
+
+@end table
+
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
Allow the use of up to @var{n} CPU cores for the build. The special
value @code{0} means to use as many CPU cores as available.
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel. @xref{Invoking
+guix-daemon, @code{--max-jobs}}, for details about this option and the
+equivalent @command{guix-daemon} option.
+
@end table
Behind the scenes, @command{guix build} is essentially an interface to
the @code{package-derivation} procedure of the @code{(guix packages)}
module, and to the @code{build-derivations} procedure of the @code{(guix
-store)} module.
+derivations)} module.
+
+In addition to options explicitly passed on the command line,
+@command{guix build} and other @command{guix} commands that support
+building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
+
+@defvr {Environment Variable} GUIX_BUILD_OPTIONS
+Users can define this variable to a list of command line options that
+will automatically be used by @command{guix build} and other
+@command{guix} commands that can perform builds, as in the example
+below:
+
+@example
+$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
+@end example
+
+These options are parsed independently, and the result is appended to
+the parsed command-line options.
+@end defvr
+
@node Invoking guix download
@section Invoking @command{guix download}
guix import pypi itsdangerous
@end example
+@item cpan
+@cindex CPAN
+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, 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:
+
+@example
+guix import cpan Acme::Boolean
+@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
@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
names, as in this example:
@example
-guix refresh -u emacs idutils
+guix refresh -u emacs idutils gcc-4.8.4
@end example
@noindent
@node Invoking guix lint
@section Invoking @command{guix lint}
The @command{guix lint} is meant to help package developers avoid common
-errors and use a consistent style. It runs a few checks on a given set of
-packages in order to find common mistakes in their definitions.
+errors and use a consistent style. It runs a number of checks on a
+given set of packages in order to find common mistakes in their
+definitions. Available @dfn{checkers} include (see
+@code{--list-checkers} for a complete list):
+
+@table @code
+@item synopsis
+@itemx description
+Validate certain typographical and stylistic rules about package
+descriptions and synopses.
+
+@item inputs-should-be-native
+Identify inputs that should most likely be native inputs.
+
+@item source
+@itemx home-page
+Probe @code{home-page} and @code{source} URLs and report those that are
+invalid.
+@end table
The general syntax is:
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
-Guix comes with a distribution of free software@footnote{The term
-``free'' here refers to the
+@cindex Guix System Distribution
+@cindex GSD
+Guix comes with a distribution of the GNU system consisting entirely of
+free software@footnote{The term ``free'' here refers to the
@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
-users of that software}.} that forms the basis of the GNU system. This
-includes core GNU packages such as GNU libc, GCC, and Binutils, as well
-as many GNU and non-GNU applications. The complete list of available
-packages can be browsed
+users of that software}.}. The
+distribution can be installed on its own (@pxref{System Installation}),
+but it is also possible to install Guix as a package manager on top of
+an installed GNU/Linux system (@pxref{Installation}). To distinguish
+between the two, we refer to the standalone distribution as the Guix
+System Distribution, or GNU@tie{}GSD.
+
+The distribution provides core GNU packages such as GNU libc, GCC, and
+Binutils, as well as many GNU and non-GNU applications. The complete
+list of available packages can be browsed
@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
guix package --list-available
@end example
-Our goal is to build a practical 100% free software distribution of
+Our goal has been to provide a practical 100% free software distribution of
Linux-based and other variants of GNU, with a focus on the promotion and
tight integration of GNU components, and an emphasis on programs and
tools that help users exert that freedom.
-The GNU distribution is currently available on the following platforms:
+Packages are currently available on the following platforms:
@table @code
@item i686-linux
Intel 32-bit architecture (IA32), Linux-Libre kernel;
+@item armhf-linux
+ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
+using the EABI hard-float ABI, and Linux-Libre kernel.
+
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
n32 application binary interface (ABI), and Linux-Libre kernel.
@end table
+GSD itself is currently only available on @code{i686} and @code{x86_64}.
+
@noindent
For information on porting to other architectures or kernels,
@xref{Porting}.
@menu
* System Installation:: Installing the whole operating system.
-* System Configuration:: Configuring a GNU system.
+* System Configuration:: Configuring the operating system.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
@node System Installation
@section System Installation
-This section explains how to install the complete GNU operating system
-on a machine. The Guix package manager can also be installed on top of
-a running GNU/Linux system, @pxref{Installation}.
+@cindex Guix System Distribution
+This section explains how to install the Guix System Distribution
+on a machine. The Guix package manager can
+also be installed on top of a running GNU/Linux system,
+@pxref{Installation}.
@ifinfo
@c This paragraph is for people reading this from tty2 of the
@subsection Limitations
-As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
-distribution are alpha software. It may contain bugs and lack important
+As of version @value{VERSION}, the Guix System Distribution (GSD) is
+not production-ready. It may contain bugs and lack important
features. Thus, if you are looking for a stable production system that
respects your freedom as a computer user, a good solution at this point
is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
more established GNU/Linux distributions}. We hope you can soon switch
-to the GNU system without fear, of course. In the meantime, you can
+to the GSD without fear, of course. In the meantime, you can
also keep using your distribution and try out the package manager on top
of it (@pxref{Installation}).
get a feel of what that means.)
@item
-The system does not yet provide graphical desktop environments such as
-GNOME and KDE.
+The system does not yet provide GNOME and KDE; it provides Xfce, though,
+if graphical desktop environments are your thing.
@item
Support for the Logical Volume Manager (LVM) is missing.
(@pxref{Services}).
@item
-On the order of 1,000 packages are available, which means that you may
+On the order of 1,200 packages are available, which means that you may
occasionally find that a useful package is missing.
@end itemize
@subsection USB Stick Installation
An installation image for USB sticks can be downloaded from
-@url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.xz},
+@code{ftp://alpha.gnu.org/gnu/guix/gsd-usb-install-@value{VERSION}.@var{system}.xz},
where @var{system} is one of:
@table @code
Decompress the image using the @command{xz} command:
@example
-xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
+xz -d gsd-usb-install-@value{VERSION}.@var{system}.xz
@end example
@item
copy the image with:
@example
-dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
+dd if=gsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
@end example
Access to @file{/dev/sdX} usually requires root privileges.
@enumerate
@item
-Configure the network, by running @command{dhclient eth0} (to get an
+Configure the network, by running @command{dhclient eno1} (to get an
automatically assigned IP address from the wired network interface
-controller), or using the @command{ifconfig} command.
+controller@footnote{
+@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+The name @code{eno1} is for the first on-board Ethernet controller. The
+interface name for an Ethernet controller that is in the first slot of
+the first PCI bus, for instance, would be @code{enp1s0}. Use
+@command{ifconfig -a} to list all the available network interfaces.}),
+or using the @command{ifconfig} command.
The system automatically loads drivers for your network interface
controllers.
system} command, specifically:
@example
-guix system disk-image --image-size=800MiB gnu/system/install.scm
+guix system disk-image --image-size=850MiB gnu/system/install.scm
@end example
@xref{Invoking guix system}, for more information. See
@section System Configuration
@cindex system configuration
-The GNU system supports a consistent whole-system configuration
+The Guix System Distribution supports a consistent whole-system configuration
mechanism. By that we mean that all aspects of the global system
configuration---such as the available system services, timezone and
locale settings, user accounts---are declared in a single place. Such
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
+* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
+* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
(operating-system
(host-name "komputilo")
(timezone "Europe/Paris")
- (locale "fr_FR.UTF-8")
+ (locale "fr_FR.utf8")
(bootloader (grub-configuration
(device "/dev/sda")))
(file-systems (cons (file-system
%base-file-systems))
(users (list (user-account
(name "alice")
- (uid 1000) (group 100)
+ (group "users")
(comment "Bob's sister")
(home-directory "/home/alice"))))
(packages (cons emacs %base-packages))
@item @code{timezone}
A timezone identifying string---e.g., @code{"Europe/Paris"}.
-@item @code{locale} (default: @code{"en_US.UTF-8"})
-The name of the default locale (@pxref{Locales,,, libc, The GNU C
-Library Reference Manual}).
+@item @code{locale} (default: @code{"en_US.utf8"})
+The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
+Library Reference Manual}). @xref{Locales}, for more information.
+
+@item @code{locale-definitions} (default: @var{%default-locale-definitions})
+The list of locale definitions to be compiled and that may be used at
+run time. @xref{Locales}.
+
+@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
+details.
@item @code{services} (default: @var{%base-services})
A list of monadic values denoting system services. @xref{Services}.
The @code{label} and @code{uuid} options offer a way to refer to disk
partitions without having to hard-code their actual device name.
+However, when a file system's source is a mapped device (@pxref{Mapped
+Devices}), its @code{device} field @emph{must} refer to the mapped
+device name---e.g., @file{/dev/mapper/root-partition}---and consequently
+@code{title} must be set to @code{'device}. This is required so that
+the system knows that mounting the file system depends on having the
+corresponding device mapping established.
+
@item @code{flags} (default: @code{'()})
This is a list of symbols denoting mount flags. Recognized flags
include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
@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
@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
@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
(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:
@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.
specific devices such as ``audio'', ``disk'', and ``cdrom''.
@end defvr
+@node Locales
+@subsection Locales
+
+@cindex locale
+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{fr_LU.utf8} designates the locale for the French language, with
+cultural conventions from Luxembourg, and using the UTF-8 encoding.
+
+@cindex locale definition
+Usually, you will want to specify the default locale for the machine
+using the @code{locale} field of the @code{operating-system} declaration
+(@pxref{operating-system Reference, @code{locale}}).
+
+That locale must be among the @dfn{locale definitions} that are known to
+the system---and these are specified in the @code{locale-definitions}
+slot of @code{operating-system}. The default value includes locale
+definition for some widely used locales, but not for all the available
+locales, in order to save space.
+
+If the locale specified in the @code{locale} field is not among the
+definitions listed in @code{locale-definitions}, @command{guix system}
+raises an error. In that case, you should add the locale definition to
+the @code{locale-definitions} field. For instance, to add the North
+Frisian locale for Germany, the value of that field may be:
+
+@example
+(cons (locale-definition
+ (name "fy_DE.utf8") (source "fy_DE"))
+ %default-locale-definitions)
+@end example
+
+Likewise, to save space, one might want @code{locale-definitions} to
+list only the locales that are actually used, as in:
+
+@example
+(list (locale-definition
+ (name "ja_JP.eucjp") (source "ja_JP")
+ (charset "EUC-JP")))
+@end example
+
+The @code{locale-definition} form is provided by the @code{(gnu system
+locale)} module. Details are given below.
+
+@deftp {Data Type} locale-definition
+This is the data type of a locale definition.
+
+@table @asis
+
+@item @code{name}
+The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
+Reference Manual}, for more information on locale names.
+
+@item @code{source}
+The name of the source for that locale. This is typically the
+@code{@var{language}_@var{territory}} part of the locale name.
+
+@item @code{charset} (default: @code{"UTF-8"})
+The ``character set'' or ``code set'' for that locale,
+@uref{http://www.iana.org/assignments/character-sets, as defined by
+IANA}.
+
+@end table
+@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}
+declarations.
+@end defvr
@node Services
@subsection Services
listing @dfn{system services} and their configuration (@pxref{Using the
Configuration System}). System services are typically daemons launched
when the system boots, or other actions needed at that time---e.g.,
-configuring network access. They are managed by GNU@tie{}dmd
-(@pxref{Introduction,,, dmd, GNU dmd Manual}).
+configuring network access.
+
+Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
+dmd Manual}). On a running system, the @command{deco} command allows
+you to list the available services, show their status, start and stop
+them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
+Manual}). For example:
+
+@example
+# deco status dmd
+@end example
+
+The above command, run as @code{root}, lists the currently defined
+services. The @command{deco doc} command shows a synopsis of the given
+service:
+
+@example
+# deco doc nscd
+Run libc's name service cache daemon (nscd).
+@end example
+
+The @command{start}, @command{stop}, and @command{restart} sub-commands
+have the effect you would expect. For instance, the commands below stop
+the nscd service and restart the Xorg display server:
+
+@example
+# deco stop nscd
+Service nscd has been stopped.
+# deco restart xorg-server
+Service xorg-server has been stopped.
+Service xorg-server has been started.
+@end example
The following sections document the available services, starting with
-the core services.
+the core services, that may be used in an @code{operating-system}
+declaration.
@menu
* 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
the ``message of the day''.
@end deffn
-@deffn {Monadic Procedure} nscd-service [#:glibc glibc]
-Return a service that runs libc's name service cache daemon (nscd).
+@cindex name service cache daemon
+@cindex nscd
+@deffn {Monadic 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.
@end deffn
-@deffn {Monadic Procedure} syslog-service
-Return a service that runs @code{syslogd} with reasonable default
+@defvr {Scheme Variable} %nscd-default-configuration
+This is the default @code{<nscd-configuration>} value (see below) used
+by @code{nscd-service}. This uses the caches defined by
+@var{%nscd-default-caches}; see below.
+@end defvr
+
+@deftp {Data Type} nscd-configuration
+This is the type representing the name service cache daemon (nscd)
+configuration.
+
+@table @asis
+
+@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.
+
+@item @code{debug-level} (default: @code{0})
+Integer denoting the debugging levels. Higher numbers mean more
+debugging output is logged.
+
+@item @code{caches} (default: @var{%nscd-default-caches})
+List of @code{<nscd-cache>} objects denoting things to be cached; see
+below.
+
+@end table
+@end deftp
+
+@deftp {Data Type} nscd-cache
+Data type representing a cache database of nscd and its parameters.
+
+@table @asis
+
+@item @code{database}
+This is a symbol representing the name of the database to be cached.
+Valid values are @code{passwd}, @code{group}, @code{hosts}, and
+@code{services}, which designate the corresponding NSS database
+(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
+
+@item @code{positive-time-to-live}
+@itemx @code{negative-time-to-live} (default: @code{20})
+A number representing the number of seconds during which a positive or
+negative lookup result remains in cache.
+
+@item @code{check-files?} (default: @code{#t})
+Whether to check for updates of the files corresponding to
+@var{database}.
+
+For instance, when @var{database} is @code{hosts}, setting this flag
+instructs nscd to check for updates in @file{/etc/hosts} and to take
+them into account.
+
+@item @code{persistent?} (default: @code{#t})
+Whether the cache should be stored persistently on disk.
+
+@item @code{shared?} (default: @code{#t})
+Whether the cache should be shared among users.
+
+@item @code{max-database-size} (default: 32@tie{}MiB)
+Maximum size in bytes of the database cache.
+
+@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
+@c settings, so leave them out.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %nscd-default-caches
+List of @code{<nscd-cache>} objects used by default by
+@code{nscd-configuration} (see above.)
+
+It enables persistent and aggressive caching of service and host name
+lookups. The latter provides better host name lookup performance,
+resilience in the face of unreliable name servers, and also better
+privacy---often the result of host name lookups is in local cache, so
+external name servers do not even need to be queried.
+@end defvr
+
+
+@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
@deffn {Monadic Procedure} guix-service [#:guix guix] @
[#:builder-group "guixbuild"] [#:build-accounts 10] @
- [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @
+ [#: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}.
Run @var{udev}, which populates the @file{/dev} directory dynamically.
@end deffn
+@deffn {Monadic Procedure} console-keymap-service @var{file}
+Return a service to load console keymap from @var{file} using
+@command{loadkeys} command.
+@end deffn
+
@node Networking Services
@subsubsection Networking Services
gateway.
@end deffn
+@cindex wicd
+@deffn {Monadic 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}] @
[#:name-service @var{%ntp-servers}]
Return a service that runs the daemon from @var{ntp}, the
Furthermore, @code{(gnu services ssh)} provides the following service.
@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
- [#:interfaces '()] [#:port-number 22] @
+ [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
[#: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.
+When @var{daemonic?} is true, @command{lshd} will detach from the
+controlling terminal and log its output to syslogd, unless one sets
+@var{syslog-output?} to false. Obviously, it also makes lsh-service
+depend on existence of syslogd service. When @var{pid-file?} is true,
+@command{lshd} writes its PID to the file called @var{pid-file}.
+
When @var{initialize?} is true, automatically create the seed and host key
upon service activation if they do not exist yet. This may take long and
require interaction.
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
files in this directory refer to the ``real'' binaries, which are in the
store.
+@node Name Service Switch
+@subsection Name Service Switch
+
+@cindex name service switch
+@cindex NSS
+The @code{(gnu system nss)} module provides bindings to the
+configuration file of libc's @dfn{name service switch} or @dfn{NSS}
+(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
+Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
+extended with new ``name'' lookup methods for system databases, which
+includes host names, service names, user accounts, and more (@pxref{Name
+Service Switch, System Databases and Name Service Switch,, libc, The GNU
+C Library Reference Manual}).
+
+The NSS configuration specifies, for each system database, which lookup
+method is to be used, and how the various methods are chained
+together---for instance, under which circumstances NSS should try the
+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}}).
+
+@cindex nss-mdns
+@cindex .local, host name lookup
+As an example, the declaration below configures the NSS to use the
+@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
+ (hosts (list %files ;first, check /etc/hosts
+
+ ;; If the above did not succeed, try
+ ;; with 'mdns_minimal'.
+ (name-service
+ (name "mdns_minimal")
+
+ ;; 'mdns_minimal' is authoritative for
+ ;; '.local'. When it returns "not found",
+ ;; no need to try the next methods.
+ (reaction (lookup-specification
+ (not-found => return))))
+
+ ;; Then fall back to DNS.
+ (name-service
+ (name "dns"))
+
+ ;; Finally, try with the "full" 'mdns'.
+ (name-service
+ (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
+Configuration File,,, libc, The GNU C Library Reference Manual}).
+Compared to libc's NSS configuration file format, it has the advantage
+not only of adding this warm parenthetic feel that we like, but also
+static checks: you'll know about syntax errors and typos as soon as you
+run @command{guix system}.
+
+@defvr {Scheme Variable} %default-nss
+This is the default name service switch configuration, a
+@code{name-service-switch} object.
+@end defvr
+
+@deftp {Data Type} name-service-switch
+
+This is the data type representation the configuration of libc's name
+service switch (NSS). Each field below represents one of the supported
+system databases.
+
+@table @code
+@item aliases
+@itemx ethers
+@itemx group
+@itemx gshadow
+@itemx hosts
+@itemx initgroups
+@itemx netgroup
+@itemx networks
+@itemx password
+@itemx public-key
+@itemx rpc
+@itemx services
+@itemx shadow
+The system databases handled by the NSS. Each of these fields must be a
+list of @code{<name-service>} objects (see below.)
+@end table
+@end deftp
+
+@deftp {Data Type} name-service
+
+This is the data type representing an actual name service and the
+associated lookup action.
+
+@table @code
+@item name
+A string denoting the name service (@pxref{Services in the NSS
+configuration,,, libc, The GNU C Library Reference Manual}).
+
+Note that name services listed here must be visible to nscd. This is
+achieved by passing the @code{#:name-services} argument to
+@code{nscd-service} the list of packages providing the needed name
+services (@pxref{Base Services, @code{nscd-service}}).
+
+@item reaction
+An action specified using the @code{lookup-specification} macro
+(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
+Reference Manual}). For example:
+
+@example
+(lookup-specification (unavailable => continue)
+ (success => return))
+@end example
+@end table
+@end deftp
@node Initial RAM Disk
@subsection Initial RAM Disk
@example
(initrd (lambda (file-systems . rest)
+ ;; Create a standard initrd that has modules "foo.ko"
+ ;; and "bar.ko", as well as their dependencies, in
+ ;; addition to the modules available by default.
(apply base-initrd file-systems
- #:extra-modules '("my.ko" "modules.ko")
+ #:extra-modules '("foo" "bar")
rest)))
@end example
@table @asis
@item @code{label}
-The label to show in the menu---e.g., @code{"GNU System"}.
+The label to show in the menu---e.g., @code{"GNU"}.
@item @code{linux}
The Linux kernel to boot.
@item init
Populate the given directory with all the files necessary to run the
operating system specified in @var{file}. This is useful for first-time
-installations of the GNU system. For instance:
+installations of GSD. For instance:
@example
guix system init my-os-config.scm /mnt
@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
@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
Modules} and @ref{Perl Modules} for special rules concerning modules for
the Python and Perl languages.
-Font package names are handled differently, @pxref {Fonts}.
+Font package names are handled differently, @pxref{Fonts}.
@node Version Numbers
In the case where several formats of the same font family or font collection
are packaged separately, a short form of the format, prepended by a dash,
is added to the package name. We use @code{-ttf} for TrueType fonts,
-@code {-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
+@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
fonts.
the final tool chain contain references to the @file{/gnu/store}
directories of the bootstrap inputs. The process that leads to this
``final'' tool chain is described by the package definitions found in
-the @code{(gnu packages base)} module.
+the @code{(gnu packages commencement)} module.
@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
The first tool that gets built with the bootstrap binaries is
the GNU Build System expects. These are in the @code{%final-inputs}
variable of the @code{(gnu packages commencement)} module, and are
implicitly used by any package that uses @code{gnu-build-system}
-(@pxref{Defining Packages}).
+(@pxref{Build Systems, @code{gnu-build-system}}).
@unnumberedsubsec Building the Bootstrap Binaries
guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
@end example
+For this to work, the @code{glibc-dynamic-linker} procedure in
+@code{(gnu packages bootstrap)} must be augmented to return the right
+file name for libc's dynamic linker on that platform; likewise,
+@code{system->linux-architecture} in @code{(gnu packages linux)} must be
+taught about the new platform.
+
Once these are built, the @code{(gnu packages bootstrap)} module needs
-to be updated to refer to these binaries on the target platform. In
-addition, the @code{glibc-dynamic-linker} procedure in that module must
-be augmented to return the right file name for libc's dynamic linker on
-that platform; likewise, @code{system->linux-architecture} in @code{(gnu
-packages linux)} must be taught about the new platform.
+to be updated to refer to these binaries on the target platform. That
+is, the hashes and URLs of the bootstrap tarballs for the new platform
+must be added alongside those of the currently supported platforms. The
+bootstrap Guile tarball is treated specially: it is expected to be
+available locally, and @file{gnu-system.am} has rules do download it for
+the supported architectures; a rule for the new platform must be added
+as well.
In practice, there may be some complications. First, it may be that the
extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
HCoop / jackhill / guix / guix.git / blobdiff