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] @
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{local-build?} is true, declare that the derivation is not a
1757 good candidate for offloading and should rather be built locally
1758 (@pxref{Daemon Offload Setup}). This is the case for small derivations
1759 where the costs of data transfers would outweigh the benefits.
1763 Here's an example with a shell script as its builder, assuming
1764 @var{store} is an open connection to the daemon, and @var{bash} points
1765 to a Bash executable in the store:
1768 (use-modules (guix utils)
1772 (let ((builder ; add the Bash script to the store
1773 (add-text-to-store store "my-builder.sh"
1774 "echo hello world > $out\n" '())))
1775 (derivation store "foo"
1776 bash `("-e" ,builder)
1777 #:inputs `((,bash) (,builder))
1778 #:env-vars '(("HOME" . "/homeless"))))
1779 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
1782 As can be guessed, this primitive is cumbersome to use directly. A
1783 better approach is to write build scripts in Scheme, of course! The
1784 best course of action for that is to write the build code as a
1785 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
1786 information, @ref{G-Expressions}.
1788 Once upon a time, @code{gexp->derivation} did not exist and constructing
1789 derivations with build code written in Scheme was achieved with
1790 @code{build-expression->derivation}, documented below. This procedure
1791 is now deprecated in favor of the much nicer @code{gexp->derivation}.
1793 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
1794 @var{name} @var{exp} @
1795 [#:system (%current-system)] [#:inputs '()] @
1796 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1797 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
1798 [#:references-graphs #f] [#:local-build? #f] [#:guile-for-build #f]
1799 Return a derivation that executes Scheme expression @var{exp} as a
1800 builder for derivation @var{name}. @var{inputs} must be a list of
1801 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1802 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1803 modules from the current search path to be copied in the store,
1804 compiled, and made available in the load path during the execution of
1805 @var{exp}---e.g., @code{((guix build utils) (guix build
1806 gnu-build-system))}.
1808 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1809 to a list of output/path pairs, and where @code{%build-inputs} is bound
1810 to a list of string/output-path pairs made from @var{inputs}.
1811 Optionally, @var{env-vars} is a list of string pairs specifying the name
1812 and value of environment variables visible to the builder. The builder
1813 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1814 @var{exp} returns @code{#f}, the build is considered to have failed.
1816 @var{exp} is built using @var{guile-for-build} (a derivation). When
1817 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1818 @code{%guile-for-build} fluid is used instead.
1820 See the @code{derivation} procedure for the meaning of @var{references-graphs}
1821 and @var{local-build?}.
1825 Here's an example of a single-output derivation that creates a directory
1826 containing one file:
1829 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1830 (mkdir out) ; create /gnu/store/@dots{}-goo
1831 (call-with-output-file (string-append out "/test")
1833 (display '(hello guix) p))))))
1834 (build-expression->derivation store "goo" builder))
1836 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
1840 @node The Store Monad
1841 @section The Store Monad
1845 The procedures that operate on the store described in the previous
1846 sections all take an open connection to the build daemon as their first
1847 argument. Although the underlying model is functional, they either have
1848 side effects or depend on the current state of the store.
1850 The former is inconvenient: the connection to the build daemon has to be
1851 carried around in all those functions, making it impossible to compose
1852 functions that do not take that parameter with functions that do. The
1853 latter can be problematic: since store operations have side effects
1854 and/or depend on external state, they have to be properly sequenced.
1856 @cindex monadic values
1857 @cindex monadic functions
1858 This is where the @code{(guix monads)} module comes in. This module
1859 provides a framework for working with @dfn{monads}, and a particularly
1860 useful monad for our uses, the @dfn{store monad}. Monads are a
1861 construct that allows two things: associating ``context'' with values
1862 (in our case, the context is the store), and building sequences of
1863 computations (here computations includes accesses to the store.) Values
1864 in a monad---values that carry this additional context---are called
1865 @dfn{monadic values}; procedures that return such values are called
1866 @dfn{monadic procedures}.
1868 Consider this ``normal'' procedure:
1871 (define (sh-symlink store)
1872 ;; Return a derivation that symlinks the 'bash' executable.
1873 (let* ((drv (package-derivation store bash))
1874 (out (derivation->output-path drv))
1875 (sh (string-append out "/bin/bash")))
1876 (build-expression->derivation store "sh"
1877 `(symlink ,sh %output))))
1880 Using @code{(guix monads)}, it may be rewritten as a monadic function:
1882 @c FIXME: Find a better example, one that uses 'mlet'.
1884 (define (sh-symlink)
1885 ;; Same, but return a monadic value.
1886 (gexp->derivation "sh"
1887 #~(symlink (string-append #$bash "/bin/bash") #$output)))
1890 There are two things to note in the second version: the @code{store}
1891 parameter is now implicit, and the monadic value returned by
1892 @code{package-file}---a wrapper around @code{package-derivation} and
1893 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
1894 instead of plain @code{let}.
1896 Calling the monadic @code{profile.sh} has no effect. To get the desired
1897 effect, one must use @code{run-with-store}:
1900 (run-with-store (open-connection) (profile.sh))
1901 @result{} /gnu/store/...-profile.sh
1904 The main syntactic forms to deal with monads in general are described
1907 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
1908 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
1912 @deffn {Scheme Syntax} return @var{val}
1913 Return a monadic value that encapsulates @var{val}.
1916 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
1917 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
1918 procedure @var{mproc}@footnote{This operation is commonly referred to as
1919 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
1920 we use this somewhat cryptic symbol inherited from the Haskell
1924 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
1926 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
1928 Bind the variables @var{var} to the monadic values @var{mval} in
1929 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
1930 ``normal'' value @var{val}, as per @code{let}.
1932 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
1933 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
1936 The interface to the store monad provided by @code{(guix monads)} is as
1939 @defvr {Scheme Variable} %store-monad
1940 The store monad. Values in the store monad encapsulate accesses to the
1941 store. When its effect is needed, a value of the store monad must be
1942 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
1946 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
1947 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
1948 open store connection.
1951 @deffn {Monadic Procedure} text-file @var{name} @var{text}
1952 Return as a monadic value the absolute file name in the store of the file
1953 containing @var{text}, a string.
1956 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
1957 Return as a monadic value a derivation that builds a text file
1958 containing all of @var{text}. @var{text} may list, in addition to
1959 strings, packages, derivations, and store file names; the resulting
1960 store file holds references to all these.
1962 This variant should be preferred over @code{text-file} anytime the file
1963 to create will reference items from the store. This is typically the
1964 case when building a configuration file that embeds store file names,
1968 (define (profile.sh)
1969 ;; Return the name of a shell script in the store that
1970 ;; initializes the 'PATH' environment variable.
1971 (text-file* "profile.sh"
1972 "export PATH=" coreutils "/bin:"
1973 grep "/bin:" sed "/bin\n"))
1976 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
1977 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
1978 preventing them from being garbage-collected during its lifetime.
1981 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
1982 [#:system (%current-system)] [#:output "out"] Return as a monadic
1983 value in the absolute file name of @var{file} within the @var{output}
1984 directory of @var{package}. When @var{file} is omitted, return the name
1985 of the @var{output} directory of @var{package}.
1988 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
1989 Monadic version of @code{package-derivation} (@pxref{Defining
1995 @section G-Expressions
1997 @cindex G-expression
1998 @cindex build code quoting
1999 So we have ``derivations'', which represent a sequence of build actions
2000 to be performed to produce an item in the store (@pxref{Derivations}).
2001 Those build actions are performed when asking the daemon to actually
2002 build the derivations; they are run by the daemon in a container
2003 (@pxref{Invoking guix-daemon}).
2005 @cindex strata of code
2006 It should come as no surprise that we like to write those build actions
2007 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2008 code@footnote{The term @dfn{stratum} in this context was coined by
2009 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2010 Kiselyov, who has written insightful
2011 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2012 on this topic}, refers to this kind of code generation as
2013 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2014 to the daemon, etc.---and the ``build code''---code that actually
2015 performs build actions, such as making directories, invoking
2016 @command{make}, etc.
2018 To describe a derivation and its build actions, one typically needs to
2019 embed build code inside host code. It boils down to manipulating build
2020 code as data, and Scheme's homoiconicity---code has a direct
2021 representation as data---comes in handy for that. But we need more than
2022 Scheme's normal @code{quasiquote} mechanism to construct build
2025 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2026 S-expressions adapted to build expressions. G-expressions, or
2027 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2028 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2029 @code{#$}, and @code{#$@@}), which are comparable respectively to
2030 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2031 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2032 Reference Manual}). However, there are major differences:
2036 Gexps are meant to be written to a file and run or manipulated by other
2040 When a package or derivation is unquoted inside a gexp, the result is as
2041 if its output file name had been introduced.
2044 Gexps carry information about the packages or derivations they refer to,
2045 and these dependencies are automatically added as inputs to the build
2046 processes that use them.
2049 To illustrate the idea, here is an example of a gexp:
2056 (symlink (string-append #$coreutils "/bin/ls")
2060 This gexp can be passed to @code{gexp->derivation}; we obtain a
2061 derivation that builds a directory containing exactly one symlink to
2062 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2065 (gexp->derivation "the-thing" build-exp)
2068 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2069 substituted to the reference to the @var{coreutils} package in the
2070 actual build code, and @var{coreutils} is automatically made an input to
2071 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2072 output)}) is replaced by a string containing the derivation's output
2073 directory name. The syntactic form to construct gexps is summarized
2076 @deffn {Scheme Syntax} #~@var{exp}
2077 @deffnx {Scheme Syntax} (gexp @var{exp})
2078 Return a G-expression containing @var{exp}. @var{exp} may contain one
2079 or more of the following forms:
2083 @itemx (ungexp @var{obj})
2084 Introduce a reference to @var{obj}. @var{obj} may be a package or a
2085 derivation, in which case the @code{ungexp} form is replaced by its
2086 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2088 If @var{obj} is a list, it is traversed and any package or derivation
2089 references are substituted similarly.
2091 If @var{obj} is another gexp, its contents are inserted and its
2092 dependencies are added to those of the containing gexp.
2094 If @var{obj} is another kind of object, it is inserted as is.
2096 @item #$@var{package-or-derivation}:@var{output}
2097 @itemx (ungexp @var{package-or-derivation} @var{output})
2098 This is like the form above, but referring explicitly to the
2099 @var{output} of @var{package-or-derivation}---this is useful when
2100 @var{package-or-derivation} produces multiple outputs (@pxref{Packages
2101 with Multiple Outputs}).
2103 @item #$output[:@var{output}]
2104 @itemx (ungexp output [@var{output}])
2105 Insert a reference to derivation output @var{output}, or to the main
2106 output when @var{output} is omitted.
2108 This only makes sense for gexps passed to @code{gexp->derivation}.
2111 @itemx (ungexp-splicing @var{lst})
2112 Like the above, but splices the contents of @var{lst} inside the
2117 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2118 of the @code{gexp?} type (see below.)
2121 @deffn {Scheme Procedure} gexp? @var{obj}
2122 Return @code{#t} if @var{obj} is a G-expression.
2125 G-expressions are meant to be written to disk, either as code building
2126 some derivation, or as plain files in the store. The monadic procedures
2127 below allow you to do that (@pxref{The Store Monad}, for more
2128 information about monads.)
2130 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2131 [#:system (%current-system)] [#:inputs '()] @
2132 [#:hash #f] [#:hash-algo #f] @
2133 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2134 [#:references-graphs #f] [#:local-build? #f] @
2135 [#:guile-for-build #f]
2136 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2137 @var{guile-for-build} (a derivation) on @var{system}.
2139 Make @var{modules} available in the evaluation context of @var{EXP};
2140 @var{MODULES} is a list of names of Guile modules from the current
2141 search path to be copied in the store, compiled, and made available in
2142 the load path during the execution of @var{exp}---e.g., @code{((guix
2143 build utils) (guix build gnu-build-system))}.
2145 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2148 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2149 Return an executable script @var{name} that runs @var{exp} using
2150 @var{guile} with @var{modules} in its search path.
2152 The example below builds a script that simply invokes the @command{ls}
2156 (use-modules (guix gexp) (gnu packages base))
2158 (gexp->script "list-files"
2159 #~(execl (string-append #$coreutils "/bin/ls")
2163 When ``running'' it through the store (@pxref{The Store Monad,
2164 @code{run-with-store}}), we obtain a derivation that produces an
2165 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2168 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2170 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2175 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2176 Return a derivation that builds a file @var{name} containing @var{exp}.
2178 The resulting file holds references to all the dependencies of @var{exp}
2179 or a subset thereof.
2182 Of course, in addition to gexps embedded in ``host'' code, there are
2183 also modules containing build tools. To make it clear that they are
2184 meant to be used in the build stratum, these modules are kept in the
2185 @code{(guix build @dots{})} name space.
2188 @c *********************************************************************
2192 This section describes tools primarily targeted at developers and users
2193 who write new package definitions. They complement the Scheme
2194 programming interface of Guix in a convenient way.
2197 * Invoking guix build:: Building packages from the command line.
2198 * Invoking guix download:: Downloading a file and printing its hash.
2199 * Invoking guix hash:: Computing the cryptographic hash of a file.
2200 * Invoking guix refresh:: Updating package definitions.
2203 @node Invoking guix build
2204 @section Invoking @command{guix build}
2206 The @command{guix build} command builds packages or derivations and
2207 their dependencies, and prints the resulting store paths. Note that it
2208 does not modify the user's profile---this is the job of the
2209 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2210 it is mainly useful for distribution developers.
2212 The general syntax is:
2215 guix build @var{options} @var{package-or-derivation}@dots{}
2218 @var{package-or-derivation} may be either the name of a package found in
2219 the software distribution such as @code{coreutils} or
2220 @code{coreutils-8.20}, or a derivation such as
2221 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2222 package with the corresponding name (and optionally version) is searched
2223 for among the GNU distribution modules (@pxref{Package Modules}).
2225 Alternatively, the @code{--expression} option may be used to specify a
2226 Scheme expression that evaluates to a package; this is useful when
2227 disambiguation among several same-named packages or package variants is
2230 The @var{options} may be zero or more of the following:
2234 @item --expression=@var{expr}
2235 @itemx -e @var{expr}
2236 Build the package or derivation @var{expr} evaluates to.
2238 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2239 guile-1.8)}, which unambiguously designates this specific variant of
2240 version 1.8 of Guile.
2242 Alternately, @var{expr} may refer to a zero-argument monadic procedure
2243 (@pxref{The Store Monad}). The procedure must return a derivation as a
2244 monadic value, which is then passed through @code{run-with-store}.
2248 Build the packages' source derivations, rather than the packages
2251 For instance, @code{guix build -S gcc} returns something like
2252 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2254 The returned source tarball is the result of applying any patches and
2255 code snippets specified in the package's @code{origin} (@pxref{Defining
2258 @item --system=@var{system}
2259 @itemx -s @var{system}
2260 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
2261 the host's system type.
2263 An example use of this is on Linux-based systems, which can emulate
2264 different personalities. For instance, passing
2265 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
2266 to build packages in a complete 32-bit environment.
2268 @item --target=@var{triplet}
2269 @cindex cross-compilation
2270 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
2271 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
2272 configuration triplets,, configure, GNU Configure and Build System}).
2274 @item --with-source=@var{source}
2275 Use @var{source} as the source of the corresponding package.
2276 @var{source} must be a file name or a URL, as for @command{guix
2277 download} (@pxref{Invoking guix download}).
2279 The ``corresponding package'' is taken to be one specified on the
2280 command line whose name matches the base of @var{source}---e.g., if
2281 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
2282 package is @code{guile}. Likewise, the version string is inferred from
2283 @var{source}; in the previous example, it's @code{2.0.10}.
2285 This option allows users to try out versions of packages other than the
2286 one provided by the distribution. The example below downloads
2287 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
2288 the @code{ed} package:
2291 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
2294 As a developer, @code{--with-source} makes it easy to test release
2298 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
2304 Return the derivation paths, not the output paths, of the given
2307 @item --root=@var{file}
2308 @itemx -r @var{file}
2309 Make @var{file} a symlink to the result, and register it as a garbage
2313 Return the build log file names for the given
2314 @var{package-or-derivation}s, or raise an error if build logs are
2317 This works regardless of how packages or derivations are specified. For
2318 instance, the following invocations are equivalent:
2321 guix build --log-file `guix build -d guile`
2322 guix build --log-file `guix build guile`
2323 guix build --log-file guile
2324 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
2330 @cindex common build options
2331 In addition, a number of options that control the build process are
2332 common to @command{guix build} and other commands that can spawn builds,
2333 such as @command{guix package} or @command{guix archive}. These are the
2340 Keep the build tree of failed builds. Thus, if a build fail, its build
2341 tree is kept under @file{/tmp}, in a directory whose name is shown at
2342 the end of the build log. This is useful when debugging build issues.
2346 Do not build the derivations.
2349 When substituting a pre-built binary fails, fall back to building
2352 @item --no-substitutes
2353 Do not use substitutes for build products. That is, always build things
2354 locally instead of allowing downloads of pre-built binaries
2355 (@pxref{Substitutes}).
2357 @item --no-build-hook
2358 Do not attempt to offload builds @i{via} the daemon's ``build hook''
2359 (@pxref{Daemon Offload Setup}). That is, always build things locally
2360 instead of offloading builds to remote machines.
2362 @item --max-silent-time=@var{seconds}
2363 When the build or substitution process remains silent for more than
2364 @var{seconds}, terminate it and report a build failure.
2366 @item --timeout=@var{seconds}
2367 Likewise, when the build or substitution process lasts for more than
2368 @var{seconds}, terminate it and report a build failure.
2370 By default there is no timeout. This behavior can be restored with
2373 @item --verbosity=@var{level}
2374 Use the given verbosity level. @var{level} must be an integer between 0
2375 and 5; higher means more verbose output. Setting a level of 4 or more
2376 may be helpful when debugging setup issues with the build daemon.
2378 @item --cores=@var{n}
2380 Allow the use of up to @var{n} CPU cores for the build. The special
2381 value @code{0} means to use as many CPU cores as available.
2385 Behind the scenes, @command{guix build} is essentially an interface to
2386 the @code{package-derivation} procedure of the @code{(guix packages)}
2387 module, and to the @code{build-derivations} procedure of the @code{(guix
2390 @node Invoking guix download
2391 @section Invoking @command{guix download}
2393 When writing a package definition, developers typically need to download
2394 the package's source tarball, compute its SHA256 hash, and write that
2395 hash in the package definition (@pxref{Defining Packages}). The
2396 @command{guix download} tool helps with this task: it downloads a file
2397 from the given URI, adds it to the store, and prints both its file name
2398 in the store and its SHA256 hash.
2400 The fact that the downloaded file is added to the store saves bandwidth:
2401 when the developer eventually tries to build the newly defined package
2402 with @command{guix build}, the source tarball will not have to be
2403 downloaded again because it is already in the store. It is also a
2404 convenient way to temporarily stash files, which may be deleted
2405 eventually (@pxref{Invoking guix gc}).
2407 The @command{guix download} command supports the same URIs as used in
2408 package definitions. In particular, it supports @code{mirror://} URIs.
2409 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
2410 Guile bindings for GnuTLS are available in the user's environment; when
2411 they are not available, an error is raised.
2413 The following option is available:
2416 @item --format=@var{fmt}
2418 Write the hash in the format specified by @var{fmt}. For more
2419 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
2422 @node Invoking guix hash
2423 @section Invoking @command{guix hash}
2425 The @command{guix hash} command computes the SHA256 hash of a file.
2426 It is primarily a convenience tool for anyone contributing to the
2427 distribution: it computes the cryptographic hash of a file, which can be
2428 used in the definition of a package (@pxref{Defining Packages}).
2430 The general syntax is:
2433 guix hash @var{option} @var{file}
2436 @command{guix hash} has the following option:
2440 @item --format=@var{fmt}
2442 Write the hash in the format specified by @var{fmt}.
2444 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
2445 (@code{hex} and @code{hexadecimal} can be used as well).
2447 If the @option{--format} option is not specified, @command{guix hash}
2448 will output the hash in @code{nix-base32}. This representation is used
2449 in the definitions of packages.
2453 Compute the hash on @var{file} recursively.
2455 In this case, the hash is computed on an archive containing @var{file},
2456 including its children if it is a directory. Some of @var{file}'s
2457 meta-data is part of the archive; for instance, when @var{file} is a
2458 regular file, the hash is different depending on whether @var{file} is
2459 executable or not. Meta-data such as time stamps has no impact on the
2460 hash (@pxref{Invoking guix archive}).
2461 @c FIXME: Replace xref above with xref to an ``Archive'' section when
2466 @node Invoking guix refresh
2467 @section Invoking @command{guix refresh}
2469 The primary audience of the @command{guix refresh} command is developers
2470 of the GNU software distribution. By default, it reports any packages
2471 provided by the distribution that are outdated compared to the latest
2472 upstream version, like this:
2476 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
2477 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
2480 It does so by browsing each package's FTP directory and determining the
2481 highest version number of the source tarballs
2482 therein@footnote{Currently, this only works for GNU packages.}.
2484 When passed @code{--update}, it modifies distribution source files to
2485 update the version numbers and source tarball hashes of those packages'
2486 recipes (@pxref{Defining Packages}). This is achieved by downloading
2487 each package's latest source tarball and its associated OpenPGP
2488 signature, authenticating the downloaded tarball against its signature
2489 using @command{gpg}, and finally computing its hash. When the public
2490 key used to sign the tarball is missing from the user's keyring, an
2491 attempt is made to automatically retrieve it from a public key server;
2492 when it's successful, the key is added to the user's keyring; otherwise,
2493 @command{guix refresh} reports an error.
2495 The following options are supported:
2501 Update distribution source files (package recipes) in place.
2502 @ref{Defining Packages}, for more information on package definitions.
2504 @item --select=[@var{subset}]
2505 @itemx -s @var{subset}
2506 Select all the packages in @var{subset}, one of @code{core} or
2509 The @code{core} subset refers to all the packages at the core of the
2510 distribution---i.e., packages that are used to build ``everything
2511 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
2512 changing one of these packages in the distribution entails a rebuild of
2513 all the others. Thus, such updates are an inconvenience to users in
2514 terms of build time or bandwidth used to achieve the upgrade.
2516 The @code{non-core} subset refers to the remaining packages. It is
2517 typically useful in cases where an update of the core packages would be
2522 In addition, @command{guix refresh} can be passed one or more package
2523 names, as in this example:
2526 guix refresh -u emacs idutils
2530 The command above specifically updates the @code{emacs} and
2531 @code{idutils} packages. The @code{--select} option would have no
2532 effect in this case.
2534 The following options can be used to customize GnuPG operation:
2538 @item --key-server=@var{host}
2539 Use @var{host} as the OpenPGP key server when importing a public key.
2541 @item --gpg=@var{command}
2542 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
2543 for in @code{$PATH}.
2548 @c *********************************************************************
2549 @node GNU Distribution
2550 @chapter GNU Distribution
2552 Guix comes with a distribution of free software@footnote{The term
2553 ``free'' here refers to the
2554 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
2555 users of that software}.} that forms the basis of the GNU system. This
2556 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
2557 as many GNU and non-GNU applications. The complete list of available
2558 packages can be browsed
2559 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
2560 running @command{guix package} (@pxref{Invoking guix package}):
2563 guix package --list-available
2566 Our goal is to build a practical 100% free software distribution of
2567 Linux-based and other variants of GNU, with a focus on the promotion and
2568 tight integration of GNU components, and an emphasis on programs and
2569 tools that help users exert that freedom.
2571 The GNU distribution is currently available on the following platforms:
2576 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
2579 Intel 32-bit architecture (IA32), Linux-Libre kernel;
2581 @item mips64el-linux
2582 little-endian 64-bit MIPS processors, specifically the Loongson series,
2583 n32 application binary interface (ABI), and Linux-Libre kernel.
2588 For information on porting to other architectures or kernels,
2592 * Installing Debugging Files:: Feeding the debugger.
2593 * Package Modules:: Packages from the programmer's viewpoint.
2594 * Packaging Guidelines:: Growing the distribution.
2595 * Bootstrapping:: GNU/Linux built from scratch.
2596 * Porting:: Targeting another platform or kernel.
2597 * System Configuration:: Configuring a GNU system.
2600 Building this distribution is a cooperative effort, and you are invited
2601 to join! @ref{Contributing}, for information about how you can help.
2604 @node Installing Debugging Files
2605 @section Installing Debugging Files
2607 @cindex debugging files
2608 Program binaries, as produced by the GCC compilers for instance, are
2609 typically written in the ELF format, with a section containing
2610 @dfn{debugging information}. Debugging information is what allows the
2611 debugger, GDB, to map binary code to source code; it is required to
2612 debug a compiled program in good conditions.
2614 The problem with debugging information is that is takes up a fair amount
2615 of disk space. For example, debugging information for the GNU C Library
2616 weighs in at more than 60 MiB. Thus, as a user, keeping all the
2617 debugging info of all the installed programs is usually not an option.
2618 Yet, space savings should not come at the cost of an impediment to
2619 debugging---especially in the GNU system, which should make it easier
2620 for users to exert their computing freedom (@pxref{GNU Distribution}).
2622 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
2623 mechanism that allows users to get the best of both worlds: debugging
2624 information can be stripped from the binaries and stored in separate
2625 files. GDB is then able to load debugging information from those files,
2626 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
2629 The GNU distribution takes advantage of this by storing debugging
2630 information in the @code{lib/debug} sub-directory of a separate package
2631 output unimaginatively called @code{debug} (@pxref{Packages with
2632 Multiple Outputs}). Users can choose to install the @code{debug} output
2633 of a package when they need it. For instance, the following command
2634 installs the debugging information for the GNU C Library and for GNU
2638 guix package -i glibc:debug guile:debug
2641 GDB must then be told to look for debug files in the user's profile, by
2642 setting the @code{debug-file-directory} variable (consider setting it
2643 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
2647 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
2650 From there on, GDB will pick up debugging information from the
2651 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
2653 In addition, you will most likely want GDB to be able to show the source
2654 code being debugged. To do that, you will have to unpack the source
2655 code of the package of interest (obtained with @code{guix build
2656 --source}, @pxref{Invoking guix build}), and to point GDB to that source
2657 directory using the @code{directory} command (@pxref{Source Path,
2658 @code{directory},, gdb, Debugging with GDB}).
2660 @c XXX: keep me up-to-date
2661 The @code{debug} output mechanism in Guix is implemented by the
2662 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
2663 opt-in---debugging information is available only for those packages
2664 whose definition explicitly declares a @code{debug} output. This may be
2665 changed to opt-out in the future, if our build farm servers can handle
2666 the load. To check whether a package has a @code{debug} output, use
2667 @command{guix package --list-available} (@pxref{Invoking guix package}).
2670 @node Package Modules
2671 @section Package Modules
2673 From a programming viewpoint, the package definitions of the
2674 GNU distribution are provided by Guile modules in the @code{(gnu packages
2675 @dots{})} name space@footnote{Note that packages under the @code{(gnu
2676 packages @dots{})} module name space are not necessarily ``GNU
2677 packages''. This module naming scheme follows the usual Guile module
2678 naming convention: @code{gnu} means that these modules are distributed
2679 as part of the GNU system, and @code{packages} identifies modules that
2680 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
2681 Reference Manual}). For instance, the @code{(gnu packages emacs)}
2682 module exports a variable named @code{emacs}, which is bound to a
2683 @code{<package>} object (@pxref{Defining Packages}).
2685 The @code{(gnu packages @dots{})} module name space is special: it is
2686 automatically scanned for packages by the command-line tools. For
2687 instance, when running @code{guix package -i emacs}, all the @code{(gnu
2688 packages @dots{})} modules are scanned until one that exports a package
2689 object whose name is @code{emacs} is found. This package search
2690 facility is implemented in the @code{(gnu packages)} module.
2692 Users can store package definitions in modules with different
2693 names---e.g., @code{(my-packages emacs)}. In that case, commands such
2694 as @command{guix package} and @command{guix build} have to be used with
2695 the @code{-e} option so that they know where to find the package.
2697 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
2698 each package is built based solely on other packages in the
2699 distribution. The root of this dependency graph is a small set of
2700 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
2701 bootstrap)} module. For more information on bootstrapping,
2702 @ref{Bootstrapping}.
2704 @node Packaging Guidelines
2705 @section Packaging Guidelines
2707 The GNU distribution is nascent and may well lack some of your favorite
2708 packages. This section describes how you can help make the distribution
2709 grow. @xref{Contributing}, for additional information on how you can
2712 Free software packages are usually distributed in the form of
2713 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
2714 all the source files. Adding a package to the distribution means
2715 essentially two things: adding a @dfn{recipe} that describes how to
2716 build the package, including a list of other packages required to build
2717 it, and adding @dfn{package meta-data} along with that recipe, such as a
2718 description and licensing information.
2720 In Guix all this information is embodied in @dfn{package definitions}.
2721 Package definitions provide a high-level view of the package. They are
2722 written using the syntax of the Scheme programming language; in fact,
2723 for each package we define a variable bound to the package definition,
2724 and export that variable from a module (@pxref{Package Modules}).
2725 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
2726 creating packages. For more information on package definitions,
2727 @ref{Defining Packages}.
2729 Once a package definition is in place, stored in a file in the Guix
2730 source tree, it can be tested using the @command{guix build} command
2731 (@pxref{Invoking guix build}). For example, assuming the new package is
2732 called @code{gnew}, you may run this command from the Guix build tree:
2735 ./pre-inst-env guix build gnew --keep-failed
2738 Using @code{--keep-failed} makes it easier to debug build failures since
2739 it provides access to the failed build tree. Another useful
2740 command-line option when debugging is @code{--log-file}, to access the
2743 If the package is unknown to the @command{guix} command, it may be that
2744 the source file contains a syntax error, or lacks a @code{define-public}
2745 clause to export the package variable. To figure it out, you may load
2746 the module from Guile to get more information about the actual error:
2749 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
2752 Once your package builds correctly, please send us a patch
2753 (@pxref{Contributing}). Well, if you need help, we will be happy to
2754 help you too. Once the patch is committed in the Guix repository, the
2755 new package automatically gets built on the supported platforms by
2756 @url{http://hydra.gnu.org/gnu/master, our continuous integration
2760 Users can obtain the new package definition simply by running
2761 @command{guix pull} (@pxref{Invoking guix pull}). When
2762 @code{hydra.gnu.org} is done building the package, installing the
2763 package automatically downloads binaries from there
2764 (@pxref{Substitutes}). The only place where human intervention is
2765 needed is to review and apply the patch.
2769 * Software Freedom:: What may go into the distribution.
2770 * Package Naming:: What's in a name?
2771 * Version Numbers:: When the name is not enough.
2772 * Python Modules:: Taming the snake.
2773 * Perl Modules:: Little pearls.
2776 @node Software Freedom
2777 @subsection Software Freedom
2779 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
2781 The GNU operating system has been developed so that users can have
2782 freedom in their computing. GNU is @dfn{free software}, meaning that
2783 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
2784 essential freedoms}: to run the program, to study and change the program
2785 in source code form, to redistribute exact copies, and to distribute
2786 modified versions. Packages found in the GNU distribution provide only
2787 software that conveys these four freedoms.
2789 In addition, the GNU distribution follow the
2790 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
2791 software distribution guidelines}. Among other things, these guidelines
2792 reject non-free firmware, recommendations of non-free software, and
2793 discuss ways to deal with trademarks and patents.
2795 Some packages contain a small and optional subset that violates the
2796 above guidelines, for instance because this subset is itself non-free
2797 code. When that happens, the offending items are removed with
2798 appropriate patches or code snippets in the package definition's
2799 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
2800 build --source} returns the ``freed'' source rather than the unmodified
2804 @node Package Naming
2805 @subsection Package Naming
2807 A package has actually two names associated with it:
2808 First, there is the name of the @emph{Scheme variable}, the one following
2809 @code{define-public}. By this name, the package can be made known in the
2810 Scheme code, for instance as input to another package. Second, there is
2811 the string in the @code{name} field of a package definition. This name
2812 is used by package management commands such as
2813 @command{guix package} and @command{guix build}.
2815 Both are usually the same and correspond to the lowercase conversion of the
2816 project name chosen upstream. For instance, the GNUnet project is packaged
2817 as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
2818 unless these are already part of the official project name. But see
2819 @pxref{Python Modules} and @ref{Perl Modules} for special rules concerning
2820 modules for the Python and Perl languages.
2823 @node Version Numbers
2824 @subsection Version Numbers
2826 We usually package only the latest version of a given free software
2827 project. But sometimes, for instance for incompatible library versions,
2828 two (or more) versions of the same package are needed. These require
2829 different Scheme variable names. We use the name as defined
2830 in @ref{Package Naming}
2831 for the most recent version; previous versions use the same name, suffixed
2832 by @code{-} and the smallest prefix of the version number that may
2833 distinguish the two versions.
2835 The name inside the package definition is the same for all versions of a
2836 package and does not contain any version number.
2838 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
2846 (define-public gtk+-2
2852 If we also wanted GTK+ 3.8.2, this would be packaged as
2854 (define-public gtk+-3.8
2862 @node Python Modules
2863 @subsection Python Modules
2865 We currently package Python 2 and Python 3, under the Scheme variable names
2866 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
2867 To avoid confusion and naming clashes with other programming languages, it
2868 seems desirable that the name of a package for a Python module contains
2869 the word @code{python}.
2871 Some modules are compatible with only one version of Python, others with both.
2872 If the package Foo compiles only with Python 3, we name it
2873 @code{python-foo}; if it compiles only with Python 2, we name it
2874 @code{python2-foo}. If it is compatible with both versions, we create two
2875 packages with the corresponding names.
2877 If a project already contains the word @code{python}, we drop this;
2878 for instance, the module python-dateutil is packaged under the names
2879 @code{python-dateutil} and @code{python2-dateutil}.
2883 @subsection Perl Modules
2885 Perl programs standing for themselves are named as any other package,
2886 using the lowercase upstream name.
2887 For Perl packages containing a single class, we use the lowercase class name,
2888 replace all occurrences of @code{::} by dashes and prepend the prefix
2890 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
2891 Modules containing several classes keep their lowercase upstream name and
2892 are also prepended by @code{perl-}. Such modules tend to have the word
2893 @code{perl} somewhere in their name, which gets dropped in favor of the
2894 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
2899 @section Bootstrapping
2901 @c Adapted from the ELS 2013 paper.
2903 @cindex bootstrapping
2905 Bootstrapping in our context refers to how the distribution gets built
2906 ``from nothing''. Remember that the build environment of a derivation
2907 contains nothing but its declared inputs (@pxref{Introduction}). So
2908 there's an obvious chicken-and-egg problem: how does the first package
2909 get built? How does the first compiler get compiled? Note that this is
2910 a question of interest only to the curious hacker, not to the regular
2911 user, so you can shamelessly skip this section if you consider yourself
2914 @cindex bootstrap binaries
2915 The GNU system is primarily made of C code, with libc at its core. The
2916 GNU build system itself assumes the availability of a Bourne shell and
2917 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
2918 `grep'. Furthermore, build programs---programs that run
2919 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
2920 (@pxref{Derivations}). Consequently, to be able to build anything at
2921 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
2922 Binutils, libc, and the other packages mentioned above---the
2923 @dfn{bootstrap binaries}.
2925 These bootstrap binaries are ``taken for granted'', though we can also
2926 re-create them if needed (more on that later).
2928 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
2930 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
2931 @c large image, it's hard to scroll. Oh well.
2932 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
2934 The figure above shows the very beginning of the dependency graph of the
2935 distribution, corresponding to the package definitions of the @code{(gnu
2936 packages bootstrap)} module. At this level of detail, things are
2937 slightly complex. First, Guile itself consists of an ELF executable,
2938 along with many source and compiled Scheme files that are dynamically
2939 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
2940 tarball shown in this graph. This tarball is part of Guix's ``source''
2941 distribution, and gets inserted into the store with @code{add-to-store}
2942 (@pxref{The Store}).
2944 But how do we write a derivation that unpacks this tarball and adds it
2945 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
2946 derivation---the first one that gets built---uses @code{bash} as its
2947 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
2948 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
2949 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
2950 the Guix source distribution, whose sole purpose is to allow the Guile
2951 tarball to be unpacked.
2953 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
2954 Guile that can be used to run subsequent build programs. Its first task
2955 is to download tarballs containing the other pre-built binaries---this
2956 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
2957 @code{ftp-client.scm} are used for this purpose. The
2958 @code{module-import.drv} derivations import those modules in a directory
2959 in the store, using the original layout. The
2960 @code{module-import-compiled.drv} derivations compile those modules, and
2961 write them in an output directory with the right layout. This
2962 corresponds to the @code{#:modules} argument of
2963 @code{build-expression->derivation} (@pxref{Derivations}).
2965 Finally, the various tarballs are unpacked by the
2966 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
2967 etc., at which point we have a working C tool chain.
2970 @unnumberedsubsec Building the Build Tools
2972 @c TODO: Add a package-level dependency graph generated from (gnu
2975 Bootstrapping is complete when we have a full tool chain that does not
2976 depend on the pre-built bootstrap tools discussed above. This
2977 no-dependency requirement is verified by checking whether the files of
2978 the final tool chain contain references to the @file{/gnu/store}
2979 directories of the bootstrap inputs. The process that leads to this
2980 ``final'' tool chain is described by the package definitions found in
2981 the @code{(gnu packages base)} module.
2983 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
2984 The first tool that gets built with the bootstrap binaries is
2985 GNU Make, which is a prerequisite for all the following packages.
2986 From there Findutils and Diffutils get built.
2988 Then come the first-stage Binutils and GCC, built as pseudo cross
2989 tools---i.e., with @code{--target} equal to @code{--host}. They are
2990 used to build libc. Thanks to this cross-build trick, this libc is
2991 guaranteed not to hold any reference to the initial tool chain.
2993 From there the final Binutils and GCC are built. GCC uses @code{ld}
2994 from the final Binutils, and links programs against the just-built libc.
2995 This tool chain is used to build the other packages used by Guix and by
2996 the GNU Build System: Guile, Bash, Coreutils, etc.
2998 And voilà! At this point we have the complete set of build tools that
2999 the GNU Build System expects. These are in the @code{%final-inputs}
3000 variables of the @code{(gnu packages base)} module, and are implicitly
3001 used by any package that uses @code{gnu-build-system} (@pxref{Defining
3005 @unnumberedsubsec Building the Bootstrap Binaries
3007 Because the final tool chain does not depend on the bootstrap binaries,
3008 those rarely need to be updated. Nevertheless, it is useful to have an
3009 automated way to produce them, should an update occur, and this is what
3010 the @code{(gnu packages make-bootstrap)} module provides.
3012 The following command builds the tarballs containing the bootstrap
3013 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
3014 of Coreutils and other basic command-line tools):
3017 guix build bootstrap-tarballs
3020 The generated tarballs are those that should be referred to in the
3021 @code{(gnu packages bootstrap)} module mentioned at the beginning of
3024 Still here? Then perhaps by now you've started to wonder: when do we
3025 reach a fixed point? That is an interesting question! The answer is
3026 unknown, but if you would like to investigate further (and have
3027 significant computational and storage resources to do so), then let us
3031 @section Porting to a New Platform
3033 As discussed above, the GNU distribution is self-contained, and
3034 self-containment is achieved by relying on pre-built ``bootstrap
3035 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
3036 operating system kernel, CPU architecture, and application binary
3037 interface (ABI). Thus, to port the distribution to a platform that is
3038 not yet supported, one must build those bootstrap binaries, and update
3039 the @code{(gnu packages bootstrap)} module to use them on that platform.
3041 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
3042 When everything goes well, and assuming the GNU tool chain supports the
3043 target platform, this can be as simple as running a command like this
3047 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
3050 Once these are built, the @code{(gnu packages bootstrap)} module needs
3051 to be updated to refer to these binaries on the target platform. In
3052 addition, the @code{glibc-dynamic-linker} procedure in that module must
3053 be augmented to return the right file name for libc's dynamic linker on
3054 that platform; likewise, @code{system->linux-architecture} in @code{(gnu
3055 packages linux)} must be taught about the new platform.
3057 In practice, there may be some complications. First, it may be that the
3058 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
3059 above) is not recognized by all the GNU tools. Typically, glibc
3060 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
3061 configure flag (see @code{gcc.scm} for examples of how to handle this).
3062 Second, some of the required packages could fail to build for that
3063 platform. Lastly, the generated binaries could be broken for some
3067 @node System Configuration
3068 @section System Configuration
3070 @emph{This section documents work-in-progress. As such it may be
3071 incomplete, outdated, or open to discussions. Please discuss it on
3072 @email{guix-devel@@gnu.org}.}
3074 @cindex system configuration
3075 The GNU system supports a consistent whole-system configuration
3076 mechanism. By that we mean that all aspects of the global system
3077 configuration---such as the available system services, timezone and
3078 locale settings, user accounts---are declared in a single place. Such
3079 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
3081 One of the advantages of putting all the system configuration under the
3082 control of Guix is that it supports transactional system upgrades, and
3083 makes it possible to roll-back to a previous system instantiation,
3084 should something go wrong with the new one (@pxref{Features}). Another
3085 one is that it makes it easy to replicate the exact same configuration
3086 across different machines, or at different points in time, without
3087 having to resort to additional administration tools layered on top of
3088 the system's own tools.
3089 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
3091 This section describes this mechanism. First we focus on the system
3092 administrator's viewpoint---explaining how the system is configured and
3093 instantiated. Then we show how this mechanism can be extended, for
3094 instance to support new system services.
3097 * Using the Configuration System:: Customizing your GNU system.
3098 * Invoking guix system:: Instantiating a system configuration.
3099 * Defining Services:: Adding new service definitions.
3102 @node Using the Configuration System
3103 @subsection Using the Configuration System
3105 The operating system is configured by filling in an
3106 @code{operating-system} structure, as defined by the @code{(gnu system)}
3107 module. A simple setup, with the default system services, the default
3108 Linux-Libre kernel, initial RAM disk, and boot loader looks like this:
3110 @findex operating-system
3112 (use-modules (gnu services base) ; for '%base-services'
3113 (gnu services ssh) ; for 'lsh-service'
3114 (gnu system shadow) ; for 'user-account'
3115 (gnu packages base) ; Coreutils, grep, etc.
3116 (gnu packages bash) ; Bash
3117 (gnu packages admin) ; dmd, Inetutils
3118 (gnu packages zile) ; Zile
3119 (gnu packages less) ; less
3120 (gnu packages guile) ; Guile
3121 (gnu packages linux)) ; procps, psmisc
3125 (host-name "komputilo")
3126 (timezone "Europe/Paris")
3127 (locale "fr_FR.UTF-8")
3128 (bootloader (grub-configuration
3129 (device "/dev/sda")))
3130 (file-systems (list (file-system
3131 (device "/dev/disk/by-label/root")
3134 (users (list (user-account
3137 (uid 1000) (gid 100)
3138 (comment "Bob's sister")
3139 (home-directory "/home/alice"))))
3140 (packages (list coreutils bash guile-2.0
3146 (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
3150 This example should be self-describing. The @code{packages} field lists
3151 packages provided by the various @code{(gnu packages ...)} modules above
3152 (@pxref{Package Modules}). These are the packages that will be globally
3153 visible on the system, for all user accounts---i.e., in every user's
3154 @code{PATH} environment variable---in addition to the per-user profiles
3155 (@pxref{Invoking guix package}).
3157 @vindex %base-services
3158 The @code{services} field lists @dfn{system services} to be made
3159 available when the system starts. The @var{%base-services} list,
3160 from the @code{(gnu services base)} module, provides the basic services one
3161 would expect from a GNU system: a login service (mingetty) on each tty,
3162 syslogd, libc's name service cache daemon (nscd), etc.
3164 The @code{operating-system} declaration above specifies that, in
3165 addition to those services, we want the @command{lshd} secure shell
3166 daemon listening on port 2222, and allowing remote @code{root} logins
3167 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
3168 @code{lsh-service} arranges so that @code{lshd} is started with the
3169 right command-line options, possibly with supporting configuration files
3170 generated as needed (@pxref{Defining Services}).
3172 Assuming the above snippet is stored in the @file{my-system-config.scm}
3173 file, the @command{guix system boot my-system-config.scm} command
3174 instantiates that configuration, and makes it the default GRUB boot
3175 entry (@pxref{Invoking guix system}). The normal way to change the
3176 system's configuration is by updating this file and re-running the
3177 @command{guix system} command.
3179 At the Scheme level, the bulk of an @code{operating-system} declaration
3180 is instantiated with the following monadic procedure (@pxref{The Store
3183 @deffn {Monadic Procedure} operating-system-derivation os
3184 Return a derivation that builds @var{os}, an @code{operating-system}
3185 object (@pxref{Derivations}).
3187 The output of the derivation is a single directory that refers to all
3188 the packages, configuration files, and other supporting files needed to
3189 instantiate @var{os}.
3192 @node Invoking guix system
3193 @subsection Invoking @code{guix system}
3195 Once you have written an operating system declaration, as seen in the
3196 previous section, it can be @dfn{instantiated} using the @command{guix
3197 system} command. The synopsis is:
3200 guix system @var{options}@dots{} @var{action} @var{file}
3203 @var{file} must be the name of a file containing an
3204 @code{operating-system} declaration. @var{action} specifies how the
3205 operating system is instantiate. Currently the following values are
3210 Build the operating system's derivation, which includes all the
3211 configuration files and programs needed to boot and run the system.
3212 This action does not actually install anything.
3215 Populate the given directory with all the files necessary to run the
3216 operating system specified in @var{file}. This is useful for first-time
3217 installations of the GNU system. For instance:
3220 guix system init my-os-config.scm /mnt
3223 copies to @file{/mnt} all the store items required by the configuration
3224 specified in @file{my-os-config.scm}. This includes configuration
3225 files, packages, and so on. It also creates other essential files
3226 needed for the system to operate correctly---e.g., the @file{/etc},
3227 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
3229 This command also installs GRUB on the device specified in
3230 @file{my-os-config}, unless the @option{--no-grub} option was passed.
3233 @cindex virtual machine
3234 Build a virtual machine that contain the operating system declared in
3235 @var{file}, and return a script to run that virtual machine (VM).
3237 The VM shares its store with the host system.
3240 Return a virtual machine image of the operating system declared in
3241 @var{file} that stands alone. Use the @option{--image-size} option to
3242 specify the size of the image.
3245 @var{options} can contain any of the common build options provided by
3246 @command{guix build} (@pxref{Invoking guix build}).
3249 @node Defining Services
3250 @subsection Defining Services
3252 The @code{(gnu services @dots{})} modules define several procedures that allow
3253 users to declare the operating system's services (@pxref{Using the
3254 Configuration System}). These procedures are @emph{monadic
3255 procedures}---i.e., procedures that return a monadic value in the store
3256 monad (@pxref{The Store Monad}). Examples of such procedures include:
3259 @item mingetty-service
3260 return the definition of a service that runs @command{mingetty} to
3261 offer a login service on the given console tty;
3264 return a definition for libc's name service cache daemon (nscd);
3267 return a definition for a service that runs @command{guix-daemon}
3268 (@pxref{Invoking guix-daemon}).
3271 @cindex service definition
3272 The monadic value returned by those procedures is a @dfn{service
3273 definition}---a structure as returned by the @code{service} form.
3274 Service definitions specifies the inputs the service depends on, and an
3275 expression to start and stop the service. Behind the scenes, service
3276 definitions are ``translated'' into the form suitable for the
3277 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
3280 As an example, here is what the @code{nscd-service} procedure looks
3284 (define (nscd-service)
3285 (with-monad %store-monad
3287 (documentation "Run libc's name service cache daemon.")
3289 (start #~(make-forkexec-constructor
3290 (string-append #$glibc "/sbin/nscd")
3291 "-f" "/dev/null" "--foreground"))
3292 (stop #~(make-kill-destructor))
3297 The @code{start} and @code{stop} fields are G-expressions
3298 (@pxref{G-Expressions}). They refer to dmd's facilities to start and
3299 stop processes (@pxref{Service De- and Constructors,,, dmd, GNU dmd
3300 Manual}). The @code{provision} field specifies the name under which
3301 this service is known to dmd, and @code{documentation} specifies on-line
3302 documentation. Thus, the commands @command{deco start ncsd},
3303 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
3304 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
3307 @c *********************************************************************
3309 @chapter Contributing
3311 This project is a cooperative effort, and we need your help to make it
3312 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
3313 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
3314 reports, patches, and anything that may be helpful to the project. We
3315 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
3318 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
3319 @file{HACKING} file} that comes with the Guix source code for practical
3320 details about contributions.
3323 @c *********************************************************************
3324 @node Acknowledgments
3325 @chapter Acknowledgments
3327 Guix is based on the Nix package manager, which was designed and
3328 implemented by Eelco Dolstra. Nix pioneered functional package
3329 management, and promoted unprecedented features, such as transactional
3330 package upgrades and rollbacks, per-user profiles, and referentially
3331 transparent build processes. Without this work, Guix would not exist.
3333 The Nix-based software distributions, Nixpkgs and NixOS, have also been
3334 an inspiration for Guix.
3336 @c *********************************************************************
3337 @node GNU Free Documentation License
3338 @appendix GNU Free Documentation License
3340 @include fdl-1.3.texi
3342 @c *********************************************************************
3344 @unnumbered Concept Index
3347 @node Function Index
3348 @unnumbered Function Index
3354 @c ispell-local-dictionary: "american";