@c %**end of header
@include version.texi
+@set YEARS 2012, 2013
@dircategory Package management
@direntry
Edition @value{EDITION} @*
@value{UPDATED} @*
-Copyright @copyright{} 2012 Ludovic Court@`es
+Copyright @copyright{} @value{YEARS} Ludovic Court@`es
@quotation
Permission is granted to copy, distribute and/or modify this document
@copying
This manual documents GNU Guix version @value{VERSION}.
-Copyright (C) 2012 Ludovic Courtès
+Copyright @copyright{} @value{YEARS} Ludovic Courtès
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.
+@quotation
+Copyright @copyright{} @value{YEARS} Ludovic Courtès
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License.''
+@end quotation
+
@menu
* Introduction:: What is Guix about?
+* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
+* GNU Distribution:: Software for your friendly GNU system.
* Acknowledgments:: Thanks!
* GNU Free Documentation License:: The license of this manual.
build processes in dedicated ``chroots'', where only their explicit
inputs are visible.
-@cindex package store
+@cindex store
The result of package build functions is @dfn{cached} in the file
-system, in a special directory called the @dfn{package store}. In
-practice, each package is installed in a directory of its own, in the
+system, in a special directory called @dfn{the store} (@pxref{The
+Store}). Each package is installed in a directory of its own, in the
store---by default under @file{/nix/store}. The directory name contains
a hash of all the inputs used to build that package; thus, changing an
input yields a different directory name.
upgrade, and remove packages, as well as a Scheme programming interface.
The remainder of this manual describes them.
+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}.
+
+@c *********************************************************************
+@node Installation
+@chapter Installation
+
+This section describes the software requirements of Guix, as well as how
+to install it and get ready to use it.
+
+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
+* Requirements:: Software needed to build and run Guix.
+* Setting Up the Daemon:: Preparing the build daemon's environment.
+* Invoking guix-daemon:: Running the build daemon.
+@end menu
+
+@node Requirements
+@section Requirements
+
+GNU Guix depends on the following packages:
+
+@itemize
+@item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x};
+@item @url{http://gnupg.org/, GNU libgcrypt}
+@end itemize
+
+Unless @code{--disable-daemon} was passed to @command{configure}, the
+following packages are also needed:
+
+@itemize
+@item @url{http://sqlite.org, SQLite 3}
+@item @url{http://www.bzip.org, libbz2}
+@item @url{http://gcc.gnu.org, GCC's g++}
+@end itemize
+
+When a working installation of the Nix package manager is available, you
+can instead configure Guix with @code{--disable-daemon}. In that case,
+@url{http://nixos.org/nix/, Nix} replaces the three dependencies above.
+
+Guix is compatible with Nix, so it is possible to share the same store
+between both. To do so, you must pass @command{configure} not only the
+same @code{--with-store-dir} value, but also the same
+@code{--localstatedir} value (the latter is essential because it
+specifies where the database that store meta-data about the store is
+located, among other things.) The default values are
+@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
+Note that @code{--disable-daemon} is orthogonal and is not required if
+your goal is to share the same store as Nix.
+
+@node Setting Up the Daemon
+@section Setting Up the Daemon
+
+@cindex daemon
+Operations such as building a package or running the garbage collector
+are all performed by a specialized process, the @dfn{Guix daemon}, on
+behalf of clients. Only the daemon may access the store and its
+associated database. Thus, any operation that manipulates the store
+goes through the daemon. For instance, command-line tools such as
+@command{guix-package} and @command{guix-build} communicate with the
+daemon (@i{via} remote procedure calls) to instruct it what to do.
+
+In a standard multi-user setup, Guix and its daemon---the
+@command{guix-daemon} program---are installed by the system
+administrator; @file{/nix/store} is owned by @code{root} and
+@command{guix-daemon} runs as @code{root}. Unprivileged users may use
+Guix tools to build packages or otherwise access the store, and the
+daemon will do it on their behalf, ensuring that the store is kept in a
+consistent state, and allowing built packages to be shared among users.
+
+@cindex build users
+When @command{guix-daemon} runs as @code{root}, you may not want package
+build processes themselves to run as @code{root} too, for obvious
+security reasons. To avoid that, a special pool of @dfn{build users}
+should be created for use by build processes started by the daemon.
+These build users need not have a shell and a home directory: they will
+just be used when the daemon drops @code{root} privileges in build
+processes. Having several such users allows the daemon to launch
+distinct build processes under separate UIDs, which guarantees that they
+do not interfere with each other---an essential feature since builds are
+regarded as pure functions (@pxref{Introduction}).
+
+On a GNU/Linux system, a build user pool may be created like this (using
+Bash syntax and the @code{shadow} commands):
+
+@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
+@c for why `-G' is needed.
+@example
+# groupadd guix-builder
+# for i in `seq 1 10`;
+ do
+ useradd -g guix-builder -G guix-builder \
+ -d /var/empty -s `which nologin` \
+ -c "Guix build user $i" guix-builder$i;
+ done
+@end example
+
+@noindent
+The @code{guix-daemon} program may then be run as @code{root} with:
+
+@example
+# guix-daemon --build-users-group=guix-builder
+@end example
+
+Guix may also be used in a single-user setup, with @command{guix-daemon}
+running as an unprivileged user. However, to maximize non-interference
+of build processes, the daemon still needs to perform certain operations
+that are restricted to @code{root} on GNU/Linux: it should be able to
+run build processes in a chroot, and to run them under different UIDs.
+To that end, the @command{nix-setuid-helper} program is provided; it is
+a small C program (less than 300 lines) that, if it is made setuid
+@code{root}, can be executed by the daemon to perform these operations
+on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
+is read by @command{nix-setuid-helper}; it should contain exactly two
+words: the user name under which the authorized @command{guix-daemon}
+runs, and the name of the build users group.
+
+If you are installing Guix as an unprivileged user and do not have the
+ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
+possible to run @command{guix-daemon}. However, build processes will
+not be isolated from one another, and not from the rest of the system.
+Thus, build processes may interfere with each other, and may access
+programs, libraries, and other files available on the system---making it
+much harder to view them as @emph{pure} functions.
+
+@node Invoking guix-daemon
+@section Invoking @command{guix-daemon}
+
+The @command{guix-daemon} program implements all the functionality to
+access the store. This includes launching build processes, running the
+garbage collector, querying the availability of a build result, etc. It
+is normally run as @code{root} like this:
+
+@example
+# guix-daemon --build-users-group=guix-builder
+@end example
+
+@noindent
+For details on how to set it up, @ref{Setting Up the Daemon}.
+
+By default, @command{guix-daemon} launches build processes under
+different UIDs, taken from the build group specified with
+@code{--build-users-group}. In addition, each build process is run in a
+chroot environment that only contains the subset of the store that the
+build process depends on, as specified by its derivation
+(@pxref{Programming Interface, derivation}), plus a set of specific
+system directories. By default, the latter contains @file{/dev} and
+@file{/dev/pts}.
+
+The following command-line options are supported:
+
+@table @code
+@item --build-users-group=@var{group}
+Take users from @var{group} to run build processes (@pxref{Setting Up
+the Daemon, build users}).
+
+@item --cache-failures
+Cache build failures. By default, only successful builds are cached.
+
+@item --cores=@var{n}
+@itemx -c @var{n}
+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
+as the @code{--cores} option of @command{guix-build} (@pxref{Invoking
+guix-build}).
+
+The effect is to define the @code{NIX_BUILD_CORES} environment variable
+in the build process, which can then use it to exploit internal
+parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
+
+@item --max-jobs=@var{n}
+@itemx -M @var{n}
+Allow at most @var{n} build jobs in parallel. The default value is
+@code{1}.
+
+@item --debug
+Produce debugging output.
+
+This is useful to debug daemon start-up issues, but then it may be
+overridden by clients, for example the @code{--verbosity} option of
+@command{guix-build} (@pxref{Invoking guix-build}).
+
+@item --chroot-directory=@var{dir}
+Add @var{dir} to the build chroot.
+
+Doing this may change the result of build processes---for instance if
+they use optional dependencies found in @var{dir} when it is available,
+and not otherwise. For that reason, it is not recommended to do so.
+Instead, make sure that each derivation declares all the inputs that it
+needs.
+
+@item --disable-chroot
+Disable chroot builds.
+
+Using this option is not recommended since, again, it would allow build
+processes to gain access to undeclared dependencies.
+
+@item --disable-log-compression
+Disable compression of the build logs.
+
+Unless @code{--lose-logs} is used, all the build logs are kept in the
+@var{localstatedir}. To save space, the daemon automatically compresses
+them with bzip2 by default. This option disables that.
+
+@item --disable-store-optimization
+Disable automatic file ``deduplication'' in the store.
+
+By default, files added to the store are automatically ``deduplicated'':
+if a newly added file is identical as another one found in the store,
+the daemon makes the new file a hard link to the other file. This
+slightly increases the input/output load at the end of a build process.
+This option disables this.
+
+@item --impersonate-linux-2.6
+On Linux-based systems, impersonate Linux 2.6. This means that the
+kernel's @code{uname} system call will report 2.6 as the release number.
+
+This might be helpful to build programs that (usually wrongfully) depend
+on the kernel version number.
+
+@item --lose-logs
+Do not keep build logs. By default they are kept under
+@code{@var{localstatedir}/nix/log}.
+
+@item --system=@var{system}
+Assume @var{system} as the current system type. By default it is the
+architecture/kernel pair found at configure time, such as
+@code{x86_64-linux}.
+@end table
+
+
@c *********************************************************************
@node Package Management
@chapter Package Management
@menu
* Features:: How Guix will make your life brighter.
* Invoking guix-package:: Package installation, removal, etc.
+* Invoking guix-gc:: Running the garbage collector.
@end menu
@node Features
All those packages in the package store may be @emph{garbage-collected}.
Guix can determine which packages are still referenced by the user
-profiles, and remove those that are provably no longer referenced.
-Users may also explicitly remove old generations of their profile so
-that the packages they refer to can be collected.
+profiles, and remove those that are provably no longer referenced
+(@pxref{Invoking guix-gc}). Users may also explicitly remove old
+generations of their profile so that the packages they refer to can be
+collected.
Finally, Guix takes a @dfn{purely functional} approach to package
management, as described in the introduction (@pxref{Introduction}).
inputs that were used to build that package---compiler, libraries, build
scripts, etc. This direct correspondence allows users to make sure a
given package installation matches the current state of their
-distribution.
+distribution, and helps maximize @dfn{reproducibility}.
+@c FIXME: Remove footnote when it's implemented.
This foundation allows Guix to support @dfn{transparent binary/source
-deployment}. When a pre-built binary for a @file{/nix/store} path is
+deployment}@footnote{This feature is not implemented as of version
+@value{VERSION}. Please contact @email{bug-guix@@gnu.org} for more
+details.}. When a pre-built binary for a @file{/nix/store} path is
available from an external source, Guix just downloads it; otherwise, it
builds the package from source, locally.
previous generations of the profile remain available, should the user
want to roll back.
+For each user, a symlink to the user's default profile is automatically
+created in @file{$HOME/.guix-profile}. This symlink always points to the
+current generation of the user's default profile. Thus, users can add
+@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
+@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, @command{guix-package} emits an error about it.
+
+The @var{options} can be among the following:
+
@table @code
@item --install=@var{package}
@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}. In addition, @var{package} may contain a
+such as @code{guile-1.8.8}. 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{libsigsegv-2.10:lib}.
+@code{gcc:doc} or @code{binutils-2.22:lib}.
@item --remove=@var{package}
@itemx -r @var{package}
@itemx -u @var{regexp}
Upgrade all the installed packages matching @var{regexp}.
+@item --roll-back
+Roll back to the previous @dfn{generation} of the profile---i.e., undo
+the last transaction.
+
+When combined with options such as @code{--install}, roll back occurs
+before any other actions.
+
@item --profile=@var{profile}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
@item --list-available[=@var{regexp}]
@itemx -A [@var{regexp}]
-List packages currently available in the software distribution. When
-@var{regexp} is specified, list only installed packages whose name
-matches @var{regexp}.
+List packages currently available in the software distribution
+(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
+installed packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name,
-its version string, and the source location of its definition.
+its version string, the parts of the package (@code{out} for the main
+files, @code{lib} for libraries and possibly headers, etc.), and the
+source location of its definition.
@end table
+@node Invoking guix-gc
+@section Invoking @command{guix-gc}
+
+@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{/nix/store} directory.
+
+The garbage collector has a set of known @dfn{roots}: any file under
+@file{/nix/store} reachable from a root is considered @dfn{live} and
+cannot be deleted; any other file is considered @dfn{dead} and may be
+deleted. The set of garbage collector roots includes default user
+profiles, and may be augmented with @command{guix-build --root}, for
+example (@pxref{Invoking guix-build}).
+
+The @command{guix-gc} command has three modes of operation: it can be
+used to garbage-collect any dead files (the default), to delete specific
+files (the @code{--delete} option), or to print garbage-collector
+information. The available options are listed below:
+
+@table @code
+@item --collect-garbage[=@var{min}]
+@itemx -C [@var{min}]
+Collect garbage---i.e., unreachable @file{/nix/store} files and
+sub-directories. This is the default operation when no option is
+specified.
+
+When @var{min} is given, stop once @var{min} bytes have been collected.
+@var{min} may be a number of bytes, or it may include a unit as a
+suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
+
+When @var{min} is omitted, collect all the garbage.
+
+@item --delete
+@itemx -d
+Attempt to delete all the store files and directories specified as
+arguments. This fails if some of the files are not in the store, or if
+they are still live.
+
+@item --list-dead
+Show the list of dead files and directories still present in the
+store---i.e., files and directories no longer reachable from any root.
+
+@item --list-live
+Show the list of live store files and directories.
+@end table
+
@c *********************************************************************
@node Programming Interface
package looks like this:
@example
+(use-modules (guix packages)
+ (guix download)
+ (guix build-system gnu)
+ (guix licenses))
+
(define hello
(package
(name "hello")
(synopsis "GNU Hello")
(description "Yeah...")
(home-page "http://www.gnu.org/software/hello/")
- (license "GPLv3+")))
+ (license gpl3+)))
@end example
@noindent
arguments in Guile,, guile, GNU Guile Reference Manual}). They are
passed to @var{gnu-build-system}, which interprets them as meaning ``do
not run @code{make check}'', and ``run @file{configure} with the
-@code{--enable-silent-rules} flag''.
+@code{--enable-silent-rules} flag''. The value of these keyword
+parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
+Guile process launched by the daemon (@pxref{Derivations}).
Once a package definition is in place@footnote{Simple package
definitions like the one above may be automatically converted from the
@code{build-derivations} procedure (@pxref{The Store}).
@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
-Return the derivation of @var{package} for @var{system}. The result is
-the file name of the derivation---i.e., a @code{.drv} file under
-@code{/nix/store}.
+Return the derivation path and corresponding @code{<derivation>} object
+of @var{package} for @var{system} (@pxref{Derivations}).
@var{package} must be a valid @code{<package>} object, and @var{system}
must be a string denoting the target system type---e.g.,
@node The Store
@section The Store
-@code{(guix store)}
+@cindex store
+@cindex store paths
+
+Conceptually, the @dfn{store} is where derivations that have been
+successfully built are stored---by default, under @file{/nix/store}.
+Sub-directories in the store are referred to as @dfn{store paths}. The
+store has an associated database that contains information such has the
+store paths referred to by each store path, and the list of @emph{valid}
+store paths---paths that result from a successful build.
+
+The store is always accessed by the daemon on behalf of its clients
+(@pxref{Invoking guix-daemon}). To manipulate the store, clients
+connect to the daemon over a Unix-domain socket, send it requests, and
+read the result---these are remote procedure calls, or RPCs.
+
+The @code{(guix store)} module provides procedures to connect to the
+daemon, and to perform RPCs. These are described below.
+
+@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
+Connect to the daemon over the Unix-domain socket at @var{file}. When
+@var{reserve-space?} is true, instruct it to reserve a little bit of
+extra space on the file system so that the garbage collector can still
+operate, should the disk become full. Return a server object.
+
+@var{file} defaults to @var{%default-socket-path}, which is the normal
+location given the options that were passed to @command{configure}.
+@end deffn
+
+@deffn {Scheme Procedure} close-connection @var{server}
+Close the connection to @var{server}.
+@end deffn
+
+@defvr {Scheme Variable} current-build-output-port
+This variable is bound to a SRFI-39 parameter, which refers to the port
+where build and error logs sent by the daemon should be written.
+@end defvr
+
+Procedures that make RPCs all take a server object as their first
+argument.
+
+@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
+Return @code{#t} when @var{path} is a valid store path.
+@end deffn
+
+@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
+Add @var{text} under file @var{name} in the store, and return its store
+path. @var{references} is the list of store paths referred to by the
+resulting store path.
+@end deffn
+
+@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
+Build @var{derivations} (a list of derivation paths), and return when
+the worker is done building them. Return @code{#t} on success.
+@end deffn
+
+@c FIXME
+@i{This section is currently incomplete.}
@node Derivations
@section Derivations
-@code{(guix derivations)}
+@cindex derivations
+Low-level build actions and the environment in which they are performed
+are represented by @dfn{derivations}. A derivation contain the
+following pieces of information:
+
+@itemize
+@item
+The outputs of the derivation---derivations produce at least one file or
+directory in the store, but may produce more.
+
+@item
+The inputs of the derivations, which may be other derivations or plain
+files in the store (patches, build scripts, etc.)
+
+@item
+The system type targeted by the derivation---e.g., @code{x86_64-linux}.
+
+@item
+The file name of a build script in the store, along with the arguments
+to be passed.
+
+@item
+A list of environment variables to be defined.
+
+@end itemize
+
+@cindex derivation path
+Derivations allow clients of the daemon to communicate build actions to
+the store. They exist in two forms: as an in-memory representation,
+both on the client- and daemon-side, and as files in the store whose
+name end in @code{.drv}---these files are referred to as @dfn{derivation
+paths}. Derivations paths can be passed to the @code{build-derivations}
+procedure to perform the build actions they prescribe (@pxref{The
+Store}).
+
+The @code{(guix derivations)} module provides a representation of
+derivations as Scheme objects, along with procedures to create and
+otherwise manipulate derivations. The lowest-level primitive to create
+a derivation is the @code{derivation} procedure:
+
+@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f]
+Build a derivation with the given arguments. Return the resulting store
+path and @code{<derivation>} object.
+
+When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
+@dfn{fixed-output derivation} is created---i.e., one whose result is
+known in advance, such as a file download.
+@end deffn
+
+@noindent
+Here's an example with a shell script as its builder, assuming
+@var{store} is an open connection to the daemon, and @var{bash} points
+to a Bash executable in the store:
+
+@lisp
+(use-modules (guix utils)
+ (guix store)
+ (guix derivations))
+
+(call-with-values
+ (lambda ()
+ (let ((builder ; add the Bash script to the store
+ (add-text-to-store store "my-builder.sh"
+ "echo hello world > $out\n" '())))
+ (derivation store "foo" (%current-system)
+ bash `("-e" ,builder)
+ '(("HOME" . "/homeless")) '())))
+ list)
+@result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
+@end lisp
+
+As can be guessed, this primitive is cumbersome to use directly. An
+improved variant is @code{build-expression->derivation}, which allows
+the caller to directly pass a Guile expression as the build script:
+
+@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f]
+Return a derivation that executes Scheme expression @var{exp} as a
+builder for derivation @var{name}. @var{inputs} must be a list of
+@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
+@code{"out"} is assumed. @var{modules} is a list of names of Guile
+modules from the current search 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{exp} is evaluated in an environment where @code{%outputs} is bound
+to a list of output/path pairs, and where @code{%build-inputs} is bound
+to a list of string/output-path pairs made from @var{inputs}.
+Optionally, @var{env-vars} is a list of string pairs specifying the name
+and value of environment variables visible to the builder. The builder
+terminates by passing the result of @var{exp} to @code{exit}; thus, when
+@var{exp} returns @code{#f}, the build is considered to have failed.
+
+@var{exp} is built using @var{guile-for-build} (a derivation). When
+@var{guile-for-build} is omitted or is @code{#f}, the value of the
+@code{%guile-for-build} fluid is used instead.
+@end deffn
+
+@noindent
+Here's an example of a single-output derivation that creates a directory
+containing one file:
+
+@lisp
+(let ((builder '(let ((out (assoc-ref %outputs "out")))
+ (mkdir out) ; create /nix/store/@dots{}-goo
+ (call-with-output-file (string-append out "/test")
+ (lambda (p)
+ (display '(hello guix) p))))))
+ (build-expression->derivation store "goo" (%current-system)
+ builder '()))
+
+@result{} "/nix/store/@dots{}-goo.drv"
+@result{} #<<derivation> @dots{}>
+@end lisp
+
+@cindex strata of code
+Remember that the build expression passed to
+@code{build-expression->derivation} is run by a separate Guile process
+than the one that calls @code{build-expression->derivation}: it is run
+by a Guile process launched by the daemon, typically in a chroot. So,
+while there is a single language for both the @dfn{host} and the build
+side, there are really two @dfn{strata} of code: the host-side, and the
+build-side code@footnote{The term @dfn{stratum} in this context was
+coined by Manuel Serrano et al. in the context of their work on Hop.}.
+This distinction is important to keep in mind, notably when using
+higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
+Packages}). For this reason, Guix modules that are meant to be used in
+the build stratum are kept in the @code{(guix build @dots{})} name
+space.
@c *********************************************************************
@node Utilities
@end example
@var{package-or-derivation} may be either the name of a package found in
-the software distribution such as @code{coreutils}, or a derivation such
-as @file{/nix/store/xxx-coreutils-8.19.drv}. Alternatively, the
+the software distribution such as @code{coreutils} or
+@code{coreutils-8.20}, or a derivation such as
+@file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
@code{--expression} option may be used to specify a Scheme expression
that evaluates to a package; this is useful when disambiguation among
several same-named packages or package variants is needed.
@itemx -e @var{expr}
Build the package @var{expr} evaluates to.
-For example, @var{expr} may be @code{(@@ (distro packages guile)
+For example, @var{expr} may be @code{(@@ (gnu packages guile)
guile-1.8)}, which unambiguously designates this specific variant of
version 1.8 of Guile.
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
collector root.
+
+@item --verbosity=@var{level}
+Use the given verbosity level. @var{level} must be an integer between 0
+and 5; higher means more verbose output. Setting a level of 4 or more
+may be helpful when debugging setup issues with the build daemon.
+
@end table
Behind the scenes, @command{guix-build} is essentially an interface to
module, and to the @code{build-derivations} procedure of the @code{(guix
store)} module.
+@c *********************************************************************
+@node GNU Distribution
+@chapter GNU Distribution
+
+Guix comes with a distribution 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 form 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 seen by running @command{guix-package} (@pxref{Invoking
+guix-package}):
+
+@example
+guix-package --list-available
+@end example
+
+The package definitions of the distribution may are provided by Guile
+modules in the @code{(gnu packages ...)} name space---for instance, the
+@code{(gnu packages emacs)} module exports a variable named
+@code{emacs}, which is bound to a @code{<package>} object
+(@pxref{Defining Packages}). The @code{(gnu packages)} module provides
+facilities for searching for packages.
+
+The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
+each package is built based solely on other packages in the
+distribution. The root of this dependency graph is a small set of
+@dfn{bootstrap binaries}, provided by the @code{(gnu packages
+bootstrap)} module. These are statically-linked binaries of the core
+tools without which building anything at all would be impossible.
+
+
+Our goal is to build 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.
+
+Building this distribution is a cooperative effort, and you are invited
+to join! Please get in touch with us on @email{bug-guix@@gnu.org}. We
+welcome ideas, bug reports, patches, and anything that may be helpful to
+the project.
+
@c *********************************************************************
@node Acknowledgments
HCoop / jackhill / guix / guix.git / blobdiff