@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, 2013 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.
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
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 -d /var/empty -s `which nologin` \
- -m "Guix build user $i" guix-builder$i;
+ useradd -g guix-builder -G guix-builder \
+ -d /var/empty -s `which nologin` \
+ -c "Guix build user $i" guix-builder$i;
done
@end example
@end example
Guix may also be used in a single-user setup, with @command{guix-daemon}
-running as a unprivileged user. However, to maximize non-interference
+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.
@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.
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
profiles, and may be augmented with @command{guix-build --root}, for
example (@pxref{Invoking guix-build}).
-The @command{guix-gc} command has three mode of operations: it can be
+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:
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.
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