\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename guix.info @documentencoding UTF-8 @settitle GNU Guix Reference Manual @c %**end of header @include version.texi @set YEARS 2012, 2013 @dircategory Package management @direntry * guix: (guix). Guix, the functional package manager. * guix-package: (guix)Invoking guix-package Managing packages with Guix. * guix-build: (guix)Invoking guix-build Building packages with Guix. @end direntry @titlepage @title{GNU Guix Reference Manual} @subtitle{Using the GNU Guix Functional Package Manager} @author Ludovic Courtès @page @vskip 0pt plus 1filll Edition @value{EDITION} @* @value{UPDATED} @* Copyright @copyright{} @value{YEARS} Ludovic Court@`es @quotation 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 @end titlepage @copying This manual documents GNU Guix version @value{VERSION}. 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 copying @contents @c ********************************************************************* @node Top @top GNU Guix 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. * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this manual. * Concept Index:: Concepts. * Function Index:: Functions. @end menu @c ********************************************************************* @node Introduction @chapter Introduction GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using the international phonetic alphabet (IPA).} is a functional package management tool for the GNU system. Package management consists in all the activities that relate to building packages from source, honoring the build-time and run-time dependencies on packages, installing packages in user environments, upgrading installed packages to new versions or rolling back to a previous set, removing unused software packages, etc. @cindex functional package management The term @dfn{functional} refers to a specific package management discipline. In Guix, the package build and installation process is seen as a function, in the mathematical sense: that function takes inputs, such as build scripts, a compiler, and libraries depended on, and returns the installed package. As a pure function, its result depends solely on its inputs---for instance, it cannot refer to software or scripts that were not explicitly passed as inputs. A build function always produces the same result when passed a given set of inputs. Last but not least, a build function cannot alter the system's environment in any way; for instance, it cannot create, modify, or delete files outside of its build and installation directories. This is achieved by running build processes in dedicated ``chroots'', where only their explicit inputs are visible. @cindex store The result of package build functions is @dfn{cached} in the file 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. This approach is the foundation of Guix's salient features: support for transactional package upgrades and rollback, per-user installation, and garbage collection of packages (@pxref{Features}). Guix has a command-line interface allowing users to build, install, upgrade, and remove packages, as well as a Scheme programming interface. The remainder of this manual describes them. @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): @example # groupadd guix-builder # for i in `seq 1 10`; do useradd -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 The purpose of GNU Guix is to allow users to easily install, upgrade, and remove software packages, without having to know about their build procedure or dependencies. Guix also goes beyond this obvious set of features. This chapter describes the main features of Guix, as well as the package management tools it provides. @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 @section Features When using Guix, each package ends up in the @dfn{package store}, in its own directory---something that resembles @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string. Instead of referring to these directories, users have their own @dfn{profile}, which points to the packages that they actually want to use. That profile is normally stored in @code{$HOME/.guix-profile}, and each user has its own profile. For example, if @code{alice} installed GCC 4.7.2, then @file{/home/alice/.guix-profile/bin/gcc} points to @file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob} may have installed GCC 4.8.0, in which case its profile refers to these particular package installation. Both coexist, without any interference. The @command{guix-package} command is the central tool to manage packages. It operates on those per-user profiles, and can be used @emph{with normal user privileges}. The command provides the obvious install, remove, and upgrade operations. Each invocation is actually a @emph{transaction}: either the specified operation succeeds, or nothing happens. Thus, if the @command{guix-package} processed is terminated during the transaction, or if a power outage occurs during the transaction, then the user's profile remains in its previous state, and remains usable. In addition, any package transaction may be @emph{rolled back}. So, if, for example, an upgrade installs a new version of a package that turns out to have a serious bug, users may roll back to the previous instance of their profile, which was known to work well. 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 (@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}). Each @file{/nix/store} package directory name contains a hash of all the 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. @c FIXME: Remove footnote when it's implemented. This foundation allows Guix to support @dfn{transparent binary/source 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. @node Invoking guix-package @section Invoking @command{guix-package} The @command{guix-package} command is the tool that allows users to install, upgrade, and remove packages, as well as rolling back to previous configurations. It operates only on the user's own profile, and works with normal user privileges (@pxref{Features}). Its syntax is: @example guix-package @var{options} @end example Primarily, @var{options} specifies the operations to be performed during the transaction. Upon completion, a new profile is created, but 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} @itemx -i @var{package} 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.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{binutils-2.22:lib}. @item --remove=@var{package} @itemx -r @var{package} Remove @var{package}. @item --upgrade=@var{regexp} @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 --dry-run @itemx -n Show what would be done without actually doing it. @item --verbose Produce verbose output. In particular, emit the environment's build log on the standard error port. @item --bootstrap Use the bootstrap Guile to build the profile. This option is only useful to distribution developers. @end table In addition to these actions @command{guix-package} supports the following options to query the current state of a profile, or the availability of packages: @table @option @item --list-installed[=@var{regexp}] @itemx -I [@var{regexp}] List currently installed packages in the specified profile. When @var{regexp} is specified, list only installed packages whose name matches @var{regexp}. For each installed package, print the following items, separated by tabs: the package name, its version string, the part of the package that is installed (for instance, @code{out} for the default output, @code{include} for its headers, etc.), and the path of this package in the store. @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}. For each package, print the following items separated by tabs: its name, 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 @chapter Programming Interface GNU Guix provides several Scheme programming interfaces (APIs) to define, build, and query packages. The first interface allows users to write high-level package definitions. These definitions refer to familiar packaging concepts, such as the name and version of a package, its build system, and its dependencies. These definitions can then be turned into concrete build actions. Build actions are performed by the Guix daemon, on behalf of users. In a standard setup, the daemon has write access to the store---the @file{/nix/store} directory---whereas users do not. The recommended setup also has the daemon perform builds in chroots, under a specific build users, to minimize interference with the rest of the system. @cindex derivation Lower-level APIs are available to interact with the daemon and the store. To instruct the daemon to perform a build action, users actually provide it with a @dfn{derivation}. A derivation is a low-level representation of the build actions to be taken, and the environment in which they should occur---derivations are to package definitions what assembly is to C programs. This chapter describes all these APIs in turn, starting from high-level package definitions. @menu * Defining Packages:: Defining new packages. * The Store:: Manipulating the package store. * Derivations:: Low-level interface to package derivations. @end menu @node Defining Packages @section Defining Packages The high-level interface to package definitions is implemented in the @code{(guix packages)} and @code{(guix build-system)} modules. As an example, the package definition, or @dfn{recipe}, for the GNU Hello package looks like this: @example (use-modules (guix packages) (guix download) (guix build-system gnu) (guix licenses)) (define hello (package (name "hello") (version "2.8") (source (origin (method url-fetch) (uri (string-append "mirror://gnu/hello/hello-" version ".tar.gz")) (sha256 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6")))) (build-system gnu-build-system) (inputs `(("gawk" ,gawk))) (synopsis "GNU Hello") (description "Yeah...") (home-page "http://www.gnu.org/software/hello/") (license gpl3+))) @end example @noindent Without being a Scheme expert, the reader may have guessed the meaning of the various fields here. This expression binds variable @var{hello} to a @code{<package>} object, which is essentially a record (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). This package object can be inspected using procedures found in the @code{(guix packages)} module; for instance, @code{(package-name hello)} returns---surprise!---@code{"hello"}. There are a few points worth noting in the above package definition: @itemize @item The @code{source} field of the package is an @code{<origin>} object. Here, the @code{url-fetch} method from @code{(guix download)} is used, meaning that the source is a file to be downloaded over FTP or HTTP. The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of the GNU mirrors defined in @code{(guix download)}. The @code{sha256} field specifies the expected SHA256 hash of the file being downloaded. It is mandatory, and allows Guix to check the integrity of the file. The @code{(base32 @dots{})} form introduces the base32 representation of the hash. A convenient way to obtain this information is with the @code{guix-download} tool. @item @cindex GNU Build System The @code{build-system} field is set to @var{gnu-build-system}. The @var{gnu-build-system} variable is defined in the @code{(guix build-system gnu)} module, and is bound to a @code{<build-system>} object. Naturally, @var{gnu-build-system} represents the familiar GNU Build System, and variants thereof (@pxref{Configuration, configuration and makefile conventions,, standards, GNU Coding Standards}). In a nutshell, packages using the GNU Build System may be configured, built, and installed with the usual @code{./configure && make && make check && make install} command sequence. This is what @var{gnu-build-system} does. In addition, @var{gnu-build-system} ensures that the ``standard'' environment for GNU packages is available. This includes tools such as GCC, Coreutils, Bash, Make, Diffutils, and Patch. @item The @code{inputs} field specifies inputs to the build process---i.e., build-time or run-time dependencies of the package. Here, we define an input called @code{"gawk"} whose value is that of the @var{gawk} variable; @var{gawk} is itself bound to a @code{<package>} object. Note that GCC, Coreutils, Bash, and other essential tools do not need to be specified as inputs here. Instead, @var{gnu-build-system} takes care of ensuring that they are present. However, any other dependencies need to be specified in the @code{inputs} field. Any dependency not specified here will simply be unavailable to the build process, possibly leading to a build failure. @end itemize There are other fields that package definitions may provide. Of particular interest is the @code{arguments} field. When specified, it must be bound to a list of additional arguments to be passed to the build system. For instance, the above definition could be augmented with the following field initializer: @example (arguments `(#:tests? #f #:configure-flags '("--enable-silent-rules"))) @end example @noindent These are keyword arguments (@pxref{Optional Arguments, keyword 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''. 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 Nixpkgs distribution using the @command{guix-import} command.}, the package may actually be built using the @code{guix-build} command-line tool (@pxref{Invoking guix-build}). Behind the scenes, a derivation corresponding to the @code{<package>} object is first computed by the @code{package-derivation} procedure. That derivation is stored in a @code{.drv} file under @file{/nix/store}. The build actions it prescribes may then be realized by using 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}. @var{package} must be a valid @code{<package>} object, and @var{system} must be a string denoting the target system type---e.g., @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store} must be a connection to the daemon, which operates on the store (@pxref{The Store}). @end deffn @node The Store @section The 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 @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 @chapter Utilities @menu * Invoking guix-build:: Building packages from the command line. @end menu @node Invoking guix-build @section Invoking @command{guix-build} The @command{guix-build} command builds packages or derivations and their dependencies, and prints the resulting store paths. It is mainly useful for distribution developers. The general syntax is: @example guix-build @var{options} @var{package-or-derivation}@dots{} @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 @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. The @var{options} may be zero or more of the following: @table @code @item --expression=@var{expr} @itemx -e @var{expr} Build the package @var{expr} evaluates to. For example, @var{expr} may be @code{(@@ (distro packages guile) guile-1.8)}, which unambiguously designates this specific variant of version 1.8 of Guile. @item --source @itemx -S Build the packages' source derivations, rather than the packages themselves. For instance, @code{guix-build -S gcc} returns something like @file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the host's system type. An example use of this is on Linux-based systems, which can emulate different personalities. For instance, passing @code{--system=i686-linux} on an @code{x86_64-linux} system allows users to build packages in a complete 32-bit environment. @item --derivations @itemx -d Return the derivation paths, not the output paths, of the given packages. @item --keep-failed @itemx -K Keep the build tree of failed builds. Thus, if a build fail, its build tree is kept under @file{/tmp}, in a directory whose name is shown at the end of the build log. This is useful when debugging build issues. @item --dry-run @itemx -n Do not build the derivations. @item --no-substitutes Build instead of resorting to pre-built substitutes. @item --cores=@var{n} @itemx -c @var{n} 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 --root=@var{file} @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 the @code{package-derivation} procedure of the @code{(guix packages)} module, and to the @code{build-derivations} procedure of the @code{(guix store)} module. @c ********************************************************************* @node Acknowledgments @chapter Acknowledgments Guix is based on the Nix package manager, which was designed and implemented by Eelco Dolstra. Nix pioneered functional package management, and promoted unprecedented features, such as transactional package upgrades and rollbacks, per-user profiles, and referentially transparent build processes. Without this work, Guix would not exist. The Nix-based software distributions, Nixpkgs and NixOS, have also been an inspiration for Guix. @c ********************************************************************* @node GNU Free Documentation License @appendix GNU Free Documentation License @include fdl-1.3.texi @c ********************************************************************* @node Concept Index @unnumbered Concept Index @printindex cp @node Function Index @unnumbered Function Index @printindex fn @bye @c Local Variables: @c ispell-local-dictionary: "american"; @c End: