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. The term ``derivation'' comes from the fact
1309 that build results @emph{derive} from them.
1311 This chapter describes all these APIs in turn, starting from high-level
1312 package definitions.
1315 * Defining Packages:: Defining new packages.
1316 * Build Systems:: Specifying how packages are built.
1317 * The Store:: Manipulating the package store.
1318 * Derivations:: Low-level interface to package derivations.
1319 * The Store Monad:: Purely functional interface to the store.
1320 * G-Expressions:: Manipulating build expressions.
1323 @node Defining Packages
1324 @section Defining Packages
1326 The high-level interface to package definitions is implemented in the
1327 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1328 example, the package definition, or @dfn{recipe}, for the GNU Hello
1329 package looks like this:
1332 (define-module (gnu packages hello)
1333 #:use-module (guix packages)
1334 #:use-module (guix download)
1335 #:use-module (guix build-system gnu)
1336 #:use-module (guix licenses))
1344 (uri (string-append "mirror://gnu/hello/hello-" version
1347 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1348 (build-system gnu-build-system)
1349 (arguments `(#:configure-flags '("--enable-silent-rules")))
1350 (inputs `(("gawk" ,gawk)))
1351 (synopsis "Hello, GNU world: An example GNU package")
1352 (description "Guess what GNU Hello prints!")
1353 (home-page "http://www.gnu.org/software/hello/")
1358 Without being a Scheme expert, the reader may have guessed the meaning
1359 of the various fields here. This expression binds variable @code{hello}
1360 to a @code{<package>} object, which is essentially a record
1361 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1362 This package object can be inspected using procedures found in the
1363 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1364 returns---surprise!---@code{"hello"}.
1366 In the example above, @var{hello} is defined into a module of its own,
1367 @code{(gnu packages hello)}. Technically, this is not strictly
1368 necessary, but it is convenient to do so: all the packages defined in
1369 modules under @code{(gnu packages @dots{})} are automatically known to
1370 the command-line tools (@pxref{Package Modules}).
1372 There are a few points worth noting in the above package definition:
1376 The @code{source} field of the package is an @code{<origin>} object.
1377 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1378 meaning that the source is a file to be downloaded over FTP or HTTP.
1380 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1381 the GNU mirrors defined in @code{(guix download)}.
1383 The @code{sha256} field specifies the expected SHA256 hash of the file
1384 being downloaded. It is mandatory, and allows Guix to check the
1385 integrity of the file. The @code{(base32 @dots{})} form introduces the
1386 base32 representation of the hash. You can obtain this information with
1387 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1388 hash} (@pxref{Invoking guix hash}).
1391 When needed, the @code{origin} form can also have a @code{patches} field
1392 listing patches to be applied, and a @code{snippet} field giving a
1393 Scheme expression to modify the source code.
1396 @cindex GNU Build System
1397 The @code{build-system} field specifies the procedure to build the
1398 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1399 represents the familiar GNU Build System, where packages may be
1400 configured, built, and installed with the usual @code{./configure &&
1401 make && make check && make install} command sequence.
1404 The @code{arguments} field specifies options for the build system
1405 (@pxref{Build Systems}). Here it is interpreted by
1406 @var{gnu-build-system} as a request run @file{configure} with the
1407 @code{--enable-silent-rules} flag.
1410 The @code{inputs} field specifies inputs to the build process---i.e.,
1411 build-time or run-time dependencies of the package. Here, we define an
1412 input called @code{"gawk"} whose value is that of the @var{gawk}
1413 variable; @var{gawk} is itself bound to a @code{<package>} object.
1415 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1416 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1417 of ensuring that they are present (@pxref{Build Systems}).
1419 However, any other dependencies need to be specified in the
1420 @code{inputs} field. Any dependency not specified here will simply be
1421 unavailable to the build process, possibly leading to a build failure.
1424 Once a package definition is in place@footnote{Simple package
1425 definitions like the one above may be automatically converted from the
1426 Nixpkgs distribution using the @command{guix import} command.}, the
1427 package may actually be built using the @code{guix build} command-line
1428 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1429 more information on how to test package definitions.
1431 Eventually, updating the package definition to a new upstream version
1432 can be partly automated by the @command{guix refresh} command
1433 (@pxref{Invoking guix refresh}).
1435 Behind the scenes, a derivation corresponding to the @code{<package>}
1436 object is first computed by the @code{package-derivation} procedure.
1437 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1438 The build actions it prescribes may then be realized by using the
1439 @code{build-derivations} procedure (@pxref{The Store}).
1441 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1442 Return the @code{<derivation>} object of @var{package} for @var{system}
1443 (@pxref{Derivations}).
1445 @var{package} must be a valid @code{<package>} object, and @var{system}
1446 must be a string denoting the target system type---e.g.,
1447 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1448 must be a connection to the daemon, which operates on the store
1449 (@pxref{The Store}).
1453 @cindex cross-compilation
1454 Similarly, it is possible to compute a derivation that cross-builds a
1455 package for some other system:
1457 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1458 @var{package} @var{target} [@var{system}]
1459 Return the @code{<derivation>} object of @var{package} cross-built from
1460 @var{system} to @var{target}.
1462 @var{target} must be a valid GNU triplet denoting the target hardware
1463 and operating system, such as @code{"mips64el-linux-gnu"}
1464 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1465 Configure and Build System}).
1470 @section Build Systems
1472 @cindex build system
1473 Each package definition specifies a @dfn{build system} and arguments for
1474 that build system (@pxref{Defining Packages}). This @code{build-system}
1475 field represents the build procedure of the package, as well implicit
1476 dependencies of that build procedure.
1478 Build systems are @code{<build-system>} objects. The interface to
1479 create and manipulate them is provided by the @code{(guix build-system)}
1480 module, and actual build systems are exported by specific modules.
1482 Build systems accept an optional list of @dfn{arguments}. In package
1483 definitions, these are passed @i{via} the @code{arguments} field
1484 (@pxref{Defining Packages}). They are typically keyword arguments
1485 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
1486 Guile Reference Manual}). The value of these arguments is usually
1487 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
1488 by the daemon (@pxref{Derivations}).
1490 The main build system is @var{gnu-build-system}, which implements the
1491 standard build procedure for GNU packages and many other packages. It
1492 is provided by the @code{(guix build-system gnu)} module.
1494 @defvr {Scheme Variable} gnu-build-system
1495 @var{gnu-build-system} represents the GNU Build System, and variants
1496 thereof (@pxref{Configuration, configuration and makefile conventions,,
1497 standards, GNU Coding Standards}).
1499 @cindex build phases
1500 In a nutshell, packages using it configured, built, and installed with
1501 the usual @code{./configure && make && make check && make install}
1502 command sequence. In practice, a few additional steps are often needed.
1503 All these steps are split up in separate @dfn{phases},
1504 notably@footnote{Please see the @code{(guix build gnu-build-system)}
1505 modules for more details about the build phases.}:
1509 Unpack the source tarball, and change the current directory to the
1510 extracted source tree. If the source is actually a directory, copy it
1511 to the build tree, and enter that directory.
1513 @item patch-source-shebangs
1514 Patch shebangs encountered in source files so they refer to the right
1515 store file names. For instance, this changes @code{#!/bin/sh} to
1516 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
1519 Run the @file{configure} script with a number of default options, such
1520 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
1521 by the @code{#:configure-flags} argument.
1524 Run @code{make} with the list of flags specified with
1525 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
1526 (the default), build with @code{make -j}.
1529 Run @code{make check}, or some other target specified with
1530 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
1531 @code{#:parallel-tests?} argument is true (the default), run @code{make
1535 Run @code{make install} with the flags listed in @code{#:make-flags}.
1537 @item patch-shebangs
1538 Patch shebangs on the installed executable files.
1541 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
1542 is false), copying them to the @code{debug} output when available
1543 (@pxref{Installing Debugging Files}).
1546 @vindex %standard-phases
1547 The build-side module @code{(guix build gnu-build-system)} defines
1548 @var{%standard-phases} as the default list of build phases.
1549 @var{%standard-phases} is a list of symbol/procedure pairs, where the
1550 procedure implements the actual phase.
1552 The list of phases used for a particular package can be changed with the
1553 @code{#:phases} parameter. For instance, passing:
1556 #:phases (alist-delete 'configure %standard-phases)
1559 means that all the phases described above will be used, except the
1560 @code{configure} phase.
1562 In addition, this build system ensures that the ``standard'' environment
1563 for GNU packages is available. This includes tools such as GCC, libc,
1564 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
1565 build-system gnu)} module for a complete list.) We call these the
1566 @dfn{implicit inputs} of a package, because package definitions don't
1567 have to mention them.
1570 Other @code{<build-system>} objects are defined to support other
1571 conventions and tools used by free software packages. They inherit most
1572 of @var{gnu-build-system}, and differ mainly in the set of inputs
1573 implicitly added to the build process, and in the list of phases
1574 executed. Some of these build systems are listed below.
1576 @defvr {Scheme Variable} cmake-build-system
1577 This variable is exported by @code{(guix build-system cmake)}. It
1578 implements the build procedure for packages using the
1579 @url{http://www.cmake.org, CMake build tool}.
1581 It automatically adds the @code{cmake} package to the set of inputs.
1582 Which package is used can be specified with the @code{#:cmake}
1586 @defvr {Scheme Variable} python-build-system
1587 This variable is exported by @code{(guix build-system python)}. It
1588 implements the more or less standard build procedure used by Python
1589 packages, which consists in running @code{python setup.py build} and
1590 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
1592 For packages that install stand-alone Python programs under @code{bin/},
1593 it takes care of wrapping these programs so their @code{PYTHONPATH}
1594 environment variable points to all the Python libraries they depend on.
1596 Which Python package is used can be specified with the @code{#:python}
1600 @defvr {Scheme Variable} perl-build-system
1601 This variable is exported by @code{(guix build-system perl)}. It
1602 implements the standard build procedure for Perl packages, which
1603 consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
1604 followed by @code{make} and @code{make install}.
1606 The initial @code{perl Makefile.PL} invocation passes flags specified by
1607 the @code{#:make-maker-flags} parameter.
1609 Which Perl package is used can be specified with @code{#:perl}.
1613 Lastly, for packages that do not need anything as sophisticated, a
1614 ``trivial'' build system is provided. It is trivial in the sense that
1615 it provides basically no support: it does not pull any implicit inputs,
1616 and does not have a notion of build phases.
1618 @defvr {Scheme Variable} trivial-build-system
1619 This variable is exported by @code{(guix build-system trivial)}.
1621 This build system requires a @code{#:builder} argument. This argument
1622 must be a Scheme expression that builds the package's output(s)---as
1623 with @code{build-expression->derivation} (@pxref{Derivations,
1624 @code{build-expression->derivation}}).
1633 Conceptually, the @dfn{store} is where derivations that have been
1634 successfully built are stored---by default, under @file{/gnu/store}.
1635 Sub-directories in the store are referred to as @dfn{store paths}. The
1636 store has an associated database that contains information such has the
1637 store paths referred to by each store path, and the list of @emph{valid}
1638 store paths---paths that result from a successful build.
1640 The store is always accessed by the daemon on behalf of its clients
1641 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1642 connect to the daemon over a Unix-domain socket, send it requests, and
1643 read the result---these are remote procedure calls, or RPCs.
1645 The @code{(guix store)} module provides procedures to connect to the
1646 daemon, and to perform RPCs. These are described below.
1648 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1649 Connect to the daemon over the Unix-domain socket at @var{file}. When
1650 @var{reserve-space?} is true, instruct it to reserve a little bit of
1651 extra space on the file system so that the garbage collector can still
1652 operate, should the disk become full. Return a server object.
1654 @var{file} defaults to @var{%default-socket-path}, which is the normal
1655 location given the options that were passed to @command{configure}.
1658 @deffn {Scheme Procedure} close-connection @var{server}
1659 Close the connection to @var{server}.
1662 @defvr {Scheme Variable} current-build-output-port
1663 This variable is bound to a SRFI-39 parameter, which refers to the port
1664 where build and error logs sent by the daemon should be written.
1667 Procedures that make RPCs all take a server object as their first
1670 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1671 Return @code{#t} when @var{path} is a valid store path.
1674 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1675 Add @var{text} under file @var{name} in the store, and return its store
1676 path. @var{references} is the list of store paths referred to by the
1677 resulting store path.
1680 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1681 Build @var{derivations} (a list of @code{<derivation>} objects or
1682 derivation paths), and return when the worker is done building them.
1683 Return @code{#t} on success.
1686 Note that the @code{(guix monads)} module provides a monad as well as
1687 monadic versions of the above procedures, with the goal of making it
1688 more convenient to work with code that accesses the store (@pxref{The
1692 @i{This section is currently incomplete.}
1695 @section Derivations
1698 Low-level build actions and the environment in which they are performed
1699 are represented by @dfn{derivations}. A derivation contain the
1700 following pieces of information:
1704 The outputs of the derivation---derivations produce at least one file or
1705 directory in the store, but may produce more.
1708 The inputs of the derivations, which may be other derivations or plain
1709 files in the store (patches, build scripts, etc.)
1712 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1715 The file name of a build script in the store, along with the arguments
1719 A list of environment variables to be defined.
1723 @cindex derivation path
1724 Derivations allow clients of the daemon to communicate build actions to
1725 the store. They exist in two forms: as an in-memory representation,
1726 both on the client- and daemon-side, and as files in the store whose
1727 name end in @code{.drv}---these files are referred to as @dfn{derivation
1728 paths}. Derivations paths can be passed to the @code{build-derivations}
1729 procedure to perform the build actions they prescribe (@pxref{The
1732 The @code{(guix derivations)} module provides a representation of
1733 derivations as Scheme objects, along with procedures to create and
1734 otherwise manipulate derivations. The lowest-level primitive to create
1735 a derivation is the @code{derivation} procedure:
1737 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
1738 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1739 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
1740 [#:system (%current-system)] [#:references-graphs #f] @
1741 [#:allowed-references #f] [#:local-build? #f]
1742 Build a derivation with the given arguments, and return the resulting
1743 @code{<derivation>} object.
1745 When @var{hash} and @var{hash-algo} are given, a
1746 @dfn{fixed-output derivation} is created---i.e., one whose result is
1747 known in advance, such as a file download. If, in addition,
1748 @var{recursive?} is true, then that fixed output may be an executable
1749 file or a directory and @var{hash} must be the hash of an archive
1750 containing this output.
1752 When @var{references-graphs} is true, it must be a list of file
1753 name/store path pairs. In that case, the reference graph of each store
1754 path is exported in the build environment in the corresponding file, in
1755 a simple text format.
1757 When @var{allowed-references} is true, it must be a list of store items
1758 or outputs that the derivation's output may refer to.
1760 When @var{local-build?} is true, declare that the derivation is not a
1761 good candidate for offloading and should rather be built locally
1762 (@pxref{Daemon Offload Setup}). This is the case for small derivations
1763 where the costs of data transfers would outweigh the benefits.
1767 Here's an example with a shell script as its builder, assuming
1768 @var{store} is an open connection to the daemon, and @var{bash} points
1769 to a Bash executable in the store:
1772 (use-modules (guix utils)
1776 (let ((builder ; add the Bash script to the store
1777 (add-text-to-store store "my-builder.sh"
1778 "echo hello world > $out\n" '())))
1779 (derivation store "foo"
1780 bash `("-e" ,builder)
1781 #:inputs `((,bash) (,builder))
1782 #:env-vars '(("HOME" . "/homeless"))))
1783 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
1786 As can be guessed, this primitive is cumbersome to use directly. A
1787 better approach is to write build scripts in Scheme, of course! The
1788 best course of action for that is to write the build code as a
1789 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
1790 information, @ref{G-Expressions}.
1792 Once upon a time, @code{gexp->derivation} did not exist and constructing
1793 derivations with build code written in Scheme was achieved with
1794 @code{build-expression->derivation}, documented below. This procedure
1795 is now deprecated in favor of the much nicer @code{gexp->derivation}.
1797 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
1798 @var{name} @var{exp} @
1799 [#:system (%current-system)] [#:inputs '()] @
1800 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1801 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
1802 [#:references-graphs #f] [#:allowed-references #f] @
1803 [#:local-build? #f] [#:guile-for-build #f]
1804 Return a derivation that executes Scheme expression @var{exp} as a
1805 builder for derivation @var{name}. @var{inputs} must be a list of
1806 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1807 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1808 modules from the current search path to be copied in the store,
1809 compiled, and made available in the load path during the execution of
1810 @var{exp}---e.g., @code{((guix build utils) (guix build
1811 gnu-build-system))}.
1813 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1814 to a list of output/path pairs, and where @code{%build-inputs} is bound
1815 to a list of string/output-path pairs made from @var{inputs}.
1816 Optionally, @var{env-vars} is a list of string pairs specifying the name
1817 and value of environment variables visible to the builder. The builder
1818 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1819 @var{exp} returns @code{#f}, the build is considered to have failed.
1821 @var{exp} is built using @var{guile-for-build} (a derivation). When
1822 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1823 @code{%guile-for-build} fluid is used instead.
1825 See the @code{derivation} procedure for the meaning of
1826 @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
1830 Here's an example of a single-output derivation that creates a directory
1831 containing one file:
1834 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1835 (mkdir out) ; create /gnu/store/@dots{}-goo
1836 (call-with-output-file (string-append out "/test")
1838 (display '(hello guix) p))))))
1839 (build-expression->derivation store "goo" builder))
1841 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
1845 @node The Store Monad
1846 @section The Store Monad
1850 The procedures that operate on the store described in the previous
1851 sections all take an open connection to the build daemon as their first
1852 argument. Although the underlying model is functional, they either have
1853 side effects or depend on the current state of the store.
1855 The former is inconvenient: the connection to the build daemon has to be
1856 carried around in all those functions, making it impossible to compose
1857 functions that do not take that parameter with functions that do. The
1858 latter can be problematic: since store operations have side effects
1859 and/or depend on external state, they have to be properly sequenced.
1861 @cindex monadic values
1862 @cindex monadic functions
1863 This is where the @code{(guix monads)} module comes in. This module
1864 provides a framework for working with @dfn{monads}, and a particularly
1865 useful monad for our uses, the @dfn{store monad}. Monads are a
1866 construct that allows two things: associating ``context'' with values
1867 (in our case, the context is the store), and building sequences of
1868 computations (here computations includes accesses to the store.) Values
1869 in a monad---values that carry this additional context---are called
1870 @dfn{monadic values}; procedures that return such values are called
1871 @dfn{monadic procedures}.
1873 Consider this ``normal'' procedure:
1876 (define (sh-symlink store)
1877 ;; Return a derivation that symlinks the 'bash' executable.
1878 (let* ((drv (package-derivation store bash))
1879 (out (derivation->output-path drv))
1880 (sh (string-append out "/bin/bash")))
1881 (build-expression->derivation store "sh"
1882 `(symlink ,sh %output))))
1885 Using @code{(guix monads)}, it may be rewritten as a monadic function:
1887 @c FIXME: Find a better example, one that uses 'mlet'.
1889 (define (sh-symlink)
1890 ;; Same, but return a monadic value.
1891 (gexp->derivation "sh"
1892 #~(symlink (string-append #$bash "/bin/bash") #$output)))
1895 There are two things to note in the second version: the @code{store}
1896 parameter is now implicit, and the monadic value returned by
1897 @code{package-file}---a wrapper around @code{package-derivation} and
1898 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
1899 instead of plain @code{let}.
1901 Calling the monadic @code{profile.sh} has no effect. To get the desired
1902 effect, one must use @code{run-with-store}:
1905 (run-with-store (open-connection) (profile.sh))
1906 @result{} /gnu/store/...-profile.sh
1909 The main syntactic forms to deal with monads in general are described
1912 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
1913 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
1917 @deffn {Scheme Syntax} return @var{val}
1918 Return a monadic value that encapsulates @var{val}.
1921 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
1922 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
1923 procedure @var{mproc}@footnote{This operation is commonly referred to as
1924 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
1925 we use this somewhat cryptic symbol inherited from the Haskell
1929 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
1931 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
1933 Bind the variables @var{var} to the monadic values @var{mval} in
1934 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
1935 ``normal'' value @var{val}, as per @code{let}.
1937 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
1938 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
1941 The interface to the store monad provided by @code{(guix monads)} is as
1944 @defvr {Scheme Variable} %store-monad
1945 The store monad. Values in the store monad encapsulate accesses to the
1946 store. When its effect is needed, a value of the store monad must be
1947 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
1951 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
1952 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
1953 open store connection.
1956 @deffn {Monadic Procedure} text-file @var{name} @var{text}
1957 Return as a monadic value the absolute file name in the store of the file
1958 containing @var{text}, a string.
1961 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
1962 Return as a monadic value a derivation that builds a text file
1963 containing all of @var{text}. @var{text} may list, in addition to
1964 strings, packages, derivations, and store file names; the resulting
1965 store file holds references to all these.
1967 This variant should be preferred over @code{text-file} anytime the file
1968 to create will reference items from the store. This is typically the
1969 case when building a configuration file that embeds store file names,
1973 (define (profile.sh)
1974 ;; Return the name of a shell script in the store that
1975 ;; initializes the 'PATH' environment variable.
1976 (text-file* "profile.sh"
1977 "export PATH=" coreutils "/bin:"
1978 grep "/bin:" sed "/bin\n"))
1981 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
1982 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
1983 preventing them from being garbage-collected during its lifetime.
1986 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
1987 [#:system (%current-system)] [#:output "out"] Return as a monadic
1988 value in the absolute file name of @var{file} within the @var{output}
1989 directory of @var{package}. When @var{file} is omitted, return the name
1990 of the @var{output} directory of @var{package}.
1993 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
1994 Monadic version of @code{package-derivation} (@pxref{Defining
2000 @section G-Expressions
2002 @cindex G-expression
2003 @cindex build code quoting
2004 So we have ``derivations'', which represent a sequence of build actions
2005 to be performed to produce an item in the store (@pxref{Derivations}).
2006 Those build actions are performed when asking the daemon to actually
2007 build the derivations; they are run by the daemon in a container
2008 (@pxref{Invoking guix-daemon}).
2010 @cindex strata of code
2011 It should come as no surprise that we like to write those build actions
2012 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2013 code@footnote{The term @dfn{stratum} in this context was coined by
2014 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2015 Kiselyov, who has written insightful
2016 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2017 on this topic}, refers to this kind of code generation as
2018 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2019 to the daemon, etc.---and the ``build code''---code that actually
2020 performs build actions, such as making directories, invoking
2021 @command{make}, etc.
2023 To describe a derivation and its build actions, one typically needs to
2024 embed build code inside host code. It boils down to manipulating build
2025 code as data, and Scheme's homoiconicity---code has a direct
2026 representation as data---comes in handy for that. But we need more than
2027 Scheme's normal @code{quasiquote} mechanism to construct build
2030 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2031 S-expressions adapted to build expressions. G-expressions, or
2032 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2033 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2034 @code{#$}, and @code{#$@@}), which are comparable respectively to
2035 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2036 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2037 Reference Manual}). However, there are major differences:
2041 Gexps are meant to be written to a file and run or manipulated by other
2045 When a package or derivation is unquoted inside a gexp, the result is as
2046 if its output file name had been introduced.
2049 Gexps carry information about the packages or derivations they refer to,
2050 and these dependencies are automatically added as inputs to the build
2051 processes that use them.
2054 To illustrate the idea, here is an example of a gexp:
2061 (symlink (string-append #$coreutils "/bin/ls")
2065 This gexp can be passed to @code{gexp->derivation}; we obtain a
2066 derivation that builds a directory containing exactly one symlink to
2067 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2070 (gexp->derivation "the-thing" build-exp)
2073 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2074 substituted to the reference to the @var{coreutils} package in the
2075 actual build code, and @var{coreutils} is automatically made an input to
2076 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2077 output)}) is replaced by a string containing the derivation's output
2078 directory name. The syntactic form to construct gexps is summarized
2081 @deffn {Scheme Syntax} #~@var{exp}
2082 @deffnx {Scheme Syntax} (gexp @var{exp})
2083 Return a G-expression containing @var{exp}. @var{exp} may contain one
2084 or more of the following forms:
2088 @itemx (ungexp @var{obj})
2089 Introduce a reference to @var{obj}. @var{obj} may be a package or a
2090 derivation, in which case the @code{ungexp} form is replaced by its
2091 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2093 If @var{obj} is a list, it is traversed and any package or derivation
2094 references are substituted similarly.
2096 If @var{obj} is another gexp, its contents are inserted and its
2097 dependencies are added to those of the containing gexp.
2099 If @var{obj} is another kind of object, it is inserted as is.
2101 @item #$@var{package-or-derivation}:@var{output}
2102 @itemx (ungexp @var{package-or-derivation} @var{output})
2103 This is like the form above, but referring explicitly to the
2104 @var{output} of @var{package-or-derivation}---this is useful when
2105 @var{package-or-derivation} produces multiple outputs (@pxref{Packages
2106 with Multiple Outputs}).
2108 @item #$output[:@var{output}]
2109 @itemx (ungexp output [@var{output}])
2110 Insert a reference to derivation output @var{output}, or to the main
2111 output when @var{output} is omitted.
2113 This only makes sense for gexps passed to @code{gexp->derivation}.
2116 @itemx (ungexp-splicing @var{lst})
2117 Like the above, but splices the contents of @var{lst} inside the
2122 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2123 of the @code{gexp?} type (see below.)
2126 @deffn {Scheme Procedure} gexp? @var{obj}
2127 Return @code{#t} if @var{obj} is a G-expression.
2130 G-expressions are meant to be written to disk, either as code building
2131 some derivation, or as plain files in the store. The monadic procedures
2132 below allow you to do that (@pxref{The Store Monad}, for more
2133 information about monads.)
2135 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2136 [#:system (%current-system)] [#:inputs '()] @
2137 [#:hash #f] [#:hash-algo #f] @
2138 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2139 [#:references-graphs #f] [#:local-build? #f] @
2140 [#:guile-for-build #f]
2141 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2142 @var{guile-for-build} (a derivation) on @var{system}.
2144 Make @var{modules} available in the evaluation context of @var{EXP};
2145 @var{MODULES} is a list of names of Guile modules from the current
2146 search path to be copied in the store, compiled, and made available in
2147 the load path during the execution of @var{exp}---e.g., @code{((guix
2148 build utils) (guix build gnu-build-system))}.
2150 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2153 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2154 Return an executable script @var{name} that runs @var{exp} using
2155 @var{guile} with @var{modules} in its search path.
2157 The example below builds a script that simply invokes the @command{ls}
2161 (use-modules (guix gexp) (gnu packages base))
2163 (gexp->script "list-files"
2164 #~(execl (string-append #$coreutils "/bin/ls")
2168 When ``running'' it through the store (@pxref{The Store Monad,
2169 @code{run-with-store}}), we obtain a derivation that produces an
2170 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2173 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2175 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2180 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2181 Return a derivation that builds a file @var{name} containing @var{exp}.
2183 The resulting file holds references to all the dependencies of @var{exp}
2184 or a subset thereof.
2187 Of course, in addition to gexps embedded in ``host'' code, there are
2188 also modules containing build tools. To make it clear that they are
2189 meant to be used in the build stratum, these modules are kept in the
2190 @code{(guix build @dots{})} name space.
2193 @c *********************************************************************
2197 This section describes tools primarily targeted at developers and users
2198 who write new package definitions. They complement the Scheme
2199 programming interface of Guix in a convenient way.
2202 * Invoking guix build:: Building packages from the command line.
2203 * Invoking guix download:: Downloading a file and printing its hash.
2204 * Invoking guix hash:: Computing the cryptographic hash of a file.
2205 * Invoking guix refresh:: Updating package definitions.
2208 @node Invoking guix build
2209 @section Invoking @command{guix build}
2211 The @command{guix build} command builds packages or derivations and
2212 their dependencies, and prints the resulting store paths. Note that it
2213 does not modify the user's profile---this is the job of the
2214 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2215 it is mainly useful for distribution developers.
2217 The general syntax is:
2220 guix build @var{options} @var{package-or-derivation}@dots{}
2223 @var{package-or-derivation} may be either the name of a package found in
2224 the software distribution such as @code{coreutils} or
2225 @code{coreutils-8.20}, or a derivation such as
2226 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2227 package with the corresponding name (and optionally version) is searched
2228 for among the GNU distribution modules (@pxref{Package Modules}).
2230 Alternatively, the @code{--expression} option may be used to specify a
2231 Scheme expression that evaluates to a package; this is useful when
2232 disambiguation among several same-named packages or package variants is
2235 The @var{options} may be zero or more of the following:
2239 @item --expression=@var{expr}
2240 @itemx -e @var{expr}
2241 Build the package or derivation @var{expr} evaluates to.
2243 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2244 guile-1.8)}, which unambiguously designates this specific variant of
2245 version 1.8 of Guile.
2247 Alternately, @var{expr} may be a G-expression, in which case it is used
2248 as a build program passed to @code{gexp->derivation}
2249 (@pxref{G-Expressions}).
2251 Lastly, @var{expr} may refer to a zero-argument monadic procedure
2252 (@pxref{The Store Monad}). The procedure must return a derivation as a
2253 monadic value, which is then passed through @code{run-with-store}.
2257 Build the packages' source derivations, rather than the packages
2260 For instance, @code{guix build -S gcc} returns something like
2261 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2263 The returned source tarball is the result of applying any patches and
2264 code snippets specified in the package's @code{origin} (@pxref{Defining
2267 @item --system=@var{system}
2268 @itemx -s @var{system}
2269 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
2270 the host's system type.
2272 An example use of this is on Linux-based systems, which can emulate
2273 different personalities. For instance, passing
2274 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
2275 to build packages in a complete 32-bit environment.
2277 @item --target=@var{triplet}
2278 @cindex cross-compilation
2279 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
2280 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
2281 configuration triplets,, configure, GNU Configure and Build System}).
2283 @item --with-source=@var{source}
2284 Use @var{source} as the source of the corresponding package.
2285 @var{source} must be a file name or a URL, as for @command{guix
2286 download} (@pxref{Invoking guix download}).
2288 The ``corresponding package'' is taken to be one specified on the
2289 command line whose name matches the base of @var{source}---e.g., if
2290 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
2291 package is @code{guile}. Likewise, the version string is inferred from
2292 @var{source}; in the previous example, it's @code{2.0.10}.
2294 This option allows users to try out versions of packages other than the
2295 one provided by the distribution. The example below downloads
2296 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
2297 the @code{ed} package:
2300 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
2303 As a developer, @code{--with-source} makes it easy to test release
2307 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
2313 Return the derivation paths, not the output paths, of the given
2316 @item --root=@var{file}
2317 @itemx -r @var{file}
2318 Make @var{file} a symlink to the result, and register it as a garbage
2322 Return the build log file names for the given
2323 @var{package-or-derivation}s, or raise an error if build logs are
2326 This works regardless of how packages or derivations are specified. For
2327 instance, the following invocations are equivalent:
2330 guix build --log-file `guix build -d guile`
2331 guix build --log-file `guix build guile`
2332 guix build --log-file guile
2333 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
2339 @cindex common build options
2340 In addition, a number of options that control the build process are
2341 common to @command{guix build} and other commands that can spawn builds,
2342 such as @command{guix package} or @command{guix archive}. These are the
2349 Keep the build tree of failed builds. Thus, if a build fail, its build
2350 tree is kept under @file{/tmp}, in a directory whose name is shown at
2351 the end of the build log. This is useful when debugging build issues.
2355 Do not build the derivations.
2358 When substituting a pre-built binary fails, fall back to building
2361 @item --no-substitutes
2362 Do not use substitutes for build products. That is, always build things
2363 locally instead of allowing downloads of pre-built binaries
2364 (@pxref{Substitutes}).
2366 @item --no-build-hook
2367 Do not attempt to offload builds @i{via} the daemon's ``build hook''
2368 (@pxref{Daemon Offload Setup}). That is, always build things locally
2369 instead of offloading builds to remote machines.
2371 @item --max-silent-time=@var{seconds}
2372 When the build or substitution process remains silent for more than
2373 @var{seconds}, terminate it and report a build failure.
2375 @item --timeout=@var{seconds}
2376 Likewise, when the build or substitution process lasts for more than
2377 @var{seconds}, terminate it and report a build failure.
2379 By default there is no timeout. This behavior can be restored with
2382 @item --verbosity=@var{level}
2383 Use the given verbosity level. @var{level} must be an integer between 0
2384 and 5; higher means more verbose output. Setting a level of 4 or more
2385 may be helpful when debugging setup issues with the build daemon.
2387 @item --cores=@var{n}
2389 Allow the use of up to @var{n} CPU cores for the build. The special
2390 value @code{0} means to use as many CPU cores as available.
2394 Behind the scenes, @command{guix build} is essentially an interface to
2395 the @code{package-derivation} procedure of the @code{(guix packages)}
2396 module, and to the @code{build-derivations} procedure of the @code{(guix
2399 @node Invoking guix download
2400 @section Invoking @command{guix download}
2402 When writing a package definition, developers typically need to download
2403 the package's source tarball, compute its SHA256 hash, and write that
2404 hash in the package definition (@pxref{Defining Packages}). The
2405 @command{guix download} tool helps with this task: it downloads a file
2406 from the given URI, adds it to the store, and prints both its file name
2407 in the store and its SHA256 hash.
2409 The fact that the downloaded file is added to the store saves bandwidth:
2410 when the developer eventually tries to build the newly defined package
2411 with @command{guix build}, the source tarball will not have to be
2412 downloaded again because it is already in the store. It is also a
2413 convenient way to temporarily stash files, which may be deleted
2414 eventually (@pxref{Invoking guix gc}).
2416 The @command{guix download} command supports the same URIs as used in
2417 package definitions. In particular, it supports @code{mirror://} URIs.
2418 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
2419 Guile bindings for GnuTLS are available in the user's environment; when
2420 they are not available, an error is raised.
2422 The following option is available:
2425 @item --format=@var{fmt}
2427 Write the hash in the format specified by @var{fmt}. For more
2428 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
2431 @node Invoking guix hash
2432 @section Invoking @command{guix hash}
2434 The @command{guix hash} command computes the SHA256 hash of a file.
2435 It is primarily a convenience tool for anyone contributing to the
2436 distribution: it computes the cryptographic hash of a file, which can be
2437 used in the definition of a package (@pxref{Defining Packages}).
2439 The general syntax is:
2442 guix hash @var{option} @var{file}
2445 @command{guix hash} has the following option:
2449 @item --format=@var{fmt}
2451 Write the hash in the format specified by @var{fmt}.
2453 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
2454 (@code{hex} and @code{hexadecimal} can be used as well).
2456 If the @option{--format} option is not specified, @command{guix hash}
2457 will output the hash in @code{nix-base32}. This representation is used
2458 in the definitions of packages.
2462 Compute the hash on @var{file} recursively.
2464 In this case, the hash is computed on an archive containing @var{file},
2465 including its children if it is a directory. Some of @var{file}'s
2466 meta-data is part of the archive; for instance, when @var{file} is a
2467 regular file, the hash is different depending on whether @var{file} is
2468 executable or not. Meta-data such as time stamps has no impact on the
2469 hash (@pxref{Invoking guix archive}).
2470 @c FIXME: Replace xref above with xref to an ``Archive'' section when
2475 @node Invoking guix refresh
2476 @section Invoking @command{guix refresh}
2478 The primary audience of the @command{guix refresh} command is developers
2479 of the GNU software distribution. By default, it reports any packages
2480 provided by the distribution that are outdated compared to the latest
2481 upstream version, like this:
2485 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
2486 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
2489 It does so by browsing each package's FTP directory and determining the
2490 highest version number of the source tarballs
2491 therein@footnote{Currently, this only works for GNU packages.}.
2493 When passed @code{--update}, it modifies distribution source files to
2494 update the version numbers and source tarball hashes of those packages'
2495 recipes (@pxref{Defining Packages}). This is achieved by downloading
2496 each package's latest source tarball and its associated OpenPGP
2497 signature, authenticating the downloaded tarball against its signature
2498 using @command{gpg}, and finally computing its hash. When the public
2499 key used to sign the tarball is missing from the user's keyring, an
2500 attempt is made to automatically retrieve it from a public key server;
2501 when it's successful, the key is added to the user's keyring; otherwise,
2502 @command{guix refresh} reports an error.
2504 The following options are supported:
2510 Update distribution source files (package recipes) in place.
2511 @ref{Defining Packages}, for more information on package definitions.
2513 @item --select=[@var{subset}]
2514 @itemx -s @var{subset}
2515 Select all the packages in @var{subset}, one of @code{core} or
2518 The @code{core} subset refers to all the packages at the core of the
2519 distribution---i.e., packages that are used to build ``everything
2520 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
2521 changing one of these packages in the distribution entails a rebuild of
2522 all the others. Thus, such updates are an inconvenience to users in
2523 terms of build time or bandwidth used to achieve the upgrade.
2525 The @code{non-core} subset refers to the remaining packages. It is
2526 typically useful in cases where an update of the core packages would be
2531 In addition, @command{guix refresh} can be passed one or more package
2532 names, as in this example:
2535 guix refresh -u emacs idutils
2539 The command above specifically updates the @code{emacs} and
2540 @code{idutils} packages. The @code{--select} option would have no
2541 effect in this case.
2543 The following options can be used to customize GnuPG operation:
2547 @item --key-server=@var{host}
2548 Use @var{host} as the OpenPGP key server when importing a public key.
2550 @item --gpg=@var{command}
2551 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
2552 for in @code{$PATH}.
2557 @c *********************************************************************
2558 @node GNU Distribution
2559 @chapter GNU Distribution
2561 Guix comes with a distribution of free software@footnote{The term
2562 ``free'' here refers to the
2563 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
2564 users of that software}.} that forms the basis of the GNU system. This
2565 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
2566 as many GNU and non-GNU applications. The complete list of available
2567 packages can be browsed
2568 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
2569 running @command{guix package} (@pxref{Invoking guix package}):
2572 guix package --list-available
2575 Our goal is to build a practical 100% free software distribution of
2576 Linux-based and other variants of GNU, with a focus on the promotion and
2577 tight integration of GNU components, and an emphasis on programs and
2578 tools that help users exert that freedom.
2580 The GNU distribution is currently available on the following platforms:
2585 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
2588 Intel 32-bit architecture (IA32), Linux-Libre kernel;
2590 @item mips64el-linux
2591 little-endian 64-bit MIPS processors, specifically the Loongson series,
2592 n32 application binary interface (ABI), and Linux-Libre kernel.
2597 For information on porting to other architectures or kernels,
2601 * Installing Debugging Files:: Feeding the debugger.
2602 * Package Modules:: Packages from the programmer's viewpoint.
2603 * Packaging Guidelines:: Growing the distribution.
2604 * Bootstrapping:: GNU/Linux built from scratch.
2605 * Porting:: Targeting another platform or kernel.
2606 * System Configuration:: Configuring a GNU system.
2609 Building this distribution is a cooperative effort, and you are invited
2610 to join! @ref{Contributing}, for information about how you can help.
2613 @node Installing Debugging Files
2614 @section Installing Debugging Files
2616 @cindex debugging files
2617 Program binaries, as produced by the GCC compilers for instance, are
2618 typically written in the ELF format, with a section containing
2619 @dfn{debugging information}. Debugging information is what allows the
2620 debugger, GDB, to map binary code to source code; it is required to
2621 debug a compiled program in good conditions.
2623 The problem with debugging information is that is takes up a fair amount
2624 of disk space. For example, debugging information for the GNU C Library
2625 weighs in at more than 60 MiB. Thus, as a user, keeping all the
2626 debugging info of all the installed programs is usually not an option.
2627 Yet, space savings should not come at the cost of an impediment to
2628 debugging---especially in the GNU system, which should make it easier
2629 for users to exert their computing freedom (@pxref{GNU Distribution}).
2631 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
2632 mechanism that allows users to get the best of both worlds: debugging
2633 information can be stripped from the binaries and stored in separate
2634 files. GDB is then able to load debugging information from those files,
2635 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
2638 The GNU distribution takes advantage of this by storing debugging
2639 information in the @code{lib/debug} sub-directory of a separate package
2640 output unimaginatively called @code{debug} (@pxref{Packages with
2641 Multiple Outputs}). Users can choose to install the @code{debug} output
2642 of a package when they need it. For instance, the following command
2643 installs the debugging information for the GNU C Library and for GNU
2647 guix package -i glibc:debug guile:debug
2650 GDB must then be told to look for debug files in the user's profile, by
2651 setting the @code{debug-file-directory} variable (consider setting it
2652 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
2656 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
2659 From there on, GDB will pick up debugging information from the
2660 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
2662 In addition, you will most likely want GDB to be able to show the source
2663 code being debugged. To do that, you will have to unpack the source
2664 code of the package of interest (obtained with @code{guix build
2665 --source}, @pxref{Invoking guix build}), and to point GDB to that source
2666 directory using the @code{directory} command (@pxref{Source Path,
2667 @code{directory},, gdb, Debugging with GDB}).
2669 @c XXX: keep me up-to-date
2670 The @code{debug} output mechanism in Guix is implemented by the
2671 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
2672 opt-in---debugging information is available only for those packages
2673 whose definition explicitly declares a @code{debug} output. This may be
2674 changed to opt-out in the future, if our build farm servers can handle
2675 the load. To check whether a package has a @code{debug} output, use
2676 @command{guix package --list-available} (@pxref{Invoking guix package}).
2679 @node Package Modules
2680 @section Package Modules
2682 From a programming viewpoint, the package definitions of the
2683 GNU distribution are provided by Guile modules in the @code{(gnu packages
2684 @dots{})} name space@footnote{Note that packages under the @code{(gnu
2685 packages @dots{})} module name space are not necessarily ``GNU
2686 packages''. This module naming scheme follows the usual Guile module
2687 naming convention: @code{gnu} means that these modules are distributed
2688 as part of the GNU system, and @code{packages} identifies modules that
2689 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
2690 Reference Manual}). For instance, the @code{(gnu packages emacs)}
2691 module exports a variable named @code{emacs}, which is bound to a
2692 @code{<package>} object (@pxref{Defining Packages}).
2694 The @code{(gnu packages @dots{})} module name space is special: it is
2695 automatically scanned for packages by the command-line tools. For
2696 instance, when running @code{guix package -i emacs}, all the @code{(gnu
2697 packages @dots{})} modules are scanned until one that exports a package
2698 object whose name is @code{emacs} is found. This package search
2699 facility is implemented in the @code{(gnu packages)} module.
2701 Users can store package definitions in modules with different
2702 names---e.g., @code{(my-packages emacs)}. In that case, commands such
2703 as @command{guix package} and @command{guix build} have to be used with
2704 the @code{-e} option so that they know where to find the package.
2706 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
2707 each package is built based solely on other packages in the
2708 distribution. The root of this dependency graph is a small set of
2709 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
2710 bootstrap)} module. For more information on bootstrapping,
2711 @ref{Bootstrapping}.
2713 @node Packaging Guidelines
2714 @section Packaging Guidelines
2716 The GNU distribution is nascent and may well lack some of your favorite
2717 packages. This section describes how you can help make the distribution
2718 grow. @xref{Contributing}, for additional information on how you can
2721 Free software packages are usually distributed in the form of
2722 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
2723 all the source files. Adding a package to the distribution means
2724 essentially two things: adding a @dfn{recipe} that describes how to
2725 build the package, including a list of other packages required to build
2726 it, and adding @dfn{package meta-data} along with that recipe, such as a
2727 description and licensing information.
2729 In Guix all this information is embodied in @dfn{package definitions}.
2730 Package definitions provide a high-level view of the package. They are
2731 written using the syntax of the Scheme programming language; in fact,
2732 for each package we define a variable bound to the package definition,
2733 and export that variable from a module (@pxref{Package Modules}).
2734 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
2735 creating packages. For more information on package definitions,
2736 @ref{Defining Packages}.
2738 Once a package definition is in place, stored in a file in the Guix
2739 source tree, it can be tested using the @command{guix build} command
2740 (@pxref{Invoking guix build}). For example, assuming the new package is
2741 called @code{gnew}, you may run this command from the Guix build tree:
2744 ./pre-inst-env guix build gnew --keep-failed
2747 Using @code{--keep-failed} makes it easier to debug build failures since
2748 it provides access to the failed build tree. Another useful
2749 command-line option when debugging is @code{--log-file}, to access the
2752 If the package is unknown to the @command{guix} command, it may be that
2753 the source file contains a syntax error, or lacks a @code{define-public}
2754 clause to export the package variable. To figure it out, you may load
2755 the module from Guile to get more information about the actual error:
2758 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
2761 Once your package builds correctly, please send us a patch
2762 (@pxref{Contributing}). Well, if you need help, we will be happy to
2763 help you too. Once the patch is committed in the Guix repository, the
2764 new package automatically gets built on the supported platforms by
2765 @url{http://hydra.gnu.org/gnu/master, our continuous integration
2769 Users can obtain the new package definition simply by running
2770 @command{guix pull} (@pxref{Invoking guix pull}). When
2771 @code{hydra.gnu.org} is done building the package, installing the
2772 package automatically downloads binaries from there
2773 (@pxref{Substitutes}). The only place where human intervention is
2774 needed is to review and apply the patch.
2778 * Software Freedom:: What may go into the distribution.
2779 * Package Naming:: What's in a name?
2780 * Version Numbers:: When the name is not enough.
2781 * Python Modules:: Taming the snake.
2782 * Perl Modules:: Little pearls.
2785 @node Software Freedom
2786 @subsection Software Freedom
2788 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
2790 The GNU operating system has been developed so that users can have
2791 freedom in their computing. GNU is @dfn{free software}, meaning that
2792 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
2793 essential freedoms}: to run the program, to study and change the program
2794 in source code form, to redistribute exact copies, and to distribute
2795 modified versions. Packages found in the GNU distribution provide only
2796 software that conveys these four freedoms.
2798 In addition, the GNU distribution follow the
2799 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
2800 software distribution guidelines}. Among other things, these guidelines
2801 reject non-free firmware, recommendations of non-free software, and
2802 discuss ways to deal with trademarks and patents.
2804 Some packages contain a small and optional subset that violates the
2805 above guidelines, for instance because this subset is itself non-free
2806 code. When that happens, the offending items are removed with
2807 appropriate patches or code snippets in the package definition's
2808 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
2809 build --source} returns the ``freed'' source rather than the unmodified
2813 @node Package Naming
2814 @subsection Package Naming
2816 A package has actually two names associated with it:
2817 First, there is the name of the @emph{Scheme variable}, the one following
2818 @code{define-public}. By this name, the package can be made known in the
2819 Scheme code, for instance as input to another package. Second, there is
2820 the string in the @code{name} field of a package definition. This name
2821 is used by package management commands such as
2822 @command{guix package} and @command{guix build}.
2824 Both are usually the same and correspond to the lowercase conversion of
2825 the project name chosen upstream, with underscores replaced with
2826 hyphens. For instance, GNUnet is available as @code{gnunet}, and
2827 SDL_net as @code{sdl-net}.
2829 We do not add @code{lib} prefixes for library packages, unless these are
2830 already part of the official project name. But see @pxref{Python
2831 Modules} and @ref{Perl Modules} for special rules concerning modules for
2832 the Python and Perl languages.
2835 @node Version Numbers
2836 @subsection Version Numbers
2838 We usually package only the latest version of a given free software
2839 project. But sometimes, for instance for incompatible library versions,
2840 two (or more) versions of the same package are needed. These require
2841 different Scheme variable names. We use the name as defined
2842 in @ref{Package Naming}
2843 for the most recent version; previous versions use the same name, suffixed
2844 by @code{-} and the smallest prefix of the version number that may
2845 distinguish the two versions.
2847 The name inside the package definition is the same for all versions of a
2848 package and does not contain any version number.
2850 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
2858 (define-public gtk+-2
2864 If we also wanted GTK+ 3.8.2, this would be packaged as
2866 (define-public gtk+-3.8
2874 @node Python Modules
2875 @subsection Python Modules
2877 We currently package Python 2 and Python 3, under the Scheme variable names
2878 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
2879 To avoid confusion and naming clashes with other programming languages, it
2880 seems desirable that the name of a package for a Python module contains
2881 the word @code{python}.
2883 Some modules are compatible with only one version of Python, others with both.
2884 If the package Foo compiles only with Python 3, we name it
2885 @code{python-foo}; if it compiles only with Python 2, we name it
2886 @code{python2-foo}. If it is compatible with both versions, we create two
2887 packages with the corresponding names.
2889 If a project already contains the word @code{python}, we drop this;
2890 for instance, the module python-dateutil is packaged under the names
2891 @code{python-dateutil} and @code{python2-dateutil}.
2895 @subsection Perl Modules
2897 Perl programs standing for themselves are named as any other package,
2898 using the lowercase upstream name.
2899 For Perl packages containing a single class, we use the lowercase class name,
2900 replace all occurrences of @code{::} by dashes and prepend the prefix
2902 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
2903 Modules containing several classes keep their lowercase upstream name and
2904 are also prepended by @code{perl-}. Such modules tend to have the word
2905 @code{perl} somewhere in their name, which gets dropped in favor of the
2906 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
2911 @section Bootstrapping
2913 @c Adapted from the ELS 2013 paper.
2915 @cindex bootstrapping
2917 Bootstrapping in our context refers to how the distribution gets built
2918 ``from nothing''. Remember that the build environment of a derivation
2919 contains nothing but its declared inputs (@pxref{Introduction}). So
2920 there's an obvious chicken-and-egg problem: how does the first package
2921 get built? How does the first compiler get compiled? Note that this is
2922 a question of interest only to the curious hacker, not to the regular
2923 user, so you can shamelessly skip this section if you consider yourself
2926 @cindex bootstrap binaries
2927 The GNU system is primarily made of C code, with libc at its core. The
2928 GNU build system itself assumes the availability of a Bourne shell and
2929 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
2930 `grep'. Furthermore, build programs---programs that run
2931 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
2932 (@pxref{Derivations}). Consequently, to be able to build anything at
2933 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
2934 Binutils, libc, and the other packages mentioned above---the
2935 @dfn{bootstrap binaries}.
2937 These bootstrap binaries are ``taken for granted'', though we can also
2938 re-create them if needed (more on that later).
2940 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
2942 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
2943 @c large image, it's hard to scroll. Oh well.
2944 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
2946 The figure above shows the very beginning of the dependency graph of the
2947 distribution, corresponding to the package definitions of the @code{(gnu
2948 packages bootstrap)} module. At this level of detail, things are
2949 slightly complex. First, Guile itself consists of an ELF executable,
2950 along with many source and compiled Scheme files that are dynamically
2951 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
2952 tarball shown in this graph. This tarball is part of Guix's ``source''
2953 distribution, and gets inserted into the store with @code{add-to-store}
2954 (@pxref{The Store}).
2956 But how do we write a derivation that unpacks this tarball and adds it
2957 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
2958 derivation---the first one that gets built---uses @code{bash} as its
2959 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
2960 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
2961 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
2962 the Guix source distribution, whose sole purpose is to allow the Guile
2963 tarball to be unpacked.
2965 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
2966 Guile that can be used to run subsequent build programs. Its first task
2967 is to download tarballs containing the other pre-built binaries---this
2968 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
2969 @code{ftp-client.scm} are used for this purpose. The
2970 @code{module-import.drv} derivations import those modules in a directory
2971 in the store, using the original layout. The
2972 @code{module-import-compiled.drv} derivations compile those modules, and
2973 write them in an output directory with the right layout. This
2974 corresponds to the @code{#:modules} argument of
2975 @code{build-expression->derivation} (@pxref{Derivations}).
2977 Finally, the various tarballs are unpacked by the
2978 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
2979 etc., at which point we have a working C tool chain.
2982 @unnumberedsubsec Building the Build Tools
2984 @c TODO: Add a package-level dependency graph generated from (gnu
2987 Bootstrapping is complete when we have a full tool chain that does not
2988 depend on the pre-built bootstrap tools discussed above. This
2989 no-dependency requirement is verified by checking whether the files of
2990 the final tool chain contain references to the @file{/gnu/store}
2991 directories of the bootstrap inputs. The process that leads to this
2992 ``final'' tool chain is described by the package definitions found in
2993 the @code{(gnu packages base)} module.
2995 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
2996 The first tool that gets built with the bootstrap binaries is
2997 GNU Make, which is a prerequisite for all the following packages.
2998 From there Findutils and Diffutils get built.
3000 Then come the first-stage Binutils and GCC, built as pseudo cross
3001 tools---i.e., with @code{--target} equal to @code{--host}. They are
3002 used to build libc. Thanks to this cross-build trick, this libc is
3003 guaranteed not to hold any reference to the initial tool chain.
3005 From there the final Binutils and GCC are built. GCC uses @code{ld}
3006 from the final Binutils, and links programs against the just-built libc.
3007 This tool chain is used to build the other packages used by Guix and by
3008 the GNU Build System: Guile, Bash, Coreutils, etc.
3010 And voilà! At this point we have the complete set of build tools that
3011 the GNU Build System expects. These are in the @code{%final-inputs}
3012 variables of the @code{(gnu packages base)} module, and are implicitly
3013 used by any package that uses @code{gnu-build-system} (@pxref{Defining
3017 @unnumberedsubsec Building the Bootstrap Binaries
3019 Because the final tool chain does not depend on the bootstrap binaries,
3020 those rarely need to be updated. Nevertheless, it is useful to have an
3021 automated way to produce them, should an update occur, and this is what
3022 the @code{(gnu packages make-bootstrap)} module provides.
3024 The following command builds the tarballs containing the bootstrap
3025 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
3026 of Coreutils and other basic command-line tools):
3029 guix build bootstrap-tarballs
3032 The generated tarballs are those that should be referred to in the
3033 @code{(gnu packages bootstrap)} module mentioned at the beginning of
3036 Still here? Then perhaps by now you've started to wonder: when do we
3037 reach a fixed point? That is an interesting question! The answer is
3038 unknown, but if you would like to investigate further (and have
3039 significant computational and storage resources to do so), then let us
3043 @section Porting to a New Platform
3045 As discussed above, the GNU distribution is self-contained, and
3046 self-containment is achieved by relying on pre-built ``bootstrap
3047 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
3048 operating system kernel, CPU architecture, and application binary
3049 interface (ABI). Thus, to port the distribution to a platform that is
3050 not yet supported, one must build those bootstrap binaries, and update
3051 the @code{(gnu packages bootstrap)} module to use them on that platform.
3053 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
3054 When everything goes well, and assuming the GNU tool chain supports the
3055 target platform, this can be as simple as running a command like this
3059 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
3062 Once these are built, the @code{(gnu packages bootstrap)} module needs
3063 to be updated to refer to these binaries on the target platform. In
3064 addition, the @code{glibc-dynamic-linker} procedure in that module must
3065 be augmented to return the right file name for libc's dynamic linker on
3066 that platform; likewise, @code{system->linux-architecture} in @code{(gnu
3067 packages linux)} must be taught about the new platform.
3069 In practice, there may be some complications. First, it may be that the
3070 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
3071 above) is not recognized by all the GNU tools. Typically, glibc
3072 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
3073 configure flag (see @code{gcc.scm} for examples of how to handle this).
3074 Second, some of the required packages could fail to build for that
3075 platform. Lastly, the generated binaries could be broken for some
3079 @node System Configuration
3080 @section System Configuration
3082 @emph{This section documents work-in-progress. As such it may be
3083 incomplete, outdated, or open to discussions. Please discuss it on
3084 @email{guix-devel@@gnu.org}.}
3086 @cindex system configuration
3087 The GNU system supports a consistent whole-system configuration
3088 mechanism. By that we mean that all aspects of the global system
3089 configuration---such as the available system services, timezone and
3090 locale settings, user accounts---are declared in a single place. Such
3091 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
3093 One of the advantages of putting all the system configuration under the
3094 control of Guix is that it supports transactional system upgrades, and
3095 makes it possible to roll-back to a previous system instantiation,
3096 should something go wrong with the new one (@pxref{Features}). Another
3097 one is that it makes it easy to replicate the exact same configuration
3098 across different machines, or at different points in time, without
3099 having to resort to additional administration tools layered on top of
3100 the system's own tools.
3101 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
3103 This section describes this mechanism. First we focus on the system
3104 administrator's viewpoint---explaining how the system is configured and
3105 instantiated. Then we show how this mechanism can be extended, for
3106 instance to support new system services.
3109 * Using the Configuration System:: Customizing your GNU system.
3110 * File Systems:: Configuring file system mounts.
3111 * User Accounts:: Specifying user accounts.
3112 * Services:: Specifying system services.
3113 * Invoking guix system:: Instantiating a system configuration.
3114 * Defining Services:: Adding new service definitions.
3117 @node Using the Configuration System
3118 @subsection Using the Configuration System
3120 The operating system is configured by providing an
3121 @code{operating-system} declaration in a file that can then be passed to
3122 the @command{guix system} command (@pxref{Invoking guix system}). A
3123 simple setup, with the default system services, the default Linux-Libre
3124 kernel, initial RAM disk, and boot loader looks like this:
3126 @findex operating-system
3128 (use-modules (gnu) ; for 'user-account', '%base-services', etc.
3129 (gnu packages emacs) ; for 'emacs'
3130 (gnu services ssh)) ; for 'lsh-service'
3133 (host-name "komputilo")
3134 (timezone "Europe/Paris")
3135 (locale "fr_FR.UTF-8")
3136 (bootloader (grub-configuration
3137 (device "/dev/sda")))
3138 (file-systems (list (file-system
3139 (device "/dev/sda1") ; or partition label
3142 (users (list (user-account
3145 (uid 1000) (gid 100)
3146 (comment "Bob's sister")
3147 (home-directory "/home/alice"))))
3148 (packages (cons emacs %base-packages))
3149 (services (cons (lsh-service #:port 2222 #:allow-root-login? #t)
3153 This example should be self-describing. Some of the fields defined
3154 above, such as @code{host-name} and @code{bootloader}, are mandatory.
3155 Others, such as @code{packages} and @code{services}, can be omitted, in
3156 which case they get a default value.
3158 @vindex %base-packages
3159 The @code{packages} field lists
3160 packages that will be globally visible on the system, for all user
3161 accounts---i.e., in every user's @code{PATH} environment variable---in
3162 addition to the per-user profiles (@pxref{Invoking guix package}). The
3163 @var{%base-packages} variable provides all the tools one would expect
3164 for basic user and administrator tasks---including the GNU Core
3165 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
3166 editor, @command{find}, @command{grep}, etc. The example above adds
3167 Emacs to those, taken from the @code{(gnu packages emacs)} module
3168 (@pxref{Package Modules}).
3170 @vindex %base-services
3171 The @code{services} field lists @dfn{system services} to be made
3172 available when the system starts. The @var{%base-services} list,
3173 from the @code{(gnu services base)} module, provides the basic services one
3174 would expect from a GNU system: a login service (mingetty) on each tty,
3175 syslogd, libc's name service cache daemon (nscd), etc.
3177 The @code{operating-system} declaration above specifies that, in
3178 addition to those services, we want the @command{lshd} secure shell
3179 daemon listening on port 2222, and allowing remote @code{root} logins
3180 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
3181 @code{lsh-service} arranges so that @code{lshd} is started with the
3182 right command-line options, possibly with supporting configuration files
3183 generated as needed (@pxref{Defining Services}).
3185 Assuming the above snippet is stored in the @file{my-system-config.scm}
3186 file, the @command{guix system reconfigure my-system-config.scm} command
3187 instantiates that configuration, and makes it the default GRUB boot
3188 entry (@pxref{Invoking guix system}). The normal way to change the
3189 system's configuration is by updating this file and re-running the
3190 @command{guix system} command.
3192 At the Scheme level, the bulk of an @code{operating-system} declaration
3193 is instantiated with the following monadic procedure (@pxref{The Store
3196 @deffn {Monadic Procedure} operating-system-derivation os
3197 Return a derivation that builds @var{os}, an @code{operating-system}
3198 object (@pxref{Derivations}).
3200 The output of the derivation is a single directory that refers to all
3201 the packages, configuration files, and other supporting files needed to
3202 instantiate @var{os}.
3206 @subsection File Systems
3208 The list of file systems to be mounted is specified in the
3209 @code{file-systems} field of the operating system's declaration
3210 (@pxref{Using the Configuration System}). Each file system is declared
3211 using the @code{file-system} form, like this:
3215 (mount-point "/home")
3216 (device "/dev/sda3")
3220 As usual, some of the fields are mandatory---those shown in the example
3221 above---while others can be omitted. These are described below.
3223 @deftp {Data Type} file-system
3224 Objects of these types represent file systems to be mounted. They
3225 contain the following members:
3229 This is a string specifying the type of the file system---e.g.,
3232 @item @code{mount-point}
3233 This designates the place where the file system is to be mounted.
3236 This names the ``source'' of the file system. By default it is the name
3237 of a node under @file{/dev}, but its meaning depends on the @code{title}
3238 field described below.
3240 @item @code{title} (default: @code{'device})
3241 This is a symbol that specifies how the @code{device} field is to be
3244 When it is the symbol @code{device}, then the @code{device} field is
3245 interpreted as a file name; when it is @code{label}, then @code{device}
3246 is interpreted as a partition label name; when it is @code{uuid},
3247 @code{device} is interpreted as a partition unique identifier (UUID).
3249 The @code{label} and @code{uuid} options offer a way to refer to disk
3250 partitions without having to hard-code their actual device name.
3252 @item @code{flags} (default: @code{'()})
3253 This is a list of symbols denoting mount flags. Recognized flags
3254 include @code{read-only} and @code{bind-mount}.
3256 @item @code{options} (default: @code{#f})
3257 This is either @code{#f}, or a string denoting mount options.
3259 @item @code{needed-for-boot?} (default: @code{#f})
3260 This Boolean value indicates whether the file system is needed when
3261 booting. If that is true, then the file system is mounted when the
3262 initial RAM disk (initrd) is loaded. This is always the case, for
3263 instance, for the root file system.
3265 @item @code{check?} (default: @code{#t})
3266 This Boolean indicates whether the file system needs to be checked for
3267 errors before being mounted.
3273 @subsection User Accounts
3278 @subsection Services
3282 @node Invoking guix system
3283 @subsection Invoking @code{guix system}
3285 Once you have written an operating system declaration, as seen in the
3286 previous section, it can be @dfn{instantiated} using the @command{guix
3287 system} command. The synopsis is:
3290 guix system @var{options}@dots{} @var{action} @var{file}
3293 @var{file} must be the name of a file containing an
3294 @code{operating-system} declaration. @var{action} specifies how the
3295 operating system is instantiate. Currently the following values are
3300 Build the operating system described in @var{file}, activate it, and
3301 switch to it@footnote{This action is usable only on systems already
3304 This effects all the configuration specified in @var{file}: user
3305 accounts, system services, global package list, setuid programs, etc.
3307 It also adds a GRUB menu entry for the new OS configuration, and moves
3308 entries for older configurations to a submenu---unless
3309 @option{--no-grub} is passed.
3312 Build the operating system's derivation, which includes all the
3313 configuration files and programs needed to boot and run the system.
3314 This action does not actually install anything.
3317 Populate the given directory with all the files necessary to run the
3318 operating system specified in @var{file}. This is useful for first-time
3319 installations of the GNU system. For instance:
3322 guix system init my-os-config.scm /mnt
3325 copies to @file{/mnt} all the store items required by the configuration
3326 specified in @file{my-os-config.scm}. This includes configuration
3327 files, packages, and so on. It also creates other essential files
3328 needed for the system to operate correctly---e.g., the @file{/etc},
3329 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
3331 This command also installs GRUB on the device specified in
3332 @file{my-os-config}, unless the @option{--no-grub} option was passed.
3335 @cindex virtual machine
3336 Build a virtual machine that contain the operating system declared in
3337 @var{file}, and return a script to run that virtual machine (VM).
3339 The VM shares its store with the host system.
3343 Return a virtual machine or disk image of the operating system declared
3344 in @var{file} that stands alone. Use the @option{--image-size} option
3345 to specify the size of the image.
3347 When using @code{vm-image}, the returned image is in qcow2 format, which
3348 the QEMU emulator can efficiently use.
3350 When using @code{disk-image}, a raw disk image is produced; it can be
3351 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
3352 the device corresponding to a USB stick, one can copy the image on it
3353 using the following command:
3356 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
3361 @var{options} can contain any of the common build options provided by
3362 @command{guix build} (@pxref{Invoking guix build}).
3364 Note that all the actions above, except @code{build} and @code{init},
3365 rely on KVM support in the Linux-Libre kernel. Specifically, the
3366 machine should have hardware virtualization support, the corresponding
3367 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
3368 must exist and be readable and writable by the user and by the daemon's
3371 @node Defining Services
3372 @subsection Defining Services
3374 The @code{(gnu services @dots{})} modules define several procedures that allow
3375 users to declare the operating system's services (@pxref{Using the
3376 Configuration System}). These procedures are @emph{monadic
3377 procedures}---i.e., procedures that return a monadic value in the store
3378 monad (@pxref{The Store Monad}). Examples of such procedures include:
3381 @item mingetty-service
3382 return the definition of a service that runs @command{mingetty} to
3383 offer a login service on the given console tty;
3386 return a definition for libc's name service cache daemon (nscd);
3389 return a definition for a service that runs @command{guix-daemon}
3390 (@pxref{Invoking guix-daemon}).
3393 @cindex service definition
3394 The monadic value returned by those procedures is a @dfn{service
3395 definition}---a structure as returned by the @code{service} form.
3396 Service definitions specifies the inputs the service depends on, and an
3397 expression to start and stop the service. Behind the scenes, service
3398 definitions are ``translated'' into the form suitable for the
3399 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
3402 As an example, here is what the @code{nscd-service} procedure looks
3406 (define (nscd-service)
3407 (with-monad %store-monad
3409 (documentation "Run libc's name service cache daemon.")
3412 (use-modules (guix build utils))
3413 (mkdir-p "/var/run/nscd")))
3414 (start #~(make-forkexec-constructor
3415 (string-append #$glibc "/sbin/nscd")
3416 "-f" "/dev/null" "--foreground"))
3417 (stop #~(make-kill-destructor))
3422 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
3423 (@pxref{G-Expressions}). The @code{activate} field contains a script to
3424 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
3425 directory exists before @command{nscd} is started.
3427 The @code{start} and @code{stop} fields refer to dmd's facilities to
3428 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
3429 GNU dmd Manual}). The @code{provision} field specifies the name under
3430 which this service is known to dmd, and @code{documentation} specifies
3431 on-line documentation. Thus, the commands @command{deco start ncsd},
3432 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
3433 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
3436 @c *********************************************************************
3438 @chapter Contributing
3440 This project is a cooperative effort, and we need your help to make it
3441 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
3442 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
3443 reports, patches, and anything that may be helpful to the project. We
3444 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
3447 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
3448 @file{HACKING} file} that comes with the Guix source code for practical
3449 details about contributions.
3452 @c *********************************************************************
3453 @node Acknowledgments
3454 @chapter Acknowledgments
3456 Guix is based on the Nix package manager, which was designed and
3457 implemented by Eelco Dolstra. Nix pioneered functional package
3458 management, and promoted unprecedented features, such as transactional
3459 package upgrades and rollbacks, per-user profiles, and referentially
3460 transparent build processes. Without this work, Guix would not exist.
3462 The Nix-based software distributions, Nixpkgs and NixOS, have also been
3463 an inspiration for Guix.
3465 @c *********************************************************************
3466 @node GNU Free Documentation License
3467 @appendix GNU Free Documentation License
3469 @include fdl-1.3.texi
3471 @c *********************************************************************
3473 @unnumbered Concept Index
3476 @node Function Index
3477 @unnumbered Function Index
3483 @c ispell-local-dictionary: "american";