6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
14 Copyright @copyright{} 2013 Andreas Enge@*
15 Copyright @copyright{} 2013 Nikita Karetnikov
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
21 copy of the license is included in the section entitled ``GNU Free
22 Documentation License''.
25 @dircategory Package management
27 * guix: (guix). Guix, the functional package manager.
28 * guix package: (guix)Invoking guix package
29 Managing packages with Guix.
30 * guix build: (guix)Invoking guix build
31 Building packages with Guix.
35 @title GNU Guix Reference Manual
36 @subtitle Using the GNU Guix Functional Package Manager
37 @author Ludovic Courtès
39 @author Nikita Karetnikov
42 @vskip 0pt plus 1filll
43 Edition @value{EDITION} @*
51 @c *********************************************************************
55 This document describes GNU Guix version @value{VERSION}, a functional
56 package management tool written for the GNU system.
59 * Introduction:: What is Guix about?
60 * Installation:: Installing Guix.
61 * Package Management:: Package installation, upgrade, etc.
62 * Programming Interface:: Using Guix in Scheme.
63 * Utilities:: Package management commands.
64 * GNU Distribution:: Software for your friendly GNU system.
65 * Contributing:: Your help needed!
67 * Acknowledgments:: Thanks!
68 * GNU Free Documentation License:: The license of this manual.
69 * Concept Index:: Concepts.
70 * Function Index:: Functions.
73 @c *********************************************************************
77 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
78 using the international phonetic alphabet (IPA).} is a functional
79 package management tool for the GNU system. Package management consists
80 of all activities that relate to building packages from sources,
81 honoring their build-time and run-time dependencies,
82 installing packages in user environments, upgrading installed packages
83 to new versions or rolling back to a previous set, removing unused
84 software packages, etc.
86 @cindex functional package management
87 The term @dfn{functional} refers to a specific package management
88 discipline. In Guix, the package build and installation process is seen
89 as a function, in the mathematical sense. That function takes inputs,
90 such as build scripts, a compiler, and libraries, and
91 returns an installed package. As a pure function, its result depends
92 solely on its inputs---for instance, it cannot refer to software or
93 scripts that were not explicitly passed as inputs. A build function
94 always produces the same result when passed a given set of inputs. It
95 cannot alter the system's environment in
96 any way; for instance, it cannot create, modify, or delete files outside
97 of its build and installation directories. This is achieved by running
98 build processes in isolated environments (or @dfn{containers}), where only their
99 explicit inputs are visible.
102 The result of package build functions is @dfn{cached} in the file
103 system, in a special directory called @dfn{the store} (@pxref{The
104 Store}). Each package is installed in a directory of its own, in the
105 store---by default under @file{/nix/store}. The directory name contains
106 a hash of all the inputs used to build that package; thus, changing an
107 input yields a different directory name.
109 This approach is the foundation of Guix's salient features: support for
110 transactional package upgrade and rollback, per-user installation, and
111 garbage collection of packages (@pxref{Features}).
113 Guix has a command-line interface, which allows users to build, install,
114 upgrade, and remove packages, as well as a Scheme programming interface.
116 Last but not least, Guix is used to build a distribution of the GNU
117 system, with many GNU and non-GNU free software packages. @xref{GNU
120 @c *********************************************************************
122 @chapter Installation
124 GNU Guix is available for download from its website at
125 @url{http://www.gnu.org/software/guix/}. This section describes the
126 software requirements of Guix, as well as how to install it and get
129 The build procedure for Guix is the same as for other GNU software, and
130 is not covered here. Please see the files @file{README} and
131 @file{INSTALL} in the Guix source tree for additional details.
134 * Requirements:: Software needed to build and run Guix.
135 * Setting Up the Daemon:: Preparing the build daemon's environment.
136 * Invoking guix-daemon:: Running the build daemon.
140 @section Requirements
142 GNU Guix depends on the following packages:
145 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
146 @item @url{http://gnupg.org/, GNU libgcrypt}
149 Unless @code{--disable-daemon} was passed to @command{configure}, the
150 following packages are also needed:
153 @item @url{http://sqlite.org, SQLite 3}
154 @item @url{http://www.bzip.org, libbz2}
155 @item @url{http://gcc.gnu.org, GCC's g++}
158 When a working installation of @url{http://nixos.org/nix/, the Nix package
159 manager} is available, you
160 can instead configure Guix with @code{--disable-daemon}. In that case,
161 Nix replaces the three dependencies above.
163 Guix is compatible with Nix, so it is possible to share the same store
164 between both. To do so, you must pass @command{configure} not only the
165 same @code{--with-store-dir} value, but also the same
166 @code{--localstatedir} value. The latter is essential because it
167 specifies where the database that stores metadata about the store is
168 located, among other things. The default values are
169 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
170 Note that @code{--disable-daemon} is not required if
171 your goal is to share the store with Nix.
173 @node Setting Up the Daemon
174 @section Setting Up the Daemon
177 Operations such as building a package or running the garbage collector
178 are all performed by a specialized process, the @dfn{build daemon}, on
179 behalf of clients. Only the daemon may access the store and its
180 associated database. Thus, any operation that manipulates the store
181 goes through the daemon. For instance, command-line tools such as
182 @command{guix package} and @command{guix build} communicate with the
183 daemon (@i{via} remote procedure calls) to instruct it what to do.
185 The following sections explain how to prepare the build daemon's
189 * Build Environment Setup:: Preparing the isolated build environment.
190 * Daemon Offload Setup:: Offloading builds to remote machines.
193 @node Build Environment Setup
194 @subsection Build Environment Setup
196 In a standard multi-user setup, Guix and its daemon---the
197 @command{guix-daemon} program---are installed by the system
198 administrator; @file{/nix/store} is owned by @code{root} and
199 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
200 Guix tools to build packages or otherwise access the store, and the
201 daemon will do it on their behalf, ensuring that the store is kept in a
202 consistent state, and allowing built packages to be shared among users.
205 When @command{guix-daemon} runs as @code{root}, you may not want package
206 build processes themselves to run as @code{root} too, for obvious
207 security reasons. To avoid that, a special pool of @dfn{build users}
208 should be created for use by build processes started by the daemon.
209 These build users need not have a shell and a home directory: they will
210 just be used when the daemon drops @code{root} privileges in build
211 processes. Having several such users allows the daemon to launch
212 distinct build processes under separate UIDs, which guarantees that they
213 do not interfere with each other---an essential feature since builds are
214 regarded as pure functions (@pxref{Introduction}).
216 On a GNU/Linux system, a build user pool may be created like this (using
217 Bash syntax and the @code{shadow} commands):
219 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
220 @c for why `-G' is needed.
222 # groupadd guix-builder
223 # for i in `seq 1 10`;
225 useradd -g guix-builder -G guix-builder \
226 -d /var/empty -s `which nologin` \
227 -c "Guix build user $i" --system \
233 The @code{guix-daemon} program may then be run as @code{root} with:
236 # guix-daemon --build-users-group=guix-builder
241 This way, the daemon starts build processes in a chroot, under one of
242 the @code{guix-builder} users. On GNU/Linux, by default, the chroot
243 environment contains nothing but:
245 @c Keep this list in sync with libstore/build.cc! -----------------------
248 the @code{/dev} and @code{/proc} directories@footnote{On some systems
249 @code{/dev/shm}, which supports shared memory, is a symlink to another
250 directory such as @code{/run/shm}, that is @emph{not} is the chroot.
251 When that is the case, shared memory support is unavailable in the
252 chroot environment. The workaround is to make sure that @file{/dev/shm}
253 is directly a @code{tmpfs} mount point.};
256 @file{/etc/passwd} with an entry for the current user and an entry for
260 @file{/etc/group} with an entry for the user's group;
263 @file{/etc/hosts} with an entry that maps @code{localhost} to
267 a writable @file{/tmp} directory.
270 If you are installing Guix as an unprivileged user, it is still
271 possible to run @command{guix-daemon}. However, build processes will
272 not be isolated from one another, and not from the rest of the system.
273 Thus, build processes may interfere with each other, and may access
274 programs, libraries, and other files available on the system---making it
275 much harder to view them as @emph{pure} functions.
278 @node Daemon Offload Setup
279 @subsection Using the Offload Facility
283 When desired, the build daemon can @dfn{offload}
284 derivation builds to other machines
285 running Guix, using the @code{offload} @dfn{build hook}. When that
286 feature is enabled, a list of user-specified build machines is read from
287 @file{/etc/guix/machines.scm}; anytime a build is requested, for
288 instance via @code{guix build}, the daemon attempts to offload it to one
289 of the machines that satisfies the derivation's constraints, in
290 particular its system type---e.g., @file{x86_64-linux}. Missing
291 prerequisites for the build are copied over SSH to the target machine,
292 which then proceeds with the build; upon success the output(s) of the
293 build are copied back to the initial machine.
295 The @file{/etc/guix/machines.scm} file typically looks like this:
299 (name "eightysix.example.org")
300 (system "x86_64-linux")
302 (speed 2.)) ; incredibly fast!
305 (name "meeps.example.org")
306 (system "mips64el-linux")
309 (string-append (getenv "HOME")
310 "/.ssh/id-rsa-for-guix"))))
314 In the example above we specify a list of two build machines, one for
315 the @code{x86_64} architecture and one for the @code{mips64el}
318 In fact, this file is---not surprisingly!---a Scheme file that is
319 evaluated when the @code{offload} hook is started. Its return value
320 must be a list of @code{build-machine} objects. While this example
321 shows a fixed list of build machines, one could imagine, say, using
322 DNS-SD to return a list of potential build machines discovered in the
323 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
324 Avahi in Guile Scheme Programs}).
326 The compulsory fields for a @code{build-machine} declaration are:
331 The remote machine's host name.
334 The remote machine's system type.
337 The user account to use when connecting to the remote machine over SSH.
338 Note that the SSH key pair must @emph{not} be passphrase-protected, to
339 allow non-interactive logins.
344 A number of optional fields may be specified:
349 The SSH private key file to use when connecting to the machine.
351 @item parallel-builds
352 The number of builds that may run in parallel on the machine (1 by
356 A ``relative speed factor''. The offload scheduler will tend to prefer
357 machines with a higher speed factor.
360 A list of strings denoting specific features supported by the machine.
361 An example is @code{"kvm"} for machines that have the KVM Linux modules
362 and corresponding hardware support. Derivations can request features by
363 name, and they will be scheduled on matching build machines.
367 The @code{guix} command must be in the search path on the build
368 machines, since offloading works by invoking the @code{guix archive} and
369 @code{guix build} commands.
371 There's one last thing to do once @file{machines.scm} is in place. As
372 explained above, when offloading, files are transferred back and forth
373 between the machine stores. For this to work, you need to generate a
374 key pair to allow the daemon to export signed archives of files from the
375 store (@pxref{Invoking guix archive}):
378 # guix archive --generate-key
382 Thus, when receiving files, a machine's build daemon can make sure they
383 are genuine, have not been tampered with, and that they are signed by an
387 @node Invoking guix-daemon
388 @section Invoking @command{guix-daemon}
390 The @command{guix-daemon} program implements all the functionality to
391 access the store. This includes launching build processes, running the
392 garbage collector, querying the availability of a build result, etc. It
393 is normally run as @code{root} like this:
396 # guix-daemon --build-users-group=guix-builder
400 For details on how to set it up, @ref{Setting Up the Daemon}.
403 @cindex container, build environment
404 @cindex build environment
405 @cindex reproducible builds
406 By default, @command{guix-daemon} launches build processes under
407 different UIDs, taken from the build group specified with
408 @code{--build-users-group}. In addition, each build process is run in a
409 chroot environment that only contains the subset of the store that the
410 build process depends on, as specified by its derivation
411 (@pxref{Programming Interface, derivation}), plus a set of specific
412 system directories. By default, the latter contains @file{/dev} and
413 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
414 @dfn{container}: in addition to having its own file system tree, it has
415 a separate mount name space, its own PID name space, network name space,
416 etc. This helps achieve reproducible builds (@pxref{Features}).
418 The following command-line options are supported:
421 @item --build-users-group=@var{group}
422 Take users from @var{group} to run build processes (@pxref{Setting Up
423 the Daemon, build users}).
425 @item --no-substitutes
427 Do not use substitutes for build products. That is, always build things
428 locally instead of allowing downloads of pre-built binaries.
430 By default substitutes are used, unless the client---such as the
431 @command{guix package} command---is explicitly invoked with
432 @code{--no-substitutes}.
434 When the daemon runs with @code{--no-substitutes}, clients can still
435 explicitly enable substitution @i{via} the @code{set-build-options}
436 remote procedure call (@pxref{The Store}).
439 @item --no-build-hook
440 Do not use the @dfn{build hook}.
442 The build hook is a helper program that the daemon can start and to
443 which it submits build requests. This mechanism is used to offload
444 builds to other machines (@pxref{Daemon Offload Setup}).
446 @item --cache-failures
447 Cache build failures. By default, only successful builds are cached.
449 @item --cores=@var{n}
451 Use @var{n} CPU cores to build each derivation; @code{0} means as many
454 The default value is @code{1}, but it may be overridden by clients, such
455 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
458 The effect is to define the @code{NIX_BUILD_CORES} environment variable
459 in the build process, which can then use it to exploit internal
460 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
462 @item --max-jobs=@var{n}
464 Allow at most @var{n} build jobs in parallel. The default value is
468 Produce debugging output.
470 This is useful to debug daemon start-up issues, but then it may be
471 overridden by clients, for example the @code{--verbosity} option of
472 @command{guix build} (@pxref{Invoking guix build}).
474 @item --chroot-directory=@var{dir}
475 Add @var{dir} to the build chroot.
477 Doing this may change the result of build processes---for instance if
478 they use optional dependencies found in @var{dir} when it is available,
479 and not otherwise. For that reason, it is not recommended to do so.
480 Instead, make sure that each derivation declares all the inputs that it
483 @item --disable-chroot
484 Disable chroot builds.
486 Using this option is not recommended since, again, it would allow build
487 processes to gain access to undeclared dependencies.
489 @item --disable-log-compression
490 Disable compression of the build logs.
492 Unless @code{--lose-logs} is used, all the build logs are kept in the
493 @var{localstatedir}. To save space, the daemon automatically compresses
494 them with bzip2 by default. This option disables that.
496 @item --disable-store-optimization
497 Disable automatic file ``deduplication'' in the store.
499 By default, files added to the store are automatically ``deduplicated'':
500 if a newly added file is identical as another one found in the store,
501 the daemon makes the new file a hard link to the other file. This
502 slightly increases the input/output load at the end of a build process.
503 This option disables this.
505 @item --gc-keep-outputs[=yes|no]
506 Tell whether the garbage collector (GC) must keep outputs of live
509 When set to ``yes'', the GC will keep the outputs of any live derivation
510 available in the store---the @code{.drv} files. The default is ``no'',
511 meaning that derivation outputs are kept only if they are GC roots.
513 @item --gc-keep-derivations[=yes|no]
514 Tell whether the garbage collector (GC) must keep derivations
515 corresponding to live outputs.
517 When set to ``yes'', as is the case by default, the GC keeps
518 derivations---i.e., @code{.drv} files---as long as at least one of their
519 outputs is live. This allows users to keep track of the origins of
520 items in their store. Setting it to ``no'' saves a bit of disk space.
522 Note that when both @code{--gc-keep-derivations} and
523 @code{--gc-keep-outputs} are used, the effect is to keep all the build
524 prerequisites (the sources, compiler, libraries, and other build-time
525 tools) of live objects in the store, regardless of whether these
526 prerequisites are live. This is convenient for developers since it
527 saves rebuilds or downloads.
529 @item --impersonate-linux-2.6
530 On Linux-based systems, impersonate Linux 2.6. This means that the
531 kernel's @code{uname} system call will report 2.6 as the release number.
533 This might be helpful to build programs that (usually wrongfully) depend
534 on the kernel version number.
537 Do not keep build logs. By default they are kept under
538 @code{@var{localstatedir}/nix/log}.
540 @item --system=@var{system}
541 Assume @var{system} as the current system type. By default it is the
542 architecture/kernel pair found at configure time, such as
545 @item --listen=@var{socket}
546 Listen for connections on @var{socket}, the file name of a Unix-domain
547 socket. The default socket is
548 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
549 useful in exceptional circumstances, such as if you need to run several
550 daemons on the same machine.
554 @c *********************************************************************
555 @node Package Management
556 @chapter Package Management
558 The purpose of GNU Guix is to allow users to easily install, upgrade, and
559 remove software packages, without having to know about their build
560 procedure or dependencies. Guix also goes beyond this obvious set of
563 This chapter describes the main features of Guix, as well as the package
564 management tools it provides.
567 * Features:: How Guix will make your life brighter.
568 * Invoking guix package:: Package installation, removal, etc.
569 * Packages with Multiple Outputs:: Single source package, multiple outputs.
570 * Invoking guix gc:: Running the garbage collector.
571 * Invoking guix pull:: Fetching the latest Guix and distribution.
572 * Invoking guix archive:: Exporting and importing store files.
578 When using Guix, each package ends up in the @dfn{package store}, in its
579 own directory---something that resembles
580 @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
582 Instead of referring to these directories, users have their own
583 @dfn{profile}, which points to the packages that they actually want to
584 use. These profiles are stored within each user's home directory, at
585 @code{$HOME/.guix-profile}.
587 For example, @code{alice} installs GCC 4.7.2. As a result,
588 @file{/home/alice/.guix-profile/bin/gcc} points to
589 @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
590 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
591 simply continues to point to
592 @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
593 coexist on the same system without any interference.
595 The @command{guix package} command is the central tool to manage
596 packages (@pxref{Invoking guix package}). It operates on those per-user
597 profiles, and can be used @emph{with normal user privileges}.
599 The command provides the obvious install, remove, and upgrade
600 operations. Each invocation is actually a @emph{transaction}: either
601 the specified operation succeeds, or nothing happens. Thus, if the
602 @command{guix package} process is terminated during the transaction,
603 or if a power outage occurs during the transaction, then the user's
604 profile remains in its previous state, and remains usable.
606 In addition, any package transaction may be @emph{rolled back}. So, if,
607 for example, an upgrade installs a new version of a package that turns
608 out to have a serious bug, users may roll back to the previous instance
609 of their profile, which was known to work well. Similarly, the global
610 system configuration is subject to transactional upgrades and roll-back
611 (@pxref{Using the Configuration System}).
613 All those packages in the package store may be @emph{garbage-collected}.
614 Guix can determine which packages are still referenced by the user
615 profiles, and remove those that are provably no longer referenced
616 (@pxref{Invoking guix gc}). Users may also explicitly remove old
617 generations of their profile so that the packages they refer to can be
620 @cindex reproducibility
621 @cindex reproducible builds
622 Finally, Guix takes a @dfn{purely functional} approach to package
623 management, as described in the introduction (@pxref{Introduction}).
624 Each @file{/nix/store} package directory name contains a hash of all the
625 inputs that were used to build that package---compiler, libraries, build
626 scripts, etc. This direct correspondence allows users to make sure a
627 given package installation matches the current state of their
628 distribution. It also helps maximize @dfn{build reproducibility}:
629 thanks to the isolated build environments that are used, a given build
630 is likely to yield bit-identical files when performed on different
631 machines (@pxref{Invoking guix-daemon, container}).
634 This foundation allows Guix to support @dfn{transparent binary/source
635 deployment}. When a pre-built binary for a @file{/nix/store} path is
636 available from an external source---a @dfn{substitute}, Guix just
637 downloads it@footnote{@c XXX: Remove me when outdated.
638 As of version @value{VERSION}, substitutes are downloaded from
639 @url{http://hydra.gnu.org/} but are @emph{not} authenticated---i.e.,
640 Guix cannot tell whether binaries it downloaded have been tampered with,
641 nor whether they come from the genuine @code{gnu.org} build farm. This
642 will be fixed in future versions. In the meantime, concerned users can
643 opt for @code{--no-substitutes} (@pxref{Invoking guix-daemon}).};
644 otherwise, it builds the package from source, locally.
646 @node Invoking guix package
647 @section Invoking @command{guix package}
649 The @command{guix package} command is the tool that allows users to
650 install, upgrade, and remove packages, as well as rolling back to
651 previous configurations. It operates only on the user's own profile,
652 and works with normal user privileges (@pxref{Features}). Its syntax
656 guix package @var{options}
659 Primarily, @var{options} specifies the operations to be performed during
660 the transaction. Upon completion, a new profile is created, but
661 previous generations of the profile remain available, should the user
664 For example, to remove @code{lua} and install @code{guile} and
665 @code{guile-cairo} in a single transaction:
668 guix package -r lua -i guile guile-cairo
671 For each user, a symlink to the user's default profile is automatically
672 created in @file{$HOME/.guix-profile}. This symlink always points to the
673 current generation of the user's default profile. Thus, users can add
674 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
677 In a multi-user setup, user profiles must be stored in a place
678 registered as a @dfn{garbage-collector root}, which
679 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
680 directory is normally
681 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
682 @var{localstatedir} is the value passed to @code{configure} as
683 @code{--localstatedir}, and @var{user} is the user name. It must be
684 created by @code{root}, with @var{user} as the owner. When it does not
685 exist, or is not owned by @var{user}, @command{guix package} emits an
688 The @var{options} can be among the following:
692 @item --install=@var{package} @dots{}
693 @itemx -i @var{package} @dots{}
694 Install the specified @var{package}s.
696 Each @var{package} may specify either a simple package name, such as
697 @code{guile}, or a package name followed by a hyphen and version number,
698 such as @code{guile-1.8.8}. If no version number is specified, the
699 newest available version will be selected. In addition, @var{package}
700 may contain a colon, followed by the name of one of the outputs of the
701 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
702 (@pxref{Packages with Multiple Outputs}).
704 @cindex propagated inputs
705 Sometimes packages have @dfn{propagated inputs}: these are dependencies
706 that automatically get installed along with the required package.
708 An example is the GNU MPC library: its C header files refer to those of
709 the GNU MPFR library, which in turn refer to those of the GMP library.
710 Thus, when installing MPC, the MPFR and GMP libraries also get installed
711 in the profile; removing MPC also removes MPFR and GMP---unless they had
712 also been explicitly installed independently.
714 Besides, packages sometimes rely on the definition of environment
715 variables for their search paths (see explanation of
716 @code{--search-paths} below). Any missing or possibly incorrect
717 environment variable definitions are reported here.
719 @c XXX: keep me up-to-date
720 Finally, when installing a GNU package, the tool reports the
721 availability of a newer upstream version. In the future, it may provide
722 the option of installing directly from the upstream version, even if
723 that version is not yet in the distribution.
725 @item --install-from-expression=@var{exp}
727 Install the package @var{exp} evaluates to.
729 @var{exp} must be a Scheme expression that evaluates to a
730 @code{<package>} object. This option is notably useful to disambiguate
731 between same-named variants of a package, with expressions such as
732 @code{(@@ (gnu packages base) guile-final)}.
734 Note that this option installs the first output of the specified
735 package, which may be insufficient when needing a specific output of a
736 multiple-output package.
738 @item --remove=@var{package} @dots{}
739 @itemx -r @var{package} @dots{}
740 Remove the specified @var{package}s.
742 As for @code{--install}, each @var{package} may specify a version number
743 and/or output name in addition to the package name. For instance,
744 @code{-r glibc:debug} would remove the @code{debug} output of
747 @item --upgrade[=@var{regexp} @dots{}]
748 @itemx -u [@var{regexp} @dots{}]
749 Upgrade all the installed packages. If one or more @var{regexp}s are
750 specified, upgrade only installed packages whose name matches a
753 Note that this upgrades package to the latest version of packages found
754 in the distribution currently installed. To update your distribution,
755 you should regularly run @command{guix pull} (@pxref{Invoking guix
759 Roll back to the previous @dfn{generation} of the profile---i.e., undo
760 the last transaction.
762 When combined with options such as @code{--install}, roll back occurs
763 before any other actions.
765 When rolling back from the first generation that actually contains
766 installed packages, the profile is made to point to the @dfn{zeroth
767 generation}, which contains no files apart from its own meta-data.
769 Installing, removing, or upgrading packages from a generation that has
770 been rolled back to overwrites previous future generations. Thus, the
771 history of a profile's generations is always linear.
775 Report environment variable definitions, in Bash syntax, that may be
776 needed in order to use the set of installed packages. These environment
777 variables are used to specify @dfn{search paths} for files used by some
778 of the installed packages.
780 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
781 environment variables to be defined so it can look for headers and
782 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
783 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
784 library are installed in the profile, then @code{--search-paths} will
785 suggest setting these variables to @code{@var{profile}/include} and
786 @code{@var{profile}/lib}, respectively.
788 @item --profile=@var{profile}
789 @itemx -p @var{profile}
790 Use @var{profile} instead of the user's default profile.
794 Show what would be done without actually doing it.
797 When substituting a pre-built binary fails, fall back to building
800 @item --no-substitutes
801 Do not use substitutes for build products. That is, always build things
802 locally instead of allowing downloads of pre-built binaries.
804 @item --max-silent-time=@var{seconds}
805 Same as for @command{guix build} (@pxref{Invoking guix build}).
808 Produce verbose output. In particular, emit the environment's build log
809 on the standard error port.
812 Use the bootstrap Guile to build the profile. This option is only
813 useful to distribution developers.
817 In addition to these actions @command{guix package} supports the
818 following options to query the current state of a profile, or the
819 availability of packages:
823 @item --search=@var{regexp}
824 @itemx -s @var{regexp}
825 List the available packages whose synopsis or description matches
826 @var{regexp}. Print all the meta-data of matching packages in
827 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
828 GNU recutils manual}).
830 This allows specific fields to be extracted using the @command{recsel}
831 command, for instance:
834 $ guix package -s malloc | recsel -p name,version
842 @item --list-installed[=@var{regexp}]
843 @itemx -I [@var{regexp}]
844 List the currently installed packages in the specified profile, with the
845 most recently installed packages shown last. When @var{regexp} is
846 specified, list only installed packages whose name matches @var{regexp}.
848 For each installed package, print the following items, separated by
849 tabs: the package name, its version string, the part of the package that
850 is installed (for instance, @code{out} for the default output,
851 @code{include} for its headers, etc.), and the path of this package in
854 @item --list-available[=@var{regexp}]
855 @itemx -A [@var{regexp}]
856 List packages currently available in the software distribution
857 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
858 installed packages whose name matches @var{regexp}.
860 For each package, print the following items separated by tabs: its name,
861 its version string, the parts of the package (@pxref{Packages with
862 Multiple Outputs}), and the source location of its definition.
864 @item --list-generations[=@var{pattern}]
865 @itemx -l [@var{pattern}]
866 Return a list of generations along with their creation dates; for each
867 generation, show the installed packages, with the most recently
868 installed packages shown last. Note that the zeroth generation is never
871 For each installed package, print the following items, separated by
872 tabs: the name of a package, its version string, the part of the package
873 that is installed (@pxref{Packages with Multiple Outputs}), and the
874 location of this package in the store.
876 When @var{pattern} is used, the command returns only matching
877 generations. Valid patterns include:
880 @item @emph{Integers and comma-separated integers}. Both patterns denote
881 generation numbers. For instance, @code{--list-generations=1} returns
884 And @code{--list-generations=1,8,2} outputs three generations in the
885 specified order. Neither spaces nor trailing commas are allowed.
887 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
888 specified generations and everything in between. Note that the start of
889 a range must be lesser than its end.
891 It is also possible to omit the endpoint. For example,
892 @code{--list-generations=2..}, returns all generations starting from the
895 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
896 or months by passing an integer along with the first letter of the
897 duration. For example, @code{--list-generations=20d} lists generations
898 that are up to 20 days old.
901 @item --delete-generations[=@var{pattern}]
902 @itemx -d [@var{pattern}]
903 When @var{pattern} is omitted, delete all generations except the current
906 This command accepts the same patterns as @option{--list-generations}.
907 When @var{pattern} is specified, delete the matching generations. When
908 @var{pattern} specifies a duration, generations @emph{older} than the
909 specified duration match. For instance, @code{--delete-generations=1m}
910 deletes generations that are more than one month old.
912 If the current generation matches, it is deleted atomically---i.e., by
913 switching to the previous available generation. Note that the zeroth
914 generation is never deleted.
916 Note that deleting generations prevents roll-back to them.
917 Consequently, this command must be used with care.
921 @node Packages with Multiple Outputs
922 @section Packages with Multiple Outputs
924 @cindex multiple-output packages
925 @cindex package outputs
927 Often, packages defined in Guix have a single @dfn{output}---i.e., the
928 source package leads exactly one directory in the store. When running
929 @command{guix package -i glibc}, one installs the default output of the
930 GNU libc package; the default output is called @code{out}, but its name
931 can be omitted as shown in this command. In this particular case, the
932 default output of @code{glibc} contains all the C header files, shared
933 libraries, static libraries, Info documentation, and other supporting
936 Sometimes it is more appropriate to separate the various types of files
937 produced from a single source package into separate outputs. For
938 instance, the GLib C library (used by GTK+ and related packages)
939 installs more than 20 MiB of reference documentation as HTML pages.
940 To save space for users who do not need it, the documentation goes to a
941 separate output, called @code{doc}. To install the main GLib output,
942 which contains everything but the documentation, one would run:
948 The command to install its documentation is:
951 guix package -i glib:doc
954 Some packages install programs with different ``dependency footprints''.
955 For instance, the WordNet package install both command-line tools and
956 graphical user interfaces (GUIs). The former depend solely on the C
957 library, whereas the latter depend on Tcl/Tk and the underlying X
958 libraries. In this case, we leave the command-line tools in the default
959 output, whereas the GUIs are in a separate output. This allows users
960 who do not need the GUIs to save space.
962 There are several such multiple-output packages in the GNU distribution.
963 Other conventional output names include @code{lib} for libraries and
964 possibly header files, @code{bin} for stand-alone programs, and
965 @code{debug} for debugging information (@pxref{Installing Debugging
966 Files}). The outputs of a packages are listed in the third column of
967 the output of @command{guix package --list-available} (@pxref{Invoking
971 @node Invoking guix gc
972 @section Invoking @command{guix gc}
974 @cindex garbage collector
975 Packages that are installed but not used may be @dfn{garbage-collected}.
976 The @command{guix gc} command allows users to explicitly run the garbage
977 collector to reclaim space from the @file{/nix/store} directory.
979 The garbage collector has a set of known @dfn{roots}: any file under
980 @file{/nix/store} reachable from a root is considered @dfn{live} and
981 cannot be deleted; any other file is considered @dfn{dead} and may be
982 deleted. The set of garbage collector roots includes default user
983 profiles, and may be augmented with @command{guix build --root}, for
984 example (@pxref{Invoking guix build}).
986 Prior to running @code{guix gc --collect-garbage} to make space, it is
987 often useful to remove old generations from user profiles; that way, old
988 package builds referenced by those generations can be reclaimed. This
989 is achieved by running @code{guix package --delete-generations}
990 (@pxref{Invoking guix package}).
992 The @command{guix gc} command has three modes of operation: it can be
993 used to garbage-collect any dead files (the default), to delete specific
994 files (the @code{--delete} option), or to print garbage-collector
995 information. The available options are listed below:
998 @item --collect-garbage[=@var{min}]
999 @itemx -C [@var{min}]
1000 Collect garbage---i.e., unreachable @file{/nix/store} files and
1001 sub-directories. This is the default operation when no option is
1004 When @var{min} is given, stop once @var{min} bytes have been collected.
1005 @var{min} may be a number of bytes, or it may include a unit as a
1006 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
1008 When @var{min} is omitted, collect all the garbage.
1012 Attempt to delete all the store files and directories specified as
1013 arguments. This fails if some of the files are not in the store, or if
1014 they are still live.
1017 Show the list of dead files and directories still present in the
1018 store---i.e., files and directories no longer reachable from any root.
1021 Show the list of live store files and directories.
1025 In addition, the references among existing store files can be queried:
1031 List the references (respectively, the referrers) of store files given
1036 List the requisites of the store files passed as arguments. Requisites
1037 include the store files themselves, their references, and the references
1038 of these, recursively. In other words, the returned list is the
1039 @dfn{transitive closure} of the store files.
1044 @node Invoking guix pull
1045 @section Invoking @command{guix pull}
1047 Packages are installed or upgraded to the latest version available in
1048 the distribution currently available on your local machine. To update
1049 that distribution, along with the Guix tools, you must run @command{guix
1050 pull}: the command downloads the latest Guix source code and package
1051 descriptions, and deploys it.
1053 On completion, @command{guix package} will use packages and package
1054 versions from this just-retrieved copy of Guix. Not only that, but all
1055 the Guix commands and Scheme modules will also be taken from that latest
1056 version. New @command{guix} sub-commands added by the update also
1059 The @command{guix pull} command is usually invoked with no arguments,
1060 but it supports the following options:
1064 Produce verbose output, writing build logs to the standard error output.
1066 @item --url=@var{url}
1067 Download the source tarball of Guix from @var{url}.
1069 By default, the tarball is taken from its canonical address at
1070 @code{gnu.org}, for the stable branch of Guix.
1073 Use the bootstrap Guile to build the latest Guix. This option is only
1074 useful to Guix developers.
1078 @node Invoking guix archive
1079 @section Invoking @command{guix archive}
1081 The @command{guix archive} command allows users to @dfn{export} files
1082 from the store into a single archive, and to later @dfn{import} them.
1083 In particular, it allows store files to be transferred from one machine
1084 to another machine's store. For example, to transfer the @code{emacs}
1085 package to a machine connected over SSH, one would run:
1088 guix archive --export emacs | ssh the-machine guix archive --import
1092 However, note that, in this example, all of @code{emacs} and its
1093 dependencies are transferred, regardless of what is already available in
1094 the target machine's store. The @code{--missing} option can help figure
1095 out which items are missing from the target's store.
1097 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1098 comparable in spirit to `tar'. When exporting, the daemon digitally
1099 signs the contents of the archive, and that digital signature is
1100 appended. When importing, the daemon verifies the signature and rejects
1101 the import in case of an invalid signature or if the signing key is not
1103 @c FIXME: Add xref to daemon doc about signatures.
1105 The main options are:
1109 Export the specified store files or packages (see below.) Write the
1110 resulting archive to the standard output.
1113 Read an archive from the standard input, and import the files listed
1114 therein into the store. Abort if the archive has an invalid digital
1115 signature, or if it is signed by a public key not among the authorized
1116 keys (see @code{--authorize} below.)
1119 Read a list of store file names from the standard input, one per line,
1120 and write on the standard output the subset of these files missing from
1123 @item --generate-key[=@var{parameters}]
1124 @cindex signing, archives
1125 Generate a new key pair for the daemons. This is a prerequisite before
1126 archives can be exported with @code{--export}. Note that this operation
1127 usually takes time, because it needs to gather enough entropy to
1128 generate the key pair.
1130 The generated key pair is typically stored under @file{/etc/guix}, in
1131 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1132 key, which must be kept secret.) When @var{parameters} is omitted, it
1133 is a 4096-bit RSA key. Alternately, @var{parameters} can specify
1134 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1135 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1136 Libgcrypt Reference Manual}).
1139 @cindex authorizing, archives
1140 Authorize imports signed by the public key passed on standard input.
1141 The public key must be in ``s-expression advanced format''---i.e., the
1142 same format as the @file{signing-key.pub} file.
1144 The list of authorized keys is kept in the human-editable file
1145 @file{/etc/guix/acl}. The file contains
1146 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1147 s-expressions''} and is structured as an access-control list in the
1148 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1152 To export store files as an archive to the standard output, run:
1155 guix archive --export @var{options} @var{specifications}...
1158 @var{specifications} may be either store file names or package
1159 specifications, as for @command{guix package} (@pxref{Invoking guix
1160 package}). For instance, the following command creates an archive
1161 containing the @code{gui} output of the @code{git} package and the main
1162 output of @code{emacs}:
1165 guix archive --export git:gui /nix/store/...-emacs-24.3 > great.nar
1168 If the specified packages are not built yet, @command{guix archive}
1169 automatically builds them. The build process may be controlled with the
1170 same options that can be passed to the @command{guix build} command
1171 (@pxref{Invoking guix build}).
1174 @c *********************************************************************
1175 @node Programming Interface
1176 @chapter Programming Interface
1178 GNU Guix provides several Scheme programming interfaces (APIs) to
1179 define, build, and query packages. The first interface allows users to
1180 write high-level package definitions. These definitions refer to
1181 familiar packaging concepts, such as the name and version of a package,
1182 its build system, and its dependencies. These definitions can then be
1183 turned into concrete build actions.
1185 Build actions are performed by the Guix daemon, on behalf of users. In a
1186 standard setup, the daemon has write access to the store---the
1187 @file{/nix/store} directory---whereas users do not. The recommended
1188 setup also has the daemon perform builds in chroots, under a specific
1189 build users, to minimize interference with the rest of the system.
1192 Lower-level APIs are available to interact with the daemon and the
1193 store. To instruct the daemon to perform a build action, users actually
1194 provide it with a @dfn{derivation}. A derivation is a low-level
1195 representation of the build actions to be taken, and the environment in
1196 which they should occur---derivations are to package definitions what
1197 assembly is to C programs.
1199 This chapter describes all these APIs in turn, starting from high-level
1200 package definitions.
1203 * Defining Packages:: Defining new packages.
1204 * The Store:: Manipulating the package store.
1205 * Derivations:: Low-level interface to package derivations.
1206 * The Store Monad:: Purely functional interface to the store.
1209 @node Defining Packages
1210 @section Defining Packages
1212 The high-level interface to package definitions is implemented in the
1213 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1214 example, the package definition, or @dfn{recipe}, for the GNU Hello
1215 package looks like this:
1218 (use-modules (guix packages)
1220 (guix build-system gnu)
1229 (uri (string-append "mirror://gnu/hello/hello-" version
1232 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1233 (build-system gnu-build-system)
1234 (inputs `(("gawk" ,gawk)))
1235 (synopsis "GNU Hello")
1236 (description "Yeah...")
1237 (home-page "http://www.gnu.org/software/hello/")
1242 Without being a Scheme expert, the reader may have guessed the meaning
1243 of the various fields here. This expression binds variable @var{hello}
1244 to a @code{<package>} object, which is essentially a record
1245 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1246 This package object can be inspected using procedures found in the
1247 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1248 returns---surprise!---@code{"hello"}.
1250 There are a few points worth noting in the above package definition:
1254 The @code{source} field of the package is an @code{<origin>} object.
1255 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1256 meaning that the source is a file to be downloaded over FTP or HTTP.
1258 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1259 the GNU mirrors defined in @code{(guix download)}.
1261 The @code{sha256} field specifies the expected SHA256 hash of the file
1262 being downloaded. It is mandatory, and allows Guix to check the
1263 integrity of the file. The @code{(base32 @dots{})} form introduces the
1264 base32 representation of the hash. You can obtain this information with
1265 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1266 hash} (@pxref{Invoking guix hash}).
1269 When needed, the @code{origin} form can also have a @code{patches} field
1270 listing patches to be applied, and a @code{snippet} field giving a
1271 Scheme expression to modify the source code.
1274 @cindex GNU Build System
1275 The @code{build-system} field is set to @var{gnu-build-system}. The
1276 @var{gnu-build-system} variable is defined in the @code{(guix
1277 build-system gnu)} module, and is bound to a @code{<build-system>}
1280 Naturally, @var{gnu-build-system} represents the familiar GNU Build
1281 System, and variants thereof (@pxref{Configuration, configuration and
1282 makefile conventions,, standards, GNU Coding Standards}). In a
1283 nutshell, packages using the GNU Build System may be configured, built,
1284 and installed with the usual @code{./configure && make && make check &&
1285 make install} command sequence. This is what @var{gnu-build-system}
1288 In addition, @var{gnu-build-system} ensures that the ``standard''
1289 environment for GNU packages is available. This includes tools such as
1290 GCC, Coreutils, Bash, Make, Diffutils, and Patch.
1293 The @code{inputs} field specifies inputs to the build process---i.e.,
1294 build-time or run-time dependencies of the package. Here, we define an
1295 input called @code{"gawk"} whose value is that of the @var{gawk}
1296 variable; @var{gawk} is itself bound to a @code{<package>} object.
1298 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1299 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1300 of ensuring that they are present.
1302 However, any other dependencies need to be specified in the
1303 @code{inputs} field. Any dependency not specified here will simply be
1304 unavailable to the build process, possibly leading to a build failure.
1307 There are other fields that package definitions may provide. Of
1308 particular interest is the @code{arguments} field. When specified, it
1309 must be bound to a list of additional arguments to be passed to the
1310 build system. For instance, the above definition could be augmented
1311 with the following field initializer:
1314 (arguments `(#:tests? #f
1315 #:configure-flags '("--enable-silent-rules")))
1319 These are keyword arguments (@pxref{Optional Arguments, keyword
1320 arguments in Guile,, guile, GNU Guile Reference Manual}). They are
1321 passed to @var{gnu-build-system}, which interprets them as meaning ``do
1322 not run @code{make check}'', and ``run @file{configure} with the
1323 @code{--enable-silent-rules} flag''. The value of these keyword
1324 parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
1325 Guile process launched by the daemon (@pxref{Derivations}).
1327 Once a package definition is in place@footnote{Simple package
1328 definitions like the one above may be automatically converted from the
1329 Nixpkgs distribution using the @command{guix import} command.}, the
1330 package may actually be built using the @code{guix build} command-line
1331 tool (@pxref{Invoking guix build}). Eventually, updating the package
1332 definition to a new upstream version can be partly automated by the
1333 @command{guix refresh} command (@pxref{Invoking guix refresh}).
1335 Behind the scenes, a derivation corresponding to the @code{<package>}
1336 object is first computed by the @code{package-derivation} procedure.
1337 That derivation is stored in a @code{.drv} file under @file{/nix/store}.
1338 The build actions it prescribes may then be realized by using the
1339 @code{build-derivations} procedure (@pxref{The Store}).
1341 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1342 Return the @code{<derivation>} object of @var{package} for @var{system}
1343 (@pxref{Derivations}).
1345 @var{package} must be a valid @code{<package>} object, and @var{system}
1346 must be a string denoting the target system type---e.g.,
1347 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1348 must be a connection to the daemon, which operates on the store
1349 (@pxref{The Store}).
1353 @cindex cross-compilation
1354 Similarly, it is possible to compute a derivation that cross-builds a
1355 package for some other system:
1357 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1358 @var{package} @var{target} [@var{system}]
1359 Return the @code{<derivation>} object of @var{package} cross-built from
1360 @var{system} to @var{target}.
1362 @var{target} must be a valid GNU triplet denoting the target hardware
1363 and operating system, such as @code{"mips64el-linux-gnu"}
1364 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1365 Configure and Build System}).
1375 Conceptually, the @dfn{store} is where derivations that have been
1376 successfully built are stored---by default, under @file{/nix/store}.
1377 Sub-directories in the store are referred to as @dfn{store paths}. The
1378 store has an associated database that contains information such has the
1379 store paths referred to by each store path, and the list of @emph{valid}
1380 store paths---paths that result from a successful build.
1382 The store is always accessed by the daemon on behalf of its clients
1383 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1384 connect to the daemon over a Unix-domain socket, send it requests, and
1385 read the result---these are remote procedure calls, or RPCs.
1387 The @code{(guix store)} module provides procedures to connect to the
1388 daemon, and to perform RPCs. These are described below.
1390 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1391 Connect to the daemon over the Unix-domain socket at @var{file}. When
1392 @var{reserve-space?} is true, instruct it to reserve a little bit of
1393 extra space on the file system so that the garbage collector can still
1394 operate, should the disk become full. Return a server object.
1396 @var{file} defaults to @var{%default-socket-path}, which is the normal
1397 location given the options that were passed to @command{configure}.
1400 @deffn {Scheme Procedure} close-connection @var{server}
1401 Close the connection to @var{server}.
1404 @defvr {Scheme Variable} current-build-output-port
1405 This variable is bound to a SRFI-39 parameter, which refers to the port
1406 where build and error logs sent by the daemon should be written.
1409 Procedures that make RPCs all take a server object as their first
1412 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1413 Return @code{#t} when @var{path} is a valid store path.
1416 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1417 Add @var{text} under file @var{name} in the store, and return its store
1418 path. @var{references} is the list of store paths referred to by the
1419 resulting store path.
1422 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1423 Build @var{derivations} (a list of @code{<derivation>} objects or
1424 derivation paths), and return when the worker is done building them.
1425 Return @code{#t} on success.
1428 Note that the @code{(guix monads)} module provides a monad as well as
1429 monadic versions of the above procedures, with the goal of making it
1430 more convenient to work with code that accesses the store (@pxref{The
1434 @i{This section is currently incomplete.}
1437 @section Derivations
1440 Low-level build actions and the environment in which they are performed
1441 are represented by @dfn{derivations}. A derivation contain the
1442 following pieces of information:
1446 The outputs of the derivation---derivations produce at least one file or
1447 directory in the store, but may produce more.
1450 The inputs of the derivations, which may be other derivations or plain
1451 files in the store (patches, build scripts, etc.)
1454 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1457 The file name of a build script in the store, along with the arguments
1461 A list of environment variables to be defined.
1465 @cindex derivation path
1466 Derivations allow clients of the daemon to communicate build actions to
1467 the store. They exist in two forms: as an in-memory representation,
1468 both on the client- and daemon-side, and as files in the store whose
1469 name end in @code{.drv}---these files are referred to as @dfn{derivation
1470 paths}. Derivations paths can be passed to the @code{build-derivations}
1471 procedure to perform the build actions they prescribe (@pxref{The
1474 The @code{(guix derivations)} module provides a representation of
1475 derivations as Scheme objects, along with procedures to create and
1476 otherwise manipulate derivations. The lowest-level primitive to create
1477 a derivation is the @code{derivation} procedure:
1479 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
1480 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1481 [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] @
1482 [#:system (%current-system)] [#:references-graphs #f] @
1484 Build a derivation with the given arguments, and return the resulting
1485 @code{<derivation>} object.
1487 When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
1488 @dfn{fixed-output derivation} is created---i.e., one whose result is
1489 known in advance, such as a file download.
1491 When @var{references-graphs} is true, it must be a list of file
1492 name/store path pairs. In that case, the reference graph of each store
1493 path is exported in the build environment in the corresponding file, in
1494 a simple text format.
1496 When @var{local-build?} is true, declare that the derivation is not a
1497 good candidate for offloading and should rather be built locally
1498 (@pxref{Daemon Offload Setup}). This is the case for small derivations
1499 where the costs of data transfers would outweigh the benefits.
1503 Here's an example with a shell script as its builder, assuming
1504 @var{store} is an open connection to the daemon, and @var{bash} points
1505 to a Bash executable in the store:
1508 (use-modules (guix utils)
1512 (let ((builder ; add the Bash script to the store
1513 (add-text-to-store store "my-builder.sh"
1514 "echo hello world > $out\n" '())))
1515 (derivation store "foo"
1516 bash `("-e" ,builder)
1517 #:env-vars '(("HOME" . "/homeless"))))
1518 @result{} #<derivation /nix/store/@dots{}-foo.drv => /nix/store/@dots{}-foo>
1521 As can be guessed, this primitive is cumbersome to use directly. An
1522 improved variant is @code{build-expression->derivation}, which allows
1523 the caller to directly pass a Guile expression as the build script:
1525 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
1526 @var{name} @var{exp} @
1527 [#:system (%current-system)] [#:inputs '()] @
1528 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1529 [#:env-vars '()] [#:modules '()] @
1530 [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
1531 Return a derivation that executes Scheme expression @var{exp} as a
1532 builder for derivation @var{name}. @var{inputs} must be a list of
1533 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1534 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1535 modules from the current search path to be copied in the store,
1536 compiled, and made available in the load path during the execution of
1537 @var{exp}---e.g., @code{((guix build utils) (guix build
1538 gnu-build-system))}.
1540 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1541 to a list of output/path pairs, and where @code{%build-inputs} is bound
1542 to a list of string/output-path pairs made from @var{inputs}.
1543 Optionally, @var{env-vars} is a list of string pairs specifying the name
1544 and value of environment variables visible to the builder. The builder
1545 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1546 @var{exp} returns @code{#f}, the build is considered to have failed.
1548 @var{exp} is built using @var{guile-for-build} (a derivation). When
1549 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1550 @code{%guile-for-build} fluid is used instead.
1552 See the @code{derivation} procedure for the meaning of @var{references-graphs}
1553 and @var{local-build?}.
1557 Here's an example of a single-output derivation that creates a directory
1558 containing one file:
1561 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1562 (mkdir out) ; create /nix/store/@dots{}-goo
1563 (call-with-output-file (string-append out "/test")
1565 (display '(hello guix) p))))))
1566 (build-expression->derivation store "goo" builder))
1568 @result{} #<derivation /nix/store/@dots{}-goo.drv => @dots{}>
1571 @cindex strata of code
1572 Remember that the build expression passed to
1573 @code{build-expression->derivation} is run by a separate Guile process
1574 than the one that calls @code{build-expression->derivation}: it is run
1575 by a Guile process launched by the daemon, typically in a chroot. So,
1576 while there is a single language for both the @dfn{host} and the build
1577 side, there are really two @dfn{strata} of code: the host-side, and the
1578 build-side code@footnote{The term @dfn{stratum} in this context was
1579 coined by Manuel Serrano et al. in the context of their work on Hop.}.
1580 This distinction is important to keep in mind, notably when using
1581 higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
1582 Packages}). For this reason, Guix modules that are meant to be used in
1583 the build stratum are kept in the @code{(guix build @dots{})} name
1586 @node The Store Monad
1587 @section The Store Monad
1591 The procedures that operate on the store described in the previous
1592 sections all take an open connection to the build daemon as their first
1593 argument. Although the underlying model is functional, they either have
1594 side effects or depend on the current state of the store.
1596 The former is inconvenient: the connection to the build daemon has to be
1597 carried around in all those functions, making it impossible to compose
1598 functions that do not take that parameter with functions that do. The
1599 latter can be problematic: since store operations have side effects
1600 and/or depend on external state, they have to be properly sequenced.
1602 @cindex monadic values
1603 @cindex monadic functions
1604 This is where the @code{(guix monads)} module comes in. This module
1605 provides a framework for working with @dfn{monads}, and a particularly
1606 useful monad for our uses, the @dfn{store monad}. Monads are a
1607 construct that allows two things: associating ``context'' with values
1608 (in our case, the context is the store), and building sequences of
1609 computations (here computations includes accesses to the store.) Values
1610 in a monad---values that carry this additional context---are called
1611 @dfn{monadic values}; procedures that return such values are called
1612 @dfn{monadic procedures}.
1614 Consider this ``normal'' procedure:
1617 (define (sh-symlink store)
1618 ;; Return a derivation that symlinks the 'bash' executable.
1619 (let* ((drv (package-derivation store bash))
1620 (out (derivation->output-path drv))
1621 (sh (string-append out "/bin/bash")))
1622 (build-expression->derivation store "sh"
1623 `(symlink ,sh %output))))
1626 Using @code{(guix monads)}, it may be rewritten as a monadic function:
1629 (define (sh-symlink)
1630 ;; Same, but return a monadic value.
1631 (mlet %store-monad ((sh (package-file bash "bin")))
1632 (derivation-expression "sh" `(symlink ,sh %output))))
1635 There are two things to note in the second version: the @code{store}
1636 parameter is now implicit, and the monadic value returned by
1637 @code{package-file}---a wrapper around @code{package-derivation} and
1638 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
1639 instead of plain @code{let}.
1641 Calling the monadic @code{profile.sh} has no effect. To get the desired
1642 effect, one must use @code{run-with-store}:
1645 (run-with-store (open-connection) (profile.sh))
1646 @result{} /nix/store/...-profile.sh
1649 The main syntactic forms to deal with monads in general are described
1652 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
1653 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
1657 @deffn {Scheme Syntax} return @var{val}
1658 Return a monadic value that encapsulates @var{val}.
1661 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
1662 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
1663 procedure @var{mproc}@footnote{This operation is commonly referred to as
1664 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
1665 we use this somewhat cryptic symbol inherited from the Haskell
1669 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
1671 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
1673 Bind the variables @var{var} to the monadic values @var{mval} in
1674 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
1675 ``normal'' value @var{val}, as per @code{let}.
1677 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
1678 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
1681 The interface to the store monad provided by @code{(guix monads)} is as
1684 @defvr {Scheme Variable} %store-monad
1685 The store monad. Values in the store monad encapsulate accesses to the
1686 store. When its effect is needed, a value of the store monad must be
1687 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
1691 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
1692 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
1693 open store connection.
1696 @deffn {Monadic Procedure} text-file @var{name} @var{text}
1697 Return as a monadic value the absolute file name in the store of the file
1698 containing @var{text}, a string.
1701 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
1702 Return as a monadic value a derivation that builds a text file
1703 containing all of @var{text}. @var{text} may list, in addition to
1704 strings, packages, derivations, and store file names; the resulting
1705 store file holds references to all these.
1707 This variant should be preferred over @code{text-file} anytime the file
1708 to create will reference items from the store. This is typically the
1709 case when building a configuration file that embeds store file names,
1713 (define (profile.sh)
1714 ;; Return the name of a shell script in the store that
1715 ;; initializes the 'PATH' environment variable.
1716 (text-file* "profile.sh"
1717 "export PATH=" coreutils "/bin:"
1718 grep "/bin:" sed "/bin\n"))
1721 In this example, the resulting @file{/nix/store/@dots{}-profile.sh} file
1722 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
1723 preventing them from being garbage-collected during its lifetime.
1726 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
1727 [#:system (%current-system)] [#:output "out"] Return as a monadic
1728 value in the absolute file name of @var{file} within the @var{output}
1729 directory of @var{package}. When @var{file} is omitted, return the name
1730 of the @var{output} directory of @var{package}.
1733 @deffn {Monadic Procedure} derivation-expression @var{name} @var{exp} @
1734 [#:system (%current-system)] [#:inputs '()] @
1735 [#:outputs '("out")] [#:hash #f] @
1736 [#:hash-algo #f] [#:env-vars '()] [#:modules '()] @
1737 [#:references-graphs #f] [#:guile-for-build #f]
1738 Monadic version of @code{build-expression->derivation}
1739 (@pxref{Derivations}).
1742 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
1743 Monadic version of @code{package-derivation} (@pxref{Defining
1748 @c *********************************************************************
1752 This section describes tools primarily targeted at developers and users
1753 who write new package definitions. They complement the Scheme
1754 programming interface of Guix in a convenient way.
1757 * Invoking guix build:: Building packages from the command line.
1758 * Invoking guix download:: Downloading a file and printing its hash.
1759 * Invoking guix hash:: Computing the cryptographic hash of a file.
1760 * Invoking guix refresh:: Updating package definitions.
1763 @node Invoking guix build
1764 @section Invoking @command{guix build}
1766 The @command{guix build} command builds packages or derivations and
1767 their dependencies, and prints the resulting store paths. Note that it
1768 does not modify the user's profile---this is the job of the
1769 @command{guix package} command (@pxref{Invoking guix package}). Thus,
1770 it is mainly useful for distribution developers.
1772 The general syntax is:
1775 guix build @var{options} @var{package-or-derivation}@dots{}
1778 @var{package-or-derivation} may be either the name of a package found in
1779 the software distribution such as @code{coreutils} or
1780 @code{coreutils-8.20}, or a derivation such as
1781 @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
1782 @code{--expression} option may be used to specify a Scheme expression
1783 that evaluates to a package; this is useful when disambiguation among
1784 several same-named packages or package variants is needed.
1786 The @var{options} may be zero or more of the following:
1790 @item --expression=@var{expr}
1791 @itemx -e @var{expr}
1792 Build the package or derivation @var{expr} evaluates to.
1794 For example, @var{expr} may be @code{(@@ (gnu packages guile)
1795 guile-1.8)}, which unambiguously designates this specific variant of
1796 version 1.8 of Guile.
1798 Alternately, @var{expr} may refer to a zero-argument monadic procedure
1799 (@pxref{The Store Monad}). The procedure must return a derivation as a
1800 monadic value, which is then passed through @code{run-with-store}.
1804 Build the packages' source derivations, rather than the packages
1807 For instance, @code{guix build -S gcc} returns something like
1808 @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
1810 The returned source tarball is the result of applying any patches and
1811 code snippets specified in the package's @code{origin} (@pxref{Defining
1814 @item --system=@var{system}
1815 @itemx -s @var{system}
1816 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
1817 the host's system type.
1819 An example use of this is on Linux-based systems, which can emulate
1820 different personalities. For instance, passing
1821 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
1822 to build packages in a complete 32-bit environment.
1824 @item --target=@var{triplet}
1825 @cindex cross-compilation
1826 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
1827 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
1828 configuration triplets,, configure, GNU Configure and Build System}).
1832 Return the derivation paths, not the output paths, of the given
1837 Keep the build tree of failed builds. Thus, if a build fail, its build
1838 tree is kept under @file{/tmp}, in a directory whose name is shown at
1839 the end of the build log. This is useful when debugging build issues.
1843 Do not build the derivations.
1846 When substituting a pre-built binary fails, fall back to building
1849 @item --no-substitutes
1850 Do not use substitutes for build products. That is, always build things
1851 locally instead of allowing downloads of pre-built binaries.
1853 @item --no-build-hook
1854 Do not attempt to offload builds @i{via} the daemon's ``build hook''
1855 (@pxref{Daemon Offload Setup}). That is, always build things locally
1856 instead of offloading builds to remote machines.
1858 @item --max-silent-time=@var{seconds}
1859 When the build or substitution process remains silent for more than
1860 @var{seconds}, terminate it and report a build failure.
1862 @item --cores=@var{n}
1864 Allow the use of up to @var{n} CPU cores for the build. The special
1865 value @code{0} means to use as many CPU cores as available.
1867 @item --root=@var{file}
1868 @itemx -r @var{file}
1869 Make @var{file} a symlink to the result, and register it as a garbage
1872 @item --verbosity=@var{level}
1873 Use the given verbosity level. @var{level} must be an integer between 0
1874 and 5; higher means more verbose output. Setting a level of 4 or more
1875 may be helpful when debugging setup issues with the build daemon.
1878 Return the build log file names for the given
1879 @var{package-or-derivation}s, or raise an error if build logs are
1882 This works regardless of how packages or derivations are specified. For
1883 instance, the following invocations are equivalent:
1886 guix build --log-file `guix build -d guile`
1887 guix build --log-file `guix build guile`
1888 guix build --log-file guile
1889 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
1895 Behind the scenes, @command{guix build} is essentially an interface to
1896 the @code{package-derivation} procedure of the @code{(guix packages)}
1897 module, and to the @code{build-derivations} procedure of the @code{(guix
1900 @node Invoking guix download
1901 @section Invoking @command{guix download}
1903 When writing a package definition, developers typically need to download
1904 the package's source tarball, compute its SHA256 hash, and write that
1905 hash in the package definition (@pxref{Defining Packages}). The
1906 @command{guix download} tool helps with this task: it downloads a file
1907 from the given URI, adds it to the store, and prints both its file name
1908 in the store and its SHA256 hash.
1910 The fact that the downloaded file is added to the store saves bandwidth:
1911 when the developer eventually tries to build the newly defined package
1912 with @command{guix build}, the source tarball will not have to be
1913 downloaded again because it is already in the store. It is also a
1914 convenient way to temporarily stash files, which may be deleted
1915 eventually (@pxref{Invoking guix gc}).
1917 The @command{guix download} command supports the same URIs as used in
1918 package definitions. In particular, it supports @code{mirror://} URIs.
1919 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
1920 Guile bindings for GnuTLS are available in the user's environment; when
1921 they are not available, an error is raised.
1923 The following option is available:
1926 @item --format=@var{fmt}
1928 Write the hash in the format specified by @var{fmt}. For more
1929 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
1932 @node Invoking guix hash
1933 @section Invoking @command{guix hash}
1935 The @command{guix hash} command computes the SHA256 hash of a file.
1936 It is primarily a convenience tool for anyone contributing to the
1937 distribution: it computes the cryptographic hash of a file, which can be
1938 used in the definition of a package (@pxref{Defining Packages}).
1940 The general syntax is:
1943 guix hash @var{option} @var{file}
1946 @command{guix hash} has the following option:
1950 @item --format=@var{fmt}
1952 Write the hash in the format specified by @var{fmt}.
1954 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
1955 (@code{hex} and @code{hexadecimal} can be used as well).
1957 If the @option{--format} option is not specified, @command{guix hash}
1958 will output the hash in @code{nix-base32}. This representation is used
1959 in the definitions of packages.
1963 @node Invoking guix refresh
1964 @section Invoking @command{guix refresh}
1966 The primary audience of the @command{guix refresh} command is developers
1967 of the GNU software distribution. By default, it reports any packages
1968 provided by the distribution that are outdated compared to the latest
1969 upstream version, like this:
1973 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
1974 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
1977 It does so by browsing each package's FTP directory and determining the
1978 highest version number of the source tarballs
1979 therein@footnote{Currently, this only works for GNU packages.}.
1981 When passed @code{--update}, it modifies distribution source files to
1982 update the version numbers and source tarball hashes of those packages'
1983 recipes (@pxref{Defining Packages}). This is achieved by downloading
1984 each package's latest source tarball and its associated OpenPGP
1985 signature, authenticating the downloaded tarball against its signature
1986 using @command{gpg}, and finally computing its hash. When the public
1987 key used to sign the tarball is missing from the user's keyring, an
1988 attempt is made to automatically retrieve it from a public key server;
1989 when it's successful, the key is added to the user's keyring; otherwise,
1990 @command{guix refresh} reports an error.
1992 The following options are supported:
1998 Update distribution source files (package recipes) in place.
1999 @ref{Defining Packages}, for more information on package definitions.
2001 @item --select=[@var{subset}]
2002 @itemx -s @var{subset}
2003 Select all the packages in @var{subset}, one of @code{core} or
2006 The @code{core} subset refers to all the packages at the core of the
2007 distribution---i.e., packages that are used to build ``everything
2008 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
2009 changing one of these packages in the distribution entails a rebuild of
2010 all the others. Thus, such updates are an inconvenience to users in
2011 terms of build time or bandwidth used to achieve the upgrade.
2013 The @code{non-core} subset refers to the remaining packages. It is
2014 typically useful in cases where an update of the core packages would be
2019 In addition, @command{guix refresh} can be passed one or more package
2020 names, as in this example:
2023 guix refresh -u emacs idutils
2027 The command above specifically updates the @code{emacs} and
2028 @code{idutils} packages. The @code{--select} option would have no
2029 effect in this case.
2031 The following options can be used to customize GnuPG operation:
2035 @item --key-server=@var{host}
2036 Use @var{host} as the OpenPGP key server when importing a public key.
2038 @item --gpg=@var{command}
2039 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
2040 for in @code{$PATH}.
2045 @c *********************************************************************
2046 @node GNU Distribution
2047 @chapter GNU Distribution
2049 Guix comes with a distribution of free software@footnote{The term
2050 ``free'' here refers to the
2051 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
2052 users of that software}.} that forms the basis of the GNU system. This
2053 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
2054 as many GNU and non-GNU applications. The complete list of available
2055 packages can be browsed
2056 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
2057 running @command{guix package} (@pxref{Invoking guix package}):
2060 guix package --list-available
2063 Our goal is to build a practical 100% free software distribution of
2064 Linux-based and other variants of GNU, with a focus on the promotion and
2065 tight integration of GNU components, and an emphasis on programs and
2066 tools that help users exert that freedom.
2068 The GNU distribution is currently available on the following platforms:
2073 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
2076 Intel 32-bit architecture (IA32), Linux-Libre kernel;
2078 @item mips64el-linux
2079 little-endian 64-bit MIPS processors, specifically the Loongson series,
2080 n32 application binary interface (ABI), and Linux-Libre kernel.
2085 For information on porting to other architectures or kernels,
2089 * Installing Debugging Files:: Feeding the debugger.
2090 * Package Modules:: Packages from the programmer's viewpoint.
2091 * Packaging Guidelines:: Growing the distribution.
2092 * Bootstrapping:: GNU/Linux built from scratch.
2093 * Porting:: Targeting another platform or kernel.
2094 * System Configuration:: Configuring a GNU system.
2097 Building this distribution is a cooperative effort, and you are invited
2098 to join! @ref{Contributing}, for information about how you can help.
2101 @node Installing Debugging Files
2102 @section Installing Debugging Files
2104 Program binaries, as produced by the GCC compilers for instance, are
2105 typically written in the ELF format, with a section containing
2106 @dfn{debugging information}. Debugging information is what allows the
2107 debugger, GDB, to map binary code to source code; it is required to
2108 debug a compiled program in good conditions.
2110 The problem with debugging information is that is takes up a fair amount
2111 of disk space. For example, debugging information for the GNU C Library
2112 weighs in at more than 60 MiB. Thus, as a user, keeping all the
2113 debugging info of all the installed programs is usually not an option.
2114 Yet, space savings should not come at the cost of an impediment to
2115 debugging---especially in the GNU system, which should make it easier
2116 for users to exert their computing freedom (@pxref{GNU Distribution}).
2118 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
2119 mechanism that allows users to get the best of both worlds: debugging
2120 information can be stripped from the binaries and stored in separate
2121 files. GDB is then able to load debugging information from those files,
2122 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
2125 The GNU distribution takes advantage of this by storing debugging
2126 information in the @code{lib/debug} sub-directory of a separate package
2127 output unimaginatively called @code{debug} (@pxref{Packages with
2128 Multiple Outputs}). Users can choose to install the @code{debug} output
2129 of a package when they need it. For instance, the following command
2130 installs the debugging information for the GNU C Library and for GNU
2134 guix package -i glibc:debug -i guile:debug
2137 GDB must then be told to look for debug files in the user's profile, by
2138 setting the @code{debug-file-directory} variable (consider setting it
2139 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
2143 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
2146 From there on, GDB will pick up debugging information from the
2147 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
2149 @c XXX: keep me up-to-date
2150 The @code{debug} output mechanism in Guix is implemented by the
2151 @code{gnu-build-system} (@pxref{Defining Packages}). Currently, it is
2152 opt-in---debugging information is available only for those packages
2153 whose definition explicitly declares a @code{debug} output. This may be
2154 changed to opt-out in the future, if our build farm servers can handle
2155 the load. To check whether a package has a @code{debug} output, use
2156 @command{guix package --list-available} (@pxref{Invoking guix package}).
2159 @node Package Modules
2160 @section Package Modules
2162 From a programming viewpoint, the package definitions of the
2163 distribution are provided by Guile modules in the @code{(gnu packages
2164 @dots{})} name space@footnote{Note that packages under the @code{(gnu
2165 packages @dots{})} module name space are not necessarily ``GNU
2166 packages''. This module naming scheme follows the usual Guile module
2167 naming convention: @code{gnu} means that these modules are distributed
2168 as part of the GNU system, and @code{packages} identifies modules that
2169 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
2170 Reference Manual}). For instance, the @code{(gnu packages emacs)}
2171 module exports a variable named @code{emacs}, which is bound to a
2172 @code{<package>} object (@pxref{Defining Packages}). The @code{(gnu
2173 packages)} module provides facilities for searching for packages.
2175 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
2176 each package is built based solely on other packages in the
2177 distribution. The root of this dependency graph is a small set of
2178 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
2179 bootstrap)} module. For more information on bootstrapping,
2180 @ref{Bootstrapping}.
2182 @node Packaging Guidelines
2183 @section Packaging Guidelines
2185 The GNU distribution is nascent and may well lack some of your favorite
2186 packages. This section describes how you can help make the distribution
2187 grow. @xref{Contributing}, for additional information on how you can
2190 Free software packages are usually distributed in the form of
2191 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
2192 all the source files. Adding a package to the distribution means
2193 essentially two things: adding a @dfn{recipe} that describes how to
2194 build the package, including a list of other packages required to build
2195 it, and adding @dfn{package meta-data} along with that recipe, such as a
2196 description and licensing information.
2198 In Guix all this information is embodied in @dfn{package definitions}.
2199 Package definitions provide a high-level view of the package. They are
2200 written using the syntax of the Scheme programming language; in fact,
2201 for each package we define a variable bound to the package definition,
2202 and export that variable from a module (@pxref{Package Modules}).
2203 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
2204 creating packages. For more information on package definitions,
2205 @ref{Defining Packages}.
2207 Once a package definition is in place, stored in a file in the Guix
2208 source tree, it can be tested using the @command{guix build} command
2209 (@pxref{Invoking guix build}). For example, assuming the new package is
2210 called @code{gnew}, you may run this command from the Guix build tree:
2213 ./pre-inst-env guix build gnew --keep-failed
2216 Using @code{--keep-failed} makes it easier to debug build failures since
2217 it provides access to the failed build tree.
2219 Once your package builds correctly, please send us a patch
2220 (@pxref{Contributing}). Well, if you need help, we will be happy to
2221 help you too. Once the patch is committed in the Guix repository, the
2222 new package automatically gets built on the supported platforms by
2223 @url{http://hydra.gnu.org/gnu/master, our continuous integration
2227 Users can obtain the new package definition simply by running
2228 @command{guix pull} (@pxref{Invoking guix pull}). When
2229 @code{hydra.gnu.org} is done building the package, installing the
2230 package automatically downloads binaries from there (except when using
2231 @code{--no-substitutes}). The only place where human intervention is
2232 needed is to review and apply the patch.
2236 * Software Freedom:: What may go into the distribution.
2237 * Package Naming:: What's in a name?
2238 * Version Numbers:: When the name is not enough.
2239 * Python Modules:: Taming the snake.
2242 @node Software Freedom
2243 @subsection Software Freedom
2245 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
2247 The GNU operating system has been developed so that users can have
2248 freedom in their computing. GNU is @dfn{free software}, meaning that
2249 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
2250 essential freedoms}: to run the program, to study and change the program
2251 in source code form, to redistribute exact copies, and to distribute
2252 modified versions. Packages found in the GNU distribution provide only
2253 software that conveys these four freedoms.
2255 In addition, the GNU distribution follow the
2256 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
2257 software distribution guidelines}. Among other things, these guidelines
2258 reject non-free firmware, recommendations of non-free software, and
2259 discuss ways to deal with trademarks and patents.
2261 Some packages contain a small and optional subset that violates the
2262 above guidelines, for instance because this subset is itself non-free
2263 code. When that happens, the offending items are removed with
2264 appropriate patches or code snippets in the package definition's
2265 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
2266 build --source} returns the ``freed'' source rather than the unmodified
2270 @node Package Naming
2271 @subsection Package Naming
2273 A package has actually two names associated with it:
2274 First, there is the name of the @emph{Scheme variable}, the one following
2275 @code{define-public}. By this name, the package can be made known in the
2276 Scheme code, for instance as input to another package. Second, there is
2277 the string in the @code{name} field of a package definition. This name
2278 is used by package management commands such as
2279 @command{guix package} and @command{guix build}.
2281 Both are usually the same and correspond to the lowercase conversion of the
2282 project name chosen upstream. For instance, the GNUnet project is packaged
2283 as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
2284 unless these are already part of the official project name. But see
2285 @ref{Python Modules} for special rules concerning modules for
2286 the Python language.
2289 @node Version Numbers
2290 @subsection Version Numbers
2292 We usually package only the latest version of a given free software
2293 project. But sometimes, for instance for incompatible library versions,
2294 two (or more) versions of the same package are needed. These require
2295 different Scheme variable names. We use the name as defined
2296 in @ref{Package Naming}
2297 for the most recent version; previous versions use the same name, suffixed
2298 by @code{-} and the smallest prefix of the version number that may
2299 distinguish the two versions.
2301 The name inside the package definition is the same for all versions of a
2302 package and does not contain any version number.
2304 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
2312 (define-public gtk+-2
2318 If we also wanted GTK+ 3.8.2, this would be packaged as
2320 (define-public gtk+-3.8
2328 @node Python Modules
2329 @subsection Python Modules
2331 We currently package Python 2 and Python 3, under the Scheme variable names
2332 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
2333 To avoid confusion and naming clashes with other programming languages, it
2334 seems desirable that the name of a package for a Python module contains
2335 the word @code{python}.
2337 Some modules are compatible with only one version of Python, others with both.
2338 If the package Foo compiles only with Python 3, we name it
2339 @code{python-foo}; if it compiles only with Python 2, we name it
2340 @code{python2-foo}. If it is compatible with both versions, we create two
2341 packages with the corresponding names.
2343 If a project already contains the word @code{python}, we drop this;
2344 for instance, the module python-dateutil is packaged under the names
2345 @code{python-dateutil} and @code{python2-dateutil}.
2352 @section Bootstrapping
2354 @c Adapted from the ELS 2013 paper.
2356 @cindex bootstrapping
2358 Bootstrapping in our context refers to how the distribution gets built
2359 ``from nothing''. Remember that the build environment of a derivation
2360 contains nothing but its declared inputs (@pxref{Introduction}). So
2361 there's an obvious chicken-and-egg problem: how does the first package
2362 get built? How does the first compiler get compiled? Note that this is
2363 a question of interest only to the curious hacker, not to the regular
2364 user, so you can shamelessly skip this section if you consider yourself
2367 @cindex bootstrap binaries
2368 The GNU system is primarily made of C code, with libc at its core. The
2369 GNU build system itself assumes the availability of a Bourne shell and
2370 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
2371 `grep'. Furthermore, build programs---programs that run
2372 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
2373 (@pxref{Derivations}). Consequently, to be able to build anything at
2374 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
2375 Binutils, libc, and the other packages mentioned above---the
2376 @dfn{bootstrap binaries}.
2378 These bootstrap binaries are ``taken for granted'', though we can also
2379 re-create them if needed (more on that later).
2381 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
2383 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
2384 @c large image, it's hard to scroll. Oh well.
2385 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
2387 The figure above shows the very beginning of the dependency graph of the
2388 distribution, corresponding to the package definitions of the @code{(gnu
2389 packages bootstrap)} module. At this level of detail, things are
2390 slightly complex. First, Guile itself consists of an ELF executable,
2391 along with many source and compiled Scheme files that are dynamically
2392 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
2393 tarball shown in this graph. This tarball is part of Guix's ``source''
2394 distribution, and gets inserted into the store with @code{add-to-store}
2395 (@pxref{The Store}).
2397 But how do we write a derivation that unpacks this tarball and adds it
2398 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
2399 derivation---the first one that gets built---uses @code{bash} as its
2400 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
2401 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
2402 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
2403 the Guix source distribution, whose sole purpose is to allow the Guile
2404 tarball to be unpacked.
2406 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
2407 Guile that can be used to run subsequent build programs. Its first task
2408 is to download tarballs containing the other pre-built binaries---this
2409 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
2410 @code{ftp-client.scm} are used for this purpose. The
2411 @code{module-import.drv} derivations import those modules in a directory
2412 in the store, using the original layout. The
2413 @code{module-import-compiled.drv} derivations compile those modules, and
2414 write them in an output directory with the right layout. This
2415 corresponds to the @code{#:modules} argument of
2416 @code{build-expression->derivation} (@pxref{Derivations}).
2418 Finally, the various tarballs are unpacked by the
2419 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
2420 etc., at which point we have a working C tool chain.
2423 @unnumberedsubsec Building the Build Tools
2425 @c TODO: Add a package-level dependency graph generated from (gnu
2428 Bootstrapping is complete when we have a full tool chain that does not
2429 depend on the pre-built bootstrap tools discussed above. This
2430 no-dependency requirement is verified by checking whether the files of
2431 the final tool chain contain references to the @file{/nix/store}
2432 directories of the bootstrap inputs. The process that leads to this
2433 ``final'' tool chain is described by the package definitions found in
2434 the @code{(gnu packages base)} module.
2436 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
2437 The first tool that gets built with the bootstrap binaries is
2438 GNU Make, which is a prerequisite for all the following packages.
2439 From there Findutils and Diffutils get built.
2441 Then come the first-stage Binutils and GCC, built as pseudo cross
2442 tools---i.e., with @code{--target} equal to @code{--host}. They are
2443 used to build libc. Thanks to this cross-build trick, this libc is
2444 guaranteed not to hold any reference to the initial tool chain.
2446 From there the final Binutils and GCC are built. GCC uses @code{ld}
2447 from the final Binutils, and links programs against the just-built libc.
2448 This tool chain is used to build the other packages used by Guix and by
2449 the GNU Build System: Guile, Bash, Coreutils, etc.
2451 And voilà! At this point we have the complete set of build tools that
2452 the GNU Build System expects. These are in the @code{%final-inputs}
2453 variables of the @code{(gnu packages base)} module, and are implicitly
2454 used by any package that uses @code{gnu-build-system} (@pxref{Defining
2458 @unnumberedsubsec Building the Bootstrap Binaries
2460 Because the final tool chain does not depend on the bootstrap binaries,
2461 those rarely need to be updated. Nevertheless, it is useful to have an
2462 automated way to produce them, should an update occur, and this is what
2463 the @code{(gnu packages make-bootstrap)} module provides.
2465 The following command builds the tarballs containing the bootstrap
2466 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
2467 of Coreutils and other basic command-line tools):
2470 guix build bootstrap-tarballs
2473 The generated tarballs are those that should be referred to in the
2474 @code{(gnu packages bootstrap)} module mentioned at the beginning of
2477 Still here? Then perhaps by now you've started to wonder: when do we
2478 reach a fixed point? That is an interesting question! The answer is
2479 unknown, but if you would like to investigate further (and have
2480 significant computational and storage resources to do so), then let us
2484 @section Porting to a New Platform
2486 As discussed above, the GNU distribution is self-contained, and
2487 self-containment is achieved by relying on pre-built ``bootstrap
2488 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
2489 operating system kernel, CPU architecture, and application binary
2490 interface (ABI). Thus, to port the distribution to a platform that is
2491 not yet supported, one must build those bootstrap binaries, and update
2492 the @code{(gnu packages bootstrap)} module to use them on that platform.
2494 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
2495 When everything goes well, and assuming the GNU tool chain supports the
2496 target platform, this can be as simple as running a command like this
2500 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
2503 Once these are built, the @code{(gnu packages bootstrap)} module needs
2504 to be updated to refer to these binaries on the target platform. In
2505 addition, the @code{glibc-dynamic-linker} procedure in that module must
2506 be augmented to return the right file name for libc's dynamic linker on
2507 that platform; likewise, @code{system->linux-architecture} in @code{(gnu
2508 packages linux)} must be taught about the new platform.
2510 In practice, there may be some complications. First, it may be that the
2511 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
2512 above) is not recognized by all the GNU tools. Typically, glibc
2513 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
2514 configure flag (see @code{gcc.scm} for examples of how to handle this).
2515 Second, some of the required packages could fail to build for that
2516 platform. Lastly, the generated binaries could be broken for some
2520 @node System Configuration
2521 @section System Configuration
2523 @emph{This section documents work-in-progress. As such it may be
2524 incomplete, outdated, or open to discussions. Please discuss it on
2525 @email{guix-devel@@gnu.org}.}
2527 @cindex system configuration
2528 The GNU system supports a consistent whole-system configuration
2529 mechanism. By that we mean that all aspects of the global system
2530 configuration---such as the available system services, timezone and
2531 locale settings, user accounts---are declared in a single place. Such
2532 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
2534 One of the advantages of putting all the system configuration under the
2535 control of Guix is that it supports transactional system upgrades, and
2536 makes it possible to roll-back to a previous system instantiation,
2537 should something go wrong with the new one (@pxref{Features}). Another
2538 one is that it makes it easy to replicate the exact same configuration
2539 across different machines, or at different points in time, without
2540 having to resort to additional administration tools layered on top of
2541 the system's own tools.
2542 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
2544 This section describes this mechanism. First we focus on the system
2545 administrator's viewpoint---explaining how the system is configured and
2546 instantiated. Then we show how this mechanism can be extended, for
2547 instance to support new system services.
2550 * Using the Configuration System:: Customizing your GNU system.
2551 * Invoking guix system:: Instantiating a system configuration.
2552 * Defining Services:: Adding new service definitions.
2555 @node Using the Configuration System
2556 @subsection Using the Configuration System
2558 The operating system is configured by filling in an
2559 @code{operating-system} structure, as defined by the @code{(gnu system)}
2560 module. A simple setup, with the default system services, the default
2561 Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
2563 @findex operating-system
2565 (use-modules (gnu services base)
2566 (gnu services ssh) ; for 'lsh-service'
2567 (gnu system shadow) ; for 'user-account'
2568 (gnu packages base) ; Coreutils, grep, etc.
2569 (gnu packages bash) ; Bash
2570 (gnu packages admin) ; dmd, Inetutils
2571 (gnu packages zile) ; Zile
2572 (gnu packages less) ; less
2573 (gnu packages guile) ; Guile
2574 (gnu packages linux)) ; procps, psmisc
2578 (host-name "komputilo")
2579 (timezone "Europe/Paris")
2580 (locale "fr_FR.UTF-8")
2581 (users (list (user-account
2584 (uid 1000) (gid 100)
2585 (comment "Bob's sister")
2586 (home-directory "/home/alice"))))
2587 (packages (list coreutils bash guile-2.0
2593 (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
2594 %standard-services))))
2597 This example should be self-describing. The @code{packages} field lists
2598 packages provided by the various @code{(gnu packages ...)} modules above
2599 (@pxref{Package Modules}). These are the packages that will be globally
2600 visible on the system, for all user accounts---i.e., in every user's
2601 @code{PATH} environment variable---in addition to the per-user profiles
2602 (@pxref{Invoking guix package}).
2604 The @code{services} field lists @dfn{system services} to be made
2605 available when the system starts. The @var{%standard-services} list,
2606 from the @code{(gnu services base)} module, provides the basic services one
2607 would expect from a GNU system: a login service (mingetty) on each tty,
2608 syslogd, libc's name service cache daemon (nscd), etc.
2610 The @code{operating-system} declaration above specifies that, in
2611 addition to those services, we want the @command{lshd} secure shell
2612 daemon listening on port 2222, and allowing remote @code{root} logins
2613 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
2614 @code{lsh-service} arranges so that @code{lshd} is started with the
2615 right command-line options, possibly with supporting configuration files
2616 generated as needed (@pxref{Defining Services}).
2618 Assuming the above snippet is stored in the @file{my-system-config.scm}
2619 file, the @command{guix system boot my-system-config.scm} command
2620 instantiates that configuration, and makes it the default GRUB boot
2621 entry (@pxref{Invoking guix system}). The normal way to change the
2622 system's configuration is by updating this file and re-running the
2623 @command{guix system} command.
2625 At the Scheme level, the bulk of an @code{operating-system} declaration
2626 is instantiated with the following monadic procedure (@pxref{The Store
2629 @deffn {Monadic Procedure} operating-system-derivation os
2630 Return a derivation that builds @var{os}, an @code{operating-system}
2631 object (@pxref{Derivations}).
2633 The output of the derivation is a single directory that refers to all
2634 the packages, configuration files, and other supporting files needed to
2635 instantiate @var{os}.
2638 @node Invoking guix system
2639 @subsection Invoking @code{guix system}
2641 Once you have written an operating system declaration, as seen in the
2642 previous section, it can be @dfn{instantiated} using the @command{guix
2643 system} command. The synopsis is:
2646 guix system @var{options}@dots{} @var{action} @var{file}
2649 @var{file} must be the name of a file containing an
2650 @code{operating-system} declaration. @var{action} specifies how the
2651 operating system is instantiate. Currently only one value is supported:
2655 @cindex virtual machine
2656 Build a virtual machine that contain the operating system declared in
2657 @var{file}, and return a script to run that virtual machine (VM).
2659 The VM shares its store with the host system.
2662 @var{options} can contain any of the common build options provided by
2663 @command{guix build} (@pxref{Invoking guix build}).
2666 @node Defining Services
2667 @subsection Defining Services
2669 The @code{(gnu services @dots{})} modules define several procedures that allow
2670 users to declare the operating system's services (@pxref{Using the
2671 Configuration System}). These procedures are @emph{monadic
2672 procedures}---i.e., procedures that return a monadic value in the store
2673 monad (@pxref{The Store Monad}). Examples of such procedures include:
2676 @item mingetty-service
2677 return the definition of a service that runs @command{mingetty} to
2678 offer a login service on the given console tty;
2681 return a definition for libc's name service cache daemon (nscd);
2684 return a definition for a service that runs @command{guix-daemon}
2685 (@pxref{Invoking guix-daemon}).
2688 @cindex service definition
2689 The monadic value returned by those procedures is a @dfn{service
2690 definition}---a structure as returned by the @code{service} form.
2691 Service definitions specifies the inputs the service depends on, and an
2692 expression to start and stop the service. Behind the scenes, service
2693 definitions are ``translated'' into the form suitable for the
2694 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
2697 As an example, here is what the @code{nscd-service} procedure looks
2701 (define (nscd-service)
2702 (mlet %store-monad ((nscd (package-file glibc "sbin/nscd")))
2704 (documentation "Run libc's name service cache daemon.")
2706 (start `(make-forkexec-constructor ,nscd "-f" "/dev/null"
2708 (stop `(make-kill-destructor))
2711 (inputs `(("glibc" ,glibc)))))))
2715 The @code{inputs} field specifies that this service depends on the
2716 @var{glibc} package---the package that contains the @command{nscd}
2717 program. The @code{start} and @code{stop} fields are expressions that
2718 make use of dmd's facilities to start and stop processes (@pxref{Service
2719 De- and Constructors,,, dmd, GNU dmd Manual}). The @code{provision}
2720 field specifies the name under which this service is known to dmd, and
2721 @code{documentation} specifies on-line documentation. Thus, the
2722 commands @command{deco start ncsd}, @command{deco stop nscd}, and
2723 @command{deco doc nscd} will do what you would expect (@pxref{Invoking
2724 deco,,, dmd, GNU dmd Manual}).
2727 @c *********************************************************************
2729 @chapter Contributing
2731 This project is a cooperative effort, and we need your help to make it
2732 grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We
2733 welcome ideas, bug reports, patches, and anything that may be helpful to
2734 the project. We particularly welcome help on packaging
2735 (@pxref{Packaging Guidelines}).
2738 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
2739 @file{HACKING} file} that comes with the Guix source code for practical
2740 details about contributions.
2743 @c *********************************************************************
2744 @node Acknowledgments
2745 @chapter Acknowledgments
2747 Guix is based on the Nix package manager, which was designed and
2748 implemented by Eelco Dolstra. Nix pioneered functional package
2749 management, and promoted unprecedented features, such as transactional
2750 package upgrades and rollbacks, per-user profiles, and referentially
2751 transparent build processes. Without this work, Guix would not exist.
2753 The Nix-based software distributions, Nixpkgs and NixOS, have also been
2754 an inspiration for Guix.
2756 @c *********************************************************************
2757 @node GNU Free Documentation License
2758 @appendix GNU Free Documentation License
2760 @include fdl-1.3.texi
2762 @c *********************************************************************
2764 @unnumbered Concept Index
2767 @node Function Index
2768 @unnumbered Function Index
2774 @c ispell-local-dictionary: "american";