6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
14 Copyright @copyright{} 2013, 2014 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{/gnu/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 for Nix 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{/gnu/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 a minimal @code{/dev} directory, created mostly independently from the
249 host @code{/dev}@footnote{``Mostly'', because while the set of files
250 that appear in the chroot's @code{/dev} is fixed, most of these files
251 can only be created if the host has them.};
254 the @code{/proc} directory; it only shows the container's processes
255 since a separate PID name space is used;
258 @file{/etc/passwd} with an entry for the current user and an entry for
262 @file{/etc/group} with an entry for the user's group;
265 @file{/etc/hosts} with an entry that maps @code{localhost} to
269 a writable @file{/tmp} directory.
272 If you are installing Guix as an unprivileged user, it is still
273 possible to run @command{guix-daemon}. However, build processes will
274 not be isolated from one another, and not from the rest of the system.
275 Thus, build processes may interfere with each other, and may access
276 programs, libraries, and other files available on the system---making it
277 much harder to view them as @emph{pure} functions.
280 @node Daemon Offload Setup
281 @subsection Using the Offload Facility
285 When desired, the build daemon can @dfn{offload}
286 derivation builds to other machines
287 running Guix, using the @code{offload} @dfn{build hook}. When that
288 feature is enabled, a list of user-specified build machines is read from
289 @file{/etc/guix/machines.scm}; anytime a build is requested, for
290 instance via @code{guix build}, the daemon attempts to offload it to one
291 of the machines that satisfies the derivation's constraints, in
292 particular its system type---e.g., @file{x86_64-linux}. Missing
293 prerequisites for the build are copied over SSH to the target machine,
294 which then proceeds with the build; upon success the output(s) of the
295 build are copied back to the initial machine.
297 The @file{/etc/guix/machines.scm} file typically looks like this:
301 (name "eightysix.example.org")
302 (system "x86_64-linux")
304 (speed 2.)) ; incredibly fast!
307 (name "meeps.example.org")
308 (system "mips64el-linux")
311 (string-append (getenv "HOME")
312 "/.ssh/id-rsa-for-guix"))))
316 In the example above we specify a list of two build machines, one for
317 the @code{x86_64} architecture and one for the @code{mips64el}
320 In fact, this file is---not surprisingly!---a Scheme file that is
321 evaluated when the @code{offload} hook is started. Its return value
322 must be a list of @code{build-machine} objects. While this example
323 shows a fixed list of build machines, one could imagine, say, using
324 DNS-SD to return a list of potential build machines discovered in the
325 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
326 Avahi in Guile Scheme Programs}).
328 The compulsory fields for a @code{build-machine} declaration are:
333 The remote machine's host name.
336 The remote machine's system type.
339 The user account to use when connecting to the remote machine over SSH.
340 Note that the SSH key pair must @emph{not} be passphrase-protected, to
341 allow non-interactive logins.
346 A number of optional fields may be specified:
351 Port number of the machine's SSH server (default: 22).
354 The SSH private key file to use when connecting to the machine.
356 @item parallel-builds
357 The number of builds that may run in parallel on the machine (1 by
361 A ``relative speed factor''. The offload scheduler will tend to prefer
362 machines with a higher speed factor.
365 A list of strings denoting specific features supported by the machine.
366 An example is @code{"kvm"} for machines that have the KVM Linux modules
367 and corresponding hardware support. Derivations can request features by
368 name, and they will be scheduled on matching build machines.
372 The @code{guix} command must be in the search path on the build
373 machines, since offloading works by invoking the @code{guix archive} and
374 @code{guix build} commands.
376 There's one last thing to do once @file{machines.scm} is in place. As
377 explained above, when offloading, files are transferred back and forth
378 between the machine stores. For this to work, you need to generate a
379 key pair to allow the daemon to export signed archives of files from the
380 store (@pxref{Invoking guix archive}):
383 # guix archive --generate-key
387 Thus, when receiving files, a machine's build daemon can make sure they
388 are genuine, have not been tampered with, and that they are signed by an
392 @node Invoking guix-daemon
393 @section Invoking @command{guix-daemon}
395 The @command{guix-daemon} program implements all the functionality to
396 access the store. This includes launching build processes, running the
397 garbage collector, querying the availability of a build result, etc. It
398 is normally run as @code{root} like this:
401 # guix-daemon --build-users-group=guix-builder
405 For details on how to set it up, @ref{Setting Up the Daemon}.
408 @cindex container, build environment
409 @cindex build environment
410 @cindex reproducible builds
411 By default, @command{guix-daemon} launches build processes under
412 different UIDs, taken from the build group specified with
413 @code{--build-users-group}. In addition, each build process is run in a
414 chroot environment that only contains the subset of the store that the
415 build process depends on, as specified by its derivation
416 (@pxref{Programming Interface, derivation}), plus a set of specific
417 system directories. By default, the latter contains @file{/dev} and
418 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
419 @dfn{container}: in addition to having its own file system tree, it has
420 a separate mount name space, its own PID name space, network name space,
421 etc. This helps achieve reproducible builds (@pxref{Features}).
423 The following command-line options are supported:
426 @item --build-users-group=@var{group}
427 Take users from @var{group} to run build processes (@pxref{Setting Up
428 the Daemon, build users}).
430 @item --no-substitutes
432 Do not use substitutes for build products. That is, always build things
433 locally instead of allowing downloads of pre-built binaries
434 (@pxref{Substitutes}).
436 By default substitutes are used, unless the client---such as the
437 @command{guix package} command---is explicitly invoked with
438 @code{--no-substitutes}.
440 When the daemon runs with @code{--no-substitutes}, clients can still
441 explicitly enable substitution @i{via} the @code{set-build-options}
442 remote procedure call (@pxref{The Store}).
445 @item --no-build-hook
446 Do not use the @dfn{build hook}.
448 The build hook is a helper program that the daemon can start and to
449 which it submits build requests. This mechanism is used to offload
450 builds to other machines (@pxref{Daemon Offload Setup}).
452 @item --cache-failures
453 Cache build failures. By default, only successful builds are cached.
455 @item --cores=@var{n}
457 Use @var{n} CPU cores to build each derivation; @code{0} means as many
460 The default value is @code{1}, but it may be overridden by clients, such
461 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
464 The effect is to define the @code{NIX_BUILD_CORES} environment variable
465 in the build process, which can then use it to exploit internal
466 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
468 @item --max-jobs=@var{n}
470 Allow at most @var{n} build jobs in parallel. The default value is
474 Produce debugging output.
476 This is useful to debug daemon start-up issues, but then it may be
477 overridden by clients, for example the @code{--verbosity} option of
478 @command{guix build} (@pxref{Invoking guix build}).
480 @item --chroot-directory=@var{dir}
481 Add @var{dir} to the build chroot.
483 Doing this may change the result of build processes---for instance if
484 they use optional dependencies found in @var{dir} when it is available,
485 and not otherwise. For that reason, it is not recommended to do so.
486 Instead, make sure that each derivation declares all the inputs that it
489 @item --disable-chroot
490 Disable chroot builds.
492 Using this option is not recommended since, again, it would allow build
493 processes to gain access to undeclared dependencies.
495 @item --disable-log-compression
496 Disable compression of the build logs.
498 Unless @code{--lose-logs} is used, all the build logs are kept in the
499 @var{localstatedir}. To save space, the daemon automatically compresses
500 them with bzip2 by default. This option disables that.
502 @item --disable-store-optimization
503 Disable automatic file ``deduplication'' in the store.
505 By default, files added to the store are automatically ``deduplicated'':
506 if a newly added file is identical as another one found in the store,
507 the daemon makes the new file a hard link to the other file. This
508 slightly increases the input/output load at the end of a build process.
509 This option disables this.
511 @item --gc-keep-outputs[=yes|no]
512 Tell whether the garbage collector (GC) must keep outputs of live
515 When set to ``yes'', the GC will keep the outputs of any live derivation
516 available in the store---the @code{.drv} files. The default is ``no'',
517 meaning that derivation outputs are kept only if they are GC roots.
519 @item --gc-keep-derivations[=yes|no]
520 Tell whether the garbage collector (GC) must keep derivations
521 corresponding to live outputs.
523 When set to ``yes'', as is the case by default, the GC keeps
524 derivations---i.e., @code{.drv} files---as long as at least one of their
525 outputs is live. This allows users to keep track of the origins of
526 items in their store. Setting it to ``no'' saves a bit of disk space.
528 Note that when both @code{--gc-keep-derivations} and
529 @code{--gc-keep-outputs} are used, the effect is to keep all the build
530 prerequisites (the sources, compiler, libraries, and other build-time
531 tools) of live objects in the store, regardless of whether these
532 prerequisites are live. This is convenient for developers since it
533 saves rebuilds or downloads.
535 @item --impersonate-linux-2.6
536 On Linux-based systems, impersonate Linux 2.6. This means that the
537 kernel's @code{uname} system call will report 2.6 as the release number.
539 This might be helpful to build programs that (usually wrongfully) depend
540 on the kernel version number.
543 Do not keep build logs. By default they are kept under
544 @code{@var{localstatedir}/nix/log}.
546 @item --system=@var{system}
547 Assume @var{system} as the current system type. By default it is the
548 architecture/kernel pair found at configure time, such as
551 @item --listen=@var{socket}
552 Listen for connections on @var{socket}, the file name of a Unix-domain
553 socket. The default socket is
554 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
555 useful in exceptional circumstances, such as if you need to run several
556 daemons on the same machine.
560 @c *********************************************************************
561 @node Package Management
562 @chapter Package Management
564 The purpose of GNU Guix is to allow users to easily install, upgrade, and
565 remove software packages, without having to know about their build
566 procedure or dependencies. Guix also goes beyond this obvious set of
569 This chapter describes the main features of Guix, as well as the package
570 management tools it provides.
573 * Features:: How Guix will make your life brighter.
574 * Invoking guix package:: Package installation, removal, etc.
575 * Substitutes:: Downloading pre-built binaries.
576 * Packages with Multiple Outputs:: Single source package, multiple outputs.
577 * Invoking guix gc:: Running the garbage collector.
578 * Invoking guix pull:: Fetching the latest Guix and distribution.
579 * Invoking guix archive:: Exporting and importing store files.
585 When using Guix, each package ends up in the @dfn{package store}, in its
586 own directory---something that resembles
587 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
589 Instead of referring to these directories, users have their own
590 @dfn{profile}, which points to the packages that they actually want to
591 use. These profiles are stored within each user's home directory, at
592 @code{$HOME/.guix-profile}.
594 For example, @code{alice} installs GCC 4.7.2. As a result,
595 @file{/home/alice/.guix-profile/bin/gcc} points to
596 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
597 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
598 simply continues to point to
599 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
600 coexist on the same system without any interference.
602 The @command{guix package} command is the central tool to manage
603 packages (@pxref{Invoking guix package}). It operates on those per-user
604 profiles, and can be used @emph{with normal user privileges}.
606 The command provides the obvious install, remove, and upgrade
607 operations. Each invocation is actually a @emph{transaction}: either
608 the specified operation succeeds, or nothing happens. Thus, if the
609 @command{guix package} process is terminated during the transaction,
610 or if a power outage occurs during the transaction, then the user's
611 profile remains in its previous state, and remains usable.
613 In addition, any package transaction may be @emph{rolled back}. So, if,
614 for example, an upgrade installs a new version of a package that turns
615 out to have a serious bug, users may roll back to the previous instance
616 of their profile, which was known to work well. Similarly, the global
617 system configuration is subject to transactional upgrades and roll-back
618 (@pxref{Using the Configuration System}).
620 All those packages in the package store may be @emph{garbage-collected}.
621 Guix can determine which packages are still referenced by the user
622 profiles, and remove those that are provably no longer referenced
623 (@pxref{Invoking guix gc}). Users may also explicitly remove old
624 generations of their profile so that the packages they refer to can be
627 @cindex reproducibility
628 @cindex reproducible builds
629 Finally, Guix takes a @dfn{purely functional} approach to package
630 management, as described in the introduction (@pxref{Introduction}).
631 Each @file{/gnu/store} package directory name contains a hash of all the
632 inputs that were used to build that package---compiler, libraries, build
633 scripts, etc. This direct correspondence allows users to make sure a
634 given package installation matches the current state of their
635 distribution. It also helps maximize @dfn{build reproducibility}:
636 thanks to the isolated build environments that are used, a given build
637 is likely to yield bit-identical files when performed on different
638 machines (@pxref{Invoking guix-daemon, container}).
641 This foundation allows Guix to support @dfn{transparent binary/source
642 deployment}. When a pre-built binary for a @file{/gnu/store} item is
643 available from an external source---a @dfn{substitute}, Guix just
644 downloads it and unpacks it;
645 otherwise, it builds the package from source, locally
646 (@pxref{Substitutes}).
648 @node Invoking guix package
649 @section Invoking @command{guix package}
651 The @command{guix package} command is the tool that allows users to
652 install, upgrade, and remove packages, as well as rolling back to
653 previous configurations. It operates only on the user's own profile,
654 and works with normal user privileges (@pxref{Features}). Its syntax
658 guix package @var{options}
661 Primarily, @var{options} specifies the operations to be performed during
662 the transaction. Upon completion, a new profile is created, but
663 previous generations of the profile remain available, should the user
666 For example, to remove @code{lua} and install @code{guile} and
667 @code{guile-cairo} in a single transaction:
670 guix package -r lua -i guile guile-cairo
673 For each user, a symlink to the user's default profile is automatically
674 created in @file{$HOME/.guix-profile}. This symlink always points to the
675 current generation of the user's default profile. Thus, users can add
676 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
679 In a multi-user setup, user profiles must be stored in a place
680 registered as a @dfn{garbage-collector root}, which
681 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
682 directory is normally
683 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
684 @var{localstatedir} is the value passed to @code{configure} as
685 @code{--localstatedir}, and @var{user} is the user name. It must be
686 created by @code{root}, with @var{user} as the owner. When it does not
687 exist, or is not owned by @var{user}, @command{guix package} emits an
690 The @var{options} can be among the following:
694 @item --install=@var{package} @dots{}
695 @itemx -i @var{package} @dots{}
696 Install the specified @var{package}s.
698 Each @var{package} may specify either a simple package name, such as
699 @code{guile}, or a package name followed by a hyphen and version number,
700 such as @code{guile-1.8.8}. If no version number is specified, the
701 newest available version will be selected. In addition, @var{package}
702 may contain a colon, followed by the name of one of the outputs of the
703 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
704 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
705 name (and optionally version) are searched for among the GNU
706 distribution modules (@pxref{Package Modules}).
708 @cindex propagated inputs
709 Sometimes packages have @dfn{propagated inputs}: these are dependencies
710 that automatically get installed along with the required package.
712 An example is the GNU MPC library: its C header files refer to those of
713 the GNU MPFR library, which in turn refer to those of the GMP library.
714 Thus, when installing MPC, the MPFR and GMP libraries also get installed
715 in the profile; removing MPC also removes MPFR and GMP---unless they had
716 also been explicitly installed independently.
718 Besides, packages sometimes rely on the definition of environment
719 variables for their search paths (see explanation of
720 @code{--search-paths} below). Any missing or possibly incorrect
721 environment variable definitions are reported here.
723 @c XXX: keep me up-to-date
724 Finally, when installing a GNU package, the tool reports the
725 availability of a newer upstream version. In the future, it may provide
726 the option of installing directly from the upstream version, even if
727 that version is not yet in the distribution.
729 @item --install-from-expression=@var{exp}
731 Install the package @var{exp} evaluates to.
733 @var{exp} must be a Scheme expression that evaluates to a
734 @code{<package>} object. This option is notably useful to disambiguate
735 between same-named variants of a package, with expressions such as
736 @code{(@@ (gnu packages base) guile-final)}.
738 Note that this option installs the first output of the specified
739 package, which may be insufficient when needing a specific output of a
740 multiple-output package.
742 @item --remove=@var{package} @dots{}
743 @itemx -r @var{package} @dots{}
744 Remove the specified @var{package}s.
746 As for @code{--install}, each @var{package} may specify a version number
747 and/or output name in addition to the package name. For instance,
748 @code{-r glibc:debug} would remove the @code{debug} output of
751 @item --upgrade[=@var{regexp} @dots{}]
752 @itemx -u [@var{regexp} @dots{}]
753 Upgrade all the installed packages. If one or more @var{regexp}s are
754 specified, upgrade only installed packages whose name matches a
757 Note that this upgrades package to the latest version of packages found
758 in the distribution currently installed. To update your distribution,
759 you should regularly run @command{guix pull} (@pxref{Invoking guix
763 Roll back to the previous @dfn{generation} of the profile---i.e., undo
764 the last transaction.
766 When combined with options such as @code{--install}, roll back occurs
767 before any other actions.
769 When rolling back from the first generation that actually contains
770 installed packages, the profile is made to point to the @dfn{zeroth
771 generation}, which contains no files apart from its own meta-data.
773 Installing, removing, or upgrading packages from a generation that has
774 been rolled back to overwrites previous future generations. Thus, the
775 history of a profile's generations is always linear.
779 Report environment variable definitions, in Bash syntax, that may be
780 needed in order to use the set of installed packages. These environment
781 variables are used to specify @dfn{search paths} for files used by some
782 of the installed packages.
784 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
785 environment variables to be defined so it can look for headers and
786 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
787 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
788 library are installed in the profile, then @code{--search-paths} will
789 suggest setting these variables to @code{@var{profile}/include} and
790 @code{@var{profile}/lib}, respectively.
792 @item --profile=@var{profile}
793 @itemx -p @var{profile}
794 Use @var{profile} instead of the user's default profile.
797 Produce verbose output. In particular, emit the environment's build log
798 on the standard error port.
801 Use the bootstrap Guile to build the profile. This option is only
802 useful to distribution developers.
806 In addition to these actions @command{guix package} supports the
807 following options to query the current state of a profile, or the
808 availability of packages:
812 @item --search=@var{regexp}
813 @itemx -s @var{regexp}
814 List the available packages whose synopsis or description matches
815 @var{regexp}. Print all the meta-data of matching packages in
816 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
817 GNU recutils manual}).
819 This allows specific fields to be extracted using the @command{recsel}
820 command, for instance:
823 $ guix package -s malloc | recsel -p name,version
831 Similarly, to show the name of all the packages available under the
832 terms of the GNU@tie{}LGPL version 3:
835 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
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 Finally, since @command{guix package} may actually start build
922 processes, it supports all the common build options that @command{guix
923 build} supports (@pxref{Invoking guix build, common build options}).
929 @cindex pre-built binaries
930 Guix supports transparent source/binary deployment, which means that it
931 can either build things locally, or download pre-built items from a
932 server. We call these pre-built items @dfn{substitutes}---they are
933 substitutes for local build results. In many cases, downloading a
934 substitute is much faster than building things locally.
936 Substitutes can be anything resulting from a derivation build
937 (@pxref{Derivations}). Of course, in the common case, they are
938 pre-built package binaries, but source tarballs, for instance, which
939 also result from derivation builds, can be available as substitutes.
941 The @code{hydra.gnu.org} server is a front-end to a build farm that
942 builds packages from the GNU distribution continuously for some
943 architectures, and makes them available as substitutes.
946 @cindex digital signatures
947 To allow Guix to download substitutes from @code{hydra.gnu.org}, you
948 must add its public key to the access control list (ACL) of archive
949 imports, using the @command{guix archive} command (@pxref{Invoking guix
950 archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
951 be compromised and to serve genuine substitutes.
953 This public key is installed along with Guix, in
954 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
955 the installation prefix of Guix. If you installed Guix from source,
956 make sure you checked the GPG signature of
957 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
958 Then, you can run something like this:
961 # guix archive --authorize < hydra.gnu.org.pub
964 Once this is in place, the output of a command like @code{guix build}
965 should change from something like:
968 $ guix build emacs --dry-run
969 The following derivations would be built:
970 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
971 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
972 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
973 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
981 $ guix build emacs --dry-run
982 The following files would be downloaded:
983 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
984 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
985 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
986 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
991 This indicates that substitutes from @code{hydra.gnu.org} are usable and
992 will be downloaded, when possible, for future builds.
994 Guix ignores substitutes that are not signed, or that are not signed by
995 one of the keys listed in the ACL. It also detects and raises an error
996 when attempting to use a substitute that has been tampered with.
998 The substitute mechanism can be disabled globally by running
999 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1000 guix-daemon}). It can also be disabled temporarily by passing the
1001 @code{--no-substitutes} option to @command{guix package}, @command{guix
1002 build}, and other command-line tools.
1005 Today, each individual's control over their own computing is at the
1006 mercy of institutions, corporations, and groups with enough power and
1007 determination to subvert the computing infrastructure and exploit its
1008 weaknesses. While using @code{hydra.gnu.org} substitutes can be
1009 convenient, we encourage users to also build on their own, or even run
1010 their own build farm, such that @code{hydra.gnu.org} is less of an
1013 Guix has the foundations to maximize build reproducibility
1014 (@pxref{Features}). In most cases, independent builds of a given
1015 package or derivation should yield bit-identical results. Thus, through
1016 a diverse set of independent package builds, we can strengthen the
1017 integrity of our systems.
1019 In the future, we want Guix to have support to publish and retrieve
1020 binaries to/from other users, in a peer-to-peer fashion. If you would
1021 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1024 @node Packages with Multiple Outputs
1025 @section Packages with Multiple Outputs
1027 @cindex multiple-output packages
1028 @cindex package outputs
1030 Often, packages defined in Guix have a single @dfn{output}---i.e., the
1031 source package leads exactly one directory in the store. When running
1032 @command{guix package -i glibc}, one installs the default output of the
1033 GNU libc package; the default output is called @code{out}, but its name
1034 can be omitted as shown in this command. In this particular case, the
1035 default output of @code{glibc} contains all the C header files, shared
1036 libraries, static libraries, Info documentation, and other supporting
1039 Sometimes it is more appropriate to separate the various types of files
1040 produced from a single source package into separate outputs. For
1041 instance, the GLib C library (used by GTK+ and related packages)
1042 installs more than 20 MiB of reference documentation as HTML pages.
1043 To save space for users who do not need it, the documentation goes to a
1044 separate output, called @code{doc}. To install the main GLib output,
1045 which contains everything but the documentation, one would run:
1048 guix package -i glib
1051 The command to install its documentation is:
1054 guix package -i glib:doc
1057 Some packages install programs with different ``dependency footprints''.
1058 For instance, the WordNet package install both command-line tools and
1059 graphical user interfaces (GUIs). The former depend solely on the C
1060 library, whereas the latter depend on Tcl/Tk and the underlying X
1061 libraries. In this case, we leave the command-line tools in the default
1062 output, whereas the GUIs are in a separate output. This allows users
1063 who do not need the GUIs to save space.
1065 There are several such multiple-output packages in the GNU distribution.
1066 Other conventional output names include @code{lib} for libraries and
1067 possibly header files, @code{bin} for stand-alone programs, and
1068 @code{debug} for debugging information (@pxref{Installing Debugging
1069 Files}). The outputs of a packages are listed in the third column of
1070 the output of @command{guix package --list-available} (@pxref{Invoking
1074 @node Invoking guix gc
1075 @section Invoking @command{guix gc}
1077 @cindex garbage collector
1078 Packages that are installed but not used may be @dfn{garbage-collected}.
1079 The @command{guix gc} command allows users to explicitly run the garbage
1080 collector to reclaim space from the @file{/gnu/store} directory.
1082 The garbage collector has a set of known @dfn{roots}: any file under
1083 @file{/gnu/store} reachable from a root is considered @dfn{live} and
1084 cannot be deleted; any other file is considered @dfn{dead} and may be
1085 deleted. The set of garbage collector roots includes default user
1086 profiles, and may be augmented with @command{guix build --root}, for
1087 example (@pxref{Invoking guix build}).
1089 Prior to running @code{guix gc --collect-garbage} to make space, it is
1090 often useful to remove old generations from user profiles; that way, old
1091 package builds referenced by those generations can be reclaimed. This
1092 is achieved by running @code{guix package --delete-generations}
1093 (@pxref{Invoking guix package}).
1095 The @command{guix gc} command has three modes of operation: it can be
1096 used to garbage-collect any dead files (the default), to delete specific
1097 files (the @code{--delete} option), or to print garbage-collector
1098 information. The available options are listed below:
1101 @item --collect-garbage[=@var{min}]
1102 @itemx -C [@var{min}]
1103 Collect garbage---i.e., unreachable @file{/gnu/store} files and
1104 sub-directories. This is the default operation when no option is
1107 When @var{min} is given, stop once @var{min} bytes have been collected.
1108 @var{min} may be a number of bytes, or it may include a unit as a
1109 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
1111 When @var{min} is omitted, collect all the garbage.
1115 Attempt to delete all the store files and directories specified as
1116 arguments. This fails if some of the files are not in the store, or if
1117 they are still live.
1120 Show the list of dead files and directories still present in the
1121 store---i.e., files and directories no longer reachable from any root.
1124 Show the list of live store files and directories.
1128 In addition, the references among existing store files can be queried:
1134 List the references (respectively, the referrers) of store files given
1139 List the requisites of the store files passed as arguments. Requisites
1140 include the store files themselves, their references, and the references
1141 of these, recursively. In other words, the returned list is the
1142 @dfn{transitive closure} of the store files.
1147 @node Invoking guix pull
1148 @section Invoking @command{guix pull}
1150 Packages are installed or upgraded to the latest version available in
1151 the distribution currently available on your local machine. To update
1152 that distribution, along with the Guix tools, you must run @command{guix
1153 pull}: the command downloads the latest Guix source code and package
1154 descriptions, and deploys it.
1156 On completion, @command{guix package} will use packages and package
1157 versions from this just-retrieved copy of Guix. Not only that, but all
1158 the Guix commands and Scheme modules will also be taken from that latest
1159 version. New @command{guix} sub-commands added by the update also
1162 The @command{guix pull} command is usually invoked with no arguments,
1163 but it supports the following options:
1167 Produce verbose output, writing build logs to the standard error output.
1169 @item --url=@var{url}
1170 Download the source tarball of Guix from @var{url}.
1172 By default, the tarball is taken from its canonical address at
1173 @code{gnu.org}, for the stable branch of Guix.
1176 Use the bootstrap Guile to build the latest Guix. This option is only
1177 useful to Guix developers.
1181 @node Invoking guix archive
1182 @section Invoking @command{guix archive}
1184 The @command{guix archive} command allows users to @dfn{export} files
1185 from the store into a single archive, and to later @dfn{import} them.
1186 In particular, it allows store files to be transferred from one machine
1187 to another machine's store. For example, to transfer the @code{emacs}
1188 package to a machine connected over SSH, one would run:
1191 guix archive --export emacs | ssh the-machine guix archive --import
1195 However, note that, in this example, all of @code{emacs} and its
1196 dependencies are transferred, regardless of what is already available in
1197 the target machine's store. The @code{--missing} option can help figure
1198 out which items are missing from the target's store.
1200 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1201 comparable in spirit to `tar', but with a few noteworthy differences
1202 that make it more appropriate for our purposes. First, rather than
1203 recording all Unix meta-data for each file, the Nar format only mentions
1204 the file type (regular, directory, or symbolic link); Unix permissions
1205 and owner/group are dismissed. Second, the order in which directory
1206 entries are stored always follows the order of file names according to
1207 the C locale collation order. This makes archive production fully
1210 When exporting, the daemon digitally signs the contents of the archive,
1211 and that digital signature is appended. When importing, the daemon
1212 verifies the signature and rejects the import in case of an invalid
1213 signature or if the signing key is not authorized.
1214 @c FIXME: Add xref to daemon doc about signatures.
1216 The main options are:
1220 Export the specified store files or packages (see below.) Write the
1221 resulting archive to the standard output.
1224 Read an archive from the standard input, and import the files listed
1225 therein into the store. Abort if the archive has an invalid digital
1226 signature, or if it is signed by a public key not among the authorized
1227 keys (see @code{--authorize} below.)
1230 Read a list of store file names from the standard input, one per line,
1231 and write on the standard output the subset of these files missing from
1234 @item --generate-key[=@var{parameters}]
1235 @cindex signing, archives
1236 Generate a new key pair for the daemons. This is a prerequisite before
1237 archives can be exported with @code{--export}. Note that this operation
1238 usually takes time, because it needs to gather enough entropy to
1239 generate the key pair.
1241 The generated key pair is typically stored under @file{/etc/guix}, in
1242 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1243 key, which must be kept secret.) When @var{parameters} is omitted, it
1244 is a 4096-bit RSA key. Alternately, @var{parameters} can specify
1245 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1246 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1247 Libgcrypt Reference Manual}).
1250 @cindex authorizing, archives
1251 Authorize imports signed by the public key passed on standard input.
1252 The public key must be in ``s-expression advanced format''---i.e., the
1253 same format as the @file{signing-key.pub} file.
1255 The list of authorized keys is kept in the human-editable file
1256 @file{/etc/guix/acl}. The file contains
1257 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1258 s-expressions''} and is structured as an access-control list in the
1259 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1263 To export store files as an archive to the standard output, run:
1266 guix archive --export @var{options} @var{specifications}...
1269 @var{specifications} may be either store file names or package
1270 specifications, as for @command{guix package} (@pxref{Invoking guix
1271 package}). For instance, the following command creates an archive
1272 containing the @code{gui} output of the @code{git} package and the main
1273 output of @code{emacs}:
1276 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
1279 If the specified packages are not built yet, @command{guix archive}
1280 automatically builds them. The build process may be controlled with the
1281 same options that can be passed to the @command{guix build} command
1282 (@pxref{Invoking guix build, common build options}).
1285 @c *********************************************************************
1286 @node Programming Interface
1287 @chapter Programming Interface
1289 GNU Guix provides several Scheme programming interfaces (APIs) to
1290 define, build, and query packages. The first interface allows users to
1291 write high-level package definitions. These definitions refer to
1292 familiar packaging concepts, such as the name and version of a package,
1293 its build system, and its dependencies. These definitions can then be
1294 turned into concrete build actions.
1296 Build actions are performed by the Guix daemon, on behalf of users. In a
1297 standard setup, the daemon has write access to the store---the
1298 @file{/gnu/store} directory---whereas users do not. The recommended
1299 setup also has the daemon perform builds in chroots, under a specific
1300 build users, to minimize interference with the rest of the system.
1303 Lower-level APIs are available to interact with the daemon and the
1304 store. To instruct the daemon to perform a build action, users actually
1305 provide it with a @dfn{derivation}. A derivation is a low-level
1306 representation of the build actions to be taken, and the environment in
1307 which they should occur---derivations are to package definitions what
1308 assembly is to C programs.
1310 This chapter describes all these APIs in turn, starting from high-level
1311 package definitions.
1314 * Defining Packages:: Defining new packages.
1315 * Build Systems:: Specifying how packages are built.
1316 * The Store:: Manipulating the package store.
1317 * Derivations:: Low-level interface to package derivations.
1318 * The Store Monad:: Purely functional interface to the store.
1319 * G-Expressions:: Manipulating build expressions.
1322 @node Defining Packages
1323 @section Defining Packages
1325 The high-level interface to package definitions is implemented in the
1326 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1327 example, the package definition, or @dfn{recipe}, for the GNU Hello
1328 package looks like this:
1331 (define-module (gnu packages hello)
1332 #:use-module (guix packages)
1333 #:use-module (guix download)
1334 #:use-module (guix build-system gnu)
1335 #:use-module (guix licenses))
1343 (uri (string-append "mirror://gnu/hello/hello-" version
1346 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1347 (build-system gnu-build-system)
1348 (arguments `(#:configure-flags '("--enable-silent-rules")))
1349 (inputs `(("gawk" ,gawk)))
1350 (synopsis "Hello, GNU world: An example GNU package")
1351 (description "Guess what GNU Hello prints!")
1352 (home-page "http://www.gnu.org/software/hello/")
1357 Without being a Scheme expert, the reader may have guessed the meaning
1358 of the various fields here. This expression binds variable @code{hello}
1359 to a @code{<package>} object, which is essentially a record
1360 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1361 This package object can be inspected using procedures found in the
1362 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1363 returns---surprise!---@code{"hello"}.
1365 In the example above, @var{hello} is defined into a module of its own,
1366 @code{(gnu packages hello)}. Technically, this is not strictly
1367 necessary, but it is convenient to do so: all the packages defined in
1368 modules under @code{(gnu packages @dots{})} are automatically known to
1369 the command-line tools (@pxref{Package Modules}).
1371 There are a few points worth noting in the above package definition:
1375 The @code{source} field of the package is an @code{<origin>} object.
1376 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1377 meaning that the source is a file to be downloaded over FTP or HTTP.
1379 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1380 the GNU mirrors defined in @code{(guix download)}.
1382 The @code{sha256} field specifies the expected SHA256 hash of the file
1383 being downloaded. It is mandatory, and allows Guix to check the
1384 integrity of the file. The @code{(base32 @dots{})} form introduces the
1385 base32 representation of the hash. You can obtain this information with
1386 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1387 hash} (@pxref{Invoking guix hash}).
1390 When needed, the @code{origin} form can also have a @code{patches} field
1391 listing patches to be applied, and a @code{snippet} field giving a
1392 Scheme expression to modify the source code.
1395 @cindex GNU Build System
1396 The @code{build-system} field specifies the procedure to build the
1397 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1398 represents the familiar GNU Build System, where packages may be
1399 configured, built, and installed with the usual @code{./configure &&
1400 make && make check && make install} command sequence.
1403 The @code{arguments} field specifies options for the build system
1404 (@pxref{Build Systems}). Here it is interpreted by
1405 @var{gnu-build-system} as a request run @file{configure} with the
1406 @code{--enable-silent-rules} flag.
1409 The @code{inputs} field specifies inputs to the build process---i.e.,
1410 build-time or run-time dependencies of the package. Here, we define an
1411 input called @code{"gawk"} whose value is that of the @var{gawk}
1412 variable; @var{gawk} is itself bound to a @code{<package>} object.
1414 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1415 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1416 of ensuring that they are present (@pxref{Build Systems}).
1418 However, any other dependencies need to be specified in the
1419 @code{inputs} field. Any dependency not specified here will simply be
1420 unavailable to the build process, possibly leading to a build failure.
1423 Once a package definition is in place@footnote{Simple package
1424 definitions like the one above may be automatically converted from the
1425 Nixpkgs distribution using the @command{guix import} command.}, the
1426 package may actually be built using the @code{guix build} command-line
1427 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1428 more information on how to test package definitions.
1430 Eventually, updating the package definition to a new upstream version
1431 can be partly automated by the @command{guix refresh} command
1432 (@pxref{Invoking guix refresh}).
1434 Behind the scenes, a derivation corresponding to the @code{<package>}
1435 object is first computed by the @code{package-derivation} procedure.
1436 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1437 The build actions it prescribes may then be realized by using the
1438 @code{build-derivations} procedure (@pxref{The Store}).
1440 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1441 Return the @code{<derivation>} object of @var{package} for @var{system}
1442 (@pxref{Derivations}).
1444 @var{package} must be a valid @code{<package>} object, and @var{system}
1445 must be a string denoting the target system type---e.g.,
1446 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1447 must be a connection to the daemon, which operates on the store
1448 (@pxref{The Store}).
1452 @cindex cross-compilation
1453 Similarly, it is possible to compute a derivation that cross-builds a
1454 package for some other system:
1456 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1457 @var{package} @var{target} [@var{system}]
1458 Return the @code{<derivation>} object of @var{package} cross-built from
1459 @var{system} to @var{target}.
1461 @var{target} must be a valid GNU triplet denoting the target hardware
1462 and operating system, such as @code{"mips64el-linux-gnu"}
1463 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1464 Configure and Build System}).
1469 @section Build Systems
1471 @cindex build system
1472 Each package definition specifies a @dfn{build system} and arguments for
1473 that build system (@pxref{Defining Packages}). This @code{build-system}
1474 field represents the build procedure of the package, as well implicit
1475 dependencies of that build procedure.
1477 Build systems are @code{<build-system>} objects. The interface to
1478 create and manipulate them is provided by the @code{(guix build-system)}
1479 module, and actual build systems are exported by specific modules.
1481 Build systems accept an optional list of @dfn{arguments}. In package
1482 definitions, these are passed @i{via} the @code{arguments} field
1483 (@pxref{Defining Packages}). They are typically keyword arguments
1484 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
1485 Guile Reference Manual}). The value of these arguments is usually
1486 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
1487 by the daemon (@pxref{Derivations}).
1489 The main build system is @var{gnu-build-system}, which implements the
1490 standard build procedure for GNU packages and many other packages. It
1491 is provided by the @code{(guix build-system gnu)} module.
1493 @defvr {Scheme Variable} gnu-build-system
1494 @var{gnu-build-system} represents the GNU Build System, and variants
1495 thereof (@pxref{Configuration, configuration and makefile conventions,,
1496 standards, GNU Coding Standards}).
1498 @cindex build phases
1499 In a nutshell, packages using it configured, built, and installed with
1500 the usual @code{./configure && make && make check && make install}
1501 command sequence. In practice, a few additional steps are often needed.
1502 All these steps are split up in separate @dfn{phases},
1503 notably@footnote{Please see the @code{(guix build gnu-build-system)}
1504 modules for more details about the build phases.}:
1508 Unpack the source tarball, and change the current directory to the
1509 extracted source tree. If the source is actually a directory, copy it
1510 to the build tree, and enter that directory.
1512 @item patch-source-shebangs
1513 Patch shebangs encountered in source files so they refer to the right
1514 store file names. For instance, this changes @code{#!/bin/sh} to
1515 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
1518 Run the @file{configure} script with a number of default options, such
1519 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
1520 by the @code{#:configure-flags} argument.
1523 Run @code{make} with the list of flags specified with
1524 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
1525 (the default), build with @code{make -j}.
1528 Run @code{make check}, or some other target specified with
1529 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
1530 @code{#:parallel-tests?} argument is true (the default), run @code{make
1534 Run @code{make install} with the flags listed in @code{#:make-flags}.
1536 @item patch-shebangs
1537 Patch shebangs on the installed executable files.
1540 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
1541 is false), copying them to the @code{debug} output when available
1542 (@pxref{Installing Debugging Files}).
1545 @vindex %standard-phases
1546 The build-side module @code{(guix build gnu-build-system)} defines
1547 @var{%standard-phases} as the default list of build phases.
1548 @var{%standard-phases} is a list of symbol/procedure pairs, where the
1549 procedure implements the actual phase.
1551 The list of phases used for a particular package can be changed with the
1552 @code{#:phases} parameter. For instance, passing:
1555 #:phases (alist-delete 'configure %standard-phases)
1558 means that all the phases described above will be used, except the
1559 @code{configure} phase.
1561 In addition, this build system ensures that the ``standard'' environment
1562 for GNU packages is available. This includes tools such as GCC, libc,
1563 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
1564 build-system gnu)} module for a complete list.) We call these the
1565 @dfn{implicit inputs} of a package, because package definitions don't
1566 have to mention them.
1569 Other @code{<build-system>} objects are defined to support other
1570 conventions and tools used by free software packages. They inherit most
1571 of @var{gnu-build-system}, and differ mainly in the set of inputs
1572 implicitly added to the build process, and in the list of phases
1573 executed. Some of these build systems are listed below.
1575 @defvr {Scheme Variable} cmake-build-system
1576 This variable is exported by @code{(guix build-system cmake)}. It
1577 implements the build procedure for packages using the
1578 @url{http://www.cmake.org, CMake build tool}.
1580 It automatically adds the @code{cmake} package to the set of inputs.
1581 Which package is used can be specified with the @code{#:cmake}
1585 @defvr {Scheme Variable} python-build-system
1586 This variable is exported by @code{(guix build-system python)}. It
1587 implements the more or less standard build procedure used by Python
1588 packages, which consists in running @code{python setup.py build} and
1589 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
1591 For packages that install stand-alone Python programs under @code{bin/},
1592 it takes care of wrapping these programs so their @code{PYTHONPATH}
1593 environment variable points to all the Python libraries they depend on.
1595 Which Python package is used can be specified with the @code{#:python}
1599 @defvr {Scheme Variable} perl-build-system
1600 This variable is exported by @code{(guix build-system perl)}. It
1601 implements the standard build procedure for Perl packages, which
1602 consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
1603 followed by @code{make} and @code{make install}.
1605 The initial @code{perl Makefile.PL} invocation passes flags specified by
1606 the @code{#:make-maker-flags} parameter.
1608 Which Perl package is used can be specified with @code{#:perl}.
1612 Lastly, for packages that do not need anything as sophisticated, a
1613 ``trivial'' build system is provided. It is trivial in the sense that
1614 it provides basically no support: it does not pull any implicit inputs,
1615 and does not have a notion of build phases.
1617 @defvr {Scheme Variable} trivial-build-system
1618 This variable is exported by @code{(guix build-system trivial)}.
1620 This build system requires a @code{#:builder} argument. This argument
1621 must be a Scheme expression that builds the package's output(s)---as
1622 with @code{build-expression->derivation} (@pxref{Derivations,
1623 @code{build-expression->derivation}}).
1632 Conceptually, the @dfn{store} is where derivations that have been
1633 successfully built are stored---by default, under @file{/gnu/store}.
1634 Sub-directories in the store are referred to as @dfn{store paths}. The
1635 store has an associated database that contains information such has the
1636 store paths referred to by each store path, and the list of @emph{valid}
1637 store paths---paths that result from a successful build.
1639 The store is always accessed by the daemon on behalf of its clients
1640 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1641 connect to the daemon over a Unix-domain socket, send it requests, and
1642 read the result---these are remote procedure calls, or RPCs.
1644 The @code{(guix store)} module provides procedures to connect to the
1645 daemon, and to perform RPCs. These are described below.
1647 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1648 Connect to the daemon over the Unix-domain socket at @var{file}. When
1649 @var{reserve-space?} is true, instruct it to reserve a little bit of
1650 extra space on the file system so that the garbage collector can still
1651 operate, should the disk become full. Return a server object.
1653 @var{file} defaults to @var{%default-socket-path}, which is the normal
1654 location given the options that were passed to @command{configure}.
1657 @deffn {Scheme Procedure} close-connection @var{server}
1658 Close the connection to @var{server}.
1661 @defvr {Scheme Variable} current-build-output-port
1662 This variable is bound to a SRFI-39 parameter, which refers to the port
1663 where build and error logs sent by the daemon should be written.
1666 Procedures that make RPCs all take a server object as their first
1669 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1670 Return @code{#t} when @var{path} is a valid store path.
1673 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1674 Add @var{text} under file @var{name} in the store, and return its store
1675 path. @var{references} is the list of store paths referred to by the
1676 resulting store path.
1679 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1680 Build @var{derivations} (a list of @code{<derivation>} objects or
1681 derivation paths), and return when the worker is done building them.
1682 Return @code{#t} on success.
1685 Note that the @code{(guix monads)} module provides a monad as well as
1686 monadic versions of the above procedures, with the goal of making it
1687 more convenient to work with code that accesses the store (@pxref{The
1691 @i{This section is currently incomplete.}
1694 @section Derivations
1697 Low-level build actions and the environment in which they are performed
1698 are represented by @dfn{derivations}. A derivation contain the
1699 following pieces of information:
1703 The outputs of the derivation---derivations produce at least one file or
1704 directory in the store, but may produce more.
1707 The inputs of the derivations, which may be other derivations or plain
1708 files in the store (patches, build scripts, etc.)
1711 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1714 The file name of a build script in the store, along with the arguments
1718 A list of environment variables to be defined.
1722 @cindex derivation path
1723 Derivations allow clients of the daemon to communicate build actions to
1724 the store. They exist in two forms: as an in-memory representation,
1725 both on the client- and daemon-side, and as files in the store whose
1726 name end in @code{.drv}---these files are referred to as @dfn{derivation
1727 paths}. Derivations paths can be passed to the @code{build-derivations}
1728 procedure to perform the build actions they prescribe (@pxref{The
1731 The @code{(guix derivations)} module provides a representation of
1732 derivations as Scheme objects, along with procedures to create and
1733 otherwise manipulate derivations. The lowest-level primitive to create
1734 a derivation is the @code{derivation} procedure:
1736 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
1737 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1738 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
1739 [#:system (%current-system)] [#:references-graphs #f] @
1740 [#:allowed-references #f] [#:local-build? #f]
1741 Build a derivation with the given arguments, and return the resulting
1742 @code{<derivation>} object.
1744 When @var{hash} and @var{hash-algo} are given, a
1745 @dfn{fixed-output derivation} is created---i.e., one whose result is
1746 known in advance, such as a file download. If, in addition,
1747 @var{recursive?} is true, then that fixed output may be an executable
1748 file or a directory and @var{hash} must be the hash of an archive
1749 containing this output.
1751 When @var{references-graphs} is true, it must be a list of file
1752 name/store path pairs. In that case, the reference graph of each store
1753 path is exported in the build environment in the corresponding file, in
1754 a simple text format.
1756 When @var{allowed-references} is true, it must be a list of store items
1757 or outputs that the derivation's output may refer to.
1759 When @var{local-build?} is true, declare that the derivation is not a
1760 good candidate for offloading and should rather be built locally
1761 (@pxref{Daemon Offload Setup}). This is the case for small derivations
1762 where the costs of data transfers would outweigh the benefits.
1766 Here's an example with a shell script as its builder, assuming
1767 @var{store} is an open connection to the daemon, and @var{bash} points
1768 to a Bash executable in the store:
1771 (use-modules (guix utils)
1775 (let ((builder ; add the Bash script to the store
1776 (add-text-to-store store "my-builder.sh"
1777 "echo hello world > $out\n" '())))
1778 (derivation store "foo"
1779 bash `("-e" ,builder)
1780 #:inputs `((,bash) (,builder))
1781 #:env-vars '(("HOME" . "/homeless"))))
1782 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
1785 As can be guessed, this primitive is cumbersome to use directly. A
1786 better approach is to write build scripts in Scheme, of course! The
1787 best course of action for that is to write the build code as a
1788 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
1789 information, @ref{G-Expressions}.
1791 Once upon a time, @code{gexp->derivation} did not exist and constructing
1792 derivations with build code written in Scheme was achieved with
1793 @code{build-expression->derivation}, documented below. This procedure
1794 is now deprecated in favor of the much nicer @code{gexp->derivation}.
1796 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
1797 @var{name} @var{exp} @
1798 [#:system (%current-system)] [#:inputs '()] @
1799 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1800 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
1801 [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
1802 Return a derivation that executes Scheme expression @var{exp} as a
1803 builder for derivation @var{name}. @var{inputs} must be a list of
1804 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1805 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1806 modules from the current search path to be copied in the store,
1807 compiled, and made available in the load path during the execution of
1808 @var{exp}---e.g., @code{((guix build utils) (guix build
1809 gnu-build-system))}.
1811 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1812 to a list of output/path pairs, and where @code{%build-inputs} is bound
1813 to a list of string/output-path pairs made from @var{inputs}.
1814 Optionally, @var{env-vars} is a list of string pairs specifying the name
1815 and value of environment variables visible to the builder. The builder
1816 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1817 @var{exp} returns @code{#f}, the build is considered to have failed.
1819 @var{exp} is built using @var{guile-for-build} (a derivation). When
1820 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1821 @code{%guile-for-build} fluid is used instead.
1823 See the @code{derivation} procedure for the meaning of @var{references-graphs}
1824 and @var{local-build?}.
1828 Here's an example of a single-output derivation that creates a directory
1829 containing one file:
1832 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1833 (mkdir out) ; create /gnu/store/@dots{}-goo
1834 (call-with-output-file (string-append out "/test")
1836 (display '(hello guix) p))))))
1837 (build-expression->derivation store "goo" builder))
1839 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
1843 @node The Store Monad
1844 @section The Store Monad
1848 The procedures that operate on the store described in the previous
1849 sections all take an open connection to the build daemon as their first
1850 argument. Although the underlying model is functional, they either have
1851 side effects or depend on the current state of the store.
1853 The former is inconvenient: the connection to the build daemon has to be
1854 carried around in all those functions, making it impossible to compose
1855 functions that do not take that parameter with functions that do. The
1856 latter can be problematic: since store operations have side effects
1857 and/or depend on external state, they have to be properly sequenced.
1859 @cindex monadic values
1860 @cindex monadic functions
1861 This is where the @code{(guix monads)} module comes in. This module
1862 provides a framework for working with @dfn{monads}, and a particularly
1863 useful monad for our uses, the @dfn{store monad}. Monads are a
1864 construct that allows two things: associating ``context'' with values
1865 (in our case, the context is the store), and building sequences of
1866 computations (here computations includes accesses to the store.) Values
1867 in a monad---values that carry this additional context---are called
1868 @dfn{monadic values}; procedures that return such values are called
1869 @dfn{monadic procedures}.
1871 Consider this ``normal'' procedure:
1874 (define (sh-symlink store)
1875 ;; Return a derivation that symlinks the 'bash' executable.
1876 (let* ((drv (package-derivation store bash))
1877 (out (derivation->output-path drv))
1878 (sh (string-append out "/bin/bash")))
1879 (build-expression->derivation store "sh"
1880 `(symlink ,sh %output))))
1883 Using @code{(guix monads)}, it may be rewritten as a monadic function:
1885 @c FIXME: Find a better example, one that uses 'mlet'.
1887 (define (sh-symlink)
1888 ;; Same, but return a monadic value.
1889 (gexp->derivation "sh"
1890 #~(symlink (string-append #$bash "/bin/bash") #$output)))
1893 There are two things to note in the second version: the @code{store}
1894 parameter is now implicit, and the monadic value returned by
1895 @code{package-file}---a wrapper around @code{package-derivation} and
1896 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
1897 instead of plain @code{let}.
1899 Calling the monadic @code{profile.sh} has no effect. To get the desired
1900 effect, one must use @code{run-with-store}:
1903 (run-with-store (open-connection) (profile.sh))
1904 @result{} /gnu/store/...-profile.sh
1907 The main syntactic forms to deal with monads in general are described
1910 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
1911 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
1915 @deffn {Scheme Syntax} return @var{val}
1916 Return a monadic value that encapsulates @var{val}.
1919 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
1920 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
1921 procedure @var{mproc}@footnote{This operation is commonly referred to as
1922 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
1923 we use this somewhat cryptic symbol inherited from the Haskell
1927 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
1929 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
1931 Bind the variables @var{var} to the monadic values @var{mval} in
1932 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
1933 ``normal'' value @var{val}, as per @code{let}.
1935 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
1936 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
1939 The interface to the store monad provided by @code{(guix monads)} is as
1942 @defvr {Scheme Variable} %store-monad
1943 The store monad. Values in the store monad encapsulate accesses to the
1944 store. When its effect is needed, a value of the store monad must be
1945 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
1949 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
1950 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
1951 open store connection.
1954 @deffn {Monadic Procedure} text-file @var{name} @var{text}
1955 Return as a monadic value the absolute file name in the store of the file
1956 containing @var{text}, a string.
1959 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
1960 Return as a monadic value a derivation that builds a text file
1961 containing all of @var{text}. @var{text} may list, in addition to
1962 strings, packages, derivations, and store file names; the resulting
1963 store file holds references to all these.
1965 This variant should be preferred over @code{text-file} anytime the file
1966 to create will reference items from the store. This is typically the
1967 case when building a configuration file that embeds store file names,
1971 (define (profile.sh)
1972 ;; Return the name of a shell script in the store that
1973 ;; initializes the 'PATH' environment variable.
1974 (text-file* "profile.sh"
1975 "export PATH=" coreutils "/bin:"
1976 grep "/bin:" sed "/bin\n"))
1979 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
1980 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
1981 preventing them from being garbage-collected during its lifetime.
1984 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
1985 [#:system (%current-system)] [#:output "out"] Return as a monadic
1986 value in the absolute file name of @var{file} within the @var{output}
1987 directory of @var{package}. When @var{file} is omitted, return the name
1988 of the @var{output} directory of @var{package}.
1991 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
1992 Monadic version of @code{package-derivation} (@pxref{Defining
1998 @section G-Expressions
2000 @cindex G-expression
2001 @cindex build code quoting
2002 So we have ``derivations'', which represent a sequence of build actions
2003 to be performed to produce an item in the store (@pxref{Derivations}).
2004 Those build actions are performed when asking the daemon to actually
2005 build the derivations; they are run by the daemon in a container
2006 (@pxref{Invoking guix-daemon}).
2008 @cindex strata of code
2009 It should come as no surprise that we like to write those build actions
2010 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2011 code@footnote{The term @dfn{stratum} in this context was coined by
2012 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2013 Kiselyov, who has written insightful
2014 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2015 on this topic}, refers to this kind of code generation as
2016 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2017 to the daemon, etc.---and the ``build code''---code that actually
2018 performs build actions, such as making directories, invoking
2019 @command{make}, etc.
2021 To describe a derivation and its build actions, one typically needs to
2022 embed build code inside host code. It boils down to manipulating build
2023 code as data, and Scheme's homoiconicity---code has a direct
2024 representation as data---comes in handy for that. But we need more than
2025 Scheme's normal @code{quasiquote} mechanism to construct build
2028 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2029 S-expressions adapted to build expressions. G-expressions, or
2030 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2031 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2032 @code{#$}, and @code{#$@@}), which are comparable respectively to
2033 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2034 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2035 Reference Manual}). However, there are major differences:
2039 Gexps are meant to be written to a file and run or manipulated by other
2043 When a package or derivation is unquoted inside a gexp, the result is as
2044 if its output file name had been introduced.
2047 Gexps carry information about the packages or derivations they refer to,
2048 and these dependencies are automatically added as inputs to the build
2049 processes that use them.
2052 To illustrate the idea, here is an example of a gexp:
2059 (symlink (string-append #$coreutils "/bin/ls")
2063 This gexp can be passed to @code{gexp->derivation}; we obtain a
2064 derivation that builds a directory containing exactly one symlink to
2065 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2068 (gexp->derivation "the-thing" build-exp)
2071 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2072 substituted to the reference to the @var{coreutils} package in the
2073 actual build code, and @var{coreutils} is automatically made an input to
2074 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2075 output)}) is replaced by a string containing the derivation's output
2076 directory name. The syntactic form to construct gexps is summarized
2079 @deffn {Scheme Syntax} #~@var{exp}
2080 @deffnx {Scheme Syntax} (gexp @var{exp})
2081 Return a G-expression containing @var{exp}. @var{exp} may contain one
2082 or more of the following forms:
2086 @itemx (ungexp @var{obj})
2087 Introduce a reference to @var{obj}. @var{obj} may be a package or a
2088 derivation, in which case the @code{ungexp} form is replaced by its
2089 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2091 If @var{obj} is a list, it is traversed and any package or derivation
2092 references are substituted similarly.
2094 If @var{obj} is another gexp, its contents are inserted and its
2095 dependencies are added to those of the containing gexp.
2097 If @var{obj} is another kind of object, it is inserted as is.
2099 @item #$@var{package-or-derivation}:@var{output}
2100 @itemx (ungexp @var{package-or-derivation} @var{output})
2101 This is like the form above, but referring explicitly to the
2102 @var{output} of @var{package-or-derivation}---this is useful when
2103 @var{package-or-derivation} produces multiple outputs (@pxref{Packages
2104 with Multiple Outputs}).
2106 @item #$output[:@var{output}]
2107 @itemx (ungexp output [@var{output}])
2108 Insert a reference to derivation output @var{output}, or to the main
2109 output when @var{output} is omitted.
2111 This only makes sense for gexps passed to @code{gexp->derivation}.
2114 @itemx (ungexp-splicing @var{lst})
2115 Like the above, but splices the contents of @var{lst} inside the
2120 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2121 of the @code{gexp?} type (see below.)
2124 @deffn {Scheme Procedure} gexp? @var{obj}
2125 Return @code{#t} if @var{obj} is a G-expression.
2128 G-expressions are meant to be written to disk, either as code building
2129 some derivation, or as plain files in the store. The monadic procedures
2130 below allow you to do that (@pxref{The Store Monad}, for more
2131 information about monads.)
2133 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2134 [#:system (%current-system)] [#:inputs '()] @
2135 [#:hash #f] [#:hash-algo #f] @
2136 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2137 [#:references-graphs #f] [#:local-build? #f] @
2138 [#:guile-for-build #f]
2139 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2140 @var{guile-for-build} (a derivation) on @var{system}.
2142 Make @var{modules} available in the evaluation context of @var{EXP};
2143 @var{MODULES} is a list of names of Guile modules from the current
2144 search path to be copied in the store, compiled, and made available in
2145 the load path during the execution of @var{exp}---e.g., @code{((guix
2146 build utils) (guix build gnu-build-system))}.
2148 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2151 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2152 Return an executable script @var{name} that runs @var{exp} using
2153 @var{guile} with @var{modules} in its search path.
2155 The example below builds a script that simply invokes the @command{ls}
2159 (use-modules (guix gexp) (gnu packages base))
2161 (gexp->script "list-files"
2162 #~(execl (string-append #$coreutils "/bin/ls")
2166 When ``running'' it through the store (@pxref{The Store Monad,
2167 @code{run-with-store}}), we obtain a derivation that produces an
2168 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2171 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2173 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2178 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2179 Return a derivation that builds a file @var{name} containing @var{exp}.
2181 The resulting file holds references to all the dependencies of @var{exp}
2182 or a subset thereof.
2185 Of course, in addition to gexps embedded in ``host'' code, there are
2186 also modules containing build tools. To make it clear that they are
2187 meant to be used in the build stratum, these modules are kept in the
2188 @code{(guix build @dots{})} name space.
2191 @c *********************************************************************
2195 This section describes tools primarily targeted at developers and users
2196 who write new package definitions. They complement the Scheme
2197 programming interface of Guix in a convenient way.
2200 * Invoking guix build:: Building packages from the command line.
2201 * Invoking guix download:: Downloading a file and printing its hash.
2202 * Invoking guix hash:: Computing the cryptographic hash of a file.
2203 * Invoking guix refresh:: Updating package definitions.
2206 @node Invoking guix build
2207 @section Invoking @command{guix build}
2209 The @command{guix build} command builds packages or derivations and
2210 their dependencies, and prints the resulting store paths. Note that it
2211 does not modify the user's profile---this is the job of the
2212 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2213 it is mainly useful for distribution developers.
2215 The general syntax is:
2218 guix build @var{options} @var{package-or-derivation}@dots{}
2221 @var{package-or-derivation} may be either the name of a package found in
2222 the software distribution such as @code{coreutils} or
2223 @code{coreutils-8.20}, or a derivation such as
2224 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2225 package with the corresponding name (and optionally version) is searched
2226 for among the GNU distribution modules (@pxref{Package Modules}).
2228 Alternatively, the @code{--expression} option may be used to specify a
2229 Scheme expression that evaluates to a package; this is useful when
2230 disambiguation among several same-named packages or package variants is
2233 The @var{options} may be zero or more of the following:
2237 @item --expression=@var{expr}
2238 @itemx -e @var{expr}
2239 Build the package or derivation @var{expr} evaluates to.
2241 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2242 guile-1.8)}, which unambiguously designates this specific variant of
2243 version 1.8 of Guile.
2245 Alternately, @var{expr} may refer to a zero-argument monadic procedure
2246 (@pxref{The Store Monad}). The procedure must return a derivation as a
2247 monadic value, which is then passed through @code{run-with-store}.
2251 Build the packages' source derivations, rather than the packages
2254 For instance, @code{guix build -S gcc} returns something like
2255 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2257 The returned source tarball is the result of applying any patches and
2258 code snippets specified in the package's @code{origin} (@pxref{Defining
2261 @item --system=@var{system}
2262 @itemx -s @var{system}
2263 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
2264 the host's system type.
2266 An example use of this is on Linux-based systems, which can emulate
2267 different personalities. For instance, passing
2268 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
2269 to build packages in a complete 32-bit environment.
2271 @item --target=@var{triplet}
2272 @cindex cross-compilation
2273 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
2274 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
2275 configuration triplets,, configure, GNU Configure and Build System}).
2277 @item --with-source=@var{source}
2278 Use @var{source} as the source of the corresponding package.
2279 @var{source} must be a file name or a URL, as for @command{guix
2280 download} (@pxref{Invoking guix download}).
2282 The ``corresponding package'' is taken to be one specified on the
2283 command line whose name matches the base of @var{source}---e.g., if
2284 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
2285 package is @code{guile}. Likewise, the version string is inferred from
2286 @var{source}; in the previous example, it's @code{2.0.10}.
2288 This option allows users to try out versions of packages other than the
2289 one provided by the distribution. The example below downloads
2290 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
2291 the @code{ed} package:
2294 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
2297 As a developer, @code{--with-source} makes it easy to test release
2301 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
2307 Return the derivation paths, not the output paths, of the given
2310 @item --root=@var{file}
2311 @itemx -r @var{file}
2312 Make @var{file} a symlink to the result, and register it as a garbage
2316 Return the build log file names for the given
2317 @var{package-or-derivation}s, or raise an error if build logs are
2320 This works regardless of how packages or derivations are specified. For
2321 instance, the following invocations are equivalent:
2324 guix build --log-file `guix build -d guile`
2325 guix build --log-file `guix build guile`
2326 guix build --log-file guile
2327 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
2333 @cindex common build options
2334 In addition, a number of options that control the build process are
2335 common to @command{guix build} and other commands that can spawn builds,
2336 such as @command{guix package} or @command{guix archive}. These are the
2343 Keep the build tree of failed builds. Thus, if a build fail, its build
2344 tree is kept under @file{/tmp}, in a directory whose name is shown at
2345 the end of the build log. This is useful when debugging build issues.
2349 Do not build the derivations.
2352 When substituting a pre-built binary fails, fall back to building
2355 @item --no-substitutes
2356 Do not use substitutes for build products. That is, always build things
2357 locally instead of allowing downloads of pre-built binaries
2358 (@pxref{Substitutes}).
2360 @item --no-build-hook
2361 Do not attempt to offload builds @i{via} the daemon's ``build hook''
2362 (@pxref{Daemon Offload Setup}). That is, always build things locally
2363 instead of offloading builds to remote machines.
2365 @item --max-silent-time=@var{seconds}
2366 When the build or substitution process remains silent for more than
2367 @var{seconds}, terminate it and report a build failure.
2369 @item --timeout=@var{seconds}
2370 Likewise, when the build or substitution process lasts for more than
2371 @var{seconds}, terminate it and report a build failure.
2373 By default there is no timeout. This behavior can be restored with
2376 @item --verbosity=@var{level}
2377 Use the given verbosity level. @var{level} must be an integer between 0
2378 and 5; higher means more verbose output. Setting a level of 4 or more
2379 may be helpful when debugging setup issues with the build daemon.
2381 @item --cores=@var{n}
2383 Allow the use of up to @var{n} CPU cores for the build. The special
2384 value @code{0} means to use as many CPU cores as available.
2388 Behind the scenes, @command{guix build} is essentially an interface to
2389 the @code{package-derivation} procedure of the @code{(guix packages)}
2390 module, and to the @code{build-derivations} procedure of the @code{(guix
2393 @node Invoking guix download
2394 @section Invoking @command{guix download}
2396 When writing a package definition, developers typically need to download
2397 the package's source tarball, compute its SHA256 hash, and write that
2398 hash in the package definition (@pxref{Defining Packages}). The
2399 @command{guix download} tool helps with this task: it downloads a file
2400 from the given URI, adds it to the store, and prints both its file name
2401 in the store and its SHA256 hash.
2403 The fact that the downloaded file is added to the store saves bandwidth:
2404 when the developer eventually tries to build the newly defined package
2405 with @command{guix build}, the source tarball will not have to be
2406 downloaded again because it is already in the store. It is also a
2407 convenient way to temporarily stash files, which may be deleted
2408 eventually (@pxref{Invoking guix gc}).
2410 The @command{guix download} command supports the same URIs as used in
2411 package definitions. In particular, it supports @code{mirror://} URIs.
2412 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
2413 Guile bindings for GnuTLS are available in the user's environment; when
2414 they are not available, an error is raised.
2416 The following option is available:
2419 @item --format=@var{fmt}
2421 Write the hash in the format specified by @var{fmt}. For more
2422 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
2425 @node Invoking guix hash
2426 @section Invoking @command{guix hash}
2428 The @command{guix hash} command computes the SHA256 hash of a file.
2429 It is primarily a convenience tool for anyone contributing to the
2430 distribution: it computes the cryptographic hash of a file, which can be
2431 used in the definition of a package (@pxref{Defining Packages}).
2433 The general syntax is:
2436 guix hash @var{option} @var{file}
2439 @command{guix hash} has the following option:
2443 @item --format=@var{fmt}
2445 Write the hash in the format specified by @var{fmt}.
2447 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
2448 (@code{hex} and @code{hexadecimal} can be used as well).
2450 If the @option{--format} option is not specified, @command{guix hash}
2451 will output the hash in @code{nix-base32}. This representation is used
2452 in the definitions of packages.
2456 Compute the hash on @var{file} recursively.
2458 In this case, the hash is computed on an archive containing @var{file},
2459 including its children if it is a directory. Some of @var{file}'s
2460 meta-data is part of the archive; for instance, when @var{file} is a
2461 regular file, the hash is different depending on whether @var{file} is
2462 executable or not. Meta-data such as time stamps has no impact on the
2463 hash (@pxref{Invoking guix archive}).
2464 @c FIXME: Replace xref above with xref to an ``Archive'' section when
2469 @node Invoking guix refresh
2470 @section Invoking @command{guix refresh}
2472 The primary audience of the @command{guix refresh} command is developers
2473 of the GNU software distribution. By default, it reports any packages
2474 provided by the distribution that are outdated compared to the latest
2475 upstream version, like this:
2479 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
2480 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
2483 It does so by browsing each package's FTP directory and determining the
2484 highest version number of the source tarballs
2485 therein@footnote{Currently, this only works for GNU packages.}.
2487 When passed @code{--update}, it modifies distribution source files to
2488 update the version numbers and source tarball hashes of those packages'
2489 recipes (@pxref{Defining Packages}). This is achieved by downloading
2490 each package's latest source tarball and its associated OpenPGP
2491 signature, authenticating the downloaded tarball against its signature
2492 using @command{gpg}, and finally computing its hash. When the public
2493 key used to sign the tarball is missing from the user's keyring, an
2494 attempt is made to automatically retrieve it from a public key server;
2495 when it's successful, the key is added to the user's keyring; otherwise,
2496 @command{guix refresh} reports an error.
2498 The following options are supported:
2504 Update distribution source files (package recipes) in place.
2505 @ref{Defining Packages}, for more information on package definitions.
2507 @item --select=[@var{subset}]
2508 @itemx -s @var{subset}
2509 Select all the packages in @var{subset}, one of @code{core} or
2512 The @code{core} subset refers to all the packages at the core of the
2513 distribution---i.e., packages that are used to build ``everything
2514 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
2515 changing one of these packages in the distribution entails a rebuild of
2516 all the others. Thus, such updates are an inconvenience to users in
2517 terms of build time or bandwidth used to achieve the upgrade.
2519 The @code{non-core} subset refers to the remaining packages. It is
2520 typically useful in cases where an update of the core packages would be
2525 In addition, @command{guix refresh} can be passed one or more package
2526 names, as in this example:
2529 guix refresh -u emacs idutils
2533 The command above specifically updates the @code{emacs} and
2534 @code{idutils} packages. The @code{--select} option would have no
2535 effect in this case.
2537 The following options can be used to customize GnuPG operation:
2541 @item --key-server=@var{host}
2542 Use @var{host} as the OpenPGP key server when importing a public key.
2544 @item --gpg=@var{command}
2545 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
2546 for in @code{$PATH}.
2551 @c *********************************************************************
2552 @node GNU Distribution
2553 @chapter GNU Distribution
2555 Guix comes with a distribution of free software@footnote{The term
2556 ``free'' here refers to the
2557 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
2558 users of that software}.} that forms the basis of the GNU system. This
2559 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
2560 as many GNU and non-GNU applications. The complete list of available
2561 packages can be browsed
2562 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
2563 running @command{guix package} (@pxref{Invoking guix package}):
2566 guix package --list-available
2569 Our goal is to build a practical 100% free software distribution of
2570 Linux-based and other variants of GNU, with a focus on the promotion and
2571 tight integration of GNU components, and an emphasis on programs and
2572 tools that help users exert that freedom.
2574 The GNU distribution is currently available on the following platforms:
2579 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
2582 Intel 32-bit architecture (IA32), Linux-Libre kernel;
2584 @item mips64el-linux
2585 little-endian 64-bit MIPS processors, specifically the Loongson series,
2586 n32 application binary interface (ABI), and Linux-Libre kernel.
2591 For information on porting to other architectures or kernels,
2595 * Installing Debugging Files:: Feeding the debugger.
2596 * Package Modules:: Packages from the programmer's viewpoint.
2597 * Packaging Guidelines:: Growing the distribution.
2598 * Bootstrapping:: GNU/Linux built from scratch.
2599 * Porting:: Targeting another platform or kernel.
2600 * System Configuration:: Configuring a GNU system.
2603 Building this distribution is a cooperative effort, and you are invited
2604 to join! @ref{Contributing}, for information about how you can help.
2607 @node Installing Debugging Files
2608 @section Installing Debugging Files
2610 @cindex debugging files
2611 Program binaries, as produced by the GCC compilers for instance, are
2612 typically written in the ELF format, with a section containing
2613 @dfn{debugging information}. Debugging information is what allows the
2614 debugger, GDB, to map binary code to source code; it is required to
2615 debug a compiled program in good conditions.
2617 The problem with debugging information is that is takes up a fair amount
2618 of disk space. For example, debugging information for the GNU C Library
2619 weighs in at more than 60 MiB. Thus, as a user, keeping all the
2620 debugging info of all the installed programs is usually not an option.
2621 Yet, space savings should not come at the cost of an impediment to
2622 debugging---especially in the GNU system, which should make it easier
2623 for users to exert their computing freedom (@pxref{GNU Distribution}).
2625 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
2626 mechanism that allows users to get the best of both worlds: debugging
2627 information can be stripped from the binaries and stored in separate
2628 files. GDB is then able to load debugging information from those files,
2629 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
2632 The GNU distribution takes advantage of this by storing debugging
2633 information in the @code{lib/debug} sub-directory of a separate package
2634 output unimaginatively called @code{debug} (@pxref{Packages with
2635 Multiple Outputs}). Users can choose to install the @code{debug} output
2636 of a package when they need it. For instance, the following command
2637 installs the debugging information for the GNU C Library and for GNU
2641 guix package -i glibc:debug guile:debug
2644 GDB must then be told to look for debug files in the user's profile, by
2645 setting the @code{debug-file-directory} variable (consider setting it
2646 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
2650 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
2653 From there on, GDB will pick up debugging information from the
2654 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
2656 In addition, you will most likely want GDB to be able to show the source
2657 code being debugged. To do that, you will have to unpack the source
2658 code of the package of interest (obtained with @code{guix build
2659 --source}, @pxref{Invoking guix build}), and to point GDB to that source
2660 directory using the @code{directory} command (@pxref{Source Path,
2661 @code{directory},, gdb, Debugging with GDB}).
2663 @c XXX: keep me up-to-date
2664 The @code{debug} output mechanism in Guix is implemented by the
2665 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
2666 opt-in---debugging information is available only for those packages
2667 whose definition explicitly declares a @code{debug} output. This may be
2668 changed to opt-out in the future, if our build farm servers can handle
2669 the load. To check whether a package has a @code{debug} output, use
2670 @command{guix package --list-available} (@pxref{Invoking guix package}).
2673 @node Package Modules
2674 @section Package Modules
2676 From a programming viewpoint, the package definitions of the
2677 GNU distribution are provided by Guile modules in the @code{(gnu packages
2678 @dots{})} name space@footnote{Note that packages under the @code{(gnu
2679 packages @dots{})} module name space are not necessarily ``GNU
2680 packages''. This module naming scheme follows the usual Guile module
2681 naming convention: @code{gnu} means that these modules are distributed
2682 as part of the GNU system, and @code{packages} identifies modules that
2683 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
2684 Reference Manual}). For instance, the @code{(gnu packages emacs)}
2685 module exports a variable named @code{emacs}, which is bound to a
2686 @code{<package>} object (@pxref{Defining Packages}).
2688 The @code{(gnu packages @dots{})} module name space is special: it is
2689 automatically scanned for packages by the command-line tools. For
2690 instance, when running @code{guix package -i emacs}, all the @code{(gnu
2691 packages @dots{})} modules are scanned until one that exports a package
2692 object whose name is @code{emacs} is found. This package search
2693 facility is implemented in the @code{(gnu packages)} module.
2695 Users can store package definitions in modules with different
2696 names---e.g., @code{(my-packages emacs)}. In that case, commands such
2697 as @command{guix package} and @command{guix build} have to be used with
2698 the @code{-e} option so that they know where to find the package.
2700 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
2701 each package is built based solely on other packages in the
2702 distribution. The root of this dependency graph is a small set of
2703 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
2704 bootstrap)} module. For more information on bootstrapping,
2705 @ref{Bootstrapping}.
2707 @node Packaging Guidelines
2708 @section Packaging Guidelines
2710 The GNU distribution is nascent and may well lack some of your favorite
2711 packages. This section describes how you can help make the distribution
2712 grow. @xref{Contributing}, for additional information on how you can
2715 Free software packages are usually distributed in the form of
2716 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
2717 all the source files. Adding a package to the distribution means
2718 essentially two things: adding a @dfn{recipe} that describes how to
2719 build the package, including a list of other packages required to build
2720 it, and adding @dfn{package meta-data} along with that recipe, such as a
2721 description and licensing information.
2723 In Guix all this information is embodied in @dfn{package definitions}.
2724 Package definitions provide a high-level view of the package. They are
2725 written using the syntax of the Scheme programming language; in fact,
2726 for each package we define a variable bound to the package definition,
2727 and export that variable from a module (@pxref{Package Modules}).
2728 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
2729 creating packages. For more information on package definitions,
2730 @ref{Defining Packages}.
2732 Once a package definition is in place, stored in a file in the Guix
2733 source tree, it can be tested using the @command{guix build} command
2734 (@pxref{Invoking guix build}). For example, assuming the new package is
2735 called @code{gnew}, you may run this command from the Guix build tree:
2738 ./pre-inst-env guix build gnew --keep-failed
2741 Using @code{--keep-failed} makes it easier to debug build failures since
2742 it provides access to the failed build tree. Another useful
2743 command-line option when debugging is @code{--log-file}, to access the
2746 If the package is unknown to the @command{guix} command, it may be that
2747 the source file contains a syntax error, or lacks a @code{define-public}
2748 clause to export the package variable. To figure it out, you may load
2749 the module from Guile to get more information about the actual error:
2752 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
2755 Once your package builds correctly, please send us a patch
2756 (@pxref{Contributing}). Well, if you need help, we will be happy to
2757 help you too. Once the patch is committed in the Guix repository, the
2758 new package automatically gets built on the supported platforms by
2759 @url{http://hydra.gnu.org/gnu/master, our continuous integration
2763 Users can obtain the new package definition simply by running
2764 @command{guix pull} (@pxref{Invoking guix pull}). When
2765 @code{hydra.gnu.org} is done building the package, installing the
2766 package automatically downloads binaries from there
2767 (@pxref{Substitutes}). The only place where human intervention is
2768 needed is to review and apply the patch.
2772 * Software Freedom:: What may go into the distribution.
2773 * Package Naming:: What's in a name?
2774 * Version Numbers:: When the name is not enough.
2775 * Python Modules:: Taming the snake.
2776 * Perl Modules:: Little pearls.
2779 @node Software Freedom
2780 @subsection Software Freedom
2782 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
2784 The GNU operating system has been developed so that users can have
2785 freedom in their computing. GNU is @dfn{free software}, meaning that
2786 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
2787 essential freedoms}: to run the program, to study and change the program
2788 in source code form, to redistribute exact copies, and to distribute
2789 modified versions. Packages found in the GNU distribution provide only
2790 software that conveys these four freedoms.
2792 In addition, the GNU distribution follow the
2793 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
2794 software distribution guidelines}. Among other things, these guidelines
2795 reject non-free firmware, recommendations of non-free software, and
2796 discuss ways to deal with trademarks and patents.
2798 Some packages contain a small and optional subset that violates the
2799 above guidelines, for instance because this subset is itself non-free
2800 code. When that happens, the offending items are removed with
2801 appropriate patches or code snippets in the package definition's
2802 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
2803 build --source} returns the ``freed'' source rather than the unmodified
2807 @node Package Naming
2808 @subsection Package Naming
2810 A package has actually two names associated with it:
2811 First, there is the name of the @emph{Scheme variable}, the one following
2812 @code{define-public}. By this name, the package can be made known in the
2813 Scheme code, for instance as input to another package. Second, there is
2814 the string in the @code{name} field of a package definition. This name
2815 is used by package management commands such as
2816 @command{guix package} and @command{guix build}.
2818 Both are usually the same and correspond to the lowercase conversion of
2819 the project name chosen upstream, with underscores replaced with
2820 hyphens. For instance, GNUnet is available as @code{gnunet}, and
2821 SDL_net as @code{sdl-net}.
2823 We do not add @code{lib} prefixes for library packages, unless these are
2824 already part of the official project name. But see @pxref{Python
2825 Modules} and @ref{Perl Modules} for special rules concerning modules for
2826 the Python and Perl languages.
2829 @node Version Numbers
2830 @subsection Version Numbers
2832 We usually package only the latest version of a given free software
2833 project. But sometimes, for instance for incompatible library versions,
2834 two (or more) versions of the same package are needed. These require
2835 different Scheme variable names. We use the name as defined
2836 in @ref{Package Naming}
2837 for the most recent version; previous versions use the same name, suffixed
2838 by @code{-} and the smallest prefix of the version number that may
2839 distinguish the two versions.
2841 The name inside the package definition is the same for all versions of a
2842 package and does not contain any version number.
2844 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
2852 (define-public gtk+-2
2858 If we also wanted GTK+ 3.8.2, this would be packaged as
2860 (define-public gtk+-3.8
2868 @node Python Modules
2869 @subsection Python Modules
2871 We currently package Python 2 and Python 3, under the Scheme variable names
2872 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
2873 To avoid confusion and naming clashes with other programming languages, it
2874 seems desirable that the name of a package for a Python module contains
2875 the word @code{python}.
2877 Some modules are compatible with only one version of Python, others with both.
2878 If the package Foo compiles only with Python 3, we name it
2879 @code{python-foo}; if it compiles only with Python 2, we name it
2880 @code{python2-foo}. If it is compatible with both versions, we create two
2881 packages with the corresponding names.
2883 If a project already contains the word @code{python}, we drop this;
2884 for instance, the module python-dateutil is packaged under the names
2885 @code{python-dateutil} and @code{python2-dateutil}.
2889 @subsection Perl Modules
2891 Perl programs standing for themselves are named as any other package,
2892 using the lowercase upstream name.
2893 For Perl packages containing a single class, we use the lowercase class name,
2894 replace all occurrences of @code{::} by dashes and prepend the prefix
2896 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
2897 Modules containing several classes keep their lowercase upstream name and
2898 are also prepended by @code{perl-}. Such modules tend to have the word
2899 @code{perl} somewhere in their name, which gets dropped in favor of the
2900 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
2905 @section Bootstrapping
2907 @c Adapted from the ELS 2013 paper.
2909 @cindex bootstrapping
2911 Bootstrapping in our context refers to how the distribution gets built
2912 ``from nothing''. Remember that the build environment of a derivation
2913 contains nothing but its declared inputs (@pxref{Introduction}). So
2914 there's an obvious chicken-and-egg problem: how does the first package
2915 get built? How does the first compiler get compiled? Note that this is
2916 a question of interest only to the curious hacker, not to the regular
2917 user, so you can shamelessly skip this section if you consider yourself
2920 @cindex bootstrap binaries
2921 The GNU system is primarily made of C code, with libc at its core. The
2922 GNU build system itself assumes the availability of a Bourne shell and
2923 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
2924 `grep'. Furthermore, build programs---programs that run
2925 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
2926 (@pxref{Derivations}). Consequently, to be able to build anything at
2927 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
2928 Binutils, libc, and the other packages mentioned above---the
2929 @dfn{bootstrap binaries}.
2931 These bootstrap binaries are ``taken for granted'', though we can also
2932 re-create them if needed (more on that later).
2934 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
2936 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
2937 @c large image, it's hard to scroll. Oh well.
2938 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
2940 The figure above shows the very beginning of the dependency graph of the
2941 distribution, corresponding to the package definitions of the @code{(gnu
2942 packages bootstrap)} module. At this level of detail, things are
2943 slightly complex. First, Guile itself consists of an ELF executable,
2944 along with many source and compiled Scheme files that are dynamically
2945 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
2946 tarball shown in this graph. This tarball is part of Guix's ``source''
2947 distribution, and gets inserted into the store with @code{add-to-store}
2948 (@pxref{The Store}).
2950 But how do we write a derivation that unpacks this tarball and adds it
2951 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
2952 derivation---the first one that gets built---uses @code{bash} as its
2953 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
2954 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
2955 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
2956 the Guix source distribution, whose sole purpose is to allow the Guile
2957 tarball to be unpacked.
2959 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
2960 Guile that can be used to run subsequent build programs. Its first task
2961 is to download tarballs containing the other pre-built binaries---this
2962 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
2963 @code{ftp-client.scm} are used for this purpose. The
2964 @code{module-import.drv} derivations import those modules in a directory
2965 in the store, using the original layout. The
2966 @code{module-import-compiled.drv} derivations compile those modules, and
2967 write them in an output directory with the right layout. This
2968 corresponds to the @code{#:modules} argument of
2969 @code{build-expression->derivation} (@pxref{Derivations}).
2971 Finally, the various tarballs are unpacked by the
2972 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
2973 etc., at which point we have a working C tool chain.
2976 @unnumberedsubsec Building the Build Tools
2978 @c TODO: Add a package-level dependency graph generated from (gnu
2981 Bootstrapping is complete when we have a full tool chain that does not
2982 depend on the pre-built bootstrap tools discussed above. This
2983 no-dependency requirement is verified by checking whether the files of
2984 the final tool chain contain references to the @file{/gnu/store}
2985 directories of the bootstrap inputs. The process that leads to this
2986 ``final'' tool chain is described by the package definitions found in
2987 the @code{(gnu packages base)} module.
2989 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
2990 The first tool that gets built with the bootstrap binaries is
2991 GNU Make, which is a prerequisite for all the following packages.
2992 From there Findutils and Diffutils get built.
2994 Then come the first-stage Binutils and GCC, built as pseudo cross
2995 tools---i.e., with @code{--target} equal to @code{--host}. They are
2996 used to build libc. Thanks to this cross-build trick, this libc is
2997 guaranteed not to hold any reference to the initial tool chain.
2999 From there the final Binutils and GCC are built. GCC uses @code{ld}
3000 from the final Binutils, and links programs against the just-built libc.
3001 This tool chain is used to build the other packages used by Guix and by
3002 the GNU Build System: Guile, Bash, Coreutils, etc.
3004 And voilà! At this point we have the complete set of build tools that
3005 the GNU Build System expects. These are in the @code{%final-inputs}
3006 variables of the @code{(gnu packages base)} module, and are implicitly
3007 used by any package that uses @code{gnu-build-system} (@pxref{Defining
3011 @unnumberedsubsec Building the Bootstrap Binaries
3013 Because the final tool chain does not depend on the bootstrap binaries,
3014 those rarely need to be updated. Nevertheless, it is useful to have an
3015 automated way to produce them, should an update occur, and this is what
3016 the @code{(gnu packages make-bootstrap)} module provides.
3018 The following command builds the tarballs containing the bootstrap
3019 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
3020 of Coreutils and other basic command-line tools):
3023 guix build bootstrap-tarballs
3026 The generated tarballs are those that should be referred to in the
3027 @code{(gnu packages bootstrap)} module mentioned at the beginning of
3030 Still here? Then perhaps by now you've started to wonder: when do we
3031 reach a fixed point? That is an interesting question! The answer is
3032 unknown, but if you would like to investigate further (and have
3033 significant computational and storage resources to do so), then let us
3037 @section Porting to a New Platform
3039 As discussed above, the GNU distribution is self-contained, and
3040 self-containment is achieved by relying on pre-built ``bootstrap
3041 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
3042 operating system kernel, CPU architecture, and application binary
3043 interface (ABI). Thus, to port the distribution to a platform that is
3044 not yet supported, one must build those bootstrap binaries, and update
3045 the @code{(gnu packages bootstrap)} module to use them on that platform.
3047 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
3048 When everything goes well, and assuming the GNU tool chain supports the
3049 target platform, this can be as simple as running a command like this
3053 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
3056 Once these are built, the @code{(gnu packages bootstrap)} module needs
3057 to be updated to refer to these binaries on the target platform. In
3058 addition, the @code{glibc-dynamic-linker} procedure in that module must
3059 be augmented to return the right file name for libc's dynamic linker on
3060 that platform; likewise, @code{system->linux-architecture} in @code{(gnu
3061 packages linux)} must be taught about the new platform.
3063 In practice, there may be some complications. First, it may be that the
3064 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
3065 above) is not recognized by all the GNU tools. Typically, glibc
3066 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
3067 configure flag (see @code{gcc.scm} for examples of how to handle this).
3068 Second, some of the required packages could fail to build for that
3069 platform. Lastly, the generated binaries could be broken for some
3073 @node System Configuration
3074 @section System Configuration
3076 @emph{This section documents work-in-progress. As such it may be
3077 incomplete, outdated, or open to discussions. Please discuss it on
3078 @email{guix-devel@@gnu.org}.}
3080 @cindex system configuration
3081 The GNU system supports a consistent whole-system configuration
3082 mechanism. By that we mean that all aspects of the global system
3083 configuration---such as the available system services, timezone and
3084 locale settings, user accounts---are declared in a single place. Such
3085 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
3087 One of the advantages of putting all the system configuration under the
3088 control of Guix is that it supports transactional system upgrades, and
3089 makes it possible to roll-back to a previous system instantiation,
3090 should something go wrong with the new one (@pxref{Features}). Another
3091 one is that it makes it easy to replicate the exact same configuration
3092 across different machines, or at different points in time, without
3093 having to resort to additional administration tools layered on top of
3094 the system's own tools.
3095 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
3097 This section describes this mechanism. First we focus on the system
3098 administrator's viewpoint---explaining how the system is configured and
3099 instantiated. Then we show how this mechanism can be extended, for
3100 instance to support new system services.
3103 * Using the Configuration System:: Customizing your GNU system.
3104 * Invoking guix system:: Instantiating a system configuration.
3105 * Defining Services:: Adding new service definitions.
3108 @node Using the Configuration System
3109 @subsection Using the Configuration System
3111 The operating system is configured by filling in an
3112 @code{operating-system} structure, as defined by the @code{(gnu system)}
3113 module. A simple setup, with the default system services, the default
3114 Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
3116 @findex operating-system
3118 (use-modules (gnu) ; for 'user-account', '%base-services', etc.
3119 (gnu packages emacs) ; for 'emacs'
3120 (gnu services ssh)) ; for 'lsh-service'
3124 (host-name "komputilo")
3125 (timezone "Europe/Paris")
3126 (locale "fr_FR.UTF-8")
3127 (bootloader (grub-configuration
3128 (device "/dev/sda")))
3129 (file-systems (list (file-system
3130 (device "/dev/sda1") ; or partition label
3133 (users (list (user-account
3136 (uid 1000) (gid 100)
3137 (comment "Bob's sister")
3138 (home-directory "/home/alice"))))
3139 (packages (cons emacs %base-packages))
3140 (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
3144 This example should be self-describing. The @code{packages} field lists
3145 packages that will be globally visible on the system, for all user
3146 accounts---i.e., in every user's @code{PATH} environment variable---in
3147 addition to the per-user profiles (@pxref{Invoking guix package}). The
3148 @var{%base-packages} variables provides all the tools one would expect
3149 for basic user and administrator tasks---including the GNU Core
3150 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
3151 editor, @command{find}, @command{grep}, etc. The example above adds
3152 Emacs to those, taken from the @code{(gnu packages emacs)} module
3153 (@pxref{Package Modules}).
3155 @vindex %base-services
3156 The @code{services} field lists @dfn{system services} to be made
3157 available when the system starts. The @var{%base-services} list,
3158 from the @code{(gnu services base)} module, provides the basic services one
3159 would expect from a GNU system: a login service (mingetty) on each tty,
3160 syslogd, libc's name service cache daemon (nscd), etc.
3162 The @code{operating-system} declaration above specifies that, in
3163 addition to those services, we want the @command{lshd} secure shell
3164 daemon listening on port 2222, and allowing remote @code{root} logins
3165 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
3166 @code{lsh-service} arranges so that @code{lshd} is started with the
3167 right command-line options, possibly with supporting configuration files
3168 generated as needed (@pxref{Defining Services}).
3170 Assuming the above snippet is stored in the @file{my-system-config.scm}
3171 file, the @command{guix system boot my-system-config.scm} command
3172 instantiates that configuration, and makes it the default GRUB boot
3173 entry (@pxref{Invoking guix system}). The normal way to change the
3174 system's configuration is by updating this file and re-running the
3175 @command{guix system} command.
3177 At the Scheme level, the bulk of an @code{operating-system} declaration
3178 is instantiated with the following monadic procedure (@pxref{The Store
3181 @deffn {Monadic Procedure} operating-system-derivation os
3182 Return a derivation that builds @var{os}, an @code{operating-system}
3183 object (@pxref{Derivations}).
3185 The output of the derivation is a single directory that refers to all
3186 the packages, configuration files, and other supporting files needed to
3187 instantiate @var{os}.
3190 @node Invoking guix system
3191 @subsection Invoking @code{guix system}
3193 Once you have written an operating system declaration, as seen in the
3194 previous section, it can be @dfn{instantiated} using the @command{guix
3195 system} command. The synopsis is:
3198 guix system @var{options}@dots{} @var{action} @var{file}
3201 @var{file} must be the name of a file containing an
3202 @code{operating-system} declaration. @var{action} specifies how the
3203 operating system is instantiate. Currently the following values are
3208 Build the operating system's derivation, which includes all the
3209 configuration files and programs needed to boot and run the system.
3210 This action does not actually install anything.
3213 Populate the given directory with all the files necessary to run the
3214 operating system specified in @var{file}. This is useful for first-time
3215 installations of the GNU system. For instance:
3218 guix system init my-os-config.scm /mnt
3221 copies to @file{/mnt} all the store items required by the configuration
3222 specified in @file{my-os-config.scm}. This includes configuration
3223 files, packages, and so on. It also creates other essential files
3224 needed for the system to operate correctly---e.g., the @file{/etc},
3225 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
3227 This command also installs GRUB on the device specified in
3228 @file{my-os-config}, unless the @option{--no-grub} option was passed.
3231 @cindex virtual machine
3232 Build a virtual machine that contain the operating system declared in
3233 @var{file}, and return a script to run that virtual machine (VM).
3235 The VM shares its store with the host system.
3239 Return a virtual machine or disk image of the operating system declared
3240 in @var{file} that stands alone. Use the @option{--image-size} option
3241 to specify the size of the image.
3243 When using @code{vm-image}, the returned image is in qcow2 format, which
3244 the QEMU emulator can efficiently use.
3246 When using @code{disk-image}, a raw disk image is produced; it can be
3247 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
3248 the device corresponding to a USB stick, one can copy the image on it
3249 using the following command:
3252 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
3257 @var{options} can contain any of the common build options provided by
3258 @command{guix build} (@pxref{Invoking guix build}).
3261 @node Defining Services
3262 @subsection Defining Services
3264 The @code{(gnu services @dots{})} modules define several procedures that allow
3265 users to declare the operating system's services (@pxref{Using the
3266 Configuration System}). These procedures are @emph{monadic
3267 procedures}---i.e., procedures that return a monadic value in the store
3268 monad (@pxref{The Store Monad}). Examples of such procedures include:
3271 @item mingetty-service
3272 return the definition of a service that runs @command{mingetty} to
3273 offer a login service on the given console tty;
3276 return a definition for libc's name service cache daemon (nscd);
3279 return a definition for a service that runs @command{guix-daemon}
3280 (@pxref{Invoking guix-daemon}).
3283 @cindex service definition
3284 The monadic value returned by those procedures is a @dfn{service
3285 definition}---a structure as returned by the @code{service} form.
3286 Service definitions specifies the inputs the service depends on, and an
3287 expression to start and stop the service. Behind the scenes, service
3288 definitions are ``translated'' into the form suitable for the
3289 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
3292 As an example, here is what the @code{nscd-service} procedure looks
3296 (define (nscd-service)
3297 (with-monad %store-monad
3299 (documentation "Run libc's name service cache daemon.")
3302 (use-modules (guix build utils))
3303 (mkdir-p "/var/run/nscd")))
3304 (start #~(make-forkexec-constructor
3305 (string-append #$glibc "/sbin/nscd")
3306 "-f" "/dev/null" "--foreground"))
3307 (stop #~(make-kill-destructor))
3312 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
3313 (@pxref{G-Expressions}). The @code{activate} field contains a script to
3314 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
3315 directory exists before @command{nscd} is started.
3317 The @code{start} and @code{stop} fields refer to dmd's facilities to
3318 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
3319 GNU dmd Manual}). The @code{provision} field specifies the name under
3320 which this service is known to dmd, and @code{documentation} specifies
3321 on-line documentation. Thus, the commands @command{deco start ncsd},
3322 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
3323 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
3326 @c *********************************************************************
3328 @chapter Contributing
3330 This project is a cooperative effort, and we need your help to make it
3331 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
3332 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
3333 reports, patches, and anything that may be helpful to the project. We
3334 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
3337 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
3338 @file{HACKING} file} that comes with the Guix source code for practical
3339 details about contributions.
3342 @c *********************************************************************
3343 @node Acknowledgments
3344 @chapter Acknowledgments
3346 Guix is based on the Nix package manager, which was designed and
3347 implemented by Eelco Dolstra. Nix pioneered functional package
3348 management, and promoted unprecedented features, such as transactional
3349 package upgrades and rollbacks, per-user profiles, and referentially
3350 transparent build processes. Without this work, Guix would not exist.
3352 The Nix-based software distributions, Nixpkgs and NixOS, have also been
3353 an inspiration for Guix.
3355 @c *********************************************************************
3356 @node GNU Free Documentation License
3357 @appendix GNU Free Documentation License
3359 @include fdl-1.3.texi
3361 @c *********************************************************************
3363 @unnumbered Concept Index
3366 @node Function Index
3367 @unnumbered Function Index
3373 @c ispell-local-dictionary: "american";