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