6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
14 Copyright @copyright{} 2013, 2014 Andreas Enge@*
15 Copyright @copyright{} 2013 Nikita Karetnikov
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
21 copy of the license is included in the section entitled ``GNU Free
22 Documentation License''.
25 @dircategory Package management
27 * guix: (guix). Guix, the functional package manager.
28 * guix package: (guix)Invoking guix package
29 Managing packages with Guix.
30 * guix build: (guix)Invoking guix build
31 Building packages with Guix.
32 * guix system: (guix)Invoking guix system
33 Managing the operating system configuration.
36 @dircategory Software development
38 * guix environment: (guix)Invoking guix environment
39 Building development environments with Guix.
43 @title GNU Guix Reference Manual
44 @subtitle Using the GNU Guix Functional Package Manager
45 @author Ludovic Courtès
47 @author Nikita Karetnikov
50 @vskip 0pt plus 1filll
51 Edition @value{EDITION} @*
59 @c *********************************************************************
63 This document describes GNU Guix version @value{VERSION}, a functional
64 package management tool written for the GNU system.
67 * Introduction:: What is Guix about?
68 * Installation:: Installing Guix.
69 * Package Management:: Package installation, upgrade, etc.
70 * Programming Interface:: Using Guix in Scheme.
71 * Utilities:: Package management commands.
72 * GNU Distribution:: Software for your friendly GNU system.
73 * Contributing:: Your help needed!
75 * Acknowledgments:: Thanks!
76 * GNU Free Documentation License:: The license of this manual.
77 * Concept Index:: Concepts.
78 * Programming Index:: Data types, functions, and variables.
81 --- The Detailed Node Listing ---
85 * Requirements:: Software needed to build and run Guix.
86 * Setting Up the Daemon:: Preparing the build daemon's environment.
87 * Invoking guix-daemon:: Running the build daemon.
91 * Build Environment Setup:: Preparing the isolated build environment.
92 * Daemon Offload Setup:: Offloading builds to remote machines.
96 * Features:: How Guix will make your life brighter.
97 * Invoking guix package:: Package installation, removal, etc.
98 * Emacs Interface:: Package management from Emacs.
99 * Substitutes:: Downloading pre-built binaries.
100 * Packages with Multiple Outputs:: Single source package, multiple outputs.
101 * Invoking guix gc:: Running the garbage collector.
102 * Invoking guix pull:: Fetching the latest Guix and distribution.
103 * Invoking guix archive:: Exporting and importing store files.
105 Programming Interface
107 * Defining Packages:: Defining new packages.
108 * Build Systems:: Specifying how packages are built.
109 * The Store:: Manipulating the package store.
110 * Derivations:: Low-level interface to package derivations.
111 * The Store Monad:: Purely functional interface to the store.
112 * G-Expressions:: Manipulating build expressions.
116 * Invoking guix build:: Building packages from the command line.
117 * Invoking guix download:: Downloading a file and printing its hash.
118 * Invoking guix hash:: Computing the cryptographic hash of a file.
119 * Invoking guix import:: Importing package definitions.
120 * Invoking guix refresh:: Updating package definitions.
121 * Invoking guix lint:: Finding errors in package definitions.
122 * Invoking guix environment:: Setting up development environments.
126 * System Installation:: Installing the whole operating system.
127 * System Configuration:: Configuring a GNU system.
128 * Installing Debugging Files:: Feeding the debugger.
129 * Security Updates:: Deploying security fixes quickly.
130 * Package Modules:: Packages from the programmer's viewpoint.
131 * Packaging Guidelines:: Growing the distribution.
132 * Bootstrapping:: GNU/Linux built from scratch.
133 * Porting:: Targeting another platform or kernel.
137 * Using the Configuration System:: Customizing your GNU system.
138 * operating-system Reference:: Detail of operating-system declarations.
139 * File Systems:: Configuring file system mounts.
140 * Mapped Devices:: Block device extra processing.
141 * User Accounts:: Specifying user accounts.
142 * Locales:: Language and cultural convention settings.
143 * Services:: Specifying system services.
144 * Setuid Programs:: Programs running with root privileges.
145 * Initial RAM Disk:: Linux-Libre bootstrapping.
146 * GRUB Configuration:: Configuring the boot loader.
147 * Invoking guix system:: Instantiating a system configuration.
148 * Defining Services:: Adding new service definitions.
152 * Base Services:: Essential system services.
153 * Networking Services:: Network setup, SSH daemon, etc.
154 * X Window:: Graphical display.
158 * Software Freedom:: What may go into the distribution.
159 * Package Naming:: What's in a name?
160 * Version Numbers:: When the name is not enough.
161 * Python Modules:: Taming the snake.
162 * Perl Modules:: Little pearls.
163 * Fonts:: Fond of fonts.
168 @c *********************************************************************
170 @chapter Introduction
172 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
173 using the international phonetic alphabet (IPA).} is a functional
174 package management tool for the GNU system. Package management consists
175 of all activities that relate to building packages from sources,
176 honoring their build-time and run-time dependencies,
177 installing packages in user environments, upgrading installed packages
178 to new versions or rolling back to a previous set, removing unused
179 software packages, etc.
181 @cindex functional package management
182 The term @dfn{functional} refers to a specific package management
183 discipline. In Guix, the package build and installation process is seen
184 as a function, in the mathematical sense. That function takes inputs,
185 such as build scripts, a compiler, and libraries, and
186 returns an installed package. As a pure function, its result depends
187 solely on its inputs---for instance, it cannot refer to software or
188 scripts that were not explicitly passed as inputs. A build function
189 always produces the same result when passed a given set of inputs. It
190 cannot alter the system's environment in
191 any way; for instance, it cannot create, modify, or delete files outside
192 of its build and installation directories. This is achieved by running
193 build processes in isolated environments (or @dfn{containers}), where only their
194 explicit inputs are visible.
197 The result of package build functions is @dfn{cached} in the file
198 system, in a special directory called @dfn{the store} (@pxref{The
199 Store}). Each package is installed in a directory of its own, in the
200 store---by default under @file{/gnu/store}. The directory name contains
201 a hash of all the inputs used to build that package; thus, changing an
202 input yields a different directory name.
204 This approach is the foundation of Guix's salient features: support for
205 transactional package upgrade and rollback, per-user installation, and
206 garbage collection of packages (@pxref{Features}).
208 Guix has a command-line interface, which allows users to build, install,
209 upgrade, and remove packages, as well as a Scheme programming interface.
211 Last but not least, Guix is used to build a distribution of the GNU
212 system, with many GNU and non-GNU free software packages. @xref{GNU
215 @c *********************************************************************
217 @chapter Installation
219 GNU Guix is available for download from its website at
220 @url{http://www.gnu.org/software/guix/}. This section describes the
221 software requirements of Guix, as well as how to install it and get
224 Note that this section is concerned with the installation of the package
225 manager, which can be done on top of a running GNU/Linux system. If,
226 instead, you want to install the complete GNU operating system,
227 @pxref{System Installation}.
229 The build procedure for Guix is the same as for other GNU software, and
230 is not covered here. Please see the files @file{README} and
231 @file{INSTALL} in the Guix source tree for additional details.
234 * Requirements:: Software needed to build and run Guix.
235 * Setting Up the Daemon:: Preparing the build daemon's environment.
236 * Invoking guix-daemon:: Running the build daemon.
240 @section Requirements
242 GNU Guix depends on the following packages:
245 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
246 @item @url{http://gnupg.org/, GNU libgcrypt};
249 The following dependencies are optional:
254 @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
255 allow you to use the @command{guix import pypi} command (@pxref{Invoking
256 guix import}). It is of
257 interest primarily for developers and not for casual users.
259 Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
260 allow you to access @code{https} URLs with the @command{guix download}
261 command (@pxref{Invoking guix download}), the @command{guix import pypi}
262 command, and the @command{guix import cpan} command. This is primarily
263 of interest to developers. @xref{Guile Preparations, how to install the
264 GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
267 Unless @code{--disable-daemon} was passed to @command{configure}, the
268 following packages are also needed:
271 @item @url{http://sqlite.org, SQLite 3}
272 @item @url{http://www.bzip.org, libbz2}
273 @item @url{http://gcc.gnu.org, GCC's g++}
276 When a working installation of @url{http://nixos.org/nix/, the Nix package
277 manager} is available, you
278 can instead configure Guix with @code{--disable-daemon}. In that case,
279 Nix replaces the three dependencies above.
281 Guix is compatible with Nix, so it is possible to share the same store
282 between both. To do so, you must pass @command{configure} not only the
283 same @code{--with-store-dir} value, but also the same
284 @code{--localstatedir} value. The latter is essential because it
285 specifies where the database that stores metadata about the store is
286 located, among other things. The default values for Nix are
287 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
288 Note that @code{--disable-daemon} is not required if
289 your goal is to share the store with Nix.
291 @node Setting Up the Daemon
292 @section Setting Up the Daemon
295 Operations such as building a package or running the garbage collector
296 are all performed by a specialized process, the @dfn{build daemon}, on
297 behalf of clients. Only the daemon may access the store and its
298 associated database. Thus, any operation that manipulates the store
299 goes through the daemon. For instance, command-line tools such as
300 @command{guix package} and @command{guix build} communicate with the
301 daemon (@i{via} remote procedure calls) to instruct it what to do.
303 The following sections explain how to prepare the build daemon's
307 * Build Environment Setup:: Preparing the isolated build environment.
308 * Daemon Offload Setup:: Offloading builds to remote machines.
311 @node Build Environment Setup
312 @subsection Build Environment Setup
314 In a standard multi-user setup, Guix and its daemon---the
315 @command{guix-daemon} program---are installed by the system
316 administrator; @file{/gnu/store} is owned by @code{root} and
317 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
318 Guix tools to build packages or otherwise access the store, and the
319 daemon will do it on their behalf, ensuring that the store is kept in a
320 consistent state, and allowing built packages to be shared among users.
323 When @command{guix-daemon} runs as @code{root}, you may not want package
324 build processes themselves to run as @code{root} too, for obvious
325 security reasons. To avoid that, a special pool of @dfn{build users}
326 should be created for use by build processes started by the daemon.
327 These build users need not have a shell and a home directory: they will
328 just be used when the daemon drops @code{root} privileges in build
329 processes. Having several such users allows the daemon to launch
330 distinct build processes under separate UIDs, which guarantees that they
331 do not interfere with each other---an essential feature since builds are
332 regarded as pure functions (@pxref{Introduction}).
334 On a GNU/Linux system, a build user pool may be created like this (using
335 Bash syntax and the @code{shadow} commands):
337 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
338 @c for why `-G' is needed.
340 # groupadd guix-builder
341 # for i in `seq 1 10`;
343 useradd -g guix-builder -G guix-builder \
344 -d /var/empty -s `which nologin` \
345 -c "Guix build user $i" --system \
350 The @file{/gnu/store} directory (or whichever was specified with the
351 @code{--with-store-dir} option) must have ownership and permissions as
355 # chgrp guix-builder /gnu/store
356 # chmod 1775 /gnu/store
360 The @code{guix-daemon} program may then be run as @code{root} with:
363 # guix-daemon --build-users-group=guix-builder
368 This way, the daemon starts build processes in a chroot, under one of
369 the @code{guix-builder} users. On GNU/Linux, by default, the chroot
370 environment contains nothing but:
372 @c Keep this list in sync with libstore/build.cc! -----------------------
375 a minimal @code{/dev} directory, created mostly independently from the
376 host @code{/dev}@footnote{``Mostly'', because while the set of files
377 that appear in the chroot's @code{/dev} is fixed, most of these files
378 can only be created if the host has them.};
381 the @code{/proc} directory; it only shows the container's processes
382 since a separate PID name space is used;
385 @file{/etc/passwd} with an entry for the current user and an entry for
389 @file{/etc/group} with an entry for the user's group;
392 @file{/etc/hosts} with an entry that maps @code{localhost} to
396 a writable @file{/tmp} directory.
399 If you are installing Guix as an unprivileged user, it is still
400 possible to run @command{guix-daemon}. However, build processes will
401 not be isolated from one another, and not from the rest of the system.
402 Thus, build processes may interfere with each other, and may access
403 programs, libraries, and other files available on the system---making it
404 much harder to view them as @emph{pure} functions.
407 @node Daemon Offload Setup
408 @subsection Using the Offload Facility
412 When desired, the build daemon can @dfn{offload}
413 derivation builds to other machines
414 running Guix, using the @code{offload} @dfn{build hook}. When that
415 feature is enabled, a list of user-specified build machines is read from
416 @file{/etc/guix/machines.scm}; anytime a build is requested, for
417 instance via @code{guix build}, the daemon attempts to offload it to one
418 of the machines that satisfies the derivation's constraints, in
419 particular its system type---e.g., @file{x86_64-linux}. Missing
420 prerequisites for the build are copied over SSH to the target machine,
421 which then proceeds with the build; upon success the output(s) of the
422 build are copied back to the initial machine.
424 The @file{/etc/guix/machines.scm} file typically looks like this:
428 (name "eightysix.example.org")
429 (system "x86_64-linux")
431 (speed 2.)) ; incredibly fast!
434 (name "meeps.example.org")
435 (system "mips64el-linux")
438 (string-append (getenv "HOME")
439 "/.ssh/id-rsa-for-guix"))))
443 In the example above we specify a list of two build machines, one for
444 the @code{x86_64} architecture and one for the @code{mips64el}
447 In fact, this file is---not surprisingly!---a Scheme file that is
448 evaluated when the @code{offload} hook is started. Its return value
449 must be a list of @code{build-machine} objects. While this example
450 shows a fixed list of build machines, one could imagine, say, using
451 DNS-SD to return a list of potential build machines discovered in the
452 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
453 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
456 @deftp {Data Type} build-machine
457 This data type represents build machines the daemon may offload builds
458 to. The important fields are:
463 The remote machine's host name.
466 The remote machine's system type---e.g., @code{"x86_64-linux"}.
469 The user account to use when connecting to the remote machine over SSH.
470 Note that the SSH key pair must @emph{not} be passphrase-protected, to
471 allow non-interactive logins.
475 A number of optional fields may be specified:
480 Port number of the machine's SSH server (default: 22).
483 The SSH private key file to use when connecting to the machine.
485 @item parallel-builds
486 The number of builds that may run in parallel on the machine (1 by
490 A ``relative speed factor''. The offload scheduler will tend to prefer
491 machines with a higher speed factor.
494 A list of strings denoting specific features supported by the machine.
495 An example is @code{"kvm"} for machines that have the KVM Linux modules
496 and corresponding hardware support. Derivations can request features by
497 name, and they will be scheduled on matching build machines.
502 The @code{guix} command must be in the search path on the build
503 machines, since offloading works by invoking the @code{guix archive} and
504 @code{guix build} commands.
506 There's one last thing to do once @file{machines.scm} is in place. As
507 explained above, when offloading, files are transferred back and forth
508 between the machine stores. For this to work, you need to generate a
509 key pair to allow the daemon to export signed archives of files from the
510 store (@pxref{Invoking guix archive}):
513 # guix archive --generate-key
517 Thus, when receiving files, a machine's build daemon can make sure they
518 are genuine, have not been tampered with, and that they are signed by an
522 @node Invoking guix-daemon
523 @section Invoking @command{guix-daemon}
525 The @command{guix-daemon} program implements all the functionality to
526 access the store. This includes launching build processes, running the
527 garbage collector, querying the availability of a build result, etc. It
528 is normally run as @code{root} like this:
531 # guix-daemon --build-users-group=guix-builder
535 For details on how to set it up, @pxref{Setting Up the Daemon}.
538 @cindex container, build environment
539 @cindex build environment
540 @cindex reproducible builds
541 By default, @command{guix-daemon} launches build processes under
542 different UIDs, taken from the build group specified with
543 @code{--build-users-group}. In addition, each build process is run in a
544 chroot environment that only contains the subset of the store that the
545 build process depends on, as specified by its derivation
546 (@pxref{Programming Interface, derivation}), plus a set of specific
547 system directories. By default, the latter contains @file{/dev} and
548 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
549 @dfn{container}: in addition to having its own file system tree, it has
550 a separate mount name space, its own PID name space, network name space,
551 etc. This helps achieve reproducible builds (@pxref{Features}).
553 The following command-line options are supported:
556 @item --build-users-group=@var{group}
557 Take users from @var{group} to run build processes (@pxref{Setting Up
558 the Daemon, build users}).
560 @item --no-substitutes
562 Do not use substitutes for build products. That is, always build things
563 locally instead of allowing downloads of pre-built binaries
564 (@pxref{Substitutes}).
566 By default substitutes are used, unless the client---such as the
567 @command{guix package} command---is explicitly invoked with
568 @code{--no-substitutes}.
570 When the daemon runs with @code{--no-substitutes}, clients can still
571 explicitly enable substitution @i{via} the @code{set-build-options}
572 remote procedure call (@pxref{The Store}).
574 @item --substitute-urls=@var{urls}
575 Consider @var{urls} the default whitespace-separated list of substitute
576 source URLs. When this option is omitted, @code{http://hydra.gnu.org}
579 This means that substitutes may be downloaded from @var{urls}, as long
580 as they are signed by a trusted signature (@pxref{Substitutes}).
583 @item --no-build-hook
584 Do not use the @dfn{build hook}.
586 The build hook is a helper program that the daemon can start and to
587 which it submits build requests. This mechanism is used to offload
588 builds to other machines (@pxref{Daemon Offload Setup}).
590 @item --cache-failures
591 Cache build failures. By default, only successful builds are cached.
593 @item --cores=@var{n}
595 Use @var{n} CPU cores to build each derivation; @code{0} means as many
598 The default value is @code{0}, but it may be overridden by clients, such
599 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
602 The effect is to define the @code{NIX_BUILD_CORES} environment variable
603 in the build process, which can then use it to exploit internal
604 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
606 @item --max-jobs=@var{n}
608 Allow at most @var{n} build jobs in parallel. The default value is
609 @code{1}. Setting it to @code{0} means that no builds will be performed
610 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
611 Setup}), or simply fail.
614 Produce debugging output.
616 This is useful to debug daemon start-up issues, but then it may be
617 overridden by clients, for example the @code{--verbosity} option of
618 @command{guix build} (@pxref{Invoking guix build}).
620 @item --chroot-directory=@var{dir}
621 Add @var{dir} to the build chroot.
623 Doing this may change the result of build processes---for instance if
624 they use optional dependencies found in @var{dir} when it is available,
625 and not otherwise. For that reason, it is not recommended to do so.
626 Instead, make sure that each derivation declares all the inputs that it
629 @item --disable-chroot
630 Disable chroot builds.
632 Using this option is not recommended since, again, it would allow build
633 processes to gain access to undeclared dependencies.
635 @item --disable-log-compression
636 Disable compression of the build logs.
638 Unless @code{--lose-logs} is used, all the build logs are kept in the
639 @var{localstatedir}. To save space, the daemon automatically compresses
640 them with bzip2 by default. This option disables that.
642 @item --disable-deduplication
643 @cindex deduplication
644 Disable automatic file ``deduplication'' in the store.
646 By default, files added to the store are automatically ``deduplicated'':
647 if a newly added file is identical to another one found in the store,
648 the daemon makes the new file a hard link to the other file. This can
649 noticeably reduce disk usage, at the expense of slightly increasde
650 input/output load at the end of a build process. This option disables
653 @item --gc-keep-outputs[=yes|no]
654 Tell whether the garbage collector (GC) must keep outputs of live
657 When set to ``yes'', the GC will keep the outputs of any live derivation
658 available in the store---the @code{.drv} files. The default is ``no'',
659 meaning that derivation outputs are kept only if they are GC roots.
661 @item --gc-keep-derivations[=yes|no]
662 Tell whether the garbage collector (GC) must keep derivations
663 corresponding to live outputs.
665 When set to ``yes'', as is the case by default, the GC keeps
666 derivations---i.e., @code{.drv} files---as long as at least one of their
667 outputs is live. This allows users to keep track of the origins of
668 items in their store. Setting it to ``no'' saves a bit of disk space.
670 Note that when both @code{--gc-keep-derivations} and
671 @code{--gc-keep-outputs} are used, the effect is to keep all the build
672 prerequisites (the sources, compiler, libraries, and other build-time
673 tools) of live objects in the store, regardless of whether these
674 prerequisites are live. This is convenient for developers since it
675 saves rebuilds or downloads.
677 @item --impersonate-linux-2.6
678 On Linux-based systems, impersonate Linux 2.6. This means that the
679 kernel's @code{uname} system call will report 2.6 as the release number.
681 This might be helpful to build programs that (usually wrongfully) depend
682 on the kernel version number.
685 Do not keep build logs. By default they are kept under
686 @code{@var{localstatedir}/guix/log}.
688 @item --system=@var{system}
689 Assume @var{system} as the current system type. By default it is the
690 architecture/kernel pair found at configure time, such as
693 @item --listen=@var{socket}
694 Listen for connections on @var{socket}, the file name of a Unix-domain
695 socket. The default socket is
696 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
697 useful in exceptional circumstances, such as if you need to run several
698 daemons on the same machine.
702 @c *********************************************************************
703 @node Package Management
704 @chapter Package Management
706 The purpose of GNU Guix is to allow users to easily install, upgrade, and
707 remove software packages, without having to know about their build
708 procedure or dependencies. Guix also goes beyond this obvious set of
711 This chapter describes the main features of Guix, as well as the package
712 management tools it provides. Two user interfaces are provided for
713 routine package management tasks: a command-line interface
714 (@pxref{Invoking guix package, @code{guix package}}), and a visual user
715 interface in Emacs (@pxref{Emacs Interface}).
718 * Features:: How Guix will make your life brighter.
719 * Invoking guix package:: Package installation, removal, etc.
720 * Emacs Interface:: Package management from Emacs.
721 * Substitutes:: Downloading pre-built binaries.
722 * Packages with Multiple Outputs:: Single source package, multiple outputs.
723 * Invoking guix gc:: Running the garbage collector.
724 * Invoking guix pull:: Fetching the latest Guix and distribution.
725 * Invoking guix archive:: Exporting and importing store files.
731 When using Guix, each package ends up in the @dfn{package store}, in its
732 own directory---something that resembles
733 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
734 (note that Guix comes with an Emacs extension to shorten those file
735 names, @pxref{Emacs Prettify}.)
737 Instead of referring to these directories, users have their own
738 @dfn{profile}, which points to the packages that they actually want to
739 use. These profiles are stored within each user's home directory, at
740 @code{$HOME/.guix-profile}.
742 For example, @code{alice} installs GCC 4.7.2. As a result,
743 @file{/home/alice/.guix-profile/bin/gcc} points to
744 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
745 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
746 simply continues to point to
747 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
748 coexist on the same system without any interference.
750 The @command{guix package} command is the central tool to manage
751 packages (@pxref{Invoking guix package}). It operates on those per-user
752 profiles, and can be used @emph{with normal user privileges}.
754 The command provides the obvious install, remove, and upgrade
755 operations. Each invocation is actually a @emph{transaction}: either
756 the specified operation succeeds, or nothing happens. Thus, if the
757 @command{guix package} process is terminated during the transaction,
758 or if a power outage occurs during the transaction, then the user's
759 profile remains in its previous state, and remains usable.
761 In addition, any package transaction may be @emph{rolled back}. So, if,
762 for example, an upgrade installs a new version of a package that turns
763 out to have a serious bug, users may roll back to the previous instance
764 of their profile, which was known to work well. Similarly, the global
765 system configuration is subject to transactional upgrades and roll-back
766 (@pxref{Using the Configuration System}).
768 All those packages in the package store may be @emph{garbage-collected}.
769 Guix can determine which packages are still referenced by the user
770 profiles, and remove those that are provably no longer referenced
771 (@pxref{Invoking guix gc}). Users may also explicitly remove old
772 generations of their profile so that the packages they refer to can be
775 @cindex reproducibility
776 @cindex reproducible builds
777 Finally, Guix takes a @dfn{purely functional} approach to package
778 management, as described in the introduction (@pxref{Introduction}).
779 Each @file{/gnu/store} package directory name contains a hash of all the
780 inputs that were used to build that package---compiler, libraries, build
781 scripts, etc. This direct correspondence allows users to make sure a
782 given package installation matches the current state of their
783 distribution. It also helps maximize @dfn{build reproducibility}:
784 thanks to the isolated build environments that are used, a given build
785 is likely to yield bit-identical files when performed on different
786 machines (@pxref{Invoking guix-daemon, container}).
789 This foundation allows Guix to support @dfn{transparent binary/source
790 deployment}. When a pre-built binary for a @file{/gnu/store} item is
791 available from an external source---a @dfn{substitute}, Guix just
792 downloads it and unpacks it;
793 otherwise, it builds the package from source, locally
794 (@pxref{Substitutes}).
796 Control over the build environment is a feature that is also useful for
797 developers. The @command{guix environment} command allows developers of
798 a package to quickly set up the right development environment for their
799 package, without having to manually install the package's dependencies
800 in their profile (@pxref{Invoking guix environment}).
802 @node Invoking guix package
803 @section Invoking @command{guix package}
805 The @command{guix package} command is the tool that allows users to
806 install, upgrade, and remove packages, as well as rolling back to
807 previous configurations. It operates only on the user's own profile,
808 and works with normal user privileges (@pxref{Features}). Its syntax
812 guix package @var{options}
815 Primarily, @var{options} specifies the operations to be performed during
816 the transaction. Upon completion, a new profile is created, but
817 previous generations of the profile remain available, should the user
820 For example, to remove @code{lua} and install @code{guile} and
821 @code{guile-cairo} in a single transaction:
824 guix package -r lua -i guile guile-cairo
827 For each user, a symlink to the user's default profile is automatically
828 created in @file{$HOME/.guix-profile}. This symlink always points to the
829 current generation of the user's default profile. Thus, users can add
830 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
833 In a multi-user setup, user profiles are stored in a place registered as
834 a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
835 to (@pxref{Invoking guix gc}). That directory is normally
836 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
837 @var{localstatedir} is the value passed to @code{configure} as
838 @code{--localstatedir}, and @var{user} is the user name. The
839 @file{per-user} directory is created when @command{guix-daemon} is
840 started, and the @var{user} sub-directory is created by @command{guix
843 The @var{options} can be among the following:
847 @item --install=@var{package} @dots{}
848 @itemx -i @var{package} @dots{}
849 Install the specified @var{package}s.
851 Each @var{package} may specify either a simple package name, such as
852 @code{guile}, or a package name followed by a hyphen and version number,
853 such as @code{guile-1.8.8}. If no version number is specified, the
854 newest available version will be selected. In addition, @var{package}
855 may contain a colon, followed by the name of one of the outputs of the
856 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
857 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
858 name (and optionally version) are searched for among the GNU
859 distribution modules (@pxref{Package Modules}).
861 @cindex propagated inputs
862 Sometimes packages have @dfn{propagated inputs}: these are dependencies
863 that automatically get installed along with the required package.
865 An example is the GNU MPC library: its C header files refer to those of
866 the GNU MPFR library, which in turn refer to those of the GMP library.
867 Thus, when installing MPC, the MPFR and GMP libraries also get installed
868 in the profile; removing MPC also removes MPFR and GMP---unless they had
869 also been explicitly installed independently.
871 Besides, packages sometimes rely on the definition of environment
872 variables for their search paths (see explanation of
873 @code{--search-paths} below). Any missing or possibly incorrect
874 environment variable definitions are reported here.
876 @c XXX: keep me up-to-date
877 Finally, when installing a GNU package, the tool reports the
878 availability of a newer upstream version. In the future, it may provide
879 the option of installing directly from the upstream version, even if
880 that version is not yet in the distribution.
882 @item --install-from-expression=@var{exp}
884 Install the package @var{exp} evaluates to.
886 @var{exp} must be a Scheme expression that evaluates to a
887 @code{<package>} object. This option is notably useful to disambiguate
888 between same-named variants of a package, with expressions such as
889 @code{(@@ (gnu packages base) guile-final)}.
891 Note that this option installs the first output of the specified
892 package, which may be insufficient when needing a specific output of a
893 multiple-output package.
895 @item --remove=@var{package} @dots{}
896 @itemx -r @var{package} @dots{}
897 Remove the specified @var{package}s.
899 As for @code{--install}, each @var{package} may specify a version number
900 and/or output name in addition to the package name. For instance,
901 @code{-r glibc:debug} would remove the @code{debug} output of
904 @item --upgrade[=@var{regexp} @dots{}]
905 @itemx -u [@var{regexp} @dots{}]
906 Upgrade all the installed packages. If one or more @var{regexp}s are
907 specified, upgrade only installed packages whose name matches a
910 Note that this upgrades package to the latest version of packages found
911 in the distribution currently installed. To update your distribution,
912 you should regularly run @command{guix pull} (@pxref{Invoking guix
916 Roll back to the previous @dfn{generation} of the profile---i.e., undo
917 the last transaction.
919 When combined with options such as @code{--install}, roll back occurs
920 before any other actions.
922 When rolling back from the first generation that actually contains
923 installed packages, the profile is made to point to the @dfn{zeroth
924 generation}, which contains no files apart from its own meta-data.
926 Installing, removing, or upgrading packages from a generation that has
927 been rolled back to overwrites previous future generations. Thus, the
928 history of a profile's generations is always linear.
930 @item --switch-generation=@var{pattern}
931 @itemx -S @var{pattern}
932 Switch to a particular generation defined by @var{pattern}.
934 @var{pattern} may be either a generation number or a number prefixed
935 with ``+'' or ``-''. The latter means: move forward/backward by a
936 specified number of generations. For example, if you want to return to
937 the latest generation after @code{--roll-back}, use
938 @code{--switch-generation=+1}.
940 The difference between @code{--roll-back} and
941 @code{--switch-generation=-1} is that @code{--switch-generation} will
942 not make a zeroth generation, so if a specified generation does not
943 exist, the current generation will not be changed.
947 Report environment variable definitions, in Bash syntax, that may be
948 needed in order to use the set of installed packages. These environment
949 variables are used to specify @dfn{search paths} for files used by some
950 of the installed packages.
952 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
953 environment variables to be defined so it can look for headers and
954 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
955 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
956 library are installed in the profile, then @code{--search-paths} will
957 suggest setting these variables to @code{@var{profile}/include} and
958 @code{@var{profile}/lib}, respectively.
960 @item --profile=@var{profile}
961 @itemx -p @var{profile}
962 Use @var{profile} instead of the user's default profile.
965 Produce verbose output. In particular, emit the environment's build log
966 on the standard error port.
969 Use the bootstrap Guile to build the profile. This option is only
970 useful to distribution developers.
974 In addition to these actions @command{guix package} supports the
975 following options to query the current state of a profile, or the
976 availability of packages:
980 @item --search=@var{regexp}
981 @itemx -s @var{regexp}
982 List the available packages whose synopsis or description matches
983 @var{regexp}. Print all the meta-data of matching packages in
984 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
985 GNU recutils manual}).
987 This allows specific fields to be extracted using the @command{recsel}
988 command, for instance:
991 $ guix package -s malloc | recsel -p name,version
999 Similarly, to show the name of all the packages available under the
1000 terms of the GNU@tie{}LGPL version 3:
1003 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
1010 @item --show=@var{package}
1011 Show details about @var{package}, taken from the list of available packages, in
1012 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
1016 $ guix package --show=python | recsel -p name,version
1024 You may also specify the full name of a package to only get details about a
1025 specific version of it:
1027 $ guix package --show=python-3.3.5 | recsel -p name,version
1034 @item --list-installed[=@var{regexp}]
1035 @itemx -I [@var{regexp}]
1036 List the currently installed packages in the specified profile, with the
1037 most recently installed packages shown last. When @var{regexp} is
1038 specified, list only installed packages whose name matches @var{regexp}.
1040 For each installed package, print the following items, separated by
1041 tabs: the package name, its version string, the part of the package that
1042 is installed (for instance, @code{out} for the default output,
1043 @code{include} for its headers, etc.), and the path of this package in
1046 @item --list-available[=@var{regexp}]
1047 @itemx -A [@var{regexp}]
1048 List packages currently available in the software distribution
1049 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
1050 installed packages whose name matches @var{regexp}.
1052 For each package, print the following items separated by tabs: its name,
1053 its version string, the parts of the package (@pxref{Packages with
1054 Multiple Outputs}), and the source location of its definition.
1056 @item --list-generations[=@var{pattern}]
1057 @itemx -l [@var{pattern}]
1058 Return a list of generations along with their creation dates; for each
1059 generation, show the installed packages, with the most recently
1060 installed packages shown last. Note that the zeroth generation is never
1063 For each installed package, print the following items, separated by
1064 tabs: the name of a package, its version string, the part of the package
1065 that is installed (@pxref{Packages with Multiple Outputs}), and the
1066 location of this package in the store.
1068 When @var{pattern} is used, the command returns only matching
1069 generations. Valid patterns include:
1072 @item @emph{Integers and comma-separated integers}. Both patterns denote
1073 generation numbers. For instance, @code{--list-generations=1} returns
1076 And @code{--list-generations=1,8,2} outputs three generations in the
1077 specified order. Neither spaces nor trailing commas are allowed.
1079 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
1080 specified generations and everything in between. Note that the start of
1081 a range must be lesser than its end.
1083 It is also possible to omit the endpoint. For example,
1084 @code{--list-generations=2..}, returns all generations starting from the
1087 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
1088 or months by passing an integer along with the first letter of the
1089 duration. For example, @code{--list-generations=20d} lists generations
1090 that are up to 20 days old.
1093 @item --delete-generations[=@var{pattern}]
1094 @itemx -d [@var{pattern}]
1095 When @var{pattern} is omitted, delete all generations except the current
1098 This command accepts the same patterns as @option{--list-generations}.
1099 When @var{pattern} is specified, delete the matching generations. When
1100 @var{pattern} specifies a duration, generations @emph{older} than the
1101 specified duration match. For instance, @code{--delete-generations=1m}
1102 deletes generations that are more than one month old.
1104 If the current generation matches, it is deleted atomically---i.e., by
1105 switching to the previous available generation. Note that the zeroth
1106 generation is never deleted.
1108 Note that deleting generations prevents roll-back to them.
1109 Consequently, this command must be used with care.
1113 Finally, since @command{guix package} may actually start build
1114 processes, it supports all the common build options that @command{guix
1115 build} supports (@pxref{Invoking guix build, common build options}).
1120 @section Substitutes
1123 @cindex pre-built binaries
1124 Guix supports transparent source/binary deployment, which means that it
1125 can either build things locally, or download pre-built items from a
1126 server. We call these pre-built items @dfn{substitutes}---they are
1127 substitutes for local build results. In many cases, downloading a
1128 substitute is much faster than building things locally.
1130 Substitutes can be anything resulting from a derivation build
1131 (@pxref{Derivations}). Of course, in the common case, they are
1132 pre-built package binaries, but source tarballs, for instance, which
1133 also result from derivation builds, can be available as substitutes.
1135 The @code{hydra.gnu.org} server is a front-end to a build farm that
1136 builds packages from the GNU distribution continuously for some
1137 architectures, and makes them available as substitutes. This is the
1138 default source of substitutes; it can be overridden by passing
1139 @command{guix-daemon} the @code{--substitute-urls} option
1140 (@pxref{Invoking guix-daemon}).
1143 @cindex digital signatures
1144 To allow Guix to download substitutes from @code{hydra.gnu.org}, you
1145 must add its public key to the access control list (ACL) of archive
1146 imports, using the @command{guix archive} command (@pxref{Invoking guix
1147 archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
1148 be compromised and to serve genuine substitutes.
1150 This public key is installed along with Guix, in
1151 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
1152 the installation prefix of Guix. If you installed Guix from source,
1153 make sure you checked the GPG signature of
1154 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
1155 Then, you can run something like this:
1158 # guix archive --authorize < hydra.gnu.org.pub
1161 Once this is in place, the output of a command like @code{guix build}
1162 should change from something like:
1165 $ guix build emacs --dry-run
1166 The following derivations would be built:
1167 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
1168 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
1169 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
1170 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
1178 $ guix build emacs --dry-run
1179 The following files would be downloaded:
1180 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
1181 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
1182 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
1183 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
1188 This indicates that substitutes from @code{hydra.gnu.org} are usable and
1189 will be downloaded, when possible, for future builds.
1191 Guix ignores substitutes that are not signed, or that are not signed by
1192 one of the keys listed in the ACL. It also detects and raises an error
1193 when attempting to use a substitute that has been tampered with.
1195 The substitute mechanism can be disabled globally by running
1196 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1197 guix-daemon}). It can also be disabled temporarily by passing the
1198 @code{--no-substitutes} option to @command{guix package}, @command{guix
1199 build}, and other command-line tools.
1202 Today, each individual's control over their own computing is at the
1203 mercy of institutions, corporations, and groups with enough power and
1204 determination to subvert the computing infrastructure and exploit its
1205 weaknesses. While using @code{hydra.gnu.org} substitutes can be
1206 convenient, we encourage users to also build on their own, or even run
1207 their own build farm, such that @code{hydra.gnu.org} is less of an
1210 Guix has the foundations to maximize build reproducibility
1211 (@pxref{Features}). In most cases, independent builds of a given
1212 package or derivation should yield bit-identical results. Thus, through
1213 a diverse set of independent package builds, we can strengthen the
1214 integrity of our systems.
1216 In the future, we want Guix to have support to publish and retrieve
1217 binaries to/from other users, in a peer-to-peer fashion. If you would
1218 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1221 @node Packages with Multiple Outputs
1222 @section Packages with Multiple Outputs
1224 @cindex multiple-output packages
1225 @cindex package outputs
1227 Often, packages defined in Guix have a single @dfn{output}---i.e., the
1228 source package leads exactly one directory in the store. When running
1229 @command{guix package -i glibc}, one installs the default output of the
1230 GNU libc package; the default output is called @code{out}, but its name
1231 can be omitted as shown in this command. In this particular case, the
1232 default output of @code{glibc} contains all the C header files, shared
1233 libraries, static libraries, Info documentation, and other supporting
1236 Sometimes it is more appropriate to separate the various types of files
1237 produced from a single source package into separate outputs. For
1238 instance, the GLib C library (used by GTK+ and related packages)
1239 installs more than 20 MiB of reference documentation as HTML pages.
1240 To save space for users who do not need it, the documentation goes to a
1241 separate output, called @code{doc}. To install the main GLib output,
1242 which contains everything but the documentation, one would run:
1245 guix package -i glib
1248 The command to install its documentation is:
1251 guix package -i glib:doc
1254 Some packages install programs with different ``dependency footprints''.
1255 For instance, the WordNet package install both command-line tools and
1256 graphical user interfaces (GUIs). The former depend solely on the C
1257 library, whereas the latter depend on Tcl/Tk and the underlying X
1258 libraries. In this case, we leave the command-line tools in the default
1259 output, whereas the GUIs are in a separate output. This allows users
1260 who do not need the GUIs to save space.
1262 There are several such multiple-output packages in the GNU distribution.
1263 Other conventional output names include @code{lib} for libraries and
1264 possibly header files, @code{bin} for stand-alone programs, and
1265 @code{debug} for debugging information (@pxref{Installing Debugging
1266 Files}). The outputs of a packages are listed in the third column of
1267 the output of @command{guix package --list-available} (@pxref{Invoking
1271 @node Invoking guix gc
1272 @section Invoking @command{guix gc}
1274 @cindex garbage collector
1275 Packages that are installed but not used may be @dfn{garbage-collected}.
1276 The @command{guix gc} command allows users to explicitly run the garbage
1277 collector to reclaim space from the @file{/gnu/store} directory.
1279 The garbage collector has a set of known @dfn{roots}: any file under
1280 @file{/gnu/store} reachable from a root is considered @dfn{live} and
1281 cannot be deleted; any other file is considered @dfn{dead} and may be
1282 deleted. The set of garbage collector roots includes default user
1283 profiles, and may be augmented with @command{guix build --root}, for
1284 example (@pxref{Invoking guix build}).
1286 Prior to running @code{guix gc --collect-garbage} to make space, it is
1287 often useful to remove old generations from user profiles; that way, old
1288 package builds referenced by those generations can be reclaimed. This
1289 is achieved by running @code{guix package --delete-generations}
1290 (@pxref{Invoking guix package}).
1292 The @command{guix gc} command has three modes of operation: it can be
1293 used to garbage-collect any dead files (the default), to delete specific
1294 files (the @code{--delete} option), or to print garbage-collector
1295 information. The available options are listed below:
1298 @item --collect-garbage[=@var{min}]
1299 @itemx -C [@var{min}]
1300 Collect garbage---i.e., unreachable @file{/gnu/store} files and
1301 sub-directories. This is the default operation when no option is
1304 When @var{min} is given, stop once @var{min} bytes have been collected.
1305 @var{min} may be a number of bytes, or it may include a unit as a
1306 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
1307 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
1309 When @var{min} is omitted, collect all the garbage.
1313 Attempt to delete all the store files and directories specified as
1314 arguments. This fails if some of the files are not in the store, or if
1315 they are still live.
1318 Show the list of dead files and directories still present in the
1319 store---i.e., files and directories no longer reachable from any root.
1322 Show the list of live store files and directories.
1326 In addition, the references among existing store files can be queried:
1332 List the references (respectively, the referrers) of store files given
1337 List the requisites of the store files passed as arguments. Requisites
1338 include the store files themselves, their references, and the references
1339 of these, recursively. In other words, the returned list is the
1340 @dfn{transitive closure} of the store files.
1345 @node Invoking guix pull
1346 @section Invoking @command{guix pull}
1348 Packages are installed or upgraded to the latest version available in
1349 the distribution currently available on your local machine. To update
1350 that distribution, along with the Guix tools, you must run @command{guix
1351 pull}: the command downloads the latest Guix source code and package
1352 descriptions, and deploys it.
1354 On completion, @command{guix package} will use packages and package
1355 versions from this just-retrieved copy of Guix. Not only that, but all
1356 the Guix commands and Scheme modules will also be taken from that latest
1357 version. New @command{guix} sub-commands added by the update also
1360 The @command{guix pull} command is usually invoked with no arguments,
1361 but it supports the following options:
1365 Produce verbose output, writing build logs to the standard error output.
1367 @item --url=@var{url}
1368 Download the source tarball of Guix from @var{url}.
1370 By default, the tarball is taken from its canonical address at
1371 @code{gnu.org}, for the stable branch of Guix.
1374 Use the bootstrap Guile to build the latest Guix. This option is only
1375 useful to Guix developers.
1379 @node Invoking guix archive
1380 @section Invoking @command{guix archive}
1382 The @command{guix archive} command allows users to @dfn{export} files
1383 from the store into a single archive, and to later @dfn{import} them.
1384 In particular, it allows store files to be transferred from one machine
1385 to another machine's store. For example, to transfer the @code{emacs}
1386 package to a machine connected over SSH, one would run:
1389 guix archive --export emacs | ssh the-machine guix archive --import
1393 However, note that, in this example, all of @code{emacs} and its
1394 dependencies are transferred, regardless of what is already available in
1395 the target machine's store. The @code{--missing} option can help figure
1396 out which items are missing from the target's store.
1398 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1399 comparable in spirit to `tar', but with a few noteworthy differences
1400 that make it more appropriate for our purposes. First, rather than
1401 recording all Unix meta-data for each file, the Nar format only mentions
1402 the file type (regular, directory, or symbolic link); Unix permissions
1403 and owner/group are dismissed. Second, the order in which directory
1404 entries are stored always follows the order of file names according to
1405 the C locale collation order. This makes archive production fully
1408 When exporting, the daemon digitally signs the contents of the archive,
1409 and that digital signature is appended. When importing, the daemon
1410 verifies the signature and rejects the import in case of an invalid
1411 signature or if the signing key is not authorized.
1412 @c FIXME: Add xref to daemon doc about signatures.
1414 The main options are:
1418 Export the specified store files or packages (see below.) Write the
1419 resulting archive to the standard output.
1422 Read an archive from the standard input, and import the files listed
1423 therein into the store. Abort if the archive has an invalid digital
1424 signature, or if it is signed by a public key not among the authorized
1425 keys (see @code{--authorize} below.)
1428 Read a list of store file names from the standard input, one per line,
1429 and write on the standard output the subset of these files missing from
1432 @item --generate-key[=@var{parameters}]
1433 @cindex signing, archives
1434 Generate a new key pair for the daemons. This is a prerequisite before
1435 archives can be exported with @code{--export}. Note that this operation
1436 usually takes time, because it needs to gather enough entropy to
1437 generate the key pair.
1439 The generated key pair is typically stored under @file{/etc/guix}, in
1440 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1441 key, which must be kept secret.) When @var{parameters} is omitted, it
1442 is a 4096-bit RSA key. Alternately, @var{parameters} can specify
1443 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1444 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1445 Libgcrypt Reference Manual}).
1448 @cindex authorizing, archives
1449 Authorize imports signed by the public key passed on standard input.
1450 The public key must be in ``s-expression advanced format''---i.e., the
1451 same format as the @file{signing-key.pub} file.
1453 The list of authorized keys is kept in the human-editable file
1454 @file{/etc/guix/acl}. The file contains
1455 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1456 s-expressions''} and is structured as an access-control list in the
1457 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1461 To export store files as an archive to the standard output, run:
1464 guix archive --export @var{options} @var{specifications}...
1467 @var{specifications} may be either store file names or package
1468 specifications, as for @command{guix package} (@pxref{Invoking guix
1469 package}). For instance, the following command creates an archive
1470 containing the @code{gui} output of the @code{git} package and the main
1471 output of @code{emacs}:
1474 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
1477 If the specified packages are not built yet, @command{guix archive}
1478 automatically builds them. The build process may be controlled with the
1479 same options that can be passed to the @command{guix build} command
1480 (@pxref{Invoking guix build, common build options}).
1483 @c *********************************************************************
1484 @node Programming Interface
1485 @chapter Programming Interface
1487 GNU Guix provides several Scheme programming interfaces (APIs) to
1488 define, build, and query packages. The first interface allows users to
1489 write high-level package definitions. These definitions refer to
1490 familiar packaging concepts, such as the name and version of a package,
1491 its build system, and its dependencies. These definitions can then be
1492 turned into concrete build actions.
1494 Build actions are performed by the Guix daemon, on behalf of users. In a
1495 standard setup, the daemon has write access to the store---the
1496 @file{/gnu/store} directory---whereas users do not. The recommended
1497 setup also has the daemon perform builds in chroots, under a specific
1498 build users, to minimize interference with the rest of the system.
1501 Lower-level APIs are available to interact with the daemon and the
1502 store. To instruct the daemon to perform a build action, users actually
1503 provide it with a @dfn{derivation}. A derivation is a low-level
1504 representation of the build actions to be taken, and the environment in
1505 which they should occur---derivations are to package definitions what
1506 assembly is to C programs. The term ``derivation'' comes from the fact
1507 that build results @emph{derive} from them.
1509 This chapter describes all these APIs in turn, starting from high-level
1510 package definitions.
1513 * Defining Packages:: Defining new packages.
1514 * Build Systems:: Specifying how packages are built.
1515 * The Store:: Manipulating the package store.
1516 * Derivations:: Low-level interface to package derivations.
1517 * The Store Monad:: Purely functional interface to the store.
1518 * G-Expressions:: Manipulating build expressions.
1521 @node Defining Packages
1522 @section Defining Packages
1524 The high-level interface to package definitions is implemented in the
1525 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1526 example, the package definition, or @dfn{recipe}, for the GNU Hello
1527 package looks like this:
1530 (define-module (gnu packages hello)
1531 #:use-module (guix packages)
1532 #:use-module (guix download)
1533 #:use-module (guix build-system gnu)
1534 #:use-module (guix licenses))
1536 (define-public hello
1542 (uri (string-append "mirror://gnu/hello/hello-" version
1545 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1546 (build-system gnu-build-system)
1547 (arguments `(#:configure-flags '("--enable-silent-rules")))
1548 (inputs `(("gawk" ,gawk)))
1549 (synopsis "Hello, GNU world: An example GNU package")
1550 (description "Guess what GNU Hello prints!")
1551 (home-page "http://www.gnu.org/software/hello/")
1556 Without being a Scheme expert, the reader may have guessed the meaning
1557 of the various fields here. This expression binds variable @code{hello}
1558 to a @code{<package>} object, which is essentially a record
1559 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1560 This package object can be inspected using procedures found in the
1561 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1562 returns---surprise!---@code{"hello"}.
1564 With luck, you may be able to import part or all of the definition of
1565 the package you are interested in from another repository, using the
1566 @code{guix import} command (@pxref{Invoking guix import}).
1568 In the example above, @var{hello} is defined into a module of its own,
1569 @code{(gnu packages hello)}. Technically, this is not strictly
1570 necessary, but it is convenient to do so: all the packages defined in
1571 modules under @code{(gnu packages @dots{})} are automatically known to
1572 the command-line tools (@pxref{Package Modules}).
1574 There are a few points worth noting in the above package definition:
1578 The @code{source} field of the package is an @code{<origin>} object.
1579 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1580 meaning that the source is a file to be downloaded over FTP or HTTP.
1582 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1583 the GNU mirrors defined in @code{(guix download)}.
1585 The @code{sha256} field specifies the expected SHA256 hash of the file
1586 being downloaded. It is mandatory, and allows Guix to check the
1587 integrity of the file. The @code{(base32 @dots{})} form introduces the
1588 base32 representation of the hash. You can obtain this information with
1589 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1590 hash} (@pxref{Invoking guix hash}).
1593 When needed, the @code{origin} form can also have a @code{patches} field
1594 listing patches to be applied, and a @code{snippet} field giving a
1595 Scheme expression to modify the source code.
1598 @cindex GNU Build System
1599 The @code{build-system} field specifies the procedure to build the
1600 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1601 represents the familiar GNU Build System, where packages may be
1602 configured, built, and installed with the usual @code{./configure &&
1603 make && make check && make install} command sequence.
1606 The @code{arguments} field specifies options for the build system
1607 (@pxref{Build Systems}). Here it is interpreted by
1608 @var{gnu-build-system} as a request run @file{configure} with the
1609 @code{--enable-silent-rules} flag.
1612 The @code{inputs} field specifies inputs to the build process---i.e.,
1613 build-time or run-time dependencies of the package. Here, we define an
1614 input called @code{"gawk"} whose value is that of the @var{gawk}
1615 variable; @var{gawk} is itself bound to a @code{<package>} object.
1617 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1618 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1619 of ensuring that they are present (@pxref{Build Systems}).
1621 However, any other dependencies need to be specified in the
1622 @code{inputs} field. Any dependency not specified here will simply be
1623 unavailable to the build process, possibly leading to a build failure.
1626 Once a package definition is in place, the
1627 package may actually be built using the @code{guix build} command-line
1628 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1629 more information on how to test package definitions, and
1630 @ref{Invoking guix lint}, for information on how to check a definition
1631 for style conformance.
1633 Eventually, updating the package definition to a new upstream version
1634 can be partly automated by the @command{guix refresh} command
1635 (@pxref{Invoking guix refresh}).
1637 Behind the scenes, a derivation corresponding to the @code{<package>}
1638 object is first computed by the @code{package-derivation} procedure.
1639 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1640 The build actions it prescribes may then be realized by using the
1641 @code{build-derivations} procedure (@pxref{The Store}).
1643 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1644 Return the @code{<derivation>} object of @var{package} for @var{system}
1645 (@pxref{Derivations}).
1647 @var{package} must be a valid @code{<package>} object, and @var{system}
1648 must be a string denoting the target system type---e.g.,
1649 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1650 must be a connection to the daemon, which operates on the store
1651 (@pxref{The Store}).
1655 @cindex cross-compilation
1656 Similarly, it is possible to compute a derivation that cross-builds a
1657 package for some other system:
1659 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1660 @var{package} @var{target} [@var{system}]
1661 Return the @code{<derivation>} object of @var{package} cross-built from
1662 @var{system} to @var{target}.
1664 @var{target} must be a valid GNU triplet denoting the target hardware
1665 and operating system, such as @code{"mips64el-linux-gnu"}
1666 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1667 Configure and Build System}).
1672 @section Build Systems
1674 @cindex build system
1675 Each package definition specifies a @dfn{build system} and arguments for
1676 that build system (@pxref{Defining Packages}). This @code{build-system}
1677 field represents the build procedure of the package, as well implicit
1678 dependencies of that build procedure.
1680 Build systems are @code{<build-system>} objects. The interface to
1681 create and manipulate them is provided by the @code{(guix build-system)}
1682 module, and actual build systems are exported by specific modules.
1684 @cindex bag (low-level package representation)
1685 Under the hood, build systems first compile package objects to
1686 @dfn{bags}. A @dfn{bag} is like a package, but with less
1687 ornamentation---in other words, a bag is a lower-level representation of
1688 a package, which includes all the inputs of that package, including some
1689 that were implicitly added by the build system. This intermediate
1690 representation is then compiled to a derivation (@pxref{Derivations}).
1692 Build systems accept an optional list of @dfn{arguments}. In package
1693 definitions, these are passed @i{via} the @code{arguments} field
1694 (@pxref{Defining Packages}). They are typically keyword arguments
1695 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
1696 Guile Reference Manual}). The value of these arguments is usually
1697 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
1698 by the daemon (@pxref{Derivations}).
1700 The main build system is @var{gnu-build-system}, which implements the
1701 standard build procedure for GNU packages and many other packages. It
1702 is provided by the @code{(guix build-system gnu)} module.
1704 @defvr {Scheme Variable} gnu-build-system
1705 @var{gnu-build-system} represents the GNU Build System, and variants
1706 thereof (@pxref{Configuration, configuration and makefile conventions,,
1707 standards, GNU Coding Standards}).
1709 @cindex build phases
1710 In a nutshell, packages using it configured, built, and installed with
1711 the usual @code{./configure && make && make check && make install}
1712 command sequence. In practice, a few additional steps are often needed.
1713 All these steps are split up in separate @dfn{phases},
1714 notably@footnote{Please see the @code{(guix build gnu-build-system)}
1715 modules for more details about the build phases.}:
1719 Unpack the source tarball, and change the current directory to the
1720 extracted source tree. If the source is actually a directory, copy it
1721 to the build tree, and enter that directory.
1723 @item patch-source-shebangs
1724 Patch shebangs encountered in source files so they refer to the right
1725 store file names. For instance, this changes @code{#!/bin/sh} to
1726 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
1729 Run the @file{configure} script with a number of default options, such
1730 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
1731 by the @code{#:configure-flags} argument.
1734 Run @code{make} with the list of flags specified with
1735 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
1736 (the default), build with @code{make -j}.
1739 Run @code{make check}, or some other target specified with
1740 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
1741 @code{#:parallel-tests?} argument is true (the default), run @code{make
1745 Run @code{make install} with the flags listed in @code{#:make-flags}.
1747 @item patch-shebangs
1748 Patch shebangs on the installed executable files.
1751 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
1752 is false), copying them to the @code{debug} output when available
1753 (@pxref{Installing Debugging Files}).
1756 @vindex %standard-phases
1757 The build-side module @code{(guix build gnu-build-system)} defines
1758 @var{%standard-phases} as the default list of build phases.
1759 @var{%standard-phases} is a list of symbol/procedure pairs, where the
1760 procedure implements the actual phase.
1762 The list of phases used for a particular package can be changed with the
1763 @code{#:phases} parameter. For instance, passing:
1766 #:phases (alist-delete 'configure %standard-phases)
1769 means that all the phases described above will be used, except the
1770 @code{configure} phase.
1772 In addition, this build system ensures that the ``standard'' environment
1773 for GNU packages is available. This includes tools such as GCC, libc,
1774 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
1775 build-system gnu)} module for a complete list.) We call these the
1776 @dfn{implicit inputs} of a package, because package definitions don't
1777 have to mention them.
1780 Other @code{<build-system>} objects are defined to support other
1781 conventions and tools used by free software packages. They inherit most
1782 of @var{gnu-build-system}, and differ mainly in the set of inputs
1783 implicitly added to the build process, and in the list of phases
1784 executed. Some of these build systems are listed below.
1786 @defvr {Scheme Variable} cmake-build-system
1787 This variable is exported by @code{(guix build-system cmake)}. It
1788 implements the build procedure for packages using the
1789 @url{http://www.cmake.org, CMake build tool}.
1791 It automatically adds the @code{cmake} package to the set of inputs.
1792 Which package is used can be specified with the @code{#:cmake}
1795 The @code{#:configure-flags} parameter is taken as a list of flags
1796 passed to the @command{cmake} command. The @code{#:build-type}
1797 parameter specifies in abstract terms the flags passed to the compiler;
1798 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
1799 debugging information''), which roughly means that code is compiled with
1800 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
1803 @defvr {Scheme Variable} glib-or-gtk-build-system
1804 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
1805 is intended for use with packages making use of GLib or GTK+.
1807 This build system adds the following two phases to the ones defined by
1808 @var{gnu-build-system}:
1811 @item glib-or-gtk-wrap
1812 The phase @code{glib-or-gtk-wrap} ensures that programs found under
1813 @file{bin/} are able to find GLib's ``schemas'' and
1814 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
1815 modules}. This is achieved by wrapping the programs in launch scripts
1816 that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
1817 environment variables.
1819 It is possible to exclude specific package outputs from that wrapping
1820 process by listing their names in the
1821 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
1822 when an output is known not to contain any GLib or GTK+ binaries, and
1823 where wrapping would gratuitously add a dependency of that output on
1826 @item glib-or-gtk-compile-schemas
1827 The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
1828 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
1829 GSettings schemas} are compiled. Compilation is performed by the
1830 @command{glib-compile-schemas} program. It is provided by the package
1831 @code{glib:bin} which is automatically imported by the build system.
1832 The @code{glib} package providing @command{glib-compile-schemas} can be
1833 specified with the @code{#:glib} parameter.
1836 Both phases are executed after the @code{install} phase.
1839 @defvr {Scheme Variable} python-build-system
1840 This variable is exported by @code{(guix build-system python)}. It
1841 implements the more or less standard build procedure used by Python
1842 packages, which consists in running @code{python setup.py build} and
1843 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
1845 For packages that install stand-alone Python programs under @code{bin/},
1846 it takes care of wrapping these programs so their @code{PYTHONPATH}
1847 environment variable points to all the Python libraries they depend on.
1849 Which Python package is used can be specified with the @code{#:python}
1853 @defvr {Scheme Variable} perl-build-system
1854 This variable is exported by @code{(guix build-system perl)}. It
1855 implements the standard build procedure for Perl packages, which
1856 consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
1857 followed by @code{make} and @code{make install}.
1859 The initial @code{perl Makefile.PL} invocation passes flags specified by
1860 the @code{#:make-maker-flags} parameter.
1862 Which Perl package is used can be specified with @code{#:perl}.
1865 @defvr {Scheme Variable} ruby-build-system
1866 This variable is exported by @code{(guix build-system ruby)}. It
1867 implements the RubyGems build procedure used by Ruby packages, which
1868 involves running @code{gem build} followed by @code{gem install}.
1870 Which Ruby package is used can be specified with the @code{#:ruby}
1874 Lastly, for packages that do not need anything as sophisticated, a
1875 ``trivial'' build system is provided. It is trivial in the sense that
1876 it provides basically no support: it does not pull any implicit inputs,
1877 and does not have a notion of build phases.
1879 @defvr {Scheme Variable} trivial-build-system
1880 This variable is exported by @code{(guix build-system trivial)}.
1882 This build system requires a @code{#:builder} argument. This argument
1883 must be a Scheme expression that builds the package's output(s)---as
1884 with @code{build-expression->derivation} (@pxref{Derivations,
1885 @code{build-expression->derivation}}).
1894 Conceptually, the @dfn{store} is where derivations that have been
1895 successfully built are stored---by default, under @file{/gnu/store}.
1896 Sub-directories in the store are referred to as @dfn{store paths}. The
1897 store has an associated database that contains information such has the
1898 store paths referred to by each store path, and the list of @emph{valid}
1899 store paths---paths that result from a successful build.
1901 The store is always accessed by the daemon on behalf of its clients
1902 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1903 connect to the daemon over a Unix-domain socket, send it requests, and
1904 read the result---these are remote procedure calls, or RPCs.
1906 The @code{(guix store)} module provides procedures to connect to the
1907 daemon, and to perform RPCs. These are described below.
1909 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1910 Connect to the daemon over the Unix-domain socket at @var{file}. When
1911 @var{reserve-space?} is true, instruct it to reserve a little bit of
1912 extra space on the file system so that the garbage collector can still
1913 operate, should the disk become full. Return a server object.
1915 @var{file} defaults to @var{%default-socket-path}, which is the normal
1916 location given the options that were passed to @command{configure}.
1919 @deffn {Scheme Procedure} close-connection @var{server}
1920 Close the connection to @var{server}.
1923 @defvr {Scheme Variable} current-build-output-port
1924 This variable is bound to a SRFI-39 parameter, which refers to the port
1925 where build and error logs sent by the daemon should be written.
1928 Procedures that make RPCs all take a server object as their first
1931 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1932 Return @code{#t} when @var{path} is a valid store path.
1935 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1936 Add @var{text} under file @var{name} in the store, and return its store
1937 path. @var{references} is the list of store paths referred to by the
1938 resulting store path.
1941 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1942 Build @var{derivations} (a list of @code{<derivation>} objects or
1943 derivation paths), and return when the worker is done building them.
1944 Return @code{#t} on success.
1947 Note that the @code{(guix monads)} module provides a monad as well as
1948 monadic versions of the above procedures, with the goal of making it
1949 more convenient to work with code that accesses the store (@pxref{The
1953 @i{This section is currently incomplete.}
1956 @section Derivations
1959 Low-level build actions and the environment in which they are performed
1960 are represented by @dfn{derivations}. A derivation contain the
1961 following pieces of information:
1965 The outputs of the derivation---derivations produce at least one file or
1966 directory in the store, but may produce more.
1969 The inputs of the derivations, which may be other derivations or plain
1970 files in the store (patches, build scripts, etc.)
1973 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1976 The file name of a build script in the store, along with the arguments
1980 A list of environment variables to be defined.
1984 @cindex derivation path
1985 Derivations allow clients of the daemon to communicate build actions to
1986 the store. They exist in two forms: as an in-memory representation,
1987 both on the client- and daemon-side, and as files in the store whose
1988 name end in @code{.drv}---these files are referred to as @dfn{derivation
1989 paths}. Derivations paths can be passed to the @code{build-derivations}
1990 procedure to perform the build actions they prescribe (@pxref{The
1993 The @code{(guix derivations)} module provides a representation of
1994 derivations as Scheme objects, along with procedures to create and
1995 otherwise manipulate derivations. The lowest-level primitive to create
1996 a derivation is the @code{derivation} procedure:
1998 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
1999 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2000 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
2001 [#:system (%current-system)] [#:references-graphs #f] @
2002 [#:allowed-references #f] [#:local-build? #f]
2003 Build a derivation with the given arguments, and return the resulting
2004 @code{<derivation>} object.
2006 When @var{hash} and @var{hash-algo} are given, a
2007 @dfn{fixed-output derivation} is created---i.e., one whose result is
2008 known in advance, such as a file download. If, in addition,
2009 @var{recursive?} is true, then that fixed output may be an executable
2010 file or a directory and @var{hash} must be the hash of an archive
2011 containing this output.
2013 When @var{references-graphs} is true, it must be a list of file
2014 name/store path pairs. In that case, the reference graph of each store
2015 path is exported in the build environment in the corresponding file, in
2016 a simple text format.
2018 When @var{allowed-references} is true, it must be a list of store items
2019 or outputs that the derivation's output may refer to.
2021 When @var{local-build?} is true, declare that the derivation is not a
2022 good candidate for offloading and should rather be built locally
2023 (@pxref{Daemon Offload Setup}). This is the case for small derivations
2024 where the costs of data transfers would outweigh the benefits.
2028 Here's an example with a shell script as its builder, assuming
2029 @var{store} is an open connection to the daemon, and @var{bash} points
2030 to a Bash executable in the store:
2033 (use-modules (guix utils)
2037 (let ((builder ; add the Bash script to the store
2038 (add-text-to-store store "my-builder.sh"
2039 "echo hello world > $out\n" '())))
2040 (derivation store "foo"
2041 bash `("-e" ,builder)
2042 #:inputs `((,bash) (,builder))
2043 #:env-vars '(("HOME" . "/homeless"))))
2044 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
2047 As can be guessed, this primitive is cumbersome to use directly. A
2048 better approach is to write build scripts in Scheme, of course! The
2049 best course of action for that is to write the build code as a
2050 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
2051 information, @pxref{G-Expressions}.
2053 Once upon a time, @code{gexp->derivation} did not exist and constructing
2054 derivations with build code written in Scheme was achieved with
2055 @code{build-expression->derivation}, documented below. This procedure
2056 is now deprecated in favor of the much nicer @code{gexp->derivation}.
2058 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
2059 @var{name} @var{exp} @
2060 [#:system (%current-system)] [#:inputs '()] @
2061 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2062 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2063 [#:references-graphs #f] [#:allowed-references #f] @
2064 [#:local-build? #f] [#:guile-for-build #f]
2065 Return a derivation that executes Scheme expression @var{exp} as a
2066 builder for derivation @var{name}. @var{inputs} must be a list of
2067 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
2068 @code{"out"} is assumed. @var{modules} is a list of names of Guile
2069 modules from the current search path to be copied in the store,
2070 compiled, and made available in the load path during the execution of
2071 @var{exp}---e.g., @code{((guix build utils) (guix build
2072 gnu-build-system))}.
2074 @var{exp} is evaluated in an environment where @code{%outputs} is bound
2075 to a list of output/path pairs, and where @code{%build-inputs} is bound
2076 to a list of string/output-path pairs made from @var{inputs}.
2077 Optionally, @var{env-vars} is a list of string pairs specifying the name
2078 and value of environment variables visible to the builder. The builder
2079 terminates by passing the result of @var{exp} to @code{exit}; thus, when
2080 @var{exp} returns @code{#f}, the build is considered to have failed.
2082 @var{exp} is built using @var{guile-for-build} (a derivation). When
2083 @var{guile-for-build} is omitted or is @code{#f}, the value of the
2084 @code{%guile-for-build} fluid is used instead.
2086 See the @code{derivation} procedure for the meaning of
2087 @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
2091 Here's an example of a single-output derivation that creates a directory
2092 containing one file:
2095 (let ((builder '(let ((out (assoc-ref %outputs "out")))
2096 (mkdir out) ; create /gnu/store/@dots{}-goo
2097 (call-with-output-file (string-append out "/test")
2099 (display '(hello guix) p))))))
2100 (build-expression->derivation store "goo" builder))
2102 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
2106 @node The Store Monad
2107 @section The Store Monad
2111 The procedures that operate on the store described in the previous
2112 sections all take an open connection to the build daemon as their first
2113 argument. Although the underlying model is functional, they either have
2114 side effects or depend on the current state of the store.
2116 The former is inconvenient: the connection to the build daemon has to be
2117 carried around in all those functions, making it impossible to compose
2118 functions that do not take that parameter with functions that do. The
2119 latter can be problematic: since store operations have side effects
2120 and/or depend on external state, they have to be properly sequenced.
2122 @cindex monadic values
2123 @cindex monadic functions
2124 This is where the @code{(guix monads)} module comes in. This module
2125 provides a framework for working with @dfn{monads}, and a particularly
2126 useful monad for our uses, the @dfn{store monad}. Monads are a
2127 construct that allows two things: associating ``context'' with values
2128 (in our case, the context is the store), and building sequences of
2129 computations (here computations includes accesses to the store.) Values
2130 in a monad---values that carry this additional context---are called
2131 @dfn{monadic values}; procedures that return such values are called
2132 @dfn{monadic procedures}.
2134 Consider this ``normal'' procedure:
2137 (define (sh-symlink store)
2138 ;; Return a derivation that symlinks the 'bash' executable.
2139 (let* ((drv (package-derivation store bash))
2140 (out (derivation->output-path drv))
2141 (sh (string-append out "/bin/bash")))
2142 (build-expression->derivation store "sh"
2143 `(symlink ,sh %output))))
2146 Using @code{(guix monads)}, it may be rewritten as a monadic function:
2148 @c FIXME: Find a better example, one that uses 'mlet'.
2150 (define (sh-symlink)
2151 ;; Same, but return a monadic value.
2152 (gexp->derivation "sh"
2153 #~(symlink (string-append #$bash "/bin/bash") #$output)))
2156 There are two things to note in the second version: the @code{store}
2157 parameter is now implicit, and the monadic value returned by
2158 @code{package-file}---a wrapper around @code{package-derivation} and
2159 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
2160 instead of plain @code{let}.
2162 Calling the monadic @code{profile.sh} has no effect. To get the desired
2163 effect, one must use @code{run-with-store}:
2166 (run-with-store (open-connection) (profile.sh))
2167 @result{} /gnu/store/...-profile.sh
2170 Note that the @code{(guix monad-repl)} module extends Guile's REPL with
2171 new ``meta-commands'' to make it easier to deal with monadic procedures:
2172 @code{run-in-store}, and @code{enter-store-monad}. The former, is used
2173 to ``run'' a single monadic value through the store:
2176 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
2177 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2180 The latter enters a recursive REPL, where all the return values are
2181 automatically run through the store:
2184 scheme@@(guile-user)> ,enter-store-monad
2185 store-monad@@(guile-user) [1]> (package->derivation hello)
2186 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2187 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
2188 $3 = "/gnu/store/@dots{}-foo"
2189 store-monad@@(guile-user) [1]> ,q
2190 scheme@@(guile-user)>
2194 Note that non-monadic values cannot be returned in the
2195 @code{store-monad} REPL.
2197 The main syntactic forms to deal with monads in general are described
2200 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
2201 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
2205 @deffn {Scheme Syntax} return @var{val}
2206 Return a monadic value that encapsulates @var{val}.
2209 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
2210 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
2211 procedure @var{mproc}@footnote{This operation is commonly referred to as
2212 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
2213 we use this somewhat cryptic symbol inherited from the Haskell
2217 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
2219 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
2221 Bind the variables @var{var} to the monadic values @var{mval} in
2222 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
2223 ``normal'' value @var{val}, as per @code{let}.
2225 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
2226 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
2229 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
2230 Bind @var{mexp} and the following monadic expressions in sequence,
2231 returning the result of the last expression.
2233 This is akin to @code{mlet}, except that the return values of the
2234 monadic expressions are ignored. In that sense, it is analogous to
2235 @code{begin}, but applied to monadic expressions.
2238 The interface to the store monad provided by @code{(guix monads)} is as
2241 @defvr {Scheme Variable} %store-monad
2242 The store monad. Values in the store monad encapsulate accesses to the
2243 store. When its effect is needed, a value of the store monad must be
2244 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
2248 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
2249 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
2250 open store connection.
2253 @deffn {Monadic Procedure} text-file @var{name} @var{text}
2254 Return as a monadic value the absolute file name in the store of the file
2255 containing @var{text}, a string.
2258 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
2259 Return as a monadic value a derivation that builds a text file
2260 containing all of @var{text}. @var{text} may list, in addition to
2261 strings, packages, derivations, and store file names; the resulting
2262 store file holds references to all these.
2264 This variant should be preferred over @code{text-file} anytime the file
2265 to create will reference items from the store. This is typically the
2266 case when building a configuration file that embeds store file names,
2270 (define (profile.sh)
2271 ;; Return the name of a shell script in the store that
2272 ;; initializes the 'PATH' environment variable.
2273 (text-file* "profile.sh"
2274 "export PATH=" coreutils "/bin:"
2275 grep "/bin:" sed "/bin\n"))
2278 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
2279 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
2280 preventing them from being garbage-collected during its lifetime.
2283 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
2285 Return the name of @var{file} once interned in the store. Use
2286 @var{name} as its store name, or the basename of @var{file} if
2287 @var{name} is omitted.
2289 When @var{recursive?} is true, the contents of @var{file} are added
2290 recursively; if @var{file} designates a flat file and @var{recursive?}
2291 is true, its contents are added, and its permission bits are kept.
2293 The example below adds a file to the store, under two different names:
2296 (run-with-store (open-connection)
2297 (mlet %store-monad ((a (interned-file "README"))
2298 (b (interned-file "README" "LEGU-MIN")))
2299 (return (list a b))))
2301 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
2306 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
2307 [#:system (%current-system)] [#:target #f] @
2308 [#:output "out"] Return as a monadic
2309 value in the absolute file name of @var{file} within the @var{output}
2310 directory of @var{package}. When @var{file} is omitted, return the name
2311 of the @var{output} directory of @var{package}. When @var{target} is
2312 true, use it as a cross-compilation target triplet.
2315 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
2316 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
2317 @var{target} [@var{system}]
2318 Monadic version of @code{package-derivation} and
2319 @code{package-cross-derivation} (@pxref{Defining Packages}).
2324 @section G-Expressions
2326 @cindex G-expression
2327 @cindex build code quoting
2328 So we have ``derivations'', which represent a sequence of build actions
2329 to be performed to produce an item in the store (@pxref{Derivations}).
2330 Those build actions are performed when asking the daemon to actually
2331 build the derivations; they are run by the daemon in a container
2332 (@pxref{Invoking guix-daemon}).
2334 @cindex strata of code
2335 It should come as no surprise that we like to write those build actions
2336 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2337 code@footnote{The term @dfn{stratum} in this context was coined by
2338 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2339 Kiselyov, who has written insightful
2340 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2341 on this topic}, refers to this kind of code generation as
2342 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2343 to the daemon, etc.---and the ``build code''---code that actually
2344 performs build actions, such as making directories, invoking
2345 @command{make}, etc.
2347 To describe a derivation and its build actions, one typically needs to
2348 embed build code inside host code. It boils down to manipulating build
2349 code as data, and Scheme's homoiconicity---code has a direct
2350 representation as data---comes in handy for that. But we need more than
2351 Scheme's normal @code{quasiquote} mechanism to construct build
2354 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2355 S-expressions adapted to build expressions. G-expressions, or
2356 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2357 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2358 @code{#$}, and @code{#$@@}), which are comparable respectively to
2359 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2360 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2361 Reference Manual}). However, there are major differences:
2365 Gexps are meant to be written to a file and run or manipulated by other
2369 When a package or derivation is unquoted inside a gexp, the result is as
2370 if its output file name had been introduced.
2373 Gexps carry information about the packages or derivations they refer to,
2374 and these dependencies are automatically added as inputs to the build
2375 processes that use them.
2378 To illustrate the idea, here is an example of a gexp:
2385 (symlink (string-append #$coreutils "/bin/ls")
2389 This gexp can be passed to @code{gexp->derivation}; we obtain a
2390 derivation that builds a directory containing exactly one symlink to
2391 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2394 (gexp->derivation "the-thing" build-exp)
2397 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2398 substituted to the reference to the @var{coreutils} package in the
2399 actual build code, and @var{coreutils} is automatically made an input to
2400 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2401 output)}) is replaced by a string containing the derivation's output
2404 @cindex cross compilation
2405 In a cross-compilation context, it is useful to distinguish between
2406 references to the @emph{native} build of a package---that can run on the
2407 host---versus references to cross builds of a package. To that end, the
2408 @code{#+} plays the same role as @code{#$}, but is a reference to a
2409 native package build:
2412 (gexp->derivation "vi"
2415 (system* (string-append #+coreutils "/bin/ln")
2417 (string-append #$emacs "/bin/emacs")
2418 (string-append #$output "/bin/vi")))
2419 #:target "mips64el-linux")
2423 In the example above, the native build of @var{coreutils} is used, so
2424 that @command{ln} can actually run on the host; but then the
2425 cross-compiled build of @var{emacs} is referenced.
2427 The syntactic form to construct gexps is summarized below.
2429 @deffn {Scheme Syntax} #~@var{exp}
2430 @deffnx {Scheme Syntax} (gexp @var{exp})
2431 Return a G-expression containing @var{exp}. @var{exp} may contain one
2432 or more of the following forms:
2436 @itemx (ungexp @var{obj})
2437 Introduce a reference to @var{obj}. @var{obj} may be a package or a
2438 derivation, in which case the @code{ungexp} form is replaced by its
2439 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2441 If @var{obj} is a list, it is traversed and any package or derivation
2442 references are substituted similarly.
2444 If @var{obj} is another gexp, its contents are inserted and its
2445 dependencies are added to those of the containing gexp.
2447 If @var{obj} is another kind of object, it is inserted as is.
2449 @item #$@var{package-or-derivation}:@var{output}
2450 @itemx (ungexp @var{package-or-derivation} @var{output})
2451 This is like the form above, but referring explicitly to the
2452 @var{output} of @var{package-or-derivation}---this is useful when
2453 @var{package-or-derivation} produces multiple outputs (@pxref{Packages
2454 with Multiple Outputs}).
2457 @itemx #+@var{obj}:output
2458 @itemx (ungexp-native @var{obj})
2459 @itemx (ungexp-native @var{obj} @var{output})
2460 Same as @code{ungexp}, but produces a reference to the @emph{native}
2461 build of @var{obj} when used in a cross compilation context.
2463 @item #$output[:@var{output}]
2464 @itemx (ungexp output [@var{output}])
2465 Insert a reference to derivation output @var{output}, or to the main
2466 output when @var{output} is omitted.
2468 This only makes sense for gexps passed to @code{gexp->derivation}.
2471 @itemx (ungexp-splicing @var{lst})
2472 Like the above, but splices the contents of @var{lst} inside the
2476 @itemx (ungexp-native-splicing @var{lst})
2477 Like the above, but refers to native builds of the objects listed in
2482 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2483 of the @code{gexp?} type (see below.)
2486 @deffn {Scheme Procedure} gexp? @var{obj}
2487 Return @code{#t} if @var{obj} is a G-expression.
2490 G-expressions are meant to be written to disk, either as code building
2491 some derivation, or as plain files in the store. The monadic procedures
2492 below allow you to do that (@pxref{The Store Monad}, for more
2493 information about monads.)
2495 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2496 [#:system (%current-system)] [#:target #f] [#:inputs '()] @
2497 [#:hash #f] [#:hash-algo #f] @
2498 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2499 [#:module-path @var{%load-path}] @
2500 [#:references-graphs #f] [#:local-build? #f] @
2501 [#:guile-for-build #f]
2502 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2503 @var{guile-for-build} (a derivation) on @var{system}. When @var{target}
2504 is true, it is used as the cross-compilation target triplet for packages
2505 referred to by @var{exp}.
2507 Make @var{modules} available in the evaluation context of @var{EXP};
2508 @var{MODULES} is a list of names of Guile modules searched in
2509 @var{MODULE-PATH} to be copied in the store, compiled, and made available in
2510 the load path during the execution of @var{exp}---e.g., @code{((guix
2511 build utils) (guix build gnu-build-system))}.
2513 When @var{references-graphs} is true, it must be a list of tuples of one of the
2517 (@var{file-name} @var{package})
2518 (@var{file-name} @var{package} @var{output})
2519 (@var{file-name} @var{derivation})
2520 (@var{file-name} @var{derivation} @var{output})
2521 (@var{file-name} @var{store-item})
2524 The right-hand-side of each element of @var{references-graphs} is automatically made
2525 an input of the build process of @var{exp}. In the build environment, each
2526 @var{file-name} contains the reference graph of the corresponding item, in a simple
2529 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2532 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2533 Return an executable script @var{name} that runs @var{exp} using
2534 @var{guile} with @var{modules} in its search path.
2536 The example below builds a script that simply invokes the @command{ls}
2540 (use-modules (guix gexp) (gnu packages base))
2542 (gexp->script "list-files"
2543 #~(execl (string-append #$coreutils "/bin/ls")
2547 When ``running'' it through the store (@pxref{The Store Monad,
2548 @code{run-with-store}}), we obtain a derivation that produces an
2549 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2552 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2554 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2559 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2560 Return a derivation that builds a file @var{name} containing @var{exp}.
2562 The resulting file holds references to all the dependencies of @var{exp}
2563 or a subset thereof.
2566 Of course, in addition to gexps embedded in ``host'' code, there are
2567 also modules containing build tools. To make it clear that they are
2568 meant to be used in the build stratum, these modules are kept in the
2569 @code{(guix build @dots{})} name space.
2572 @c *********************************************************************
2576 This section describes tools primarily targeted at developers and users
2577 who write new package definitions. They complement the Scheme
2578 programming interface of Guix in a convenient way.
2581 * Invoking guix build:: Building packages from the command line.
2582 * Invoking guix download:: Downloading a file and printing its hash.
2583 * Invoking guix hash:: Computing the cryptographic hash of a file.
2584 * Invoking guix import:: Importing package definitions.
2585 * Invoking guix refresh:: Updating package definitions.
2586 * Invoking guix lint:: Finding errors in package definitions.
2587 * Invoking guix environment:: Setting up development environments.
2590 @node Invoking guix build
2591 @section Invoking @command{guix build}
2593 The @command{guix build} command builds packages or derivations and
2594 their dependencies, and prints the resulting store paths. Note that it
2595 does not modify the user's profile---this is the job of the
2596 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2597 it is mainly useful for distribution developers.
2599 The general syntax is:
2602 guix build @var{options} @var{package-or-derivation}@dots{}
2605 @var{package-or-derivation} may be either the name of a package found in
2606 the software distribution such as @code{coreutils} or
2607 @code{coreutils-8.20}, or a derivation such as
2608 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2609 package with the corresponding name (and optionally version) is searched
2610 for among the GNU distribution modules (@pxref{Package Modules}).
2612 Alternatively, the @code{--expression} option may be used to specify a
2613 Scheme expression that evaluates to a package; this is useful when
2614 disambiguation among several same-named packages or package variants is
2617 The @var{options} may be zero or more of the following:
2621 @item --expression=@var{expr}
2622 @itemx -e @var{expr}
2623 Build the package or derivation @var{expr} evaluates to.
2625 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2626 guile-1.8)}, which unambiguously designates this specific variant of
2627 version 1.8 of Guile.
2629 Alternately, @var{expr} may be a G-expression, in which case it is used
2630 as a build program passed to @code{gexp->derivation}
2631 (@pxref{G-Expressions}).
2633 Lastly, @var{expr} may refer to a zero-argument monadic procedure
2634 (@pxref{The Store Monad}). The procedure must return a derivation as a
2635 monadic value, which is then passed through @code{run-with-store}.
2639 Build the packages' source derivations, rather than the packages
2642 For instance, @code{guix build -S gcc} returns something like
2643 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2645 The returned source tarball is the result of applying any patches and
2646 code snippets specified in the package's @code{origin} (@pxref{Defining
2649 @item --system=@var{system}
2650 @itemx -s @var{system}
2651 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
2652 the host's system type.
2654 An example use of this is on Linux-based systems, which can emulate
2655 different personalities. For instance, passing
2656 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
2657 to build packages in a complete 32-bit environment.
2659 @item --target=@var{triplet}
2660 @cindex cross-compilation
2661 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
2662 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
2663 configuration triplets,, configure, GNU Configure and Build System}).
2665 @item --with-source=@var{source}
2666 Use @var{source} as the source of the corresponding package.
2667 @var{source} must be a file name or a URL, as for @command{guix
2668 download} (@pxref{Invoking guix download}).
2670 The ``corresponding package'' is taken to be one specified on the
2671 command line whose name matches the base of @var{source}---e.g., if
2672 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
2673 package is @code{guile}. Likewise, the version string is inferred from
2674 @var{source}; in the previous example, it's @code{2.0.10}.
2676 This option allows users to try out versions of packages other than the
2677 one provided by the distribution. The example below downloads
2678 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
2679 the @code{ed} package:
2682 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
2685 As a developer, @code{--with-source} makes it easy to test release
2689 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
2693 Do not ``graft'' packages. In practice, this means that package updates
2694 available as grafts are not applied. @xref{Security Updates}, for more
2695 information on grafts.
2699 Return the derivation paths, not the output paths, of the given
2702 @item --root=@var{file}
2703 @itemx -r @var{file}
2704 Make @var{file} a symlink to the result, and register it as a garbage
2708 Return the build log file names for the given
2709 @var{package-or-derivation}s, or raise an error if build logs are
2712 This works regardless of how packages or derivations are specified. For
2713 instance, the following invocations are equivalent:
2716 guix build --log-file `guix build -d guile`
2717 guix build --log-file `guix build guile`
2718 guix build --log-file guile
2719 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
2725 @cindex common build options
2726 In addition, a number of options that control the build process are
2727 common to @command{guix build} and other commands that can spawn builds,
2728 such as @command{guix package} or @command{guix archive}. These are the
2733 @item --load-path=@var{directory}
2734 @itemx -L @var{directory}
2735 Add @var{directory} to the front of the package module search path
2736 (@pxref{Package Modules}).
2738 This allows users to define their own packages and make them visible to
2739 the command-line tools.
2743 Keep the build tree of failed builds. Thus, if a build fail, its build
2744 tree is kept under @file{/tmp}, in a directory whose name is shown at
2745 the end of the build log. This is useful when debugging build issues.
2749 Do not build the derivations.
2752 When substituting a pre-built binary fails, fall back to building
2755 @item --no-substitutes
2756 Do not use substitutes for build products. That is, always build things
2757 locally instead of allowing downloads of pre-built binaries
2758 (@pxref{Substitutes}).
2760 @item --no-build-hook
2761 Do not attempt to offload builds @i{via} the daemon's ``build hook''
2762 (@pxref{Daemon Offload Setup}). That is, always build things locally
2763 instead of offloading builds to remote machines.
2765 @item --max-silent-time=@var{seconds}
2766 When the build or substitution process remains silent for more than
2767 @var{seconds}, terminate it and report a build failure.
2769 @item --timeout=@var{seconds}
2770 Likewise, when the build or substitution process lasts for more than
2771 @var{seconds}, terminate it and report a build failure.
2773 By default there is no timeout. This behavior can be restored with
2776 @item --verbosity=@var{level}
2777 Use the given verbosity level. @var{level} must be an integer between 0
2778 and 5; higher means more verbose output. Setting a level of 4 or more
2779 may be helpful when debugging setup issues with the build daemon.
2781 @item --cores=@var{n}
2783 Allow the use of up to @var{n} CPU cores for the build. The special
2784 value @code{0} means to use as many CPU cores as available.
2786 @item --max-jobs=@var{n}
2788 Allow at most @var{n} build jobs in parallel. @xref{Invoking
2789 guix-daemon, @code{--max-jobs}}, for details about this option and the
2790 equivalent @command{guix-daemon} option.
2794 Behind the scenes, @command{guix build} is essentially an interface to
2795 the @code{package-derivation} procedure of the @code{(guix packages)}
2796 module, and to the @code{build-derivations} procedure of the @code{(guix
2799 In addition to options explicitly passed on the command line,
2800 @command{guix build} and other @command{guix} commands that support
2801 building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
2803 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
2804 Users can define this variable to a list of command line options that
2805 will automatically be used by @command{guix build} and other
2806 @command{guix} commands that can perform builds, as in the example
2810 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
2813 These options are parsed independently, and the result is appended to
2814 the parsed command-line options.
2818 @node Invoking guix download
2819 @section Invoking @command{guix download}
2821 When writing a package definition, developers typically need to download
2822 the package's source tarball, compute its SHA256 hash, and write that
2823 hash in the package definition (@pxref{Defining Packages}). The
2824 @command{guix download} tool helps with this task: it downloads a file
2825 from the given URI, adds it to the store, and prints both its file name
2826 in the store and its SHA256 hash.
2828 The fact that the downloaded file is added to the store saves bandwidth:
2829 when the developer eventually tries to build the newly defined package
2830 with @command{guix build}, the source tarball will not have to be
2831 downloaded again because it is already in the store. It is also a
2832 convenient way to temporarily stash files, which may be deleted
2833 eventually (@pxref{Invoking guix gc}).
2835 The @command{guix download} command supports the same URIs as used in
2836 package definitions. In particular, it supports @code{mirror://} URIs.
2837 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
2838 Guile bindings for GnuTLS are available in the user's environment; when
2839 they are not available, an error is raised. @xref{Guile Preparations,
2840 how to install the GnuTLS bindings for Guile,, gnutls-guile,
2841 GnuTLS-Guile}, for more information.
2843 The following option is available:
2846 @item --format=@var{fmt}
2848 Write the hash in the format specified by @var{fmt}. For more
2849 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
2852 @node Invoking guix hash
2853 @section Invoking @command{guix hash}
2855 The @command{guix hash} command computes the SHA256 hash of a file.
2856 It is primarily a convenience tool for anyone contributing to the
2857 distribution: it computes the cryptographic hash of a file, which can be
2858 used in the definition of a package (@pxref{Defining Packages}).
2860 The general syntax is:
2863 guix hash @var{option} @var{file}
2866 @command{guix hash} has the following option:
2870 @item --format=@var{fmt}
2872 Write the hash in the format specified by @var{fmt}.
2874 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
2875 (@code{hex} and @code{hexadecimal} can be used as well).
2877 If the @option{--format} option is not specified, @command{guix hash}
2878 will output the hash in @code{nix-base32}. This representation is used
2879 in the definitions of packages.
2883 Compute the hash on @var{file} recursively.
2885 In this case, the hash is computed on an archive containing @var{file},
2886 including its children if it is a directory. Some of @var{file}'s
2887 meta-data is part of the archive; for instance, when @var{file} is a
2888 regular file, the hash is different depending on whether @var{file} is
2889 executable or not. Meta-data such as time stamps has no impact on the
2890 hash (@pxref{Invoking guix archive}).
2891 @c FIXME: Replace xref above with xref to an ``Archive'' section when
2896 @node Invoking guix import
2897 @section Invoking @command{guix import}
2899 @cindex importing packages
2900 @cindex package import
2901 @cindex package conversion
2902 The @command{guix import} command is useful for people willing to add a
2903 package to the distribution but who'd rather do as little work as
2904 possible to get there---a legitimate demand. The command knows of a few
2905 repositories from which it can ``import'' package meta-data. The result
2906 is a package definition, or a template thereof, in the format we know
2907 (@pxref{Defining Packages}).
2909 The general syntax is:
2912 guix import @var{importer} @var{options}@dots{}
2915 @var{importer} specifies the source from which to import package
2916 meta-data, and @var{options} specifies a package identifier and other
2917 options specific to @var{importer}. Currently, the available
2922 Import meta-data for the given GNU package. This provides a template
2923 for the latest version of that GNU package, including the hash of its
2924 source tarball, and its canonical synopsis and description.
2926 Additional information such as the package's dependencies and its
2927 license needs to be figured out manually.
2929 For example, the following command returns a package definition for
2933 guix import gnu hello
2936 Specific command-line options are:
2939 @item --key-download=@var{policy}
2940 As for @code{guix refresh}, specify the policy to handle missing OpenPGP
2941 keys when verifying the package's signature. @xref{Invoking guix
2942 refresh, @code{--key-download}}.
2947 Import meta-data from the @uref{https://pypi.python.org/, Python Package
2948 Index}@footnote{This functionality requires Guile-JSON to be installed.
2949 @xref{Requirements}.}. Information is taken from the JSON-formatted
2950 description available at @code{pypi.python.org} and usually includes all
2951 the relevant information, including package dependencies.
2953 The command below imports meta-data for the @code{itsdangerous} Python
2957 guix import pypi itsdangerous
2962 Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
2963 Information is taken from the JSON-formatted meta-data provided through
2964 @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
2965 relevant information. License information should be checked closely.
2966 Package dependencies are included but may in some cases needlessly
2967 include core Perl modules.
2969 The command command below imports meta-data for the @code{Acme::Boolean}
2973 guix import cpan Acme::Boolean
2977 Import meta-data from a local copy of the source of the
2978 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
2979 relies on the @command{nix-instantiate} command of
2980 @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
2981 typically written in a mixture of Nix-language and Bash code. This
2982 command only imports the high-level package structure that is written in
2983 the Nix language. It normally includes all the basic fields of a
2986 When importing a GNU package, the synopsis and descriptions are replaced
2987 by their canonical upstream variant.
2989 As an example, the command below imports the package definition of
2990 LibreOffice (more precisely, it imports the definition of the package
2991 bound to the @code{libreoffice} top-level attribute):
2994 guix import nix ~/path/to/nixpkgs libreoffice
2998 The structure of the @command{guix import} code is modular. It would be
2999 useful to have more importers for other package formats, and your help
3000 is welcome here (@pxref{Contributing}).
3002 @node Invoking guix refresh
3003 @section Invoking @command{guix refresh}
3005 The primary audience of the @command{guix refresh} command is developers
3006 of the GNU software distribution. By default, it reports any packages
3007 provided by the distribution that are outdated compared to the latest
3008 upstream version, like this:
3012 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
3013 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
3016 It does so by browsing each package's FTP directory and determining the
3017 highest version number of the source tarballs
3018 therein@footnote{Currently, this only works for GNU packages.}.
3020 When passed @code{--update}, it modifies distribution source files to
3021 update the version numbers and source tarball hashes of those packages'
3022 recipes (@pxref{Defining Packages}). This is achieved by downloading
3023 each package's latest source tarball and its associated OpenPGP
3024 signature, authenticating the downloaded tarball against its signature
3025 using @command{gpg}, and finally computing its hash. When the public
3026 key used to sign the tarball is missing from the user's keyring, an
3027 attempt is made to automatically retrieve it from a public key server;
3028 when it's successful, the key is added to the user's keyring; otherwise,
3029 @command{guix refresh} reports an error.
3031 The following options are supported:
3037 Update distribution source files (package recipes) in place.
3038 @xref{Defining Packages}, for more information on package definitions.
3040 @item --select=[@var{subset}]
3041 @itemx -s @var{subset}
3042 Select all the packages in @var{subset}, one of @code{core} or
3045 The @code{core} subset refers to all the packages at the core of the
3046 distribution---i.e., packages that are used to build ``everything
3047 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
3048 changing one of these packages in the distribution entails a rebuild of
3049 all the others. Thus, such updates are an inconvenience to users in
3050 terms of build time or bandwidth used to achieve the upgrade.
3052 The @code{non-core} subset refers to the remaining packages. It is
3053 typically useful in cases where an update of the core packages would be
3058 In addition, @command{guix refresh} can be passed one or more package
3059 names, as in this example:
3062 guix refresh -u emacs idutils
3066 The command above specifically updates the @code{emacs} and
3067 @code{idutils} packages. The @code{--select} option would have no
3068 effect in this case.
3070 When considering whether to upgrade a package, it is sometimes
3071 convenient to know which packages would be affected by the upgrade and
3072 should be checked for compatibility. For this the following option may
3073 be used when passing @command{guix refresh} one or more package names:
3077 @item --list-dependent
3079 List top-level dependent packages that would need to be rebuilt as a
3080 result of upgrading one or more packages.
3084 Be aware that the @code{--list-dependent} option only
3085 @emph{approximates} the rebuilds that would be required as a result of
3086 an upgrade. More rebuilds might be required under some circumstances.
3089 $ guix refresh --list-dependent flex
3090 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
3091 hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
3094 The command above lists a set of packages that could be built to check
3095 for compatibility with an upgraded @code{flex} package.
3097 The following options can be used to customize GnuPG operation:
3101 @item --gpg=@var{command}
3102 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
3103 for in @code{$PATH}.
3105 @item --key-download=@var{policy}
3106 Handle missing OpenPGP keys according to @var{policy}, which may be one
3111 Always download missing OpenPGP keys from the key server, and add them
3112 to the user's GnuPG keyring.
3115 Never try to download missing OpenPGP keys. Instead just bail out.
3118 When a package signed with an unknown OpenPGP key is encountered, ask
3119 the user whether to download it or not. This is the default behavior.
3122 @item --key-server=@var{host}
3123 Use @var{host} as the OpenPGP key server when importing a public key.
3127 @node Invoking guix lint
3128 @section Invoking @command{guix lint}
3129 The @command{guix lint} is meant to help package developers avoid common
3130 errors and use a consistent style. It runs a few checks on a given set of
3131 packages in order to find common mistakes in their definitions.
3133 The general syntax is:
3136 guix lint @var{options} @var{package}@dots{}
3139 If no package is given on the command line, then all packages are checked.
3140 The @var{options} may be zero or more of the following:
3146 Only enable the checkers specified in a comma-separated list using the
3147 names returned by @code{--list-checkers}.
3149 @item --list-checkers
3151 List and describe all the available checkers that will be run on packages
3156 @node Invoking guix environment
3157 @section Invoking @command{guix environment}
3159 @cindex reproducible build environments
3160 The purpose of @command{guix environment} is to assist hackers in
3161 creating reproducible development environments without polluting their
3162 package profile. The @command{guix environment} tool takes one or more
3163 packages, builds all of the necessary inputs, and creates a shell
3164 environment to use them.
3166 The general syntax is:
3169 guix environment @var{options} @var{package}@dots{}
3172 The following examples spawns a new shell that is capable of building
3173 the GNU Guile source code:
3176 guix environment guile
3179 If the specified packages are not built yet, @command{guix environment}
3180 automatically builds them. The new shell's environment is an augmented
3181 version of the environment that @command{guix environment} was run in.
3182 It contains the necessary search paths for building the given package
3183 added to the existing environment variables. To create a ``pure''
3184 environment in which the original environment variables have been unset,
3185 use the @code{--pure} option.
3187 Additionally, more than one package may be specified, in which case the
3188 union of the inputs for the given packages are used. For example, the
3189 command below spawns a shell where all of the dependencies of both Guile
3190 and Emacs are available:
3193 guix environment guile emacs
3196 Sometimes an interactive shell session is not desired. The
3197 @code{--exec} option can be used to specify the command to run instead.
3200 guix environment guile --exec=make
3203 The following options are available:
3206 @item --expression=@var{expr}
3207 @itemx -e @var{expr}
3208 Create an environment for the package that @var{expr} evaluates to.
3210 @item --load=@var{file}
3211 @itemx -l @var{file}
3212 Create an environment for the package that the code within @var{file}
3215 @item --exec=@var{command}
3216 @item -E @var{command}
3217 Execute @var{command} in the new environment.
3220 Unset existing environment variables when building the new environment.
3221 This has the effect of creating an environment in which search paths
3222 only contain package inputs.
3224 @item --search-paths
3225 Display the environment variable definitions that make up the
3229 It also supports all of the common build options that @command{guix
3230 build} supports (@pxref{Invoking guix build, common build options}).
3232 @c *********************************************************************
3233 @node GNU Distribution
3234 @chapter GNU Distribution
3236 Guix comes with a distribution of free software@footnote{The term
3237 ``free'' here refers to the
3238 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
3239 users of that software}.} that forms the basis of the GNU system. This
3240 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
3241 as many GNU and non-GNU applications. The complete list of available
3242 packages can be browsed
3243 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
3244 running @command{guix package} (@pxref{Invoking guix package}):
3247 guix package --list-available
3250 Our goal is to build a practical 100% free software distribution of
3251 Linux-based and other variants of GNU, with a focus on the promotion and
3252 tight integration of GNU components, and an emphasis on programs and
3253 tools that help users exert that freedom.
3255 The GNU distribution is currently available on the following platforms:
3260 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
3263 Intel 32-bit architecture (IA32), Linux-Libre kernel;
3265 @item mips64el-linux
3266 little-endian 64-bit MIPS processors, specifically the Loongson series,
3267 n32 application binary interface (ABI), and Linux-Libre kernel.
3272 For information on porting to other architectures or kernels,
3276 * System Installation:: Installing the whole operating system.
3277 * System Configuration:: Configuring a GNU system.
3278 * Installing Debugging Files:: Feeding the debugger.
3279 * Security Updates:: Deploying security fixes quickly.
3280 * Package Modules:: Packages from the programmer's viewpoint.
3281 * Packaging Guidelines:: Growing the distribution.
3282 * Bootstrapping:: GNU/Linux built from scratch.
3283 * Porting:: Targeting another platform or kernel.
3286 Building this distribution is a cooperative effort, and you are invited
3287 to join! @xref{Contributing}, for information about how you can help.
3289 @node System Installation
3290 @section System Installation
3292 This section explains how to install the complete GNU operating system
3293 on a machine. The Guix package manager can also be installed on top of
3294 a running GNU/Linux system, @pxref{Installation}.
3297 @c This paragraph is for people reading this from tty2 of the
3298 @c installation image.
3299 You're reading this documentation with an Info reader. For details on
3300 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
3301 link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
3302 @kbd{l} afterwards to come back here.
3305 @subsection Limitations
3307 As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
3308 distribution are alpha software. It may contain bugs and lack important
3309 features. Thus, if you are looking for a stable production system that
3310 respects your freedom as a computer user, a good solution at this point
3311 is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
3312 more established GNU/Linux distributions}. We hope you can soon switch
3313 to the GNU system without fear, of course. In the meantime, you can
3314 also keep using your distribution and try out the package manager on top
3315 of it (@pxref{Installation}).
3317 Before you proceed with the installation, be aware of the following
3318 noteworthy limitations applicable to version @value{VERSION}:
3322 The installation process does not include a graphical user interface and
3323 requires familiarity with GNU/Linux (see the following subsections to
3324 get a feel of what that means.)
3327 The system does not yet provide graphical desktop environments such as
3331 Support for the Logical Volume Manager (LVM) is missing.
3334 Few system services are currently supported out-of-the-box
3338 On the order of 1,000 packages are available, which means that you may
3339 occasionally find that a useful package is missing.
3342 You've been warned. But more than a disclaimer, this is an invitation
3343 to report issues (and success stories!), and join us in improving it.
3344 @xref{Contributing}, for more info.
3346 @subsection USB Stick Installation
3348 An installation image for USB sticks can be downloaded from
3349 @url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.xz},
3350 where @var{system} is one of:
3354 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
3357 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
3360 This image contains a single partition with the tools necessary for an
3361 installation. It is meant to be copied @emph{as is} to a large-enough
3364 To copy the image to a USB stick, follow these steps:
3368 Decompress the image using the @command{xz} command:
3371 xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
3375 Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
3376 its device name. Assuming that USB stick is known as @file{/dev/sdX},
3377 copy the image with:
3380 dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
3383 Access to @file{/dev/sdX} usually requires root privileges.
3386 Once this is done, you should be able to reboot the system and boot from
3387 the USB stick. The latter usually requires you to get in the BIOS' boot
3388 menu, where you can choose to boot from the USB stick.
3390 @subsection Preparing for Installation
3392 Once you have successfully booted the image on the USB stick, you should
3393 end up with a root prompt. Several console TTYs are configured and can
3394 be used to run commands as root. TTY2 shows this documentation,
3395 browsable using the Info reader commands (@pxref{Help,,, info, Info: An
3398 To install the system, you would:
3403 Configure the network, by running @command{dhclient eth0} (to get an
3404 automatically assigned IP address from the wired network interface
3405 controller), or using the @command{ifconfig} command.
3407 The system automatically loads drivers for your network interface
3410 Setting up network access is almost always a requirement because the
3411 image does not contain all the software and tools that may be needed.
3414 Unless this has already been done, you must partition and format the
3417 Preferably, assign partitions a label so that you can easily and
3418 reliably refer to them in @code{file-system} declarations (@pxref{File
3419 Systems}). This is typically done using the @code{-L} option of
3420 @command{mkfs.ext4} and related commands.
3422 The installation image includes Parted (@pxref{Overview,,, parted, GNU
3423 Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
3424 encryption, and e2fsprogs, the suite of tools to manipulate
3425 ext2/ext3/ext4 file systems.
3428 Once that is done, mount the target root partition under @file{/mnt}.
3431 Lastly, run @code{deco start cow-store /mnt}.
3433 This will make @file{/gnu/store} copy-on-write, such that packages added
3434 to it during the installation phase will be written to the target disk
3435 rather than kept in memory.
3440 @subsection Proceeding with the Installation
3442 With the target partitions ready, you now have to edit a file and
3443 provide the declaration of the operating system to be installed. To
3444 that end, the installation system comes with two text editors: GNU nano
3445 (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
3446 It is better to store that file on the target root file system, say, as
3447 @file{/mnt/etc/config.scm}.
3449 A minimal operating system configuration, with just the bare minimum and
3450 only a root account would look like this (on the installation system,
3451 this example is available as @file{/etc/configuration-template.scm}):
3454 @include os-config.texi
3458 For more information on @code{operating-system} declarations,
3459 @pxref{Using the Configuration System}.
3461 Once that is done, the new system must be initialized (remember that the
3462 target root file system is mounted under @file{/mnt}):
3465 guix system init /mnt/etc/config.scm /mnt
3469 This will copy all the necessary files, and install GRUB on
3470 @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
3471 more information, @pxref{Invoking guix system}. This command may trigger
3472 downloads or builds of missing packages, which can take some time.
3474 Once that command has completed---and hopefully succeeded!---you can
3475 run @command{reboot} and boot into the new system. Cross fingers, and
3476 join us on @code{#guix} on the Freenode IRC network or on
3477 @file{guix-devel@@gnu.org} to share your experience---good or not so
3480 @subsection Building the Installation Image
3482 The installation image described above was built using the @command{guix
3483 system} command, specifically:
3486 guix system disk-image --image-size=800MiB gnu/system/install.scm
3489 @xref{Invoking guix system}, for more information. See
3490 @file{gnu/system/install.scm} in the source tree for more information
3491 about the installation image.
3493 @node System Configuration
3494 @section System Configuration
3496 @cindex system configuration
3497 The GNU system supports a consistent whole-system configuration
3498 mechanism. By that we mean that all aspects of the global system
3499 configuration---such as the available system services, timezone and
3500 locale settings, user accounts---are declared in a single place. Such
3501 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
3503 One of the advantages of putting all the system configuration under the
3504 control of Guix is that it supports transactional system upgrades, and
3505 makes it possible to roll-back to a previous system instantiation,
3506 should something go wrong with the new one (@pxref{Features}). Another
3507 one is that it makes it easy to replicate the exact same configuration
3508 across different machines, or at different points in time, without
3509 having to resort to additional administration tools layered on top of
3510 the system's own tools.
3511 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
3513 This section describes this mechanism. First we focus on the system
3514 administrator's viewpoint---explaining how the system is configured and
3515 instantiated. Then we show how this mechanism can be extended, for
3516 instance to support new system services.
3519 * Using the Configuration System:: Customizing your GNU system.
3520 * operating-system Reference:: Detail of operating-system declarations.
3521 * File Systems:: Configuring file system mounts.
3522 * Mapped Devices:: Block device extra processing.
3523 * User Accounts:: Specifying user accounts.
3524 * Locales:: Language and cultural convention settings.
3525 * Services:: Specifying system services.
3526 * Setuid Programs:: Programs running with root privileges.
3527 * Initial RAM Disk:: Linux-Libre bootstrapping.
3528 * GRUB Configuration:: Configuring the boot loader.
3529 * Invoking guix system:: Instantiating a system configuration.
3530 * Defining Services:: Adding new service definitions.
3533 @node Using the Configuration System
3534 @subsection Using the Configuration System
3536 The operating system is configured by providing an
3537 @code{operating-system} declaration in a file that can then be passed to
3538 the @command{guix system} command (@pxref{Invoking guix system}). A
3539 simple setup, with the default system services, the default Linux-Libre
3540 kernel, initial RAM disk, and boot loader looks like this:
3542 @findex operating-system
3544 (use-modules (gnu) ; for 'user-account', '%base-services', etc.
3545 (gnu packages emacs) ; for 'emacs'
3546 (gnu services ssh)) ; for 'lsh-service'
3549 (host-name "komputilo")
3550 (timezone "Europe/Paris")
3551 (locale "fr_FR.utf8")
3552 (bootloader (grub-configuration
3553 (device "/dev/sda")))
3554 (file-systems (cons (file-system
3555 (device "/dev/sda1") ; or partition label
3558 %base-file-systems))
3559 (users (list (user-account
3562 (comment "Bob's sister")
3563 (home-directory "/home/alice"))))
3564 (packages (cons emacs %base-packages))
3565 (services (cons (lsh-service #:port 2222 #:root-login? #t)
3569 This example should be self-describing. Some of the fields defined
3570 above, such as @code{host-name} and @code{bootloader}, are mandatory.
3571 Others, such as @code{packages} and @code{services}, can be omitted, in
3572 which case they get a default value.
3574 @vindex %base-packages
3575 The @code{packages} field lists
3576 packages that will be globally visible on the system, for all user
3577 accounts---i.e., in every user's @code{PATH} environment variable---in
3578 addition to the per-user profiles (@pxref{Invoking guix package}). The
3579 @var{%base-packages} variable provides all the tools one would expect
3580 for basic user and administrator tasks---including the GNU Core
3581 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
3582 editor, @command{find}, @command{grep}, etc. The example above adds
3583 Emacs to those, taken from the @code{(gnu packages emacs)} module
3584 (@pxref{Package Modules}).
3586 @vindex %base-services
3587 The @code{services} field lists @dfn{system services} to be made
3588 available when the system starts (@pxref{Services}).
3589 The @code{operating-system} declaration above specifies that, in
3590 addition to the basic services, we want the @command{lshd} secure shell
3591 daemon listening on port 2222, and allowing remote @code{root} logins
3592 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
3593 @code{lsh-service} arranges so that @code{lshd} is started with the
3594 right command-line options, possibly with supporting configuration files
3595 generated as needed (@pxref{Defining Services}). @xref{operating-system
3596 Reference}, for details about the available @code{operating-system}
3599 Assuming the above snippet is stored in the @file{my-system-config.scm}
3600 file, the @command{guix system reconfigure my-system-config.scm} command
3601 instantiates that configuration, and makes it the default GRUB boot
3602 entry (@pxref{Invoking guix system}). The normal way to change the
3603 system's configuration is by updating this file and re-running the
3604 @command{guix system} command.
3606 At the Scheme level, the bulk of an @code{operating-system} declaration
3607 is instantiated with the following monadic procedure (@pxref{The Store
3610 @deffn {Monadic Procedure} operating-system-derivation os
3611 Return a derivation that builds @var{os}, an @code{operating-system}
3612 object (@pxref{Derivations}).
3614 The output of the derivation is a single directory that refers to all
3615 the packages, configuration files, and other supporting files needed to
3616 instantiate @var{os}.
3619 @node operating-system Reference
3620 @subsection @code{operating-system} Reference
3622 This section summarizes all the options available in
3623 @code{operating-system} declarations (@pxref{Using the Configuration
3626 @deftp {Data Type} operating-system
3627 This is the data type representing an operating system configuration.
3628 By that, we mean all the global system configuration, not per-user
3629 configuration (@pxref{Using the Configuration System}).
3632 @item @code{kernel} (default: @var{linux-libre})
3633 The package object of the operating system to use@footnote{Currently
3634 only the Linux-libre kernel is supported. In the future, it will be
3635 possible to use the GNU@tie{}Hurd.}.
3637 @item @code{bootloader}
3638 The system bootloader configuration object. @xref{GRUB Configuration}.
3640 @item @code{initrd} (default: @code{base-initrd})
3641 A two-argument monadic procedure that returns an initial RAM disk for
3642 the Linux kernel. @xref{Initial RAM Disk}.
3644 @item @code{firmware} (default: @var{%base-firmware})
3646 List of firmware packages loadable by the operating system kernel.
3648 The default includes firmware needed for Atheros-based WiFi devices
3649 (Linux-libre module @code{ath9k}.)
3651 @item @code{host-name}
3654 @item @code{hosts-file}
3656 A zero-argument monadic procedure that returns a text file for use as
3657 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
3658 Reference Manual}). The default is to produce a file with entries for
3659 @code{localhost} and @var{host-name}.
3661 @item @code{mapped-devices} (default: @code{'()})
3662 A list of mapped devices. @xref{Mapped Devices}.
3664 @item @code{file-systems}
3665 A list of file systems. @xref{File Systems}.
3667 @item @code{swap-devices} (default: @code{'()})
3668 @cindex swap devices
3669 A list of strings identifying devices to be used for ``swap space''
3670 (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
3671 For example, @code{'("/dev/sda3")}.
3673 @item @code{users} (default: @code{'()})
3674 @itemx @code{groups} (default: @var{%base-groups})
3675 List of user accounts and groups. @xref{User Accounts}.
3677 @item @code{skeletons} (default: @code{(default-skeletons)})
3678 A monadic list of pairs of target file name and files. These are the
3679 files that will be used as skeletons as new accounts are created.
3681 For instance, a valid value may look like this:
3684 (mlet %store-monad ((bashrc (text-file "bashrc" "\
3685 export PATH=$HOME/.guix-profile/bin")))
3686 (return `((".bashrc" ,bashrc))))
3689 @item @code{issue} (default: @var{%default-issue})
3690 A string denoting the contents of the @file{/etc/issue} file, which is
3691 what displayed when users log in on a text console.
3693 @item @code{packages} (default: @var{%base-packages})
3694 The set of packages installed in the global profile, which is accessible
3695 at @file{/run/current-system/profile}.
3697 The default set includes core utilities, but it is good practice to
3698 install non-core utilities in user profiles (@pxref{Invoking guix
3701 @item @code{timezone}
3702 A timezone identifying string---e.g., @code{"Europe/Paris"}.
3704 @item @code{locale} (default: @code{"en_US.utf8"})
3705 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
3706 Library Reference Manual}). @xref{Locales}, for more information.
3708 @item @code{locale-definitions} (default: @var{%default-locale-definitions})
3709 The list of locale definitions to be compiled and that may be used at
3710 run time. @xref{Locales}.
3712 @item @code{services} (default: @var{%base-services})
3713 A list of monadic values denoting system services. @xref{Services}.
3715 @item @code{pam-services} (default: @code{(base-pam-services)})
3717 @cindex pluggable authentication modules
3718 Linux @dfn{pluggable authentication module} (PAM) services.
3719 @c FIXME: Add xref to PAM services section.
3721 @item @code{setuid-programs} (default: @var{%setuid-programs})
3722 List of string-valued G-expressions denoting setuid programs.
3723 @xref{Setuid Programs}.
3725 @item @code{sudoers} (default: @var{%sudoers-specification})
3727 The contents of the @file{/etc/sudoers} file as a string.
3729 This file specifies which users can use the @command{sudo} command, what
3730 they are allowed to do, and what privileges they may gain. The default
3731 is that only @code{root} and members of the @code{wheel} group may use
3738 @subsection File Systems
3740 The list of file systems to be mounted is specified in the
3741 @code{file-systems} field of the operating system's declaration
3742 (@pxref{Using the Configuration System}). Each file system is declared
3743 using the @code{file-system} form, like this:
3747 (mount-point "/home")
3748 (device "/dev/sda3")
3752 As usual, some of the fields are mandatory---those shown in the example
3753 above---while others can be omitted. These are described below.
3755 @deftp {Data Type} file-system
3756 Objects of this type represent file systems to be mounted. They
3757 contain the following members:
3761 This is a string specifying the type of the file system---e.g.,
3764 @item @code{mount-point}
3765 This designates the place where the file system is to be mounted.
3768 This names the ``source'' of the file system. By default it is the name
3769 of a node under @file{/dev}, but its meaning depends on the @code{title}
3770 field described below.
3772 @item @code{title} (default: @code{'device})
3773 This is a symbol that specifies how the @code{device} field is to be
3776 When it is the symbol @code{device}, then the @code{device} field is
3777 interpreted as a file name; when it is @code{label}, then @code{device}
3778 is interpreted as a partition label name; when it is @code{uuid},
3779 @code{device} is interpreted as a partition unique identifier (UUID).
3781 The @code{label} and @code{uuid} options offer a way to refer to disk
3782 partitions without having to hard-code their actual device name.
3784 However, when a file system's source is a mapped device (@pxref{Mapped
3785 Devices}), its @code{device} field @emph{must} refer to the mapped
3786 device name---e.g., @file{/dev/mapper/root-partition}---and consequently
3787 @code{title} must be set to @code{'device}. This is required so that
3788 the system knows that mounting the file system depends on having the
3789 corresponding device mapping established.
3791 @item @code{flags} (default: @code{'()})
3792 This is a list of symbols denoting mount flags. Recognized flags
3793 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
3794 access to special files), @code{no-suid} (ignore setuid and setgid
3795 bits), and @code{no-exec} (disallow program execution.)
3797 @item @code{options} (default: @code{#f})
3798 This is either @code{#f}, or a string denoting mount options.
3800 @item @code{needed-for-boot?} (default: @code{#f})
3801 This Boolean value indicates whether the file system is needed when
3802 booting. If that is true, then the file system is mounted when the
3803 initial RAM disk (initrd) is loaded. This is always the case, for
3804 instance, for the root file system.
3806 @item @code{check?} (default: @code{#t})
3807 This Boolean indicates whether the file system needs to be checked for
3808 errors before being mounted.
3810 @item @code{create-mount-point?} (default: @code{#f})
3811 When true, the mount point is created if it does not exist yet.
3816 The @code{(gnu system file-systems)} exports the following useful
3819 @defvr {Scheme Variable} %base-file-systems
3820 These are essential file systems that are required on normal systems,
3821 such as @var{%devtmpfs-file-system} (see below.) Operating system
3822 declarations should always contain at least these.
3825 @defvr {Scheme Variable} %devtmpfs-file-system
3826 The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
3827 requirement for udev (@pxref{Base Services, @code{udev-service}}).
3830 @defvr {Scheme Variable} %pseudo-terminal-file-system
3831 This is the file system to be mounted as @file{/dev/pts}. It supports
3832 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
3833 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
3834 Manual}). Pseudo-terminals are used by terminal emulators such as
3838 @defvr {Scheme Variable} %shared-memory-file-system
3839 This file system is mounted as @file{/dev/shm} and is used to support
3840 memory sharing across processes (@pxref{Memory-mapped I/O,
3841 @code{shm_open},, libc, The GNU C Library Reference Manual}).
3844 @defvr {Scheme Variable} %binary-format-file-system
3845 The @code{binfmt_misc} file system, which allows handling of arbitrary
3846 executable file types to be delegated to user space. This requires the
3847 @code{binfmt.ko} kernel module to be loaded.
3850 @defvr {Scheme Variable} %fuse-control-file-system
3851 The @code{fusectl} file system, which allows unprivileged users to mount
3852 and unmount user-space FUSE file systems. This requires the
3853 @code{fuse.ko} kernel module to be loaded.
3856 @node Mapped Devices
3857 @subsection Mapped Devices
3859 @cindex device mapping
3860 @cindex mapped devices
3861 The Linux kernel has a notion of @dfn{device mapping}: a block device,
3862 such as a hard disk partition, can be @dfn{mapped} into another device,
3863 with additional processing over the data that flows through
3864 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
3865 concept of a ``mapped device'' and that of a file system: both boil down
3866 to @emph{translating} input/output operations made on a file to
3867 operations on its backing store. Thus, the Hurd implements mapped
3868 devices, like file systems, using the generic @dfn{translator} mechanism
3869 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
3870 typical example is encryption device mapping: all writes to the mapped
3871 device are encrypted, and all reads are deciphered, transparently.
3873 Mapped devices are declared using the @code{mapped-device} form:
3877 (source "/dev/sda3")
3879 (type luks-device-mapping))
3883 @cindex disk encryption
3885 This example specifies a mapping from @file{/dev/sda3} to
3886 @file{/dev/mapper/home} using LUKS---the
3887 @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
3888 standard mechanism for disk encryption. The @file{/dev/mapper/home}
3889 device can then be used as the @code{device} of a @code{file-system}
3890 declaration (@pxref{File Systems}). The @code{mapped-device} form is
3893 @deftp {Data Type} mapped-device
3894 Objects of this type represent device mappings that will be made when
3895 the system boots up.
3899 This string specifies the name of the block device to be mapped, such as
3903 This string specifies the name of the mapping to be established. For
3904 example, specifying @code{"my-partition"} will lead to the creation of
3905 the @code{"/dev/mapper/my-partition"} device.
3908 This must be a @code{mapped-device-kind} object, which specifies how
3909 @var{source} is mapped to @var{target}.
3913 @defvr {Scheme Variable} luks-device-mapping
3914 This defines LUKS block device encryption using the @command{cryptsetup}
3915 command, from the same-named package. This relies on the
3916 @code{dm-crypt} Linux kernel module.
3920 @subsection User Accounts
3922 User accounts are specified with the @code{user-account} form:
3928 (supplementary-groups '("wheel" ;allow use of sudo, etc.
3930 "video" ;video devices such as webcams
3931 "cdrom")) ;the good ol' CD-ROM
3932 (comment "Bob's sister")
3933 (home-directory "/home/alice"))
3936 @deftp {Data Type} user-account
3937 Objects of this type represent user accounts. The following members may
3942 The name of the user account.
3945 This is the name (a string) or identifier (a number) of the user group
3946 this account belongs to.
3948 @item @code{supplementary-groups} (default: @code{'()})
3949 Optionally, this can be defined as a list of group names that this
3952 @item @code{uid} (default: @code{#f})
3953 This is the user ID for this account (a number), or @code{#f}. In the
3954 latter case, a number is automatically chosen by the system when the
3957 @item @code{comment} (default: @code{""})
3958 A comment about the account, such as the account's owner full name.
3960 @item @code{home-directory}
3961 This is the name of the home directory for the account.
3963 @item @code{shell} (default: Bash)
3964 This is a G-expression denoting the file name of a program to be used as
3965 the shell (@pxref{G-Expressions}).
3967 @item @code{system?} (default: @code{#f})
3968 This Boolean value indicates whether the account is a ``system''
3969 account. System accounts are sometimes treated specially; for instance,
3970 graphical login managers do not list them.
3972 @item @code{password} (default: @code{#f})
3973 You would normally leave this field to @code{#f}, initialize user
3974 passwords as @code{root} with the @command{passwd} command, and then let
3975 users change it with @command{passwd}.
3977 If you @emph{do} want to have a preset password for an account, then
3978 this field must contain the encrypted password, as a string.
3979 @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
3980 on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
3981 Manual}, for information on Guile's @code{crypt} procedure.
3986 User group declarations are even simpler:
3989 (user-group (name "students"))
3992 @deftp {Data Type} user-group
3993 This type is for, well, user groups. There are just a few fields:
3999 @item @code{id} (default: @code{#f})
4000 The group identifier (a number). If @code{#f}, a new number is
4001 automatically allocated when the group is created.
4003 @item @code{system?} (default: @code{#f})
4004 This Boolean value indicates whether the group is a ``system'' group.
4005 System groups have low numerical IDs.
4007 @item @code{password} (default: @code{#f})
4008 What, user groups can have a password? Well, apparently yes. Unless
4009 @code{#f}, this field specifies the group's password.
4014 For convenience, a variable lists all the basic user groups one may
4017 @defvr {Scheme Variable} %base-groups
4018 This is the list of basic user groups that users and/or packages expect
4019 to be present on the system. This includes groups such as ``root'',
4020 ``wheel'', and ``users'', as well as groups used to control access to
4021 specific devices such as ``audio'', ``disk'', and ``cdrom''.
4028 A @dfn{locale} defines cultural conventions for a particular language
4029 and region of the world (@pxref{Locales,,, libc, The GNU C Library
4030 Reference Manual}). Each locale has a name that typically has the form
4031 @code{@var{language}_@var{territory}.@var{charset}}---e.g.,
4032 @code{fr_LU.utf8} designates the locale for the French language, with
4033 cultural conventions from Luxembourg, and using the UTF-8 encoding.
4035 @cindex locale definition
4036 Usually, you will want to specify the default locale for the machine
4037 using the @code{locale} field of the @code{operating-system} declaration
4038 (@pxref{operating-system Reference, @code{locale}}).
4040 That locale must be among the @dfn{locale definitions} that are known to
4041 the system---and these are specified in the @code{locale-definitions}
4042 slot of @code{operating-system}. The default value includes locale
4043 definition for some widely used locales, but not for all the available
4044 locales, in order to save space.
4046 If the locale specified in the @code{locale} field is not among the
4047 definitions listed in @code{locale-definitions}, @command{guix system}
4048 raises an error. In that case, you should add the locale definition to
4049 the @code{locale-definitions} field. For instance, to add the North
4050 Frisian locale for Germany, the value of that field may be:
4053 (cons (locale-definition
4054 (name "fy_DE.utf8") (source "fy_DE"))
4055 %default-locale-definitions)
4058 Likewise, to save space, one might want @code{locale-definitions} to
4059 list only the locales that are actually used, as in:
4062 (list (locale-definition
4063 (name "ja_JP.eucjp") (source "ja_JP")
4064 (charset "EUC-JP")))
4067 The @code{locale-definition} form is provided by the @code{(gnu system
4068 locale)} module. Details are given below.
4070 @deftp {Data Type} locale-definition
4071 This is the data type of a locale definition.
4076 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
4077 Reference Manual}, for more information on locale names.
4080 The name of the source for that locale. This is typically the
4081 @code{@var{language}_@var{territory}} part of the locale name.
4083 @item @code{charset} (default: @code{"UTF-8"})
4084 The ``character set'' or ``code set'' for that locale,
4085 @uref{http://www.iana.org/assignments/character-sets, as defined by
4091 @defvr {Scheme Variable} %default-locale-definitions
4092 An arbitrary list of commonly used locales, used as the default value of
4093 the @code{locale-definitions} field of @code{operating-system}
4098 @subsection Services
4100 @cindex system services
4101 An important part of preparing an @code{operating-system} declaration is
4102 listing @dfn{system services} and their configuration (@pxref{Using the
4103 Configuration System}). System services are typically daemons launched
4104 when the system boots, or other actions needed at that time---e.g.,
4105 configuring network access.
4107 Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
4108 dmd Manual}). On a running system, the @command{deco} command allows
4109 you to list the available services, show their status, start and stop
4110 them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
4111 Manual}). For example:
4117 The above command, run as @code{root}, lists the currently defined
4118 services. The @command{deco doc} command shows a synopsis of the given
4123 Run libc's name service cache daemon (nscd).
4126 The @command{start}, @command{stop}, and @command{restart} sub-commands
4127 have the effect you would expect. For instance, the commands below stop
4128 the nscd service and restart the Xorg display server:
4132 Service nscd has been stopped.
4133 # deco restart xorg-server
4134 Service xorg-server has been stopped.
4135 Service xorg-server has been started.
4138 The following sections document the available services, starting with
4139 the core services, that may be used in an @code{operating-system}
4143 * Base Services:: Essential system services.
4144 * Networking Services:: Network setup, SSH daemon, etc.
4145 * X Window:: Graphical display.
4149 @subsubsection Base Services
4151 The @code{(gnu services base)} module provides definitions for the basic
4152 services that one expects from the system. The services exported by
4153 this module are listed below.
4155 @defvr {Scheme Variable} %base-services
4156 This variable contains a list of basic services@footnote{Technically,
4157 this is a list of monadic services. @xref{The Store Monad}.} one would
4158 expect from the system: a login service (mingetty) on each tty, syslogd,
4159 libc's name service cache daemon (nscd), the udev device manager, and
4162 This is the default value of the @code{services} field of
4163 @code{operating-system} declarations. Usually, when customizing a
4164 system, you will want to append services to @var{%base-services}, like
4168 (cons* (avahi-service) (lsh-service) %base-services)
4172 @deffn {Monadic Procedure} host-name-service @var{name}
4173 Return a service that sets the host name to @var{name}.
4176 @deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
4177 [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
4178 [#:allow-empty-passwords? #f]
4179 Return a service to run mingetty on @var{tty}.
4181 When @var{allow-empty-passwords?} is true, allow empty log-in password. When
4182 @var{auto-login} is true, it must be a user name under which to log-in
4183 automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
4184 @var{auto-login}, in which case the user will have to press a key before the
4185 login shell is launched.
4187 When true, @var{login-program} is a gexp or a monadic gexp denoting the name
4188 of the log-in program (the default is the @code{login} program from the Shadow
4191 @var{motd} is a monadic value containing a text file to use as
4192 the ``message of the day''.
4195 @cindex name service cache daemon
4197 @deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc]
4198 Return a service that runs libc's name service cache daemon (nscd) with the
4199 given @var{config}---an @code{<nscd-configuration>} object.
4202 @defvr {Scheme Variable} %nscd-default-configuration
4203 This is the default @code{<nscd-configuration>} value (see below) used
4204 by @code{nscd-service}. This uses the caches defined by
4205 @var{%nscd-default-caches}; see below.
4208 @deftp {Data Type} nscd-configuration
4209 This is the type representing the name service cache daemon (nscd)
4214 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
4215 Name of nscd's log file. This is where debugging output goes when
4216 @code{debug-level} is strictly positive.
4218 @item @code{debug-level} (default: @code{0})
4219 Integer denoting the debugging levels. Higher numbers mean more
4220 debugging output is logged.
4222 @item @code{caches} (default: @var{%nscd-default-caches})
4223 List of @code{<nscd-cache>} objects denoting things to be cached; see
4229 @deftp {Data Type} nscd-cache
4230 Data type representing a cache database of nscd and its parameters.
4234 @item @code{database}
4235 This is a symbol representing the name of the database to be cached.
4236 Valid values are @code{passwd}, @code{group}, @code{hosts}, and
4237 @code{services}, which designate the corresponding NSS database
4238 (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
4240 @item @code{positive-time-to-live}
4241 @itemx @code{negative-time-to-live} (default: @code{20})
4242 A number representing the number of seconds during which a positive or
4243 negative lookup result remains in cache.
4245 @item @code{check-files?} (default: @code{#t})
4246 Whether to check for updates of the files corresponding to
4249 For instance, when @var{database} is @code{hosts}, setting this flag
4250 instructs nscd to check for updates in @file{/etc/hosts} and to take
4253 @item @code{persistent?} (default: @code{#t})
4254 Whether the cache should be stored persistently on disk.
4256 @item @code{shared?} (default: @code{#t})
4257 Whether the cache should be shared among users.
4259 @item @code{max-database-size} (default: 32@tie{}MiB)
4260 Maximum size in bytes of the database cache.
4262 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
4263 @c settings, so leave them out.
4268 @defvr {Scheme Variable} %nscd-default-caches
4269 List of @code{<nscd-cache>} objects used by default by
4270 @code{nscd-configuration} (see above.)
4272 It enables persistent and aggressive caching of service and host name
4273 lookups. The latter provides better host name lookup performance,
4274 resilience in the face of unreliable name servers, and also better
4275 privacy---often the result of host name lookups is in local cache, so
4276 external name servers do not even need to be queried.
4280 @deffn {Monadic Procedure} syslog-service
4281 Return a service that runs @code{syslogd} with reasonable default
4285 @deffn {Monadic Procedure} guix-service [#:guix guix] @
4286 [#:builder-group "guixbuild"] [#:build-accounts 10] @
4287 [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @
4288 [#:extra-options '()]
4289 Return a service that runs the build daemon from @var{guix}, and has
4290 @var{build-accounts} user accounts available under @var{builder-group}.
4292 When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
4293 provided by @var{guix} is authorized upon activation, meaning that substitutes
4294 from @code{hydra.gnu.org} are used by default.
4296 If @var{use-substitutes?} is false, the daemon is run with
4297 @option{--no-substitutes} (@pxref{Invoking guix-daemon,
4298 @option{--no-substitutes}}).
4300 Finally, @var{extra-options} is a list of additional command-line options
4301 passed to @command{guix-daemon}.
4304 @deffn {Monadic Procedure} udev-service [#:udev udev]
4305 Run @var{udev}, which populates the @file{/dev} directory dynamically.
4309 @node Networking Services
4310 @subsubsection Networking Services
4312 The @code{(gnu services networking)} module provides services to configure
4313 the network interface.
4315 @cindex DHCP, networking service
4316 @deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
4317 Return a service that runs @var{dhcp}, a Dynamic Host Configuration
4318 Protocol (DHCP) client, on all the non-loopback network interfaces.
4321 @deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
4322 [#:gateway #f] [#:name-services @code{'()}]
4323 Return a service that starts @var{interface} with address @var{ip}. If
4324 @var{gateway} is true, it must be a string specifying the default network
4328 @deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
4329 [#:name-service @var{%ntp-servers}]
4330 Return a service that runs the daemon from @var{ntp}, the
4331 @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
4332 keep the system clock synchronized with that of @var{servers}.
4335 @defvr {Scheme Variable} %ntp-servers
4336 List of host names used as the default NTP servers.
4339 @deffn {Monadic Procedure} tor-service [#:tor tor]
4340 Return a service to run the @uref{https://torproject.org,Tor} daemon.
4342 The daemon runs with the default settings (in particular the default exit
4343 policy) as the @code{tor} unprivileged user.
4346 @deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
4347 [#:interface "127.0.0.1"] [#:port 6667] @
4348 [#:extra-settings ""]
4349 Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
4350 acts as a gateway between IRC and chat networks.
4352 The daemon will listen to the interface corresponding to the IP address
4353 specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
4354 local clients can connect, whereas @code{0.0.0.0} means that connections can
4355 come from any networking interface.
4357 In addition, @var{extra-settings} specifies a string to append to the
4361 Furthermore, @code{(gnu services ssh)} provides the following service.
4363 @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
4364 [#:interfaces '()] [#:port-number 22] @
4365 [#:allow-empty-passwords? #f] [#:root-login? #f] @
4366 [#:syslog-output? #t] [#:x11-forwarding? #t] @
4367 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
4368 [public-key-authentication? #t] [#:initialize? #f]
4369 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
4370 @var{host-key} must designate a file containing the host key, and readable
4373 When @var{initialize?} is true, automatically create the seed and host key
4374 upon service activation if they do not exist yet. This may take long and
4375 require interaction.
4377 When @var{initialize?} is false, it is up to the user to initialize the
4378 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
4379 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
4380 basics,,, lsh, LSH Manual}).
4382 When @var{interfaces} is empty, lshd listens for connections on all the
4383 network interfaces; otherwise, @var{interfaces} must be a list of host names
4386 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
4387 passwords, and @var{root-login?} specifies whether to accept log-ins as
4390 The other options should be self-descriptive.
4393 @defvr {Scheme Variable} %facebook-host-aliases
4394 This variable contains a string for use in @file{/etc/hosts}
4395 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
4396 line contains a entry that maps a known server name of the Facebook
4397 on-line service---e.g., @code{www.facebook.com}---to the local
4398 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
4400 This variable is typically used in the @code{hosts-file} field of an
4401 @code{operating-system} declaration (@pxref{operating-system Reference,
4402 @file{/etc/hosts}}):
4405 (use-modules (gnu) (guix))
4408 (host-name "mymachine")
4411 ;; Create a /etc/hosts file with aliases for "localhost"
4412 ;; and "mymachine", as well as for Facebook servers.
4414 (string-append (local-host-aliases host-name)
4415 %facebook-host-aliases))))
4418 This mechanism can prevent programs running locally, such as Web
4419 browsers, from accessing Facebook.
4423 @subsubsection X Window
4425 Support for the X Window graphical display system---specifically
4426 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
4427 there is no @code{xorg-service} procedure. Instead, the X server is
4428 started by the @dfn{login manager}, currently SLiM.
4430 @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
4431 [#:auto-login? #f] [#:default-user ""] [#:startx] @
4432 [#:theme @var{%default-slim-theme}] @
4433 [#:theme-name @var{%default-slim-theme-name}]
4434 Return a service that spawns the SLiM graphical login manager, which in
4435 turn starts the X display server with @var{startx}, a command as returned by
4436 @code{xorg-start-command}.
4438 When @var{allow-empty-passwords?} is true, allow logins with an empty
4439 password. When @var{auto-login?} is true, log in automatically as
4442 If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
4443 @var{theme} must be a gexp denoting the name of a directory containing the
4444 theme to use. In that case, @var{theme-name} specifies the name of the
4448 @defvr {Scheme Variable} %default-theme
4449 @defvrx {Scheme Variable} %default-theme-name
4450 The G-Expression denoting the default SLiM theme and its name.
4453 @deffn {Monadic Procedure} xorg-start-command [#:guile] @
4454 [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
4455 Return a derivation that builds a @var{guile} script to start the X server
4456 from @var{xorg-server}. Usually the X server is started by a login manager.
4458 @var{drivers} must be either the empty list, in which case Xorg chooses a
4459 graphics driver automatically, or a list of driver names that will be tried in
4460 this order---e.g., @code{("modesetting" "vesa")}.
4462 Likewise, when @var{resolutions} is the empty list, Xorg chooses an
4463 appropriate screen resolution; otherwise, it must be a list of
4464 resolutions---e.g., @code{((1024 768) (640 480))}.
4467 @node Setuid Programs
4468 @subsection Setuid Programs
4470 @cindex setuid programs
4471 Some programs need to run with ``root'' privileges, even when they are
4472 launched by unprivileged users. A notorious example is the
4473 @command{passwd} programs, which can users can run to change their
4474 password, and which requires write access to the @file{/etc/passwd} and
4475 @file{/etc/shadow} files---something normally restricted to root, for
4476 obvious security reasons. To address that, these executables are
4477 @dfn{setuid-root}, meaning that they always run with root privileges
4478 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
4479 for more info about the setuid mechanisms.)
4481 The store itself @emph{cannot} contain setuid programs: that would be a
4482 security issue since any user on the system can write derivations that
4483 populate the store (@pxref{The Store}). Thus, a different mechanism is
4484 used: instead of changing the setuid bit directly on files that are in
4485 the store, we let the system administrator @emph{declare} which programs
4486 should be setuid root.
4488 The @code{setuid-programs} field of an @code{operating-system}
4489 declaration contains a list of G-expressions denoting the names of
4490 programs to be setuid-root (@pxref{Using the Configuration System}).
4491 For instance, the @command{passwd} program, which is part of the Shadow
4492 package, can be designated by this G-expression (@pxref{G-Expressions}):
4495 #~(string-append #$shadow "/bin/passwd")
4498 A default set of setuid programs is defined by the
4499 @code{%setuid-programs} variable of the @code{(gnu system)} module.
4501 @defvr {Scheme Variable} %setuid-programs
4502 A list of G-expressions denoting common programs that are setuid-root.
4504 The list includes commands such as @command{passwd}, @command{ping},
4505 @command{su}, and @command{sudo}.
4508 Under the hood, the actual setuid programs are created in the
4509 @file{/run/setuid-programs} directory at system activation time. The
4510 files in this directory refer to the ``real'' binaries, which are in the
4514 @node Initial RAM Disk
4515 @subsection Initial RAM Disk
4517 @cindex initial RAM disk (initrd)
4518 @cindex initrd (initial RAM disk)
4519 For bootstrapping purposes, the Linux-Libre kernel is passed an
4520 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
4521 root file system, as well as an initialization script. The latter is
4522 responsible for mounting the real root file system, and for loading any
4523 kernel modules that may be needed to achieve that.
4525 The @code{initrd} field of an @code{operating-system} declaration allows
4526 you to specify which initrd you would like to use. The @code{(gnu
4527 system linux-initrd)} module provides two ways to build an initrd: the
4528 high-level @code{base-initrd} procedure, and the low-level
4529 @code{expression->initrd} procedure.
4531 The @code{base-initrd} procedure is intended to cover most common uses.
4532 For example, if you want to add a bunch of kernel modules to be loaded
4533 at boot time, you can define the @code{initrd} field of the operating
4534 system declaration like this:
4537 (initrd (lambda (file-systems . rest)
4538 (apply base-initrd file-systems
4539 #:extra-modules '("my.ko" "modules.ko")
4543 The @code{base-initrd} procedure also handles common use cases that
4544 involves using the system as a QEMU guest, or as a ``live'' system whose
4545 root file system is volatile.
4547 @deffn {Monadic Procedure} base-initrd @var{file-systems} @
4548 [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
4549 [#:extra-modules '()] [#:mapped-devices '()]
4550 Return a monadic derivation that builds a generic initrd. @var{file-systems} is
4551 a list of file-systems to be mounted by the initrd, possibly in addition to
4552 the root file system specified on the kernel command line via @code{--root}.
4553 @var{mapped-devices} is a list of device mappings to realize before
4554 @var{file-systems} are mounted (@pxref{Mapped Devices}).
4556 When @var{qemu-networking?} is true, set up networking with the standard QEMU
4557 parameters. When @var{virtio?} is true, load additional modules so the initrd can
4558 be used as a QEMU guest with para-virtualized I/O drivers.
4560 When @var{volatile-root?} is true, the root file system is writable but any changes
4563 The initrd is automatically populated with all the kernel modules necessary
4564 for @var{file-systems} and for the given options. However, additional kernel
4565 modules can be listed in @var{extra-modules}. They will be added to the initrd, and
4566 loaded at boot time in the order in which they appear.
4569 Needless to say, the initrds we produce and use embed a
4570 statically-linked Guile, and the initialization program is a Guile
4571 program. That gives a lot of flexibility. The
4572 @code{expression->initrd} procedure builds such an initrd, given the
4573 program to run in that initrd.
4575 @deffn {Monadic Procedure} expression->initrd @var{exp} @
4576 [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
4578 Return a derivation that builds a Linux initrd (a gzipped cpio archive)
4579 containing @var{guile} and that evaluates @var{exp}, a G-expression,
4580 upon booting. All the derivations referenced by @var{exp} are
4581 automatically copied to the initrd.
4583 @var{modules} is a list of Guile module names to be embedded in the
4587 @node GRUB Configuration
4588 @subsection GRUB Configuration
4593 The operating system uses GNU@tie{}GRUB as its boot loader
4594 (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
4595 configured using @code{grub-configuration} declarations. This data type
4596 is exported by the @code{(gnu system grub)} module, and described below.
4598 @deftp {Data Type} grub-configuration
4599 The type of a GRUB configuration declaration.
4604 This is a string denoting the boot device. It must be a device name
4605 understood by the @command{grub-install} command, such as
4606 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
4609 @item @code{menu-entries} (default: @code{()})
4610 A possibly empty list of @code{menu-entry} objects (see below), denoting
4611 entries to appear in the GRUB boot menu, in addition to the current
4612 system entry and the entry pointing to previous system generations.
4614 @item @code{default-entry} (default: @code{0})
4615 The index of the default boot menu entry. Index 0 is for the current
4618 @item @code{timeout} (default: @code{5})
4619 The number of seconds to wait for keyboard input before booting. Set to
4620 0 to boot immediately, and to -1 to wait indefinitely.
4622 @item @code{theme} (default: @var{%default-theme})
4623 The @code{grub-theme} object describing the theme to use.
4628 Should you want to list additional boot menu entries @i{via} the
4629 @code{menu-entries} field above, you will need to create them with the
4630 @code{menu-entry} form:
4632 @deftp {Data Type} menu-entry
4633 The type of an entry in the GRUB boot menu.
4638 The label to show in the menu---e.g., @code{"GNU System"}.
4641 The Linux kernel to boot.
4643 @item @code{linux-arguments} (default: @code{()})
4644 The list of extra Linux kernel command-line arguments---e.g.,
4645 @code{("console=ttyS0")}.
4648 A G-Expression or string denoting the file name of the initial RAM disk
4649 to use (@pxref{G-Expressions}).
4654 @c FIXME: Write documentation once it's stable.
4655 Themes are created using the @code{grub-theme} form, which is not
4658 @defvr {Scheme Variable} %default-theme
4659 This is the default GRUB theme used by the operating system, with a
4660 fancy background image displaying the GNU and Guix logos.
4664 @node Invoking guix system
4665 @subsection Invoking @code{guix system}
4667 Once you have written an operating system declaration, as seen in the
4668 previous section, it can be @dfn{instantiated} using the @command{guix
4669 system} command. The synopsis is:
4672 guix system @var{options}@dots{} @var{action} @var{file}
4675 @var{file} must be the name of a file containing an
4676 @code{operating-system} declaration. @var{action} specifies how the
4677 operating system is instantiate. Currently the following values are
4682 Build the operating system described in @var{file}, activate it, and
4683 switch to it@footnote{This action is usable only on systems already
4686 This effects all the configuration specified in @var{file}: user
4687 accounts, system services, global package list, setuid programs, etc.
4689 It also adds a GRUB menu entry for the new OS configuration, and moves
4690 entries for older configurations to a submenu---unless
4691 @option{--no-grub} is passed.
4693 @c The paragraph below refers to the problem discussed at
4694 @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
4695 It is highly recommended to run @command{guix pull} once before you run
4696 @command{guix system reconfigure} for the first time (@pxref{Invoking
4697 guix pull}). Failing to do that you would see an older version of Guix
4698 once @command{reconfigure} has completed.
4701 Build the operating system's derivation, which includes all the
4702 configuration files and programs needed to boot and run the system.
4703 This action does not actually install anything.
4706 Populate the given directory with all the files necessary to run the
4707 operating system specified in @var{file}. This is useful for first-time
4708 installations of the GNU system. For instance:
4711 guix system init my-os-config.scm /mnt
4714 copies to @file{/mnt} all the store items required by the configuration
4715 specified in @file{my-os-config.scm}. This includes configuration
4716 files, packages, and so on. It also creates other essential files
4717 needed for the system to operate correctly---e.g., the @file{/etc},
4718 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
4720 This command also installs GRUB on the device specified in
4721 @file{my-os-config}, unless the @option{--no-grub} option was passed.
4724 @cindex virtual machine
4726 Build a virtual machine that contain the operating system declared in
4727 @var{file}, and return a script to run that virtual machine (VM).
4728 Arguments given to the script are passed as is to QEMU.
4730 The VM shares its store with the host system.
4732 Additional file systems can be shared between the host and the VM using
4733 the @code{--share} and @code{--expose} command-line options: the former
4734 specifies a directory to be shared with write access, while the latter
4735 provides read-only access to the shared directory.
4737 The example below creates a VM in which the user's home directory is
4738 accessible read-only, and where the @file{/exchange} directory is a
4739 read-write mapping of the host's @file{$HOME/tmp}:
4742 guix system vm my-config.scm \
4743 --expose=$HOME --share=$HOME/tmp=/exchange
4746 On GNU/Linux, the default is to boot directly to the kernel; this has
4747 the advantage of requiring only a very tiny root disk image since the
4748 host's store can then be mounted.
4750 The @code{--full-boot} option forces a complete boot sequence, starting
4751 with the bootloader. This requires more disk space since a root image
4752 containing at least the kernel, initrd, and bootloader data files must
4753 be created. The @code{--image-size} option can be used to specify the
4758 Return a virtual machine or disk image of the operating system declared
4759 in @var{file} that stands alone. Use the @option{--image-size} option
4760 to specify the size of the image.
4762 When using @code{vm-image}, the returned image is in qcow2 format, which
4763 the QEMU emulator can efficiently use.
4765 When using @code{disk-image}, a raw disk image is produced; it can be
4766 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
4767 the device corresponding to a USB stick, one can copy the image on it
4768 using the following command:
4771 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
4776 @var{options} can contain any of the common build options provided by
4777 @command{guix build} (@pxref{Invoking guix build}). In addition,
4778 @var{options} can contain one of the following:
4781 @item --system=@var{system}
4782 @itemx -s @var{system}
4783 Attempt to build for @var{system} instead of the host's system type.
4784 This works as per @command{guix build} (@pxref{Invoking guix build}).
4786 @item --image-size=@var{size}
4787 For the @code{vm-image} and @code{disk-image} actions, create an image
4788 of the given @var{size}. @var{size} may be a number of bytes, or it may
4789 include a unit as a suffix (@pxref{Block size, size specifications,,
4790 coreutils, GNU Coreutils}).
4793 Note that all the actions above, except @code{build} and @code{init},
4794 rely on KVM support in the Linux-Libre kernel. Specifically, the
4795 machine should have hardware virtualization support, the corresponding
4796 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
4797 must exist and be readable and writable by the user and by the daemon's
4800 @node Defining Services
4801 @subsection Defining Services
4803 The @code{(gnu services @dots{})} modules define several procedures that allow
4804 users to declare the operating system's services (@pxref{Using the
4805 Configuration System}). These procedures are @emph{monadic
4806 procedures}---i.e., procedures that return a monadic value in the store
4807 monad (@pxref{The Store Monad}). For examples of such procedures,
4810 @cindex service definition
4811 The monadic value returned by those procedures is a @dfn{service
4812 definition}---a structure as returned by the @code{service} form.
4813 Service definitions specifies the inputs the service depends on, and an
4814 expression to start and stop the service. Behind the scenes, service
4815 definitions are ``translated'' into the form suitable for the
4816 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
4819 As an example, here is what the @code{nscd-service} procedure looks
4823 (define (nscd-service)
4824 (with-monad %store-monad
4826 (documentation "Run libc's name service cache daemon.")
4829 (use-modules (guix build utils))
4830 (mkdir-p "/var/run/nscd")))
4831 (start #~(make-forkexec-constructor
4832 (string-append #$glibc "/sbin/nscd")
4833 "-f" "/dev/null" "--foreground"))
4834 (stop #~(make-kill-destructor))
4839 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
4840 (@pxref{G-Expressions}). The @code{activate} field contains a script to
4841 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
4842 directory exists before @command{nscd} is started.
4844 The @code{start} and @code{stop} fields refer to dmd's facilities to
4845 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
4846 GNU dmd Manual}). The @code{provision} field specifies the name under
4847 which this service is known to dmd, and @code{documentation} specifies
4848 on-line documentation. Thus, the commands @command{deco start ncsd},
4849 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
4850 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
4853 @node Installing Debugging Files
4854 @section Installing Debugging Files
4856 @cindex debugging files
4857 Program binaries, as produced by the GCC compilers for instance, are
4858 typically written in the ELF format, with a section containing
4859 @dfn{debugging information}. Debugging information is what allows the
4860 debugger, GDB, to map binary code to source code; it is required to
4861 debug a compiled program in good conditions.
4863 The problem with debugging information is that is takes up a fair amount
4864 of disk space. For example, debugging information for the GNU C Library
4865 weighs in at more than 60 MiB. Thus, as a user, keeping all the
4866 debugging info of all the installed programs is usually not an option.
4867 Yet, space savings should not come at the cost of an impediment to
4868 debugging---especially in the GNU system, which should make it easier
4869 for users to exert their computing freedom (@pxref{GNU Distribution}).
4871 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
4872 mechanism that allows users to get the best of both worlds: debugging
4873 information can be stripped from the binaries and stored in separate
4874 files. GDB is then able to load debugging information from those files,
4875 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
4878 The GNU distribution takes advantage of this by storing debugging
4879 information in the @code{lib/debug} sub-directory of a separate package
4880 output unimaginatively called @code{debug} (@pxref{Packages with
4881 Multiple Outputs}). Users can choose to install the @code{debug} output
4882 of a package when they need it. For instance, the following command
4883 installs the debugging information for the GNU C Library and for GNU
4887 guix package -i glibc:debug guile:debug
4890 GDB must then be told to look for debug files in the user's profile, by
4891 setting the @code{debug-file-directory} variable (consider setting it
4892 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
4896 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
4899 From there on, GDB will pick up debugging information from the
4900 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
4902 In addition, you will most likely want GDB to be able to show the source
4903 code being debugged. To do that, you will have to unpack the source
4904 code of the package of interest (obtained with @code{guix build
4905 --source}, @pxref{Invoking guix build}), and to point GDB to that source
4906 directory using the @code{directory} command (@pxref{Source Path,
4907 @code{directory},, gdb, Debugging with GDB}).
4909 @c XXX: keep me up-to-date
4910 The @code{debug} output mechanism in Guix is implemented by the
4911 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
4912 opt-in---debugging information is available only for those packages
4913 whose definition explicitly declares a @code{debug} output. This may be
4914 changed to opt-out in the future, if our build farm servers can handle
4915 the load. To check whether a package has a @code{debug} output, use
4916 @command{guix package --list-available} (@pxref{Invoking guix package}).
4919 @node Security Updates
4920 @section Security Updates
4923 As of version @value{VERSION}, the feature described in this section is
4927 @cindex security updates
4928 Occasionally, important security vulnerabilities are discovered in core
4929 software packages and must be patched. Guix follows a functional
4930 package management discipline (@pxref{Introduction}), which implies
4931 that, when a package is changed, @emph{every package that depends on it}
4932 must be rebuilt. This can significantly slow down the deployment of
4933 fixes in core packages such as libc or Bash, since basically the whole
4934 distribution would need to be rebuilt. Using pre-built binaries helps
4935 (@pxref{Substitutes}), but deployment may still take more time than
4939 To address that, Guix implements @dfn{grafts}, a mechanism that allows
4940 for fast deployment of critical updates without the costs associated
4941 with a whole-distribution rebuild. The idea is to rebuild only the
4942 package that needs to be patched, and then to ``graft'' it onto packages
4943 explicitly installed by the user and that were previously referring to
4944 the original package. The cost of grafting is typically very low, and
4945 order of magnitudes lower than a full rebuild of the dependency chain.
4947 @cindex replacements of packages, for grafts
4948 For instance, suppose a security update needs to be applied to Bash.
4949 Guix developers will provide a package definition for the ``fixed''
4950 Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
4951 Packages}). Then, the original package definition is augmented with a
4952 @code{replacement} field pointing to the package containing the bug fix:
4959 (replacement bash-fixed)))
4962 From there on, any package depending directly or indirectly on Bash that
4963 is installed will automatically be ``rewritten'' to refer to
4964 @var{bash-fixed} instead of @var{bash}. This grafting process takes
4965 time proportional to the size of the package, but expect less than a
4966 minute for an ``average'' package on a recent machine.
4968 Currently, the graft and the package it replaces (@var{bash-fixed} and
4969 @var{bash} in the example above) must have the exact same @code{name}
4970 and @code{version} fields. This restriction mostly comes from the fact
4971 that grafting works by patching files, including binary files, directly.
4972 Other restrictions may apply: for instance, when adding a graft to a
4973 package providing a shared library, the original shared library and its
4974 replacement must have the same @code{SONAME} and be binary-compatible.
4977 @node Package Modules
4978 @section Package Modules
4980 From a programming viewpoint, the package definitions of the
4981 GNU distribution are provided by Guile modules in the @code{(gnu packages
4982 @dots{})} name space@footnote{Note that packages under the @code{(gnu
4983 packages @dots{})} module name space are not necessarily ``GNU
4984 packages''. This module naming scheme follows the usual Guile module
4985 naming convention: @code{gnu} means that these modules are distributed
4986 as part of the GNU system, and @code{packages} identifies modules that
4987 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
4988 Reference Manual}). For instance, the @code{(gnu packages emacs)}
4989 module exports a variable named @code{emacs}, which is bound to a
4990 @code{<package>} object (@pxref{Defining Packages}).
4992 The @code{(gnu packages @dots{})} module name space is
4993 automatically scanned for packages by the command-line tools. For
4994 instance, when running @code{guix package -i emacs}, all the @code{(gnu
4995 packages @dots{})} modules are scanned until one that exports a package
4996 object whose name is @code{emacs} is found. This package search
4997 facility is implemented in the @code{(gnu packages)} module.
4999 @cindex customization, of packages
5000 @cindex package module search path
5001 Users can store package definitions in modules with different
5002 names---e.g., @code{(my-packages emacs)}. These package definitions
5003 will not be visible by default. Thus, users can invoke commands such as
5004 @command{guix package} and @command{guix build} have to be used with the
5005 @code{-e} option so that they know where to find the package, or use the
5006 @code{-L} option of these commands to make those modules visible
5007 (@pxref{Invoking guix build, @code{--load-path}}), or define the
5008 @code{GUIX_PACKAGE_PATH} environment variable. This environment
5009 variable makes it easy to extend or customize the distribution and is
5010 honored by all the user interfaces.
5012 @defvr {Environment Variable} GUIX_PACKAGE_PATH
5013 This is a colon-separated list of directories to search for package
5014 modules. Directories listed in this variable take precedence over the
5015 distribution's own modules.
5018 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
5019 each package is built based solely on other packages in the
5020 distribution. The root of this dependency graph is a small set of
5021 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
5022 bootstrap)} module. For more information on bootstrapping,
5023 @pxref{Bootstrapping}.
5025 @node Packaging Guidelines
5026 @section Packaging Guidelines
5028 The GNU distribution is nascent and may well lack some of your favorite
5029 packages. This section describes how you can help make the distribution
5030 grow. @xref{Contributing}, for additional information on how you can
5033 Free software packages are usually distributed in the form of
5034 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
5035 all the source files. Adding a package to the distribution means
5036 essentially two things: adding a @dfn{recipe} that describes how to
5037 build the package, including a list of other packages required to build
5038 it, and adding @dfn{package meta-data} along with that recipe, such as a
5039 description and licensing information.
5041 In Guix all this information is embodied in @dfn{package definitions}.
5042 Package definitions provide a high-level view of the package. They are
5043 written using the syntax of the Scheme programming language; in fact,
5044 for each package we define a variable bound to the package definition,
5045 and export that variable from a module (@pxref{Package Modules}).
5046 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
5047 creating packages. For more information on package definitions,
5048 @pxref{Defining Packages}.
5050 Once a package definition is in place, stored in a file in the Guix
5051 source tree, it can be tested using the @command{guix build} command
5052 (@pxref{Invoking guix build}). For example, assuming the new package is
5053 called @code{gnew}, you may run this command from the Guix build tree:
5056 ./pre-inst-env guix build gnew --keep-failed
5059 Using @code{--keep-failed} makes it easier to debug build failures since
5060 it provides access to the failed build tree. Another useful
5061 command-line option when debugging is @code{--log-file}, to access the
5064 If the package is unknown to the @command{guix} command, it may be that
5065 the source file contains a syntax error, or lacks a @code{define-public}
5066 clause to export the package variable. To figure it out, you may load
5067 the module from Guile to get more information about the actual error:
5070 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
5073 Once your package builds correctly, please send us a patch
5074 (@pxref{Contributing}). Well, if you need help, we will be happy to
5075 help you too. Once the patch is committed in the Guix repository, the
5076 new package automatically gets built on the supported platforms by
5077 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
5081 Users can obtain the new package definition simply by running
5082 @command{guix pull} (@pxref{Invoking guix pull}). When
5083 @code{hydra.gnu.org} is done building the package, installing the
5084 package automatically downloads binaries from there
5085 (@pxref{Substitutes}). The only place where human intervention is
5086 needed is to review and apply the patch.
5090 * Software Freedom:: What may go into the distribution.
5091 * Package Naming:: What's in a name?
5092 * Version Numbers:: When the name is not enough.
5093 * Python Modules:: Taming the snake.
5094 * Perl Modules:: Little pearls.
5095 * Fonts:: Fond of fonts.
5098 @node Software Freedom
5099 @subsection Software Freedom
5101 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
5103 The GNU operating system has been developed so that users can have
5104 freedom in their computing. GNU is @dfn{free software}, meaning that
5105 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
5106 essential freedoms}: to run the program, to study and change the program
5107 in source code form, to redistribute exact copies, and to distribute
5108 modified versions. Packages found in the GNU distribution provide only
5109 software that conveys these four freedoms.
5111 In addition, the GNU distribution follow the
5112 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
5113 software distribution guidelines}. Among other things, these guidelines
5114 reject non-free firmware, recommendations of non-free software, and
5115 discuss ways to deal with trademarks and patents.
5117 Some packages contain a small and optional subset that violates the
5118 above guidelines, for instance because this subset is itself non-free
5119 code. When that happens, the offending items are removed with
5120 appropriate patches or code snippets in the package definition's
5121 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
5122 build --source} returns the ``freed'' source rather than the unmodified
5126 @node Package Naming
5127 @subsection Package Naming
5129 A package has actually two names associated with it:
5130 First, there is the name of the @emph{Scheme variable}, the one following
5131 @code{define-public}. By this name, the package can be made known in the
5132 Scheme code, for instance as input to another package. Second, there is
5133 the string in the @code{name} field of a package definition. This name
5134 is used by package management commands such as
5135 @command{guix package} and @command{guix build}.
5137 Both are usually the same and correspond to the lowercase conversion of
5138 the project name chosen upstream, with underscores replaced with
5139 hyphens. For instance, GNUnet is available as @code{gnunet}, and
5140 SDL_net as @code{sdl-net}.
5142 We do not add @code{lib} prefixes for library packages, unless these are
5143 already part of the official project name. But @pxref{Python
5144 Modules} and @ref{Perl Modules} for special rules concerning modules for
5145 the Python and Perl languages.
5147 Font package names are handled differently, @pxref{Fonts}.
5150 @node Version Numbers
5151 @subsection Version Numbers
5153 We usually package only the latest version of a given free software
5154 project. But sometimes, for instance for incompatible library versions,
5155 two (or more) versions of the same package are needed. These require
5156 different Scheme variable names. We use the name as defined
5157 in @ref{Package Naming}
5158 for the most recent version; previous versions use the same name, suffixed
5159 by @code{-} and the smallest prefix of the version number that may
5160 distinguish the two versions.
5162 The name inside the package definition is the same for all versions of a
5163 package and does not contain any version number.
5165 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
5173 (define-public gtk+-2
5179 If we also wanted GTK+ 3.8.2, this would be packaged as
5181 (define-public gtk+-3.8
5189 @node Python Modules
5190 @subsection Python Modules
5192 We currently package Python 2 and Python 3, under the Scheme variable names
5193 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
5194 To avoid confusion and naming clashes with other programming languages, it
5195 seems desirable that the name of a package for a Python module contains
5196 the word @code{python}.
5198 Some modules are compatible with only one version of Python, others with both.
5199 If the package Foo compiles only with Python 3, we name it
5200 @code{python-foo}; if it compiles only with Python 2, we name it
5201 @code{python2-foo}. If it is compatible with both versions, we create two
5202 packages with the corresponding names.
5204 If a project already contains the word @code{python}, we drop this;
5205 for instance, the module python-dateutil is packaged under the names
5206 @code{python-dateutil} and @code{python2-dateutil}.
5210 @subsection Perl Modules
5212 Perl programs standing for themselves are named as any other package,
5213 using the lowercase upstream name.
5214 For Perl packages containing a single class, we use the lowercase class name,
5215 replace all occurrences of @code{::} by dashes and prepend the prefix
5217 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
5218 Modules containing several classes keep their lowercase upstream name and
5219 are also prepended by @code{perl-}. Such modules tend to have the word
5220 @code{perl} somewhere in their name, which gets dropped in favor of the
5221 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
5227 For fonts that are in general not installed by a user for typesetting
5228 purposes, or that are distributed as part of a larger software package,
5229 we rely on the general packaging rules for software; for instance, this
5230 applies to the fonts delivered as part of the X.Org system or fonts that
5231 are part of TeX Live.
5233 To make it easier for a user to search for fonts, names for other packages
5234 containing only fonts are constructed as follows, independently of the
5235 upstream package name.
5237 The name of a package containing only one font family starts with
5238 @code{font-}; it is followed by the foundry name and a dash @code{-}
5239 if the foundry is known, and the font family name, in which spaces are
5240 replaced by dashes (and as usual, all upper case letters are transformed
5242 For example, the Gentium font family by SIL is packaged under the name
5243 @code{font-sil-gentium}.
5245 For a package containing several font families, the name of the collection
5246 is used in the place of the font family name.
5247 For instance, the Liberation fonts consist of three families,
5248 Liberation Sans, Liberation Serif and Liberation Mono.
5249 These could be packaged separately under the names
5250 @code{font-liberation-sans} and so on; but as they are distributed together
5251 under a common name, we prefer to package them together as
5252 @code{font-liberation}.
5254 In the case where several formats of the same font family or font collection
5255 are packaged separately, a short form of the format, prepended by a dash,
5256 is added to the package name. We use @code{-ttf} for TrueType fonts,
5257 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
5263 @section Bootstrapping
5265 @c Adapted from the ELS 2013 paper.
5267 @cindex bootstrapping
5269 Bootstrapping in our context refers to how the distribution gets built
5270 ``from nothing''. Remember that the build environment of a derivation
5271 contains nothing but its declared inputs (@pxref{Introduction}). So
5272 there's an obvious chicken-and-egg problem: how does the first package
5273 get built? How does the first compiler get compiled? Note that this is
5274 a question of interest only to the curious hacker, not to the regular
5275 user, so you can shamelessly skip this section if you consider yourself
5278 @cindex bootstrap binaries
5279 The GNU system is primarily made of C code, with libc at its core. The
5280 GNU build system itself assumes the availability of a Bourne shell and
5281 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
5282 `grep'. Furthermore, build programs---programs that run
5283 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
5284 (@pxref{Derivations}). Consequently, to be able to build anything at
5285 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
5286 Binutils, libc, and the other packages mentioned above---the
5287 @dfn{bootstrap binaries}.
5289 These bootstrap binaries are ``taken for granted'', though we can also
5290 re-create them if needed (more on that later).
5292 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
5294 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
5295 @c large image, it's hard to scroll. Oh well.
5296 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
5298 The figure above shows the very beginning of the dependency graph of the
5299 distribution, corresponding to the package definitions of the @code{(gnu
5300 packages bootstrap)} module. At this level of detail, things are
5301 slightly complex. First, Guile itself consists of an ELF executable,
5302 along with many source and compiled Scheme files that are dynamically
5303 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
5304 tarball shown in this graph. This tarball is part of Guix's ``source''
5305 distribution, and gets inserted into the store with @code{add-to-store}
5306 (@pxref{The Store}).
5308 But how do we write a derivation that unpacks this tarball and adds it
5309 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
5310 derivation---the first one that gets built---uses @code{bash} as its
5311 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
5312 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
5313 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
5314 the Guix source distribution, whose sole purpose is to allow the Guile
5315 tarball to be unpacked.
5317 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
5318 Guile that can be used to run subsequent build programs. Its first task
5319 is to download tarballs containing the other pre-built binaries---this
5320 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
5321 @code{ftp-client.scm} are used for this purpose. The
5322 @code{module-import.drv} derivations import those modules in a directory
5323 in the store, using the original layout. The
5324 @code{module-import-compiled.drv} derivations compile those modules, and
5325 write them in an output directory with the right layout. This
5326 corresponds to the @code{#:modules} argument of
5327 @code{build-expression->derivation} (@pxref{Derivations}).
5329 Finally, the various tarballs are unpacked by the
5330 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
5331 etc., at which point we have a working C tool chain.
5334 @unnumberedsubsec Building the Build Tools
5336 @c TODO: Add a package-level dependency graph generated from (gnu
5339 Bootstrapping is complete when we have a full tool chain that does not
5340 depend on the pre-built bootstrap tools discussed above. This
5341 no-dependency requirement is verified by checking whether the files of
5342 the final tool chain contain references to the @file{/gnu/store}
5343 directories of the bootstrap inputs. The process that leads to this
5344 ``final'' tool chain is described by the package definitions found in
5345 the @code{(gnu packages commencement)} module.
5347 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
5348 The first tool that gets built with the bootstrap binaries is
5349 GNU Make, which is a prerequisite for all the following packages.
5350 From there Findutils and Diffutils get built.
5352 Then come the first-stage Binutils and GCC, built as pseudo cross
5353 tools---i.e., with @code{--target} equal to @code{--host}. They are
5354 used to build libc. Thanks to this cross-build trick, this libc is
5355 guaranteed not to hold any reference to the initial tool chain.
5357 From there the final Binutils and GCC are built. GCC uses @code{ld}
5358 from the final Binutils, and links programs against the just-built libc.
5359 This tool chain is used to build the other packages used by Guix and by
5360 the GNU Build System: Guile, Bash, Coreutils, etc.
5362 And voilà! At this point we have the complete set of build tools that
5363 the GNU Build System expects. These are in the @code{%final-inputs}
5364 variable of the @code{(gnu packages commencement)} module, and are
5365 implicitly used by any package that uses @code{gnu-build-system}
5366 (@pxref{Build Systems, @code{gnu-build-system}}).
5369 @unnumberedsubsec Building the Bootstrap Binaries
5371 Because the final tool chain does not depend on the bootstrap binaries,
5372 those rarely need to be updated. Nevertheless, it is useful to have an
5373 automated way to produce them, should an update occur, and this is what
5374 the @code{(gnu packages make-bootstrap)} module provides.
5376 The following command builds the tarballs containing the bootstrap
5377 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
5378 of Coreutils and other basic command-line tools):
5381 guix build bootstrap-tarballs
5384 The generated tarballs are those that should be referred to in the
5385 @code{(gnu packages bootstrap)} module mentioned at the beginning of
5388 Still here? Then perhaps by now you've started to wonder: when do we
5389 reach a fixed point? That is an interesting question! The answer is
5390 unknown, but if you would like to investigate further (and have
5391 significant computational and storage resources to do so), then let us
5395 @section Porting to a New Platform
5397 As discussed above, the GNU distribution is self-contained, and
5398 self-containment is achieved by relying on pre-built ``bootstrap
5399 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
5400 operating system kernel, CPU architecture, and application binary
5401 interface (ABI). Thus, to port the distribution to a platform that is
5402 not yet supported, one must build those bootstrap binaries, and update
5403 the @code{(gnu packages bootstrap)} module to use them on that platform.
5405 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
5406 When everything goes well, and assuming the GNU tool chain supports the
5407 target platform, this can be as simple as running a command like this
5411 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
5414 For this to work, the @code{glibc-dynamic-linker} procedure in
5415 @code{(gnu packages bootstrap)} must be augmented to return the right
5416 file name for libc's dynamic linker on that platform; likewise,
5417 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
5418 taught about the new platform.
5420 Once these are built, the @code{(gnu packages bootstrap)} module needs
5421 to be updated to refer to these binaries on the target platform. That
5422 is, the hashes and URLs of the bootstrap tarballs for the new platform
5423 must be added alongside those of the currently supported platforms. The
5424 bootstrap Guile tarball is treated specially: it is expected to be
5425 available locally, and @file{gnu-system.am} has rules do download it for
5426 the supported architectures; a rule for the new platform must be added
5429 In practice, there may be some complications. First, it may be that the
5430 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
5431 above) is not recognized by all the GNU tools. Typically, glibc
5432 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
5433 configure flag (see @code{gcc.scm} for examples of how to handle this).
5434 Second, some of the required packages could fail to build for that
5435 platform. Lastly, the generated binaries could be broken for some
5439 @c *********************************************************************
5441 @chapter Contributing
5443 This project is a cooperative effort, and we need your help to make it
5444 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
5445 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
5446 reports, patches, and anything that may be helpful to the project. We
5447 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
5450 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
5451 @file{HACKING} file} that comes with the Guix source code for practical
5452 details about contributions.
5455 @c *********************************************************************
5456 @node Acknowledgments
5457 @chapter Acknowledgments
5459 Guix is based on the Nix package manager, which was designed and
5460 implemented by Eelco Dolstra, with contributions from other people (see
5461 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
5462 management, and promoted unprecedented features, such as transactional
5463 package upgrades and rollbacks, per-user profiles, and referentially
5464 transparent build processes. Without this work, Guix would not exist.
5466 The Nix-based software distributions, Nixpkgs and NixOS, have also been
5467 an inspiration for Guix.
5469 GNU@tie{}Guix itself is a collective work with contributions from a
5470 number of people. See the @file{AUTHORS} file in Guix for more
5471 information on these fine people. The @file{THANKS} file lists people
5472 who have helped by reporting bugs, taking care of the infrastructure,
5473 providing artwork and themes, making suggestions, and more---thank you!
5476 @c *********************************************************************
5477 @node GNU Free Documentation License
5478 @appendix GNU Free Documentation License
5480 @include fdl-1.3.texi
5482 @c *********************************************************************
5484 @unnumbered Concept Index
5487 @node Programming Index
5488 @unnumbered Programming Index
5496 @c ispell-local-dictionary: "american";