6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 Copyright @copyright{} 2012, 2013, 2014 Ludovic Courtès@*
14 Copyright @copyright{} 2013, 2014 Andreas Enge@*
15 Copyright @copyright{} 2013 Nikita Karetnikov
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
21 copy of the license is included in the section entitled ``GNU Free
22 Documentation License''.
25 @dircategory Package management
27 * guix: (guix). Guix, the functional package manager.
28 * guix package: (guix)Invoking guix package
29 Managing packages with Guix.
30 * guix build: (guix)Invoking guix build
31 Building packages with Guix.
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}) and the @command{guix import
262 pypi} command. This is primarily of interest to developers.
263 @xref{Guile Preparations, how to install the GnuTLS bindings for Guile,,
264 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 \
351 The @code{guix-daemon} program may then be run as @code{root} with:
354 # guix-daemon --build-users-group=guix-builder
359 This way, the daemon starts build processes in a chroot, under one of
360 the @code{guix-builder} users. On GNU/Linux, by default, the chroot
361 environment contains nothing but:
363 @c Keep this list in sync with libstore/build.cc! -----------------------
366 a minimal @code{/dev} directory, created mostly independently from the
367 host @code{/dev}@footnote{``Mostly'', because while the set of files
368 that appear in the chroot's @code{/dev} is fixed, most of these files
369 can only be created if the host has them.};
372 the @code{/proc} directory; it only shows the container's processes
373 since a separate PID name space is used;
376 @file{/etc/passwd} with an entry for the current user and an entry for
380 @file{/etc/group} with an entry for the user's group;
383 @file{/etc/hosts} with an entry that maps @code{localhost} to
387 a writable @file{/tmp} directory.
390 If you are installing Guix as an unprivileged user, it is still
391 possible to run @command{guix-daemon}. However, build processes will
392 not be isolated from one another, and not from the rest of the system.
393 Thus, build processes may interfere with each other, and may access
394 programs, libraries, and other files available on the system---making it
395 much harder to view them as @emph{pure} functions.
398 @node Daemon Offload Setup
399 @subsection Using the Offload Facility
403 When desired, the build daemon can @dfn{offload}
404 derivation builds to other machines
405 running Guix, using the @code{offload} @dfn{build hook}. When that
406 feature is enabled, a list of user-specified build machines is read from
407 @file{/etc/guix/machines.scm}; anytime a build is requested, for
408 instance via @code{guix build}, the daemon attempts to offload it to one
409 of the machines that satisfies the derivation's constraints, in
410 particular its system type---e.g., @file{x86_64-linux}. Missing
411 prerequisites for the build are copied over SSH to the target machine,
412 which then proceeds with the build; upon success the output(s) of the
413 build are copied back to the initial machine.
415 The @file{/etc/guix/machines.scm} file typically looks like this:
419 (name "eightysix.example.org")
420 (system "x86_64-linux")
422 (speed 2.)) ; incredibly fast!
425 (name "meeps.example.org")
426 (system "mips64el-linux")
429 (string-append (getenv "HOME")
430 "/.ssh/id-rsa-for-guix"))))
434 In the example above we specify a list of two build machines, one for
435 the @code{x86_64} architecture and one for the @code{mips64el}
438 In fact, this file is---not surprisingly!---a Scheme file that is
439 evaluated when the @code{offload} hook is started. Its return value
440 must be a list of @code{build-machine} objects. While this example
441 shows a fixed list of build machines, one could imagine, say, using
442 DNS-SD to return a list of potential build machines discovered in the
443 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
444 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
447 @deftp {Data Type} build-machine
448 This data type represents build machines the daemon may offload builds
449 to. The important fields are:
454 The remote machine's host name.
457 The remote machine's system type---e.g., @code{"x86_64-linux"}.
460 The user account to use when connecting to the remote machine over SSH.
461 Note that the SSH key pair must @emph{not} be passphrase-protected, to
462 allow non-interactive logins.
466 A number of optional fields may be specified:
471 Port number of the machine's SSH server (default: 22).
474 The SSH private key file to use when connecting to the machine.
476 @item parallel-builds
477 The number of builds that may run in parallel on the machine (1 by
481 A ``relative speed factor''. The offload scheduler will tend to prefer
482 machines with a higher speed factor.
485 A list of strings denoting specific features supported by the machine.
486 An example is @code{"kvm"} for machines that have the KVM Linux modules
487 and corresponding hardware support. Derivations can request features by
488 name, and they will be scheduled on matching build machines.
493 The @code{guix} command must be in the search path on the build
494 machines, since offloading works by invoking the @code{guix archive} and
495 @code{guix build} commands.
497 There's one last thing to do once @file{machines.scm} is in place. As
498 explained above, when offloading, files are transferred back and forth
499 between the machine stores. For this to work, you need to generate a
500 key pair to allow the daemon to export signed archives of files from the
501 store (@pxref{Invoking guix archive}):
504 # guix archive --generate-key
508 Thus, when receiving files, a machine's build daemon can make sure they
509 are genuine, have not been tampered with, and that they are signed by an
513 @node Invoking guix-daemon
514 @section Invoking @command{guix-daemon}
516 The @command{guix-daemon} program implements all the functionality to
517 access the store. This includes launching build processes, running the
518 garbage collector, querying the availability of a build result, etc. It
519 is normally run as @code{root} like this:
522 # guix-daemon --build-users-group=guix-builder
526 For details on how to set it up, @pxref{Setting Up the Daemon}.
529 @cindex container, build environment
530 @cindex build environment
531 @cindex reproducible builds
532 By default, @command{guix-daemon} launches build processes under
533 different UIDs, taken from the build group specified with
534 @code{--build-users-group}. In addition, each build process is run in a
535 chroot environment that only contains the subset of the store that the
536 build process depends on, as specified by its derivation
537 (@pxref{Programming Interface, derivation}), plus a set of specific
538 system directories. By default, the latter contains @file{/dev} and
539 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
540 @dfn{container}: in addition to having its own file system tree, it has
541 a separate mount name space, its own PID name space, network name space,
542 etc. This helps achieve reproducible builds (@pxref{Features}).
544 The following command-line options are supported:
547 @item --build-users-group=@var{group}
548 Take users from @var{group} to run build processes (@pxref{Setting Up
549 the Daemon, build users}).
551 @item --no-substitutes
553 Do not use substitutes for build products. That is, always build things
554 locally instead of allowing downloads of pre-built binaries
555 (@pxref{Substitutes}).
557 By default substitutes are used, unless the client---such as the
558 @command{guix package} command---is explicitly invoked with
559 @code{--no-substitutes}.
561 When the daemon runs with @code{--no-substitutes}, clients can still
562 explicitly enable substitution @i{via} the @code{set-build-options}
563 remote procedure call (@pxref{The Store}).
565 @item --substitute-urls=@var{urls}
566 Consider @var{urls} the default whitespace-separated list of substitute
567 source URLs. When this option is omitted, @code{http://hydra.gnu.org}
570 This means that substitutes may be downloaded from @var{urls}, as long
571 as they are signed by a trusted signature (@pxref{Substitutes}).
574 @item --no-build-hook
575 Do not use the @dfn{build hook}.
577 The build hook is a helper program that the daemon can start and to
578 which it submits build requests. This mechanism is used to offload
579 builds to other machines (@pxref{Daemon Offload Setup}).
581 @item --cache-failures
582 Cache build failures. By default, only successful builds are cached.
584 @item --cores=@var{n}
586 Use @var{n} CPU cores to build each derivation; @code{0} means as many
589 The default value is @code{1}, but it may be overridden by clients, such
590 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
593 The effect is to define the @code{NIX_BUILD_CORES} environment variable
594 in the build process, which can then use it to exploit internal
595 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
597 @item --max-jobs=@var{n}
599 Allow at most @var{n} build jobs in parallel. The default value is
600 @code{1}. Setting it to @code{0} means that no builds will be performed
601 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
602 Setup}), or simply fail.
605 Produce debugging output.
607 This is useful to debug daemon start-up issues, but then it may be
608 overridden by clients, for example the @code{--verbosity} option of
609 @command{guix build} (@pxref{Invoking guix build}).
611 @item --chroot-directory=@var{dir}
612 Add @var{dir} to the build chroot.
614 Doing this may change the result of build processes---for instance if
615 they use optional dependencies found in @var{dir} when it is available,
616 and not otherwise. For that reason, it is not recommended to do so.
617 Instead, make sure that each derivation declares all the inputs that it
620 @item --disable-chroot
621 Disable chroot builds.
623 Using this option is not recommended since, again, it would allow build
624 processes to gain access to undeclared dependencies.
626 @item --disable-log-compression
627 Disable compression of the build logs.
629 Unless @code{--lose-logs} is used, all the build logs are kept in the
630 @var{localstatedir}. To save space, the daemon automatically compresses
631 them with bzip2 by default. This option disables that.
633 @item --disable-deduplication
634 @cindex deduplication
635 Disable automatic file ``deduplication'' in the store.
637 By default, files added to the store are automatically ``deduplicated'':
638 if a newly added file is identical to another one found in the store,
639 the daemon makes the new file a hard link to the other file. This can
640 noticeably reduce disk usage, at the expense of slightly increasde
641 input/output load at the end of a build process. This option disables
644 @item --gc-keep-outputs[=yes|no]
645 Tell whether the garbage collector (GC) must keep outputs of live
648 When set to ``yes'', the GC will keep the outputs of any live derivation
649 available in the store---the @code{.drv} files. The default is ``no'',
650 meaning that derivation outputs are kept only if they are GC roots.
652 @item --gc-keep-derivations[=yes|no]
653 Tell whether the garbage collector (GC) must keep derivations
654 corresponding to live outputs.
656 When set to ``yes'', as is the case by default, the GC keeps
657 derivations---i.e., @code{.drv} files---as long as at least one of their
658 outputs is live. This allows users to keep track of the origins of
659 items in their store. Setting it to ``no'' saves a bit of disk space.
661 Note that when both @code{--gc-keep-derivations} and
662 @code{--gc-keep-outputs} are used, the effect is to keep all the build
663 prerequisites (the sources, compiler, libraries, and other build-time
664 tools) of live objects in the store, regardless of whether these
665 prerequisites are live. This is convenient for developers since it
666 saves rebuilds or downloads.
668 @item --impersonate-linux-2.6
669 On Linux-based systems, impersonate Linux 2.6. This means that the
670 kernel's @code{uname} system call will report 2.6 as the release number.
672 This might be helpful to build programs that (usually wrongfully) depend
673 on the kernel version number.
676 Do not keep build logs. By default they are kept under
677 @code{@var{localstatedir}/guix/log}.
679 @item --system=@var{system}
680 Assume @var{system} as the current system type. By default it is the
681 architecture/kernel pair found at configure time, such as
684 @item --listen=@var{socket}
685 Listen for connections on @var{socket}, the file name of a Unix-domain
686 socket. The default socket is
687 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
688 useful in exceptional circumstances, such as if you need to run several
689 daemons on the same machine.
693 @c *********************************************************************
694 @node Package Management
695 @chapter Package Management
697 The purpose of GNU Guix is to allow users to easily install, upgrade, and
698 remove software packages, without having to know about their build
699 procedure or dependencies. Guix also goes beyond this obvious set of
702 This chapter describes the main features of Guix, as well as the package
703 management tools it provides. Two user interfaces are provided for
704 routine package management tasks: a command-line interface
705 (@pxref{Invoking guix package, @code{guix package}}), and a visual user
706 interface in Emacs (@pxref{Emacs Interface}).
709 * Features:: How Guix will make your life brighter.
710 * Invoking guix package:: Package installation, removal, etc.
711 * Emacs Interface:: Package management from Emacs.
712 * Substitutes:: Downloading pre-built binaries.
713 * Packages with Multiple Outputs:: Single source package, multiple outputs.
714 * Invoking guix gc:: Running the garbage collector.
715 * Invoking guix pull:: Fetching the latest Guix and distribution.
716 * Invoking guix archive:: Exporting and importing store files.
722 When using Guix, each package ends up in the @dfn{package store}, in its
723 own directory---something that resembles
724 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
725 (note that Guix comes with an Emacs extension to shorten those file
726 names, @pxref{Emacs Prettify}.)
728 Instead of referring to these directories, users have their own
729 @dfn{profile}, which points to the packages that they actually want to
730 use. These profiles are stored within each user's home directory, at
731 @code{$HOME/.guix-profile}.
733 For example, @code{alice} installs GCC 4.7.2. As a result,
734 @file{/home/alice/.guix-profile/bin/gcc} points to
735 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
736 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
737 simply continues to point to
738 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
739 coexist on the same system without any interference.
741 The @command{guix package} command is the central tool to manage
742 packages (@pxref{Invoking guix package}). It operates on those per-user
743 profiles, and can be used @emph{with normal user privileges}.
745 The command provides the obvious install, remove, and upgrade
746 operations. Each invocation is actually a @emph{transaction}: either
747 the specified operation succeeds, or nothing happens. Thus, if the
748 @command{guix package} process is terminated during the transaction,
749 or if a power outage occurs during the transaction, then the user's
750 profile remains in its previous state, and remains usable.
752 In addition, any package transaction may be @emph{rolled back}. So, if,
753 for example, an upgrade installs a new version of a package that turns
754 out to have a serious bug, users may roll back to the previous instance
755 of their profile, which was known to work well. Similarly, the global
756 system configuration is subject to transactional upgrades and roll-back
757 (@pxref{Using the Configuration System}).
759 All those packages in the package store may be @emph{garbage-collected}.
760 Guix can determine which packages are still referenced by the user
761 profiles, and remove those that are provably no longer referenced
762 (@pxref{Invoking guix gc}). Users may also explicitly remove old
763 generations of their profile so that the packages they refer to can be
766 @cindex reproducibility
767 @cindex reproducible builds
768 Finally, Guix takes a @dfn{purely functional} approach to package
769 management, as described in the introduction (@pxref{Introduction}).
770 Each @file{/gnu/store} package directory name contains a hash of all the
771 inputs that were used to build that package---compiler, libraries, build
772 scripts, etc. This direct correspondence allows users to make sure a
773 given package installation matches the current state of their
774 distribution. It also helps maximize @dfn{build reproducibility}:
775 thanks to the isolated build environments that are used, a given build
776 is likely to yield bit-identical files when performed on different
777 machines (@pxref{Invoking guix-daemon, container}).
780 This foundation allows Guix to support @dfn{transparent binary/source
781 deployment}. When a pre-built binary for a @file{/gnu/store} item is
782 available from an external source---a @dfn{substitute}, Guix just
783 downloads it and unpacks it;
784 otherwise, it builds the package from source, locally
785 (@pxref{Substitutes}).
787 Control over the build environment is a feature that is also useful for
788 developers. The @command{guix environment} command allows developers of
789 a package to quickly set up the right development environment for their
790 package, without having to manually install the package's dependencies
791 in their profile (@pxref{Invoking guix environment}).
793 @node Invoking guix package
794 @section Invoking @command{guix package}
796 The @command{guix package} command is the tool that allows users to
797 install, upgrade, and remove packages, as well as rolling back to
798 previous configurations. It operates only on the user's own profile,
799 and works with normal user privileges (@pxref{Features}). Its syntax
803 guix package @var{options}
806 Primarily, @var{options} specifies the operations to be performed during
807 the transaction. Upon completion, a new profile is created, but
808 previous generations of the profile remain available, should the user
811 For example, to remove @code{lua} and install @code{guile} and
812 @code{guile-cairo} in a single transaction:
815 guix package -r lua -i guile guile-cairo
818 For each user, a symlink to the user's default profile is automatically
819 created in @file{$HOME/.guix-profile}. This symlink always points to the
820 current generation of the user's default profile. Thus, users can add
821 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
824 In a multi-user setup, user profiles must be stored in a place
825 registered as a @dfn{garbage-collector root}, which
826 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
827 directory is normally
828 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
829 @var{localstatedir} is the value passed to @code{configure} as
830 @code{--localstatedir}, and @var{user} is the user name. It must be
831 created by @code{root}, with @var{user} as the owner. When it does not
832 exist, or is not owned by @var{user}, @command{guix package} emits an
835 The @var{options} can be among the following:
839 @item --install=@var{package} @dots{}
840 @itemx -i @var{package} @dots{}
841 Install the specified @var{package}s.
843 Each @var{package} may specify either a simple package name, such as
844 @code{guile}, or a package name followed by a hyphen and version number,
845 such as @code{guile-1.8.8}. If no version number is specified, the
846 newest available version will be selected. In addition, @var{package}
847 may contain a colon, followed by the name of one of the outputs of the
848 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
849 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
850 name (and optionally version) are searched for among the GNU
851 distribution modules (@pxref{Package Modules}).
853 @cindex propagated inputs
854 Sometimes packages have @dfn{propagated inputs}: these are dependencies
855 that automatically get installed along with the required package.
857 An example is the GNU MPC library: its C header files refer to those of
858 the GNU MPFR library, which in turn refer to those of the GMP library.
859 Thus, when installing MPC, the MPFR and GMP libraries also get installed
860 in the profile; removing MPC also removes MPFR and GMP---unless they had
861 also been explicitly installed independently.
863 Besides, packages sometimes rely on the definition of environment
864 variables for their search paths (see explanation of
865 @code{--search-paths} below). Any missing or possibly incorrect
866 environment variable definitions are reported here.
868 @c XXX: keep me up-to-date
869 Finally, when installing a GNU package, the tool reports the
870 availability of a newer upstream version. In the future, it may provide
871 the option of installing directly from the upstream version, even if
872 that version is not yet in the distribution.
874 @item --install-from-expression=@var{exp}
876 Install the package @var{exp} evaluates to.
878 @var{exp} must be a Scheme expression that evaluates to a
879 @code{<package>} object. This option is notably useful to disambiguate
880 between same-named variants of a package, with expressions such as
881 @code{(@@ (gnu packages base) guile-final)}.
883 Note that this option installs the first output of the specified
884 package, which may be insufficient when needing a specific output of a
885 multiple-output package.
887 @item --remove=@var{package} @dots{}
888 @itemx -r @var{package} @dots{}
889 Remove the specified @var{package}s.
891 As for @code{--install}, each @var{package} may specify a version number
892 and/or output name in addition to the package name. For instance,
893 @code{-r glibc:debug} would remove the @code{debug} output of
896 @item --upgrade[=@var{regexp} @dots{}]
897 @itemx -u [@var{regexp} @dots{}]
898 Upgrade all the installed packages. If one or more @var{regexp}s are
899 specified, upgrade only installed packages whose name matches a
902 Note that this upgrades package to the latest version of packages found
903 in the distribution currently installed. To update your distribution,
904 you should regularly run @command{guix pull} (@pxref{Invoking guix
908 Roll back to the previous @dfn{generation} of the profile---i.e., undo
909 the last transaction.
911 When combined with options such as @code{--install}, roll back occurs
912 before any other actions.
914 When rolling back from the first generation that actually contains
915 installed packages, the profile is made to point to the @dfn{zeroth
916 generation}, which contains no files apart from its own meta-data.
918 Installing, removing, or upgrading packages from a generation that has
919 been rolled back to overwrites previous future generations. Thus, the
920 history of a profile's generations is always linear.
922 @item --switch-generation=@var{pattern}
923 @itemx -S @var{pattern}
924 Switch to a particular generation defined by @var{pattern}.
926 @var{pattern} may be either a generation number or a number prefixed
927 with ``+'' or ``-''. The latter means: move forward/backward by a
928 specified number of generations. For example, if you want to return to
929 the latest generation after @code{--roll-back}, use
930 @code{--switch-generation=+1}.
932 The difference between @code{--roll-back} and
933 @code{--switch-generation=-1} is that @code{--switch-generation} will
934 not make a zeroth generation, so if a specified generation does not
935 exist, the current generation will not be changed.
939 Report environment variable definitions, in Bash syntax, that may be
940 needed in order to use the set of installed packages. These environment
941 variables are used to specify @dfn{search paths} for files used by some
942 of the installed packages.
944 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
945 environment variables to be defined so it can look for headers and
946 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
947 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
948 library are installed in the profile, then @code{--search-paths} will
949 suggest setting these variables to @code{@var{profile}/include} and
950 @code{@var{profile}/lib}, respectively.
952 @item --profile=@var{profile}
953 @itemx -p @var{profile}
954 Use @var{profile} instead of the user's default profile.
957 Produce verbose output. In particular, emit the environment's build log
958 on the standard error port.
961 Use the bootstrap Guile to build the profile. This option is only
962 useful to distribution developers.
966 In addition to these actions @command{guix package} supports the
967 following options to query the current state of a profile, or the
968 availability of packages:
972 @item --search=@var{regexp}
973 @itemx -s @var{regexp}
974 List the available packages whose synopsis or description matches
975 @var{regexp}. Print all the meta-data of matching packages in
976 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
977 GNU recutils manual}).
979 This allows specific fields to be extracted using the @command{recsel}
980 command, for instance:
983 $ guix package -s malloc | recsel -p name,version
991 Similarly, to show the name of all the packages available under the
992 terms of the GNU@tie{}LGPL version 3:
995 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
1002 @item --show=@var{package}
1003 Show details about @var{package}, taken from the list of available packages, in
1004 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
1008 $ guix package --show=python | recsel -p name,version
1016 You may also specify the full name of a package to only get details about a
1017 specific version of it:
1019 $ guix package --show=python-3.3.5 | recsel -p name,version
1026 @item --list-installed[=@var{regexp}]
1027 @itemx -I [@var{regexp}]
1028 List the currently installed packages in the specified profile, with the
1029 most recently installed packages shown last. When @var{regexp} is
1030 specified, list only installed packages whose name matches @var{regexp}.
1032 For each installed package, print the following items, separated by
1033 tabs: the package name, its version string, the part of the package that
1034 is installed (for instance, @code{out} for the default output,
1035 @code{include} for its headers, etc.), and the path of this package in
1038 @item --list-available[=@var{regexp}]
1039 @itemx -A [@var{regexp}]
1040 List packages currently available in the software distribution
1041 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
1042 installed packages whose name matches @var{regexp}.
1044 For each package, print the following items separated by tabs: its name,
1045 its version string, the parts of the package (@pxref{Packages with
1046 Multiple Outputs}), and the source location of its definition.
1048 @item --list-generations[=@var{pattern}]
1049 @itemx -l [@var{pattern}]
1050 Return a list of generations along with their creation dates; for each
1051 generation, show the installed packages, with the most recently
1052 installed packages shown last. Note that the zeroth generation is never
1055 For each installed package, print the following items, separated by
1056 tabs: the name of a package, its version string, the part of the package
1057 that is installed (@pxref{Packages with Multiple Outputs}), and the
1058 location of this package in the store.
1060 When @var{pattern} is used, the command returns only matching
1061 generations. Valid patterns include:
1064 @item @emph{Integers and comma-separated integers}. Both patterns denote
1065 generation numbers. For instance, @code{--list-generations=1} returns
1068 And @code{--list-generations=1,8,2} outputs three generations in the
1069 specified order. Neither spaces nor trailing commas are allowed.
1071 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
1072 specified generations and everything in between. Note that the start of
1073 a range must be lesser than its end.
1075 It is also possible to omit the endpoint. For example,
1076 @code{--list-generations=2..}, returns all generations starting from the
1079 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
1080 or months by passing an integer along with the first letter of the
1081 duration. For example, @code{--list-generations=20d} lists generations
1082 that are up to 20 days old.
1085 @item --delete-generations[=@var{pattern}]
1086 @itemx -d [@var{pattern}]
1087 When @var{pattern} is omitted, delete all generations except the current
1090 This command accepts the same patterns as @option{--list-generations}.
1091 When @var{pattern} is specified, delete the matching generations. When
1092 @var{pattern} specifies a duration, generations @emph{older} than the
1093 specified duration match. For instance, @code{--delete-generations=1m}
1094 deletes generations that are more than one month old.
1096 If the current generation matches, it is deleted atomically---i.e., by
1097 switching to the previous available generation. Note that the zeroth
1098 generation is never deleted.
1100 Note that deleting generations prevents roll-back to them.
1101 Consequently, this command must be used with care.
1105 Finally, since @command{guix package} may actually start build
1106 processes, it supports all the common build options that @command{guix
1107 build} supports (@pxref{Invoking guix build, common build options}).
1112 @section Substitutes
1115 @cindex pre-built binaries
1116 Guix supports transparent source/binary deployment, which means that it
1117 can either build things locally, or download pre-built items from a
1118 server. We call these pre-built items @dfn{substitutes}---they are
1119 substitutes for local build results. In many cases, downloading a
1120 substitute is much faster than building things locally.
1122 Substitutes can be anything resulting from a derivation build
1123 (@pxref{Derivations}). Of course, in the common case, they are
1124 pre-built package binaries, but source tarballs, for instance, which
1125 also result from derivation builds, can be available as substitutes.
1127 The @code{hydra.gnu.org} server is a front-end to a build farm that
1128 builds packages from the GNU distribution continuously for some
1129 architectures, and makes them available as substitutes. This is the
1130 default source of substitutes; it can be overridden by passing
1131 @command{guix-daemon} the @code{--substitute-urls} option
1132 (@pxref{Invoking guix-daemon}).
1135 @cindex digital signatures
1136 To allow Guix to download substitutes from @code{hydra.gnu.org}, you
1137 must add its public key to the access control list (ACL) of archive
1138 imports, using the @command{guix archive} command (@pxref{Invoking guix
1139 archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
1140 be compromised and to serve genuine substitutes.
1142 This public key is installed along with Guix, in
1143 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
1144 the installation prefix of Guix. If you installed Guix from source,
1145 make sure you checked the GPG signature of
1146 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
1147 Then, you can run something like this:
1150 # guix archive --authorize < hydra.gnu.org.pub
1153 Once this is in place, the output of a command like @code{guix build}
1154 should change from something like:
1157 $ guix build emacs --dry-run
1158 The following derivations would be built:
1159 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
1160 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
1161 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
1162 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
1170 $ guix build emacs --dry-run
1171 The following files would be downloaded:
1172 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
1173 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
1174 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
1175 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
1180 This indicates that substitutes from @code{hydra.gnu.org} are usable and
1181 will be downloaded, when possible, for future builds.
1183 Guix ignores substitutes that are not signed, or that are not signed by
1184 one of the keys listed in the ACL. It also detects and raises an error
1185 when attempting to use a substitute that has been tampered with.
1187 The substitute mechanism can be disabled globally by running
1188 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1189 guix-daemon}). It can also be disabled temporarily by passing the
1190 @code{--no-substitutes} option to @command{guix package}, @command{guix
1191 build}, and other command-line tools.
1194 Today, each individual's control over their own computing is at the
1195 mercy of institutions, corporations, and groups with enough power and
1196 determination to subvert the computing infrastructure and exploit its
1197 weaknesses. While using @code{hydra.gnu.org} substitutes can be
1198 convenient, we encourage users to also build on their own, or even run
1199 their own build farm, such that @code{hydra.gnu.org} is less of an
1202 Guix has the foundations to maximize build reproducibility
1203 (@pxref{Features}). In most cases, independent builds of a given
1204 package or derivation should yield bit-identical results. Thus, through
1205 a diverse set of independent package builds, we can strengthen the
1206 integrity of our systems.
1208 In the future, we want Guix to have support to publish and retrieve
1209 binaries to/from other users, in a peer-to-peer fashion. If you would
1210 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1213 @node Packages with Multiple Outputs
1214 @section Packages with Multiple Outputs
1216 @cindex multiple-output packages
1217 @cindex package outputs
1219 Often, packages defined in Guix have a single @dfn{output}---i.e., the
1220 source package leads exactly one directory in the store. When running
1221 @command{guix package -i glibc}, one installs the default output of the
1222 GNU libc package; the default output is called @code{out}, but its name
1223 can be omitted as shown in this command. In this particular case, the
1224 default output of @code{glibc} contains all the C header files, shared
1225 libraries, static libraries, Info documentation, and other supporting
1228 Sometimes it is more appropriate to separate the various types of files
1229 produced from a single source package into separate outputs. For
1230 instance, the GLib C library (used by GTK+ and related packages)
1231 installs more than 20 MiB of reference documentation as HTML pages.
1232 To save space for users who do not need it, the documentation goes to a
1233 separate output, called @code{doc}. To install the main GLib output,
1234 which contains everything but the documentation, one would run:
1237 guix package -i glib
1240 The command to install its documentation is:
1243 guix package -i glib:doc
1246 Some packages install programs with different ``dependency footprints''.
1247 For instance, the WordNet package install both command-line tools and
1248 graphical user interfaces (GUIs). The former depend solely on the C
1249 library, whereas the latter depend on Tcl/Tk and the underlying X
1250 libraries. In this case, we leave the command-line tools in the default
1251 output, whereas the GUIs are in a separate output. This allows users
1252 who do not need the GUIs to save space.
1254 There are several such multiple-output packages in the GNU distribution.
1255 Other conventional output names include @code{lib} for libraries and
1256 possibly header files, @code{bin} for stand-alone programs, and
1257 @code{debug} for debugging information (@pxref{Installing Debugging
1258 Files}). The outputs of a packages are listed in the third column of
1259 the output of @command{guix package --list-available} (@pxref{Invoking
1263 @node Invoking guix gc
1264 @section Invoking @command{guix gc}
1266 @cindex garbage collector
1267 Packages that are installed but not used may be @dfn{garbage-collected}.
1268 The @command{guix gc} command allows users to explicitly run the garbage
1269 collector to reclaim space from the @file{/gnu/store} directory.
1271 The garbage collector has a set of known @dfn{roots}: any file under
1272 @file{/gnu/store} reachable from a root is considered @dfn{live} and
1273 cannot be deleted; any other file is considered @dfn{dead} and may be
1274 deleted. The set of garbage collector roots includes default user
1275 profiles, and may be augmented with @command{guix build --root}, for
1276 example (@pxref{Invoking guix build}).
1278 Prior to running @code{guix gc --collect-garbage} to make space, it is
1279 often useful to remove old generations from user profiles; that way, old
1280 package builds referenced by those generations can be reclaimed. This
1281 is achieved by running @code{guix package --delete-generations}
1282 (@pxref{Invoking guix package}).
1284 The @command{guix gc} command has three modes of operation: it can be
1285 used to garbage-collect any dead files (the default), to delete specific
1286 files (the @code{--delete} option), or to print garbage-collector
1287 information. The available options are listed below:
1290 @item --collect-garbage[=@var{min}]
1291 @itemx -C [@var{min}]
1292 Collect garbage---i.e., unreachable @file{/gnu/store} files and
1293 sub-directories. This is the default operation when no option is
1296 When @var{min} is given, stop once @var{min} bytes have been collected.
1297 @var{min} may be a number of bytes, or it may include a unit as a
1298 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
1299 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
1301 When @var{min} is omitted, collect all the garbage.
1305 Attempt to delete all the store files and directories specified as
1306 arguments. This fails if some of the files are not in the store, or if
1307 they are still live.
1310 Show the list of dead files and directories still present in the
1311 store---i.e., files and directories no longer reachable from any root.
1314 Show the list of live store files and directories.
1318 In addition, the references among existing store files can be queried:
1324 List the references (respectively, the referrers) of store files given
1329 List the requisites of the store files passed as arguments. Requisites
1330 include the store files themselves, their references, and the references
1331 of these, recursively. In other words, the returned list is the
1332 @dfn{transitive closure} of the store files.
1337 @node Invoking guix pull
1338 @section Invoking @command{guix pull}
1340 Packages are installed or upgraded to the latest version available in
1341 the distribution currently available on your local machine. To update
1342 that distribution, along with the Guix tools, you must run @command{guix
1343 pull}: the command downloads the latest Guix source code and package
1344 descriptions, and deploys it.
1346 On completion, @command{guix package} will use packages and package
1347 versions from this just-retrieved copy of Guix. Not only that, but all
1348 the Guix commands and Scheme modules will also be taken from that latest
1349 version. New @command{guix} sub-commands added by the update also
1352 The @command{guix pull} command is usually invoked with no arguments,
1353 but it supports the following options:
1357 Produce verbose output, writing build logs to the standard error output.
1359 @item --url=@var{url}
1360 Download the source tarball of Guix from @var{url}.
1362 By default, the tarball is taken from its canonical address at
1363 @code{gnu.org}, for the stable branch of Guix.
1366 Use the bootstrap Guile to build the latest Guix. This option is only
1367 useful to Guix developers.
1371 @node Invoking guix archive
1372 @section Invoking @command{guix archive}
1374 The @command{guix archive} command allows users to @dfn{export} files
1375 from the store into a single archive, and to later @dfn{import} them.
1376 In particular, it allows store files to be transferred from one machine
1377 to another machine's store. For example, to transfer the @code{emacs}
1378 package to a machine connected over SSH, one would run:
1381 guix archive --export emacs | ssh the-machine guix archive --import
1385 However, note that, in this example, all of @code{emacs} and its
1386 dependencies are transferred, regardless of what is already available in
1387 the target machine's store. The @code{--missing} option can help figure
1388 out which items are missing from the target's store.
1390 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1391 comparable in spirit to `tar', but with a few noteworthy differences
1392 that make it more appropriate for our purposes. First, rather than
1393 recording all Unix meta-data for each file, the Nar format only mentions
1394 the file type (regular, directory, or symbolic link); Unix permissions
1395 and owner/group are dismissed. Second, the order in which directory
1396 entries are stored always follows the order of file names according to
1397 the C locale collation order. This makes archive production fully
1400 When exporting, the daemon digitally signs the contents of the archive,
1401 and that digital signature is appended. When importing, the daemon
1402 verifies the signature and rejects the import in case of an invalid
1403 signature or if the signing key is not authorized.
1404 @c FIXME: Add xref to daemon doc about signatures.
1406 The main options are:
1410 Export the specified store files or packages (see below.) Write the
1411 resulting archive to the standard output.
1414 Read an archive from the standard input, and import the files listed
1415 therein into the store. Abort if the archive has an invalid digital
1416 signature, or if it is signed by a public key not among the authorized
1417 keys (see @code{--authorize} below.)
1420 Read a list of store file names from the standard input, one per line,
1421 and write on the standard output the subset of these files missing from
1424 @item --generate-key[=@var{parameters}]
1425 @cindex signing, archives
1426 Generate a new key pair for the daemons. This is a prerequisite before
1427 archives can be exported with @code{--export}. Note that this operation
1428 usually takes time, because it needs to gather enough entropy to
1429 generate the key pair.
1431 The generated key pair is typically stored under @file{/etc/guix}, in
1432 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1433 key, which must be kept secret.) When @var{parameters} is omitted, it
1434 is a 4096-bit RSA key. Alternately, @var{parameters} can specify
1435 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1436 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1437 Libgcrypt Reference Manual}).
1440 @cindex authorizing, archives
1441 Authorize imports signed by the public key passed on standard input.
1442 The public key must be in ``s-expression advanced format''---i.e., the
1443 same format as the @file{signing-key.pub} file.
1445 The list of authorized keys is kept in the human-editable file
1446 @file{/etc/guix/acl}. The file contains
1447 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1448 s-expressions''} and is structured as an access-control list in the
1449 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1453 To export store files as an archive to the standard output, run:
1456 guix archive --export @var{options} @var{specifications}...
1459 @var{specifications} may be either store file names or package
1460 specifications, as for @command{guix package} (@pxref{Invoking guix
1461 package}). For instance, the following command creates an archive
1462 containing the @code{gui} output of the @code{git} package and the main
1463 output of @code{emacs}:
1466 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
1469 If the specified packages are not built yet, @command{guix archive}
1470 automatically builds them. The build process may be controlled with the
1471 same options that can be passed to the @command{guix build} command
1472 (@pxref{Invoking guix build, common build options}).
1475 @c *********************************************************************
1476 @node Programming Interface
1477 @chapter Programming Interface
1479 GNU Guix provides several Scheme programming interfaces (APIs) to
1480 define, build, and query packages. The first interface allows users to
1481 write high-level package definitions. These definitions refer to
1482 familiar packaging concepts, such as the name and version of a package,
1483 its build system, and its dependencies. These definitions can then be
1484 turned into concrete build actions.
1486 Build actions are performed by the Guix daemon, on behalf of users. In a
1487 standard setup, the daemon has write access to the store---the
1488 @file{/gnu/store} directory---whereas users do not. The recommended
1489 setup also has the daemon perform builds in chroots, under a specific
1490 build users, to minimize interference with the rest of the system.
1493 Lower-level APIs are available to interact with the daemon and the
1494 store. To instruct the daemon to perform a build action, users actually
1495 provide it with a @dfn{derivation}. A derivation is a low-level
1496 representation of the build actions to be taken, and the environment in
1497 which they should occur---derivations are to package definitions what
1498 assembly is to C programs. The term ``derivation'' comes from the fact
1499 that build results @emph{derive} from them.
1501 This chapter describes all these APIs in turn, starting from high-level
1502 package definitions.
1505 * Defining Packages:: Defining new packages.
1506 * Build Systems:: Specifying how packages are built.
1507 * The Store:: Manipulating the package store.
1508 * Derivations:: Low-level interface to package derivations.
1509 * The Store Monad:: Purely functional interface to the store.
1510 * G-Expressions:: Manipulating build expressions.
1513 @node Defining Packages
1514 @section Defining Packages
1516 The high-level interface to package definitions is implemented in the
1517 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1518 example, the package definition, or @dfn{recipe}, for the GNU Hello
1519 package looks like this:
1522 (define-module (gnu packages hello)
1523 #:use-module (guix packages)
1524 #:use-module (guix download)
1525 #:use-module (guix build-system gnu)
1526 #:use-module (guix licenses))
1528 (define-public hello
1534 (uri (string-append "mirror://gnu/hello/hello-" version
1537 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1538 (build-system gnu-build-system)
1539 (arguments `(#:configure-flags '("--enable-silent-rules")))
1540 (inputs `(("gawk" ,gawk)))
1541 (synopsis "Hello, GNU world: An example GNU package")
1542 (description "Guess what GNU Hello prints!")
1543 (home-page "http://www.gnu.org/software/hello/")
1548 Without being a Scheme expert, the reader may have guessed the meaning
1549 of the various fields here. This expression binds variable @code{hello}
1550 to a @code{<package>} object, which is essentially a record
1551 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1552 This package object can be inspected using procedures found in the
1553 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1554 returns---surprise!---@code{"hello"}.
1556 With luck, you may be able to import part or all of the definition of
1557 the package you are interested in from another repository, using the
1558 @code{guix import} command (@pxref{Invoking guix import}).
1560 In the example above, @var{hello} is defined into a module of its own,
1561 @code{(gnu packages hello)}. Technically, this is not strictly
1562 necessary, but it is convenient to do so: all the packages defined in
1563 modules under @code{(gnu packages @dots{})} are automatically known to
1564 the command-line tools (@pxref{Package Modules}).
1566 There are a few points worth noting in the above package definition:
1570 The @code{source} field of the package is an @code{<origin>} object.
1571 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1572 meaning that the source is a file to be downloaded over FTP or HTTP.
1574 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1575 the GNU mirrors defined in @code{(guix download)}.
1577 The @code{sha256} field specifies the expected SHA256 hash of the file
1578 being downloaded. It is mandatory, and allows Guix to check the
1579 integrity of the file. The @code{(base32 @dots{})} form introduces the
1580 base32 representation of the hash. You can obtain this information with
1581 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1582 hash} (@pxref{Invoking guix hash}).
1585 When needed, the @code{origin} form can also have a @code{patches} field
1586 listing patches to be applied, and a @code{snippet} field giving a
1587 Scheme expression to modify the source code.
1590 @cindex GNU Build System
1591 The @code{build-system} field specifies the procedure to build the
1592 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1593 represents the familiar GNU Build System, where packages may be
1594 configured, built, and installed with the usual @code{./configure &&
1595 make && make check && make install} command sequence.
1598 The @code{arguments} field specifies options for the build system
1599 (@pxref{Build Systems}). Here it is interpreted by
1600 @var{gnu-build-system} as a request run @file{configure} with the
1601 @code{--enable-silent-rules} flag.
1604 The @code{inputs} field specifies inputs to the build process---i.e.,
1605 build-time or run-time dependencies of the package. Here, we define an
1606 input called @code{"gawk"} whose value is that of the @var{gawk}
1607 variable; @var{gawk} is itself bound to a @code{<package>} object.
1609 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1610 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1611 of ensuring that they are present (@pxref{Build Systems}).
1613 However, any other dependencies need to be specified in the
1614 @code{inputs} field. Any dependency not specified here will simply be
1615 unavailable to the build process, possibly leading to a build failure.
1618 Once a package definition is in place, the
1619 package may actually be built using the @code{guix build} command-line
1620 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1621 more information on how to test package definitions, and
1622 @ref{Invoking guix lint}, for information on how to check a definition
1623 for style conformance.
1625 Eventually, updating the package definition to a new upstream version
1626 can be partly automated by the @command{guix refresh} command
1627 (@pxref{Invoking guix refresh}).
1629 Behind the scenes, a derivation corresponding to the @code{<package>}
1630 object is first computed by the @code{package-derivation} procedure.
1631 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1632 The build actions it prescribes may then be realized by using the
1633 @code{build-derivations} procedure (@pxref{The Store}).
1635 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1636 Return the @code{<derivation>} object of @var{package} for @var{system}
1637 (@pxref{Derivations}).
1639 @var{package} must be a valid @code{<package>} object, and @var{system}
1640 must be a string denoting the target system type---e.g.,
1641 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1642 must be a connection to the daemon, which operates on the store
1643 (@pxref{The Store}).
1647 @cindex cross-compilation
1648 Similarly, it is possible to compute a derivation that cross-builds a
1649 package for some other system:
1651 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1652 @var{package} @var{target} [@var{system}]
1653 Return the @code{<derivation>} object of @var{package} cross-built from
1654 @var{system} to @var{target}.
1656 @var{target} must be a valid GNU triplet denoting the target hardware
1657 and operating system, such as @code{"mips64el-linux-gnu"}
1658 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1659 Configure and Build System}).
1664 @section Build Systems
1666 @cindex build system
1667 Each package definition specifies a @dfn{build system} and arguments for
1668 that build system (@pxref{Defining Packages}). This @code{build-system}
1669 field represents the build procedure of the package, as well implicit
1670 dependencies of that build procedure.
1672 Build systems are @code{<build-system>} objects. The interface to
1673 create and manipulate them is provided by the @code{(guix build-system)}
1674 module, and actual build systems are exported by specific modules.
1676 @cindex bag (low-level package representation)
1677 Under the hood, build systems first compile package objects to
1678 @dfn{bags}. A @dfn{bag} is like a package, but with less
1679 ornamentation---in other words, a bag is a lower-level representation of
1680 a package, which includes all the inputs of that package, including some
1681 that were implicitly added by the build system. This intermediate
1682 representation is then compiled to a derivation (@pxref{Derivations}).
1684 Build systems accept an optional list of @dfn{arguments}. In package
1685 definitions, these are passed @i{via} the @code{arguments} field
1686 (@pxref{Defining Packages}). They are typically keyword arguments
1687 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
1688 Guile Reference Manual}). The value of these arguments is usually
1689 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
1690 by the daemon (@pxref{Derivations}).
1692 The main build system is @var{gnu-build-system}, which implements the
1693 standard build procedure for GNU packages and many other packages. It
1694 is provided by the @code{(guix build-system gnu)} module.
1696 @defvr {Scheme Variable} gnu-build-system
1697 @var{gnu-build-system} represents the GNU Build System, and variants
1698 thereof (@pxref{Configuration, configuration and makefile conventions,,
1699 standards, GNU Coding Standards}).
1701 @cindex build phases
1702 In a nutshell, packages using it configured, built, and installed with
1703 the usual @code{./configure && make && make check && make install}
1704 command sequence. In practice, a few additional steps are often needed.
1705 All these steps are split up in separate @dfn{phases},
1706 notably@footnote{Please see the @code{(guix build gnu-build-system)}
1707 modules for more details about the build phases.}:
1711 Unpack the source tarball, and change the current directory to the
1712 extracted source tree. If the source is actually a directory, copy it
1713 to the build tree, and enter that directory.
1715 @item patch-source-shebangs
1716 Patch shebangs encountered in source files so they refer to the right
1717 store file names. For instance, this changes @code{#!/bin/sh} to
1718 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
1721 Run the @file{configure} script with a number of default options, such
1722 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
1723 by the @code{#:configure-flags} argument.
1726 Run @code{make} with the list of flags specified with
1727 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
1728 (the default), build with @code{make -j}.
1731 Run @code{make check}, or some other target specified with
1732 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
1733 @code{#:parallel-tests?} argument is true (the default), run @code{make
1737 Run @code{make install} with the flags listed in @code{#:make-flags}.
1739 @item patch-shebangs
1740 Patch shebangs on the installed executable files.
1743 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
1744 is false), copying them to the @code{debug} output when available
1745 (@pxref{Installing Debugging Files}).
1748 @vindex %standard-phases
1749 The build-side module @code{(guix build gnu-build-system)} defines
1750 @var{%standard-phases} as the default list of build phases.
1751 @var{%standard-phases} is a list of symbol/procedure pairs, where the
1752 procedure implements the actual phase.
1754 The list of phases used for a particular package can be changed with the
1755 @code{#:phases} parameter. For instance, passing:
1758 #:phases (alist-delete 'configure %standard-phases)
1761 means that all the phases described above will be used, except the
1762 @code{configure} phase.
1764 In addition, this build system ensures that the ``standard'' environment
1765 for GNU packages is available. This includes tools such as GCC, libc,
1766 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
1767 build-system gnu)} module for a complete list.) We call these the
1768 @dfn{implicit inputs} of a package, because package definitions don't
1769 have to mention them.
1772 Other @code{<build-system>} objects are defined to support other
1773 conventions and tools used by free software packages. They inherit most
1774 of @var{gnu-build-system}, and differ mainly in the set of inputs
1775 implicitly added to the build process, and in the list of phases
1776 executed. Some of these build systems are listed below.
1778 @defvr {Scheme Variable} cmake-build-system
1779 This variable is exported by @code{(guix build-system cmake)}. It
1780 implements the build procedure for packages using the
1781 @url{http://www.cmake.org, CMake build tool}.
1783 It automatically adds the @code{cmake} package to the set of inputs.
1784 Which package is used can be specified with the @code{#:cmake}
1787 The @code{#:configure-flags} parameter is taken as a list of flags
1788 passed to the @command{cmake} command. The @code{#:build-type}
1789 parameter specifies in abstract terms the flags passed to the compiler;
1790 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
1791 debugging information''), which roughly means that code is compiled with
1792 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
1795 @defvr {Scheme Variable} glib-or-gtk-build-system
1796 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
1797 is intended for use with packages making use of GLib or GTK+.
1799 This build system adds the following two phases to the ones defined by
1800 @var{gnu-build-system}:
1803 @item glib-or-gtk-wrap
1804 The phase @code{glib-or-gtk-wrap} ensures that programs found under
1805 @file{bin/} are able to find GLib's ``schemas'' and
1806 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
1807 modules}. This is achieved by wrapping the programs in launch scripts
1808 that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
1809 environment variables.
1811 @item glib-or-gtk-compile-schemas
1812 The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
1813 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
1814 GSettings schemas} are compiled. Compilation is performed by the
1815 @command{glib-compile-schemas} program. It is provided by the package
1816 @code{glib:bin} which is automatically imported by the build system.
1817 The @code{glib} package providing @command{glib-compile-schemas} can be
1818 specified with the @code{#:glib} parameter.
1821 Both phases are executed after the @code{install} phase.
1824 @defvr {Scheme Variable} python-build-system
1825 This variable is exported by @code{(guix build-system python)}. It
1826 implements the more or less standard build procedure used by Python
1827 packages, which consists in running @code{python setup.py build} and
1828 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
1830 For packages that install stand-alone Python programs under @code{bin/},
1831 it takes care of wrapping these programs so their @code{PYTHONPATH}
1832 environment variable points to all the Python libraries they depend on.
1834 Which Python package is used can be specified with the @code{#:python}
1838 @defvr {Scheme Variable} perl-build-system
1839 This variable is exported by @code{(guix build-system perl)}. It
1840 implements the standard build procedure for Perl packages, which
1841 consists in running @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}},
1842 followed by @code{make} and @code{make install}.
1844 The initial @code{perl Makefile.PL} invocation passes flags specified by
1845 the @code{#:make-maker-flags} parameter.
1847 Which Perl package is used can be specified with @code{#:perl}.
1850 @defvr {Scheme Variable} ruby-build-system
1851 This variable is exported by @code{(guix build-system ruby)}. It
1852 implements the RubyGems build procedure used by Ruby packages, which
1853 involves running @code{gem build} followed by @code{gem install}.
1855 Which Ruby package is used can be specified with the @code{#:ruby}
1859 Lastly, for packages that do not need anything as sophisticated, a
1860 ``trivial'' build system is provided. It is trivial in the sense that
1861 it provides basically no support: it does not pull any implicit inputs,
1862 and does not have a notion of build phases.
1864 @defvr {Scheme Variable} trivial-build-system
1865 This variable is exported by @code{(guix build-system trivial)}.
1867 This build system requires a @code{#:builder} argument. This argument
1868 must be a Scheme expression that builds the package's output(s)---as
1869 with @code{build-expression->derivation} (@pxref{Derivations,
1870 @code{build-expression->derivation}}).
1879 Conceptually, the @dfn{store} is where derivations that have been
1880 successfully built are stored---by default, under @file{/gnu/store}.
1881 Sub-directories in the store are referred to as @dfn{store paths}. The
1882 store has an associated database that contains information such has the
1883 store paths referred to by each store path, and the list of @emph{valid}
1884 store paths---paths that result from a successful build.
1886 The store is always accessed by the daemon on behalf of its clients
1887 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1888 connect to the daemon over a Unix-domain socket, send it requests, and
1889 read the result---these are remote procedure calls, or RPCs.
1891 The @code{(guix store)} module provides procedures to connect to the
1892 daemon, and to perform RPCs. These are described below.
1894 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1895 Connect to the daemon over the Unix-domain socket at @var{file}. When
1896 @var{reserve-space?} is true, instruct it to reserve a little bit of
1897 extra space on the file system so that the garbage collector can still
1898 operate, should the disk become full. Return a server object.
1900 @var{file} defaults to @var{%default-socket-path}, which is the normal
1901 location given the options that were passed to @command{configure}.
1904 @deffn {Scheme Procedure} close-connection @var{server}
1905 Close the connection to @var{server}.
1908 @defvr {Scheme Variable} current-build-output-port
1909 This variable is bound to a SRFI-39 parameter, which refers to the port
1910 where build and error logs sent by the daemon should be written.
1913 Procedures that make RPCs all take a server object as their first
1916 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1917 Return @code{#t} when @var{path} is a valid store path.
1920 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1921 Add @var{text} under file @var{name} in the store, and return its store
1922 path. @var{references} is the list of store paths referred to by the
1923 resulting store path.
1926 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1927 Build @var{derivations} (a list of @code{<derivation>} objects or
1928 derivation paths), and return when the worker is done building them.
1929 Return @code{#t} on success.
1932 Note that the @code{(guix monads)} module provides a monad as well as
1933 monadic versions of the above procedures, with the goal of making it
1934 more convenient to work with code that accesses the store (@pxref{The
1938 @i{This section is currently incomplete.}
1941 @section Derivations
1944 Low-level build actions and the environment in which they are performed
1945 are represented by @dfn{derivations}. A derivation contain the
1946 following pieces of information:
1950 The outputs of the derivation---derivations produce at least one file or
1951 directory in the store, but may produce more.
1954 The inputs of the derivations, which may be other derivations or plain
1955 files in the store (patches, build scripts, etc.)
1958 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1961 The file name of a build script in the store, along with the arguments
1965 A list of environment variables to be defined.
1969 @cindex derivation path
1970 Derivations allow clients of the daemon to communicate build actions to
1971 the store. They exist in two forms: as an in-memory representation,
1972 both on the client- and daemon-side, and as files in the store whose
1973 name end in @code{.drv}---these files are referred to as @dfn{derivation
1974 paths}. Derivations paths can be passed to the @code{build-derivations}
1975 procedure to perform the build actions they prescribe (@pxref{The
1978 The @code{(guix derivations)} module provides a representation of
1979 derivations as Scheme objects, along with procedures to create and
1980 otherwise manipulate derivations. The lowest-level primitive to create
1981 a derivation is the @code{derivation} procedure:
1983 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
1984 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
1985 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
1986 [#:system (%current-system)] [#:references-graphs #f] @
1987 [#:allowed-references #f] [#:local-build? #f]
1988 Build a derivation with the given arguments, and return the resulting
1989 @code{<derivation>} object.
1991 When @var{hash} and @var{hash-algo} are given, a
1992 @dfn{fixed-output derivation} is created---i.e., one whose result is
1993 known in advance, such as a file download. If, in addition,
1994 @var{recursive?} is true, then that fixed output may be an executable
1995 file or a directory and @var{hash} must be the hash of an archive
1996 containing this output.
1998 When @var{references-graphs} is true, it must be a list of file
1999 name/store path pairs. In that case, the reference graph of each store
2000 path is exported in the build environment in the corresponding file, in
2001 a simple text format.
2003 When @var{allowed-references} is true, it must be a list of store items
2004 or outputs that the derivation's output may refer to.
2006 When @var{local-build?} is true, declare that the derivation is not a
2007 good candidate for offloading and should rather be built locally
2008 (@pxref{Daemon Offload Setup}). This is the case for small derivations
2009 where the costs of data transfers would outweigh the benefits.
2013 Here's an example with a shell script as its builder, assuming
2014 @var{store} is an open connection to the daemon, and @var{bash} points
2015 to a Bash executable in the store:
2018 (use-modules (guix utils)
2022 (let ((builder ; add the Bash script to the store
2023 (add-text-to-store store "my-builder.sh"
2024 "echo hello world > $out\n" '())))
2025 (derivation store "foo"
2026 bash `("-e" ,builder)
2027 #:inputs `((,bash) (,builder))
2028 #:env-vars '(("HOME" . "/homeless"))))
2029 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
2032 As can be guessed, this primitive is cumbersome to use directly. A
2033 better approach is to write build scripts in Scheme, of course! The
2034 best course of action for that is to write the build code as a
2035 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
2036 information, @pxref{G-Expressions}.
2038 Once upon a time, @code{gexp->derivation} did not exist and constructing
2039 derivations with build code written in Scheme was achieved with
2040 @code{build-expression->derivation}, documented below. This procedure
2041 is now deprecated in favor of the much nicer @code{gexp->derivation}.
2043 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
2044 @var{name} @var{exp} @
2045 [#:system (%current-system)] [#:inputs '()] @
2046 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2047 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2048 [#:references-graphs #f] [#:allowed-references #f] @
2049 [#:local-build? #f] [#:guile-for-build #f]
2050 Return a derivation that executes Scheme expression @var{exp} as a
2051 builder for derivation @var{name}. @var{inputs} must be a list of
2052 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
2053 @code{"out"} is assumed. @var{modules} is a list of names of Guile
2054 modules from the current search path to be copied in the store,
2055 compiled, and made available in the load path during the execution of
2056 @var{exp}---e.g., @code{((guix build utils) (guix build
2057 gnu-build-system))}.
2059 @var{exp} is evaluated in an environment where @code{%outputs} is bound
2060 to a list of output/path pairs, and where @code{%build-inputs} is bound
2061 to a list of string/output-path pairs made from @var{inputs}.
2062 Optionally, @var{env-vars} is a list of string pairs specifying the name
2063 and value of environment variables visible to the builder. The builder
2064 terminates by passing the result of @var{exp} to @code{exit}; thus, when
2065 @var{exp} returns @code{#f}, the build is considered to have failed.
2067 @var{exp} is built using @var{guile-for-build} (a derivation). When
2068 @var{guile-for-build} is omitted or is @code{#f}, the value of the
2069 @code{%guile-for-build} fluid is used instead.
2071 See the @code{derivation} procedure for the meaning of
2072 @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
2076 Here's an example of a single-output derivation that creates a directory
2077 containing one file:
2080 (let ((builder '(let ((out (assoc-ref %outputs "out")))
2081 (mkdir out) ; create /gnu/store/@dots{}-goo
2082 (call-with-output-file (string-append out "/test")
2084 (display '(hello guix) p))))))
2085 (build-expression->derivation store "goo" builder))
2087 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
2091 @node The Store Monad
2092 @section The Store Monad
2096 The procedures that operate on the store described in the previous
2097 sections all take an open connection to the build daemon as their first
2098 argument. Although the underlying model is functional, they either have
2099 side effects or depend on the current state of the store.
2101 The former is inconvenient: the connection to the build daemon has to be
2102 carried around in all those functions, making it impossible to compose
2103 functions that do not take that parameter with functions that do. The
2104 latter can be problematic: since store operations have side effects
2105 and/or depend on external state, they have to be properly sequenced.
2107 @cindex monadic values
2108 @cindex monadic functions
2109 This is where the @code{(guix monads)} module comes in. This module
2110 provides a framework for working with @dfn{monads}, and a particularly
2111 useful monad for our uses, the @dfn{store monad}. Monads are a
2112 construct that allows two things: associating ``context'' with values
2113 (in our case, the context is the store), and building sequences of
2114 computations (here computations includes accesses to the store.) Values
2115 in a monad---values that carry this additional context---are called
2116 @dfn{monadic values}; procedures that return such values are called
2117 @dfn{monadic procedures}.
2119 Consider this ``normal'' procedure:
2122 (define (sh-symlink store)
2123 ;; Return a derivation that symlinks the 'bash' executable.
2124 (let* ((drv (package-derivation store bash))
2125 (out (derivation->output-path drv))
2126 (sh (string-append out "/bin/bash")))
2127 (build-expression->derivation store "sh"
2128 `(symlink ,sh %output))))
2131 Using @code{(guix monads)}, it may be rewritten as a monadic function:
2133 @c FIXME: Find a better example, one that uses 'mlet'.
2135 (define (sh-symlink)
2136 ;; Same, but return a monadic value.
2137 (gexp->derivation "sh"
2138 #~(symlink (string-append #$bash "/bin/bash") #$output)))
2141 There are two things to note in the second version: the @code{store}
2142 parameter is now implicit, and the monadic value returned by
2143 @code{package-file}---a wrapper around @code{package-derivation} and
2144 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
2145 instead of plain @code{let}.
2147 Calling the monadic @code{profile.sh} has no effect. To get the desired
2148 effect, one must use @code{run-with-store}:
2151 (run-with-store (open-connection) (profile.sh))
2152 @result{} /gnu/store/...-profile.sh
2155 Note that the @code{(guix monad-repl)} module extends Guile's REPL with
2156 new ``meta-commands'' to make it easier to deal with monadic procedures:
2157 @code{run-in-store}, and @code{enter-store-monad}. The former, is used
2158 to ``run'' a single monadic value through the store:
2161 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
2162 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2165 The latter enters a recursive REPL, where all the return values are
2166 automatically run through the store:
2169 scheme@@(guile-user)> ,enter-store-monad
2170 store-monad@@(guile-user) [1]> (package->derivation hello)
2171 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2172 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
2173 $3 = "/gnu/store/@dots{}-foo"
2174 store-monad@@(guile-user) [1]> ,q
2175 scheme@@(guile-user)>
2179 Note that non-monadic values cannot be returned in the
2180 @code{store-monad} REPL.
2182 The main syntactic forms to deal with monads in general are described
2185 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
2186 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
2190 @deffn {Scheme Syntax} return @var{val}
2191 Return a monadic value that encapsulates @var{val}.
2194 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
2195 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
2196 procedure @var{mproc}@footnote{This operation is commonly referred to as
2197 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
2198 we use this somewhat cryptic symbol inherited from the Haskell
2202 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
2204 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
2206 Bind the variables @var{var} to the monadic values @var{mval} in
2207 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
2208 ``normal'' value @var{val}, as per @code{let}.
2210 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
2211 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
2214 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
2215 Bind @var{mexp} and the following monadic expressions in sequence,
2216 returning the result of the last expression.
2218 This is akin to @code{mlet}, except that the return values of the
2219 monadic expressions are ignored. In that sense, it is analogous to
2220 @code{begin}, but applied to monadic expressions.
2223 The interface to the store monad provided by @code{(guix monads)} is as
2226 @defvr {Scheme Variable} %store-monad
2227 The store monad. Values in the store monad encapsulate accesses to the
2228 store. When its effect is needed, a value of the store monad must be
2229 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
2233 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
2234 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
2235 open store connection.
2238 @deffn {Monadic Procedure} text-file @var{name} @var{text}
2239 Return as a monadic value the absolute file name in the store of the file
2240 containing @var{text}, a string.
2243 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
2244 Return as a monadic value a derivation that builds a text file
2245 containing all of @var{text}. @var{text} may list, in addition to
2246 strings, packages, derivations, and store file names; the resulting
2247 store file holds references to all these.
2249 This variant should be preferred over @code{text-file} anytime the file
2250 to create will reference items from the store. This is typically the
2251 case when building a configuration file that embeds store file names,
2255 (define (profile.sh)
2256 ;; Return the name of a shell script in the store that
2257 ;; initializes the 'PATH' environment variable.
2258 (text-file* "profile.sh"
2259 "export PATH=" coreutils "/bin:"
2260 grep "/bin:" sed "/bin\n"))
2263 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
2264 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
2265 preventing them from being garbage-collected during its lifetime.
2268 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
2270 Return the name of @var{file} once interned in the store. Use
2271 @var{name} as its store name, or the basename of @var{file} if
2272 @var{name} is omitted.
2274 When @var{recursive?} is true, the contents of @var{file} are added
2275 recursively; if @var{file} designates a flat file and @var{recursive?}
2276 is true, its contents are added, and its permission bits are kept.
2278 The example below adds a file to the store, under two different names:
2281 (run-with-store (open-connection)
2282 (mlet %store-monad ((a (interned-file "README"))
2283 (b (interned-file "README" "LEGU-MIN")))
2284 (return (list a b))))
2286 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
2291 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
2292 [#:system (%current-system)] [#:target #f] @
2293 [#:output "out"] Return as a monadic
2294 value in the absolute file name of @var{file} within the @var{output}
2295 directory of @var{package}. When @var{file} is omitted, return the name
2296 of the @var{output} directory of @var{package}. When @var{target} is
2297 true, use it as a cross-compilation target triplet.
2300 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
2301 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
2302 @var{target} [@var{system}]
2303 Monadic version of @code{package-derivation} and
2304 @code{package-cross-derivation} (@pxref{Defining Packages}).
2309 @section G-Expressions
2311 @cindex G-expression
2312 @cindex build code quoting
2313 So we have ``derivations'', which represent a sequence of build actions
2314 to be performed to produce an item in the store (@pxref{Derivations}).
2315 Those build actions are performed when asking the daemon to actually
2316 build the derivations; they are run by the daemon in a container
2317 (@pxref{Invoking guix-daemon}).
2319 @cindex strata of code
2320 It should come as no surprise that we like to write those build actions
2321 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2322 code@footnote{The term @dfn{stratum} in this context was coined by
2323 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2324 Kiselyov, who has written insightful
2325 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2326 on this topic}, refers to this kind of code generation as
2327 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2328 to the daemon, etc.---and the ``build code''---code that actually
2329 performs build actions, such as making directories, invoking
2330 @command{make}, etc.
2332 To describe a derivation and its build actions, one typically needs to
2333 embed build code inside host code. It boils down to manipulating build
2334 code as data, and Scheme's homoiconicity---code has a direct
2335 representation as data---comes in handy for that. But we need more than
2336 Scheme's normal @code{quasiquote} mechanism to construct build
2339 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2340 S-expressions adapted to build expressions. G-expressions, or
2341 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2342 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2343 @code{#$}, and @code{#$@@}), which are comparable respectively to
2344 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2345 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2346 Reference Manual}). However, there are major differences:
2350 Gexps are meant to be written to a file and run or manipulated by other
2354 When a package or derivation is unquoted inside a gexp, the result is as
2355 if its output file name had been introduced.
2358 Gexps carry information about the packages or derivations they refer to,
2359 and these dependencies are automatically added as inputs to the build
2360 processes that use them.
2363 To illustrate the idea, here is an example of a gexp:
2370 (symlink (string-append #$coreutils "/bin/ls")
2374 This gexp can be passed to @code{gexp->derivation}; we obtain a
2375 derivation that builds a directory containing exactly one symlink to
2376 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2379 (gexp->derivation "the-thing" build-exp)
2382 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2383 substituted to the reference to the @var{coreutils} package in the
2384 actual build code, and @var{coreutils} is automatically made an input to
2385 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2386 output)}) is replaced by a string containing the derivation's output
2389 @cindex cross compilation
2390 In a cross-compilation context, it is useful to distinguish between
2391 references to the @emph{native} build of a package---that can run on the
2392 host---versus references to cross builds of a package. To that end, the
2393 @code{#+} plays the same role as @code{#$}, but is a reference to a
2394 native package build:
2397 (gexp->derivation "vi"
2400 (system* (string-append #+coreutils "/bin/ln")
2402 (string-append #$emacs "/bin/emacs")
2403 (string-append #$output "/bin/vi")))
2404 #:target "mips64el-linux")
2408 In the example above, the native build of @var{coreutils} is used, so
2409 that @command{ln} can actually run on the host; but then the
2410 cross-compiled build of @var{emacs} is referenced.
2412 The syntactic form to construct gexps is summarized below.
2414 @deffn {Scheme Syntax} #~@var{exp}
2415 @deffnx {Scheme Syntax} (gexp @var{exp})
2416 Return a G-expression containing @var{exp}. @var{exp} may contain one
2417 or more of the following forms:
2421 @itemx (ungexp @var{obj})
2422 Introduce a reference to @var{obj}. @var{obj} may be a package or a
2423 derivation, in which case the @code{ungexp} form is replaced by its
2424 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2426 If @var{obj} is a list, it is traversed and any package or derivation
2427 references are substituted similarly.
2429 If @var{obj} is another gexp, its contents are inserted and its
2430 dependencies are added to those of the containing gexp.
2432 If @var{obj} is another kind of object, it is inserted as is.
2434 @item #$@var{package-or-derivation}:@var{output}
2435 @itemx (ungexp @var{package-or-derivation} @var{output})
2436 This is like the form above, but referring explicitly to the
2437 @var{output} of @var{package-or-derivation}---this is useful when
2438 @var{package-or-derivation} produces multiple outputs (@pxref{Packages
2439 with Multiple Outputs}).
2442 @itemx #+@var{obj}:output
2443 @itemx (ungexp-native @var{obj})
2444 @itemx (ungexp-native @var{obj} @var{output})
2445 Same as @code{ungexp}, but produces a reference to the @emph{native}
2446 build of @var{obj} when used in a cross compilation context.
2448 @item #$output[:@var{output}]
2449 @itemx (ungexp output [@var{output}])
2450 Insert a reference to derivation output @var{output}, or to the main
2451 output when @var{output} is omitted.
2453 This only makes sense for gexps passed to @code{gexp->derivation}.
2456 @itemx (ungexp-splicing @var{lst})
2457 Like the above, but splices the contents of @var{lst} inside the
2461 @itemx (ungexp-native-splicing @var{lst})
2462 Like the above, but refers to native builds of the objects listed in
2467 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2468 of the @code{gexp?} type (see below.)
2471 @deffn {Scheme Procedure} gexp? @var{obj}
2472 Return @code{#t} if @var{obj} is a G-expression.
2475 G-expressions are meant to be written to disk, either as code building
2476 some derivation, or as plain files in the store. The monadic procedures
2477 below allow you to do that (@pxref{The Store Monad}, for more
2478 information about monads.)
2480 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2481 [#:system (%current-system)] [#:target #f] [#:inputs '()] @
2482 [#:hash #f] [#:hash-algo #f] @
2483 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2484 [#:module-path @var{%load-path}] @
2485 [#:references-graphs #f] [#:local-build? #f] @
2486 [#:guile-for-build #f]
2487 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2488 @var{guile-for-build} (a derivation) on @var{system}. When @var{target}
2489 is true, it is used as the cross-compilation target triplet for packages
2490 referred to by @var{exp}.
2492 Make @var{modules} available in the evaluation context of @var{EXP};
2493 @var{MODULES} is a list of names of Guile modules searched in
2494 @var{MODULE-PATH} to be copied in the store, compiled, and made available in
2495 the load path during the execution of @var{exp}---e.g., @code{((guix
2496 build utils) (guix build gnu-build-system))}.
2498 When @var{references-graphs} is true, it must be a list of tuples of one of the
2502 (@var{file-name} @var{package})
2503 (@var{file-name} @var{package} @var{output})
2504 (@var{file-name} @var{derivation})
2505 (@var{file-name} @var{derivation} @var{output})
2506 (@var{file-name} @var{store-item})
2509 The right-hand-side of each element of @var{references-graphs} is automatically made
2510 an input of the build process of @var{exp}. In the build environment, each
2511 @var{file-name} contains the reference graph of the corresponding item, in a simple
2514 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2517 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2518 Return an executable script @var{name} that runs @var{exp} using
2519 @var{guile} with @var{modules} in its search path.
2521 The example below builds a script that simply invokes the @command{ls}
2525 (use-modules (guix gexp) (gnu packages base))
2527 (gexp->script "list-files"
2528 #~(execl (string-append #$coreutils "/bin/ls")
2532 When ``running'' it through the store (@pxref{The Store Monad,
2533 @code{run-with-store}}), we obtain a derivation that produces an
2534 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2537 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2539 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2544 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2545 Return a derivation that builds a file @var{name} containing @var{exp}.
2547 The resulting file holds references to all the dependencies of @var{exp}
2548 or a subset thereof.
2551 Of course, in addition to gexps embedded in ``host'' code, there are
2552 also modules containing build tools. To make it clear that they are
2553 meant to be used in the build stratum, these modules are kept in the
2554 @code{(guix build @dots{})} name space.
2557 @c *********************************************************************
2561 This section describes tools primarily targeted at developers and users
2562 who write new package definitions. They complement the Scheme
2563 programming interface of Guix in a convenient way.
2566 * Invoking guix build:: Building packages from the command line.
2567 * Invoking guix download:: Downloading a file and printing its hash.
2568 * Invoking guix hash:: Computing the cryptographic hash of a file.
2569 * Invoking guix import:: Importing package definitions.
2570 * Invoking guix refresh:: Updating package definitions.
2571 * Invoking guix lint:: Finding errors in package definitions.
2572 * Invoking guix environment:: Setting up development environments.
2575 @node Invoking guix build
2576 @section Invoking @command{guix build}
2578 The @command{guix build} command builds packages or derivations and
2579 their dependencies, and prints the resulting store paths. Note that it
2580 does not modify the user's profile---this is the job of the
2581 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2582 it is mainly useful for distribution developers.
2584 The general syntax is:
2587 guix build @var{options} @var{package-or-derivation}@dots{}
2590 @var{package-or-derivation} may be either the name of a package found in
2591 the software distribution such as @code{coreutils} or
2592 @code{coreutils-8.20}, or a derivation such as
2593 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2594 package with the corresponding name (and optionally version) is searched
2595 for among the GNU distribution modules (@pxref{Package Modules}).
2597 Alternatively, the @code{--expression} option may be used to specify a
2598 Scheme expression that evaluates to a package; this is useful when
2599 disambiguation among several same-named packages or package variants is
2602 The @var{options} may be zero or more of the following:
2606 @item --expression=@var{expr}
2607 @itemx -e @var{expr}
2608 Build the package or derivation @var{expr} evaluates to.
2610 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2611 guile-1.8)}, which unambiguously designates this specific variant of
2612 version 1.8 of Guile.
2614 Alternately, @var{expr} may be a G-expression, in which case it is used
2615 as a build program passed to @code{gexp->derivation}
2616 (@pxref{G-Expressions}).
2618 Lastly, @var{expr} may refer to a zero-argument monadic procedure
2619 (@pxref{The Store Monad}). The procedure must return a derivation as a
2620 monadic value, which is then passed through @code{run-with-store}.
2624 Build the packages' source derivations, rather than the packages
2627 For instance, @code{guix build -S gcc} returns something like
2628 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2630 The returned source tarball is the result of applying any patches and
2631 code snippets specified in the package's @code{origin} (@pxref{Defining
2634 @item --system=@var{system}
2635 @itemx -s @var{system}
2636 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
2637 the host's system type.
2639 An example use of this is on Linux-based systems, which can emulate
2640 different personalities. For instance, passing
2641 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
2642 to build packages in a complete 32-bit environment.
2644 @item --target=@var{triplet}
2645 @cindex cross-compilation
2646 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
2647 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
2648 configuration triplets,, configure, GNU Configure and Build System}).
2650 @item --with-source=@var{source}
2651 Use @var{source} as the source of the corresponding package.
2652 @var{source} must be a file name or a URL, as for @command{guix
2653 download} (@pxref{Invoking guix download}).
2655 The ``corresponding package'' is taken to be one specified on the
2656 command line whose name matches the base of @var{source}---e.g., if
2657 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
2658 package is @code{guile}. Likewise, the version string is inferred from
2659 @var{source}; in the previous example, it's @code{2.0.10}.
2661 This option allows users to try out versions of packages other than the
2662 one provided by the distribution. The example below downloads
2663 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
2664 the @code{ed} package:
2667 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
2670 As a developer, @code{--with-source} makes it easy to test release
2674 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
2678 Do not ``graft'' packages. In practice, this means that package updates
2679 available as grafts are not applied. @xref{Security Updates}, for more
2680 information on grafts.
2684 Return the derivation paths, not the output paths, of the given
2687 @item --root=@var{file}
2688 @itemx -r @var{file}
2689 Make @var{file} a symlink to the result, and register it as a garbage
2693 Return the build log file names for the given
2694 @var{package-or-derivation}s, or raise an error if build logs are
2697 This works regardless of how packages or derivations are specified. For
2698 instance, the following invocations are equivalent:
2701 guix build --log-file `guix build -d guile`
2702 guix build --log-file `guix build guile`
2703 guix build --log-file guile
2704 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
2710 @cindex common build options
2711 In addition, a number of options that control the build process are
2712 common to @command{guix build} and other commands that can spawn builds,
2713 such as @command{guix package} or @command{guix archive}. These are the
2718 @item --load-path=@var{directory}
2719 @itemx -L @var{directory}
2720 Add @var{directory} to the front of the package module search path
2721 (@pxref{Package Modules}).
2723 This allows users to define their own packages and make them visible to
2724 the command-line tools.
2728 Keep the build tree of failed builds. Thus, if a build fail, its build
2729 tree is kept under @file{/tmp}, in a directory whose name is shown at
2730 the end of the build log. This is useful when debugging build issues.
2734 Do not build the derivations.
2737 When substituting a pre-built binary fails, fall back to building
2740 @item --no-substitutes
2741 Do not use substitutes for build products. That is, always build things
2742 locally instead of allowing downloads of pre-built binaries
2743 (@pxref{Substitutes}).
2745 @item --no-build-hook
2746 Do not attempt to offload builds @i{via} the daemon's ``build hook''
2747 (@pxref{Daemon Offload Setup}). That is, always build things locally
2748 instead of offloading builds to remote machines.
2750 @item --max-silent-time=@var{seconds}
2751 When the build or substitution process remains silent for more than
2752 @var{seconds}, terminate it and report a build failure.
2754 @item --timeout=@var{seconds}
2755 Likewise, when the build or substitution process lasts for more than
2756 @var{seconds}, terminate it and report a build failure.
2758 By default there is no timeout. This behavior can be restored with
2761 @item --verbosity=@var{level}
2762 Use the given verbosity level. @var{level} must be an integer between 0
2763 and 5; higher means more verbose output. Setting a level of 4 or more
2764 may be helpful when debugging setup issues with the build daemon.
2766 @item --cores=@var{n}
2768 Allow the use of up to @var{n} CPU cores for the build. The special
2769 value @code{0} means to use as many CPU cores as available.
2771 @item --max-jobs=@var{n}
2773 Allow at most @var{n} build jobs in parallel. @xref{Invoking
2774 guix-daemon, @code{--max-jobs}}, for details about this option and the
2775 equivalent @command{guix-daemon} option.
2779 Behind the scenes, @command{guix build} is essentially an interface to
2780 the @code{package-derivation} procedure of the @code{(guix packages)}
2781 module, and to the @code{build-derivations} procedure of the @code{(guix
2784 @node Invoking guix download
2785 @section Invoking @command{guix download}
2787 When writing a package definition, developers typically need to download
2788 the package's source tarball, compute its SHA256 hash, and write that
2789 hash in the package definition (@pxref{Defining Packages}). The
2790 @command{guix download} tool helps with this task: it downloads a file
2791 from the given URI, adds it to the store, and prints both its file name
2792 in the store and its SHA256 hash.
2794 The fact that the downloaded file is added to the store saves bandwidth:
2795 when the developer eventually tries to build the newly defined package
2796 with @command{guix build}, the source tarball will not have to be
2797 downloaded again because it is already in the store. It is also a
2798 convenient way to temporarily stash files, which may be deleted
2799 eventually (@pxref{Invoking guix gc}).
2801 The @command{guix download} command supports the same URIs as used in
2802 package definitions. In particular, it supports @code{mirror://} URIs.
2803 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
2804 Guile bindings for GnuTLS are available in the user's environment; when
2805 they are not available, an error is raised. @xref{Guile Preparations,
2806 how to install the GnuTLS bindings for Guile,, gnutls-guile,
2807 GnuTLS-Guile}, for more information.
2809 The following option is available:
2812 @item --format=@var{fmt}
2814 Write the hash in the format specified by @var{fmt}. For more
2815 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
2818 @node Invoking guix hash
2819 @section Invoking @command{guix hash}
2821 The @command{guix hash} command computes the SHA256 hash of a file.
2822 It is primarily a convenience tool for anyone contributing to the
2823 distribution: it computes the cryptographic hash of a file, which can be
2824 used in the definition of a package (@pxref{Defining Packages}).
2826 The general syntax is:
2829 guix hash @var{option} @var{file}
2832 @command{guix hash} has the following option:
2836 @item --format=@var{fmt}
2838 Write the hash in the format specified by @var{fmt}.
2840 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
2841 (@code{hex} and @code{hexadecimal} can be used as well).
2843 If the @option{--format} option is not specified, @command{guix hash}
2844 will output the hash in @code{nix-base32}. This representation is used
2845 in the definitions of packages.
2849 Compute the hash on @var{file} recursively.
2851 In this case, the hash is computed on an archive containing @var{file},
2852 including its children if it is a directory. Some of @var{file}'s
2853 meta-data is part of the archive; for instance, when @var{file} is a
2854 regular file, the hash is different depending on whether @var{file} is
2855 executable or not. Meta-data such as time stamps has no impact on the
2856 hash (@pxref{Invoking guix archive}).
2857 @c FIXME: Replace xref above with xref to an ``Archive'' section when
2862 @node Invoking guix import
2863 @section Invoking @command{guix import}
2865 @cindex importing packages
2866 @cindex package import
2867 @cindex package conversion
2868 The @command{guix import} command is useful for people willing to add a
2869 package to the distribution but who'd rather do as little work as
2870 possible to get there---a legitimate demand. The command knows of a few
2871 repositories from which it can ``import'' package meta-data. The result
2872 is a package definition, or a template thereof, in the format we know
2873 (@pxref{Defining Packages}).
2875 The general syntax is:
2878 guix import @var{importer} @var{options}@dots{}
2881 @var{importer} specifies the source from which to import package
2882 meta-data, and @var{options} specifies a package identifier and other
2883 options specific to @var{importer}. Currently, the available
2888 Import meta-data for the given GNU package. This provides a template
2889 for the latest version of that GNU package, including the hash of its
2890 source tarball, and its canonical synopsis and description.
2892 Additional information such as the package's dependencies and its
2893 license needs to be figured out manually.
2895 For example, the following command returns a package definition for
2899 guix import gnu hello
2902 Specific command-line options are:
2905 @item --key-download=@var{policy}
2906 As for @code{guix refresh}, specify the policy to handle missing OpenPGP
2907 keys when verifying the package's signature. @xref{Invoking guix
2908 refresh, @code{--key-download}}.
2913 Import meta-data from the @uref{https://pypi.python.org/, Python Package
2914 Index}@footnote{This functionality requires Guile-JSON to be installed.
2915 @xref{Requirements}.}. Information is taken from the JSON-formatted
2916 description available at @code{pypi.python.org} and usually includes all
2917 the relevant information, including package dependencies.
2919 The command below imports meta-data for the @code{itsdangerous} Python
2923 guix import pypi itsdangerous
2927 Import meta-data from a local copy of the source of the
2928 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
2929 relies on the @command{nix-instantiate} command of
2930 @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
2931 typically written in a mixture of Nix-language and Bash code. This
2932 command only imports the high-level package structure that is written in
2933 the Nix language. It normally includes all the basic fields of a
2936 When importing a GNU package, the synopsis and descriptions are replaced
2937 by their canonical upstream variant.
2939 As an example, the command below imports the package definition of
2940 LibreOffice (more precisely, it imports the definition of the package
2941 bound to the @code{libreoffice} top-level attribute):
2944 guix import nix ~/path/to/nixpkgs libreoffice
2948 The structure of the @command{guix import} code is modular. It would be
2949 useful to have more importers for other package formats, and your help
2950 is welcome here (@pxref{Contributing}).
2952 @node Invoking guix refresh
2953 @section Invoking @command{guix refresh}
2955 The primary audience of the @command{guix refresh} command is developers
2956 of the GNU software distribution. By default, it reports any packages
2957 provided by the distribution that are outdated compared to the latest
2958 upstream version, like this:
2962 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
2963 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
2966 It does so by browsing each package's FTP directory and determining the
2967 highest version number of the source tarballs
2968 therein@footnote{Currently, this only works for GNU packages.}.
2970 When passed @code{--update}, it modifies distribution source files to
2971 update the version numbers and source tarball hashes of those packages'
2972 recipes (@pxref{Defining Packages}). This is achieved by downloading
2973 each package's latest source tarball and its associated OpenPGP
2974 signature, authenticating the downloaded tarball against its signature
2975 using @command{gpg}, and finally computing its hash. When the public
2976 key used to sign the tarball is missing from the user's keyring, an
2977 attempt is made to automatically retrieve it from a public key server;
2978 when it's successful, the key is added to the user's keyring; otherwise,
2979 @command{guix refresh} reports an error.
2981 The following options are supported:
2987 Update distribution source files (package recipes) in place.
2988 @xref{Defining Packages}, for more information on package definitions.
2990 @item --select=[@var{subset}]
2991 @itemx -s @var{subset}
2992 Select all the packages in @var{subset}, one of @code{core} or
2995 The @code{core} subset refers to all the packages at the core of the
2996 distribution---i.e., packages that are used to build ``everything
2997 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
2998 changing one of these packages in the distribution entails a rebuild of
2999 all the others. Thus, such updates are an inconvenience to users in
3000 terms of build time or bandwidth used to achieve the upgrade.
3002 The @code{non-core} subset refers to the remaining packages. It is
3003 typically useful in cases where an update of the core packages would be
3008 In addition, @command{guix refresh} can be passed one or more package
3009 names, as in this example:
3012 guix refresh -u emacs idutils
3016 The command above specifically updates the @code{emacs} and
3017 @code{idutils} packages. The @code{--select} option would have no
3018 effect in this case.
3020 When considering whether to upgrade a package, it is sometimes
3021 convenient to know which packages would be affected by the upgrade and
3022 should be checked for compatibility. For this the following option may
3023 be used when passing @command{guix refresh} one or more package names:
3027 @item --list-dependent
3029 List top-level dependent packages that would need to be rebuilt as a
3030 result of upgrading one or more packages.
3034 Be aware that the @code{--list-dependent} option only
3035 @emph{approximates} the rebuilds that would be required as a result of
3036 an upgrade. More rebuilds might be required under some circumstances.
3039 $ guix refresh --list-dependent flex
3040 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
3041 hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
3044 The command above lists a set of packages that could be built to check
3045 for compatibility with an upgraded @code{flex} package.
3047 The following options can be used to customize GnuPG operation:
3051 @item --gpg=@var{command}
3052 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
3053 for in @code{$PATH}.
3055 @item --key-download=@var{policy}
3056 Handle missing OpenPGP keys according to @var{policy}, which may be one
3061 Always download missing OpenPGP keys from the key server, and add them
3062 to the user's GnuPG keyring.
3065 Never try to download missing OpenPGP keys. Instead just bail out.
3068 When a package signed with an unknown OpenPGP key is encountered, ask
3069 the user whether to download it or not. This is the default behavior.
3072 @item --key-server=@var{host}
3073 Use @var{host} as the OpenPGP key server when importing a public key.
3077 @node Invoking guix lint
3078 @section Invoking @command{guix lint}
3079 The @command{guix lint} is meant to help package developers avoid common
3080 errors and use a consistent style. It runs a few checks on a given set of
3081 packages in order to find common mistakes in their definitions.
3083 The general syntax is:
3086 guix lint @var{options} @var{package}@dots{}
3089 If no package is given on the command line, then all packages are checked.
3090 The @var{options} may be zero or more of the following:
3096 Only enable the checkers specified in a comma-separated list using the
3097 names returned by @code{--list-checkers}.
3099 @item --list-checkers
3101 List and describe all the available checkers that will be run on packages
3106 @node Invoking guix environment
3107 @section Invoking @command{guix environment}
3109 @cindex reproducible build environments
3110 The purpose of @command{guix environment} is to assist hackers in
3111 creating reproducible development environments without polluting their
3112 package profile. The @command{guix environment} tool takes one or more
3113 packages, builds all of the necessary inputs, and creates a shell
3114 environment to use them.
3116 The general syntax is:
3119 guix environment @var{options} @var{package}@dots{}
3122 The following examples spawns a new shell that is capable of building
3123 the GNU Guile source code:
3126 guix environment guile
3129 If the specified packages are not built yet, @command{guix environment}
3130 automatically builds them. The new shell's environment is an augmented
3131 version of the environment that @command{guix environment} was run in.
3132 It contains the necessary search paths for building the given package
3133 added to the existing environment variables. To create a ``pure''
3134 environment in which the original environment variables have been unset,
3135 use the @code{--pure} option.
3137 Additionally, more than one package may be specified, in which case the
3138 union of the inputs for the given packages are used. For example, the
3139 command below spawns a shell where all of the dependencies of both Guile
3140 and Emacs are available:
3143 guix environment guile emacs
3146 Sometimes an interactive shell session is not desired. The
3147 @code{--exec} option can be used to specify the command to run instead.
3150 guix environment guile --exec=make
3153 The following options are available:
3156 @item --expression=@var{expr}
3157 @itemx -e @var{expr}
3158 Create an environment for the package that @var{expr} evaluates to.
3160 @item --load=@var{file}
3161 @itemx -l @var{file}
3162 Create an environment for the package that the code within @var{file}
3165 @item --exec=@var{command}
3166 @item -E @var{command}
3167 Execute @var{command} in the new environment.
3170 Unset existing environment variables when building the new environment.
3171 This has the effect of creating an environment in which search paths
3172 only contain package inputs.
3174 @item --search-paths
3175 Display the environment variable definitions that make up the
3179 It also supports all of the common build options that @command{guix
3180 build} supports (@pxref{Invoking guix build, common build options}).
3182 @c *********************************************************************
3183 @node GNU Distribution
3184 @chapter GNU Distribution
3186 Guix comes with a distribution of free software@footnote{The term
3187 ``free'' here refers to the
3188 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
3189 users of that software}.} that forms the basis of the GNU system. This
3190 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
3191 as many GNU and non-GNU applications. The complete list of available
3192 packages can be browsed
3193 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
3194 running @command{guix package} (@pxref{Invoking guix package}):
3197 guix package --list-available
3200 Our goal is to build a practical 100% free software distribution of
3201 Linux-based and other variants of GNU, with a focus on the promotion and
3202 tight integration of GNU components, and an emphasis on programs and
3203 tools that help users exert that freedom.
3205 The GNU distribution is currently available on the following platforms:
3210 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
3213 Intel 32-bit architecture (IA32), Linux-Libre kernel;
3215 @item mips64el-linux
3216 little-endian 64-bit MIPS processors, specifically the Loongson series,
3217 n32 application binary interface (ABI), and Linux-Libre kernel.
3222 For information on porting to other architectures or kernels,
3226 * System Installation:: Installing the whole operating system.
3227 * System Configuration:: Configuring a GNU system.
3228 * Installing Debugging Files:: Feeding the debugger.
3229 * Security Updates:: Deploying security fixes quickly.
3230 * Package Modules:: Packages from the programmer's viewpoint.
3231 * Packaging Guidelines:: Growing the distribution.
3232 * Bootstrapping:: GNU/Linux built from scratch.
3233 * Porting:: Targeting another platform or kernel.
3236 Building this distribution is a cooperative effort, and you are invited
3237 to join! @xref{Contributing}, for information about how you can help.
3239 @node System Installation
3240 @section System Installation
3242 This section explains how to install the complete GNU operating system
3243 on a machine. The Guix package manager can also be installed on top of
3244 a running GNU/Linux system, @pxref{Installation}.
3247 @c This paragraph is for people reading this from tty2 of the
3248 @c installation image.
3249 You're reading this documentation with an Info reader. For details on
3250 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
3251 link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
3252 @kbd{l} afterwards to come back here.
3255 @subsection Limitations
3257 As of version @value{VERSION}, GNU@tie{}Guix and the GNU system
3258 distribution are alpha software. It may contain bugs and lack important
3259 features. Thus, if you are looking for a stable production system that
3260 respects your freedom as a computer user, a good solution at this point
3261 is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
3262 more established GNU/Linux distributions}. We hope you can soon switch
3263 to the GNU system without fear, of course. In the meantime, you can
3264 also keep using your distribution and try out the package manager on top
3265 of it (@pxref{Installation}).
3267 Before you proceed with the installation, be aware of the following
3268 noteworthy limitations applicable to version @value{VERSION}:
3272 The installation process does not include a graphical user interface and
3273 requires familiarity with GNU/Linux (see the following subsections to
3274 get a feel of what that means.)
3277 The system does not yet provide graphical desktop environments such as
3281 Support for the Logical Volume Manager (LVM) is missing.
3284 Few system services are currently supported out-of-the-box
3288 On the order of 1,000 packages are available, which means that you may
3289 occasionally find that a useful package is missing.
3292 You've been warned. But more than a disclaimer, this is an invitation
3293 to report issues (and success stories!), and join us in improving it.
3294 @xref{Contributing}, for more info.
3296 @subsection USB Stick Installation
3298 An installation image for USB sticks can be downloaded from
3299 @url{ftp://alpha.gnu.org/gnu/guix/gnu-usb-install-@value{VERSION}.@var{system}.xz},
3300 where @var{system} is one of:
3304 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
3307 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
3310 This image contains a single partition with the tools necessary for an
3311 installation. It is meant to be copied @emph{as is} to a large-enough
3314 To copy the image to a USB stick, follow these steps:
3318 Decompress the image using the @command{xz} command:
3321 xz -d gnu-usb-install-@value{VERSION}.@var{system}.xz
3325 Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
3326 its device name. Assuming that USB stick is known as @file{/dev/sdX},
3327 copy the image with:
3330 dd if=gnu-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
3333 Access to @file{/dev/sdX} usually requires root privileges.
3336 Once this is done, you should be able to reboot the system and boot from
3337 the USB stick. The latter usually requires you to get in the BIOS' boot
3338 menu, where you can choose to boot from the USB stick.
3340 @subsection Preparing for Installation
3342 Once you have successfully booted the image on the USB stick, you should
3343 end up with a root prompt. Several console TTYs are configured and can
3344 be used to run commands as root. TTY2 shows this documentation,
3345 browsable using the Info reader commands (@pxref{Help,,, info, Info: An
3348 To install the system, you would:
3353 Configure the network, by running @command{dhclient eth0} (to get an
3354 automatically assigned IP address from the wired network interface
3355 controller), or using the @command{ifconfig} command.
3357 The system automatically loads drivers for your network interface
3360 Setting up network access is almost always a requirement because the
3361 image does not contain all the software and tools that may be needed.
3364 Unless this has already been done, you must partition and format the
3367 Preferably, assign partitions a label so that you can easily and
3368 reliably refer to them in @code{file-system} declarations (@pxref{File
3369 Systems}). This is typically done using the @code{-L} option of
3370 @command{mkfs.ext4} and related commands.
3372 The installation image includes Parted (@pxref{Overview,,, parted, GNU
3373 Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
3374 encryption, and e2fsprogs, the suite of tools to manipulate
3375 ext2/ext3/ext4 file systems.
3378 Once that is done, mount the target root partition under @file{/mnt}.
3381 Lastly, run @code{deco start cow-store /mnt}.
3383 This will make @file{/gnu/store} copy-on-write, such that packages added
3384 to it during the installation phase will be written to the target disk
3385 rather than kept in memory.
3390 @subsection Proceeding with the Installation
3392 With the target partitions ready, you now have to edit a file and
3393 provide the declaration of the operating system to be installed. To
3394 that end, the installation system comes with two text editors: GNU nano
3395 (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
3396 It is better to store that file on the target root file system, say, as
3397 @file{/mnt/etc/config.scm}.
3399 A minimal operating system configuration, with just the bare minimum and
3400 only a root account would look like this (on the installation system,
3401 this example is available as @file{/etc/configuration-template.scm}):
3404 @include os-config.texi
3408 For more information on @code{operating-system} declarations,
3409 @pxref{Using the Configuration System}.
3411 Once that is done, the new system must be initialized (remember that the
3412 target root file system is mounted under @file{/mnt}):
3415 guix system init /mnt/etc/config.scm /mnt
3419 This will copy all the necessary files, and install GRUB on
3420 @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
3421 more information, @pxref{Invoking guix system}. This command may trigger
3422 downloads or builds of missing packages, which can take some time.
3424 Once that command has completed---and hopefully succeeded!---you can
3425 run @command{reboot} and boot into the new system. Cross fingers, and
3426 join us on @code{#guix} on the Freenode IRC network or on
3427 @file{guix-devel@@gnu.org} to share your experience---good or not so
3430 @subsection Building the Installation Image
3432 The installation image described above was built using the @command{guix
3433 system} command, specifically:
3436 guix system disk-image --image-size=800MiB gnu/system/install.scm
3439 @xref{Invoking guix system}, for more information. See
3440 @file{gnu/system/install.scm} in the source tree for more information
3441 about the installation image.
3443 @node System Configuration
3444 @section System Configuration
3446 @cindex system configuration
3447 The GNU system supports a consistent whole-system configuration
3448 mechanism. By that we mean that all aspects of the global system
3449 configuration---such as the available system services, timezone and
3450 locale settings, user accounts---are declared in a single place. Such
3451 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
3453 One of the advantages of putting all the system configuration under the
3454 control of Guix is that it supports transactional system upgrades, and
3455 makes it possible to roll-back to a previous system instantiation,
3456 should something go wrong with the new one (@pxref{Features}). Another
3457 one is that it makes it easy to replicate the exact same configuration
3458 across different machines, or at different points in time, without
3459 having to resort to additional administration tools layered on top of
3460 the system's own tools.
3461 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
3463 This section describes this mechanism. First we focus on the system
3464 administrator's viewpoint---explaining how the system is configured and
3465 instantiated. Then we show how this mechanism can be extended, for
3466 instance to support new system services.
3469 * Using the Configuration System:: Customizing your GNU system.
3470 * operating-system Reference:: Detail of operating-system declarations.
3471 * File Systems:: Configuring file system mounts.
3472 * Mapped Devices:: Block device extra processing.
3473 * User Accounts:: Specifying user accounts.
3474 * Locales:: Language and cultural convention settings.
3475 * Services:: Specifying system services.
3476 * Setuid Programs:: Programs running with root privileges.
3477 * Initial RAM Disk:: Linux-Libre bootstrapping.
3478 * GRUB Configuration:: Configuring the boot loader.
3479 * Invoking guix system:: Instantiating a system configuration.
3480 * Defining Services:: Adding new service definitions.
3483 @node Using the Configuration System
3484 @subsection Using the Configuration System
3486 The operating system is configured by providing an
3487 @code{operating-system} declaration in a file that can then be passed to
3488 the @command{guix system} command (@pxref{Invoking guix system}). A
3489 simple setup, with the default system services, the default Linux-Libre
3490 kernel, initial RAM disk, and boot loader looks like this:
3492 @findex operating-system
3494 (use-modules (gnu) ; for 'user-account', '%base-services', etc.
3495 (gnu packages emacs) ; for 'emacs'
3496 (gnu services ssh)) ; for 'lsh-service'
3499 (host-name "komputilo")
3500 (timezone "Europe/Paris")
3501 (locale "fr_FR.utf8")
3502 (bootloader (grub-configuration
3503 (device "/dev/sda")))
3504 (file-systems (cons (file-system
3505 (device "/dev/sda1") ; or partition label
3508 %base-file-systems))
3509 (users (list (user-account
3511 (uid 1000) (group 100)
3512 (comment "Bob's sister")
3513 (home-directory "/home/alice"))))
3514 (packages (cons emacs %base-packages))
3515 (services (cons (lsh-service #:port 2222 #:root-login? #t)
3519 This example should be self-describing. Some of the fields defined
3520 above, such as @code{host-name} and @code{bootloader}, are mandatory.
3521 Others, such as @code{packages} and @code{services}, can be omitted, in
3522 which case they get a default value.
3524 @vindex %base-packages
3525 The @code{packages} field lists
3526 packages that will be globally visible on the system, for all user
3527 accounts---i.e., in every user's @code{PATH} environment variable---in
3528 addition to the per-user profiles (@pxref{Invoking guix package}). The
3529 @var{%base-packages} variable provides all the tools one would expect
3530 for basic user and administrator tasks---including the GNU Core
3531 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
3532 editor, @command{find}, @command{grep}, etc. The example above adds
3533 Emacs to those, taken from the @code{(gnu packages emacs)} module
3534 (@pxref{Package Modules}).
3536 @vindex %base-services
3537 The @code{services} field lists @dfn{system services} to be made
3538 available when the system starts (@pxref{Services}).
3539 The @code{operating-system} declaration above specifies that, in
3540 addition to the basic services, we want the @command{lshd} secure shell
3541 daemon listening on port 2222, and allowing remote @code{root} logins
3542 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
3543 @code{lsh-service} arranges so that @code{lshd} is started with the
3544 right command-line options, possibly with supporting configuration files
3545 generated as needed (@pxref{Defining Services}). @xref{operating-system
3546 Reference}, for details about the available @code{operating-system}
3549 Assuming the above snippet is stored in the @file{my-system-config.scm}
3550 file, the @command{guix system reconfigure my-system-config.scm} command
3551 instantiates that configuration, and makes it the default GRUB boot
3552 entry (@pxref{Invoking guix system}). The normal way to change the
3553 system's configuration is by updating this file and re-running the
3554 @command{guix system} command.
3556 At the Scheme level, the bulk of an @code{operating-system} declaration
3557 is instantiated with the following monadic procedure (@pxref{The Store
3560 @deffn {Monadic Procedure} operating-system-derivation os
3561 Return a derivation that builds @var{os}, an @code{operating-system}
3562 object (@pxref{Derivations}).
3564 The output of the derivation is a single directory that refers to all
3565 the packages, configuration files, and other supporting files needed to
3566 instantiate @var{os}.
3569 @node operating-system Reference
3570 @subsection @code{operating-system} Reference
3572 This section summarizes all the options available in
3573 @code{operating-system} declarations (@pxref{Using the Configuration
3576 @deftp {Data Type} operating-system
3577 This is the data type representing an operating system configuration.
3578 By that, we mean all the global system configuration, not per-user
3579 configuration (@pxref{Using the Configuration System}).
3582 @item @code{kernel} (default: @var{linux-libre})
3583 The package object of the operating system to use@footnote{Currently
3584 only the Linux-libre kernel is supported. In the future, it will be
3585 possible to use the GNU@tie{}Hurd.}.
3587 @item @code{bootloader}
3588 The system bootloader configuration object. @xref{GRUB Configuration}.
3590 @item @code{initrd} (default: @code{base-initrd})
3591 A two-argument monadic procedure that returns an initial RAM disk for
3592 the Linux kernel. @xref{Initial RAM Disk}.
3594 @item @code{firmware} (default: @var{%base-firmware})
3596 List of firmware packages loadable by the operating system kernel.
3598 The default includes firmware needed for Atheros-based WiFi devices
3599 (Linux-libre module @code{ath9k}.)
3601 @item @code{host-name}
3604 @item @code{hosts-file}
3606 A zero-argument monadic procedure that returns a text file for use as
3607 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
3608 Reference Manual}). The default is to produce a file with entries for
3609 @code{localhost} and @var{host-name}.
3611 @item @code{mapped-devices} (default: @code{'()})
3612 A list of mapped devices. @xref{Mapped Devices}.
3614 @item @code{file-systems}
3615 A list of file systems. @xref{File Systems}.
3617 @item @code{swap-devices} (default: @code{'()})
3618 @cindex swap devices
3619 A list of strings identifying devices to be used for ``swap space''
3620 (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
3621 For example, @code{'("/dev/sda3")}.
3623 @item @code{users} (default: @code{'()})
3624 @itemx @code{groups} (default: @var{%base-groups})
3625 List of user accounts and groups. @xref{User Accounts}.
3627 @item @code{skeletons} (default: @code{(default-skeletons)})
3628 A monadic list of pairs of target file name and files. These are the
3629 files that will be used as skeletons as new accounts are created.
3631 For instance, a valid value may look like this:
3634 (mlet %store-monad ((bashrc (text-file "bashrc" "\
3635 export PATH=$HOME/.guix-profile/bin")))
3636 (return `((".bashrc" ,bashrc))))
3639 @item @code{issue} (default: @var{%default-issue})
3640 A string denoting the contents of the @file{/etc/issue} file, which is
3641 what displayed when users log in on a text console.
3643 @item @code{packages} (default: @var{%base-packages})
3644 The set of packages installed in the global profile, which is accessible
3645 at @file{/run/current-system/profile}.
3647 The default set includes core utilities, but it is good practice to
3648 install non-core utilities in user profiles (@pxref{Invoking guix
3651 @item @code{timezone}
3652 A timezone identifying string---e.g., @code{"Europe/Paris"}.
3654 @item @code{locale} (default: @code{"en_US.utf8"})
3655 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
3656 Library Reference Manual}). @xref{Locales}, for more information.
3658 @item @code{locale-definitions} (default: @var{%default-locale-definitions})
3659 The list of locale definitions to be compiled and that may be used at
3660 run time. @xref{Locales}.
3662 @item @code{services} (default: @var{%base-services})
3663 A list of monadic values denoting system services. @xref{Services}.
3665 @item @code{pam-services} (default: @code{(base-pam-services)})
3667 @cindex pluggable authentication modules
3668 Linux @dfn{pluggable authentication module} (PAM) services.
3669 @c FIXME: Add xref to PAM services section.
3671 @item @code{setuid-programs} (default: @var{%setuid-programs})
3672 List of string-valued G-expressions denoting setuid programs.
3673 @xref{Setuid Programs}.
3675 @item @code{sudoers} (default: @var{%sudoers-specification})
3677 The contents of the @file{/etc/sudoers} file as a string.
3679 This file specifies which users can use the @command{sudo} command, what
3680 they are allowed to do, and what privileges they may gain. The default
3681 is that only @code{root} and members of the @code{wheel} group may use
3688 @subsection File Systems
3690 The list of file systems to be mounted is specified in the
3691 @code{file-systems} field of the operating system's declaration
3692 (@pxref{Using the Configuration System}). Each file system is declared
3693 using the @code{file-system} form, like this:
3697 (mount-point "/home")
3698 (device "/dev/sda3")
3702 As usual, some of the fields are mandatory---those shown in the example
3703 above---while others can be omitted. These are described below.
3705 @deftp {Data Type} file-system
3706 Objects of this type represent file systems to be mounted. They
3707 contain the following members:
3711 This is a string specifying the type of the file system---e.g.,
3714 @item @code{mount-point}
3715 This designates the place where the file system is to be mounted.
3718 This names the ``source'' of the file system. By default it is the name
3719 of a node under @file{/dev}, but its meaning depends on the @code{title}
3720 field described below.
3722 @item @code{title} (default: @code{'device})
3723 This is a symbol that specifies how the @code{device} field is to be
3726 When it is the symbol @code{device}, then the @code{device} field is
3727 interpreted as a file name; when it is @code{label}, then @code{device}
3728 is interpreted as a partition label name; when it is @code{uuid},
3729 @code{device} is interpreted as a partition unique identifier (UUID).
3731 The @code{label} and @code{uuid} options offer a way to refer to disk
3732 partitions without having to hard-code their actual device name.
3734 @item @code{flags} (default: @code{'()})
3735 This is a list of symbols denoting mount flags. Recognized flags
3736 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
3737 access to special files), @code{no-suid} (ignore setuid and setgid
3738 bits), and @code{no-exec} (disallow program execution.)
3740 @item @code{options} (default: @code{#f})
3741 This is either @code{#f}, or a string denoting mount options.
3743 @item @code{needed-for-boot?} (default: @code{#f})
3744 This Boolean value indicates whether the file system is needed when
3745 booting. If that is true, then the file system is mounted when the
3746 initial RAM disk (initrd) is loaded. This is always the case, for
3747 instance, for the root file system.
3749 @item @code{check?} (default: @code{#t})
3750 This Boolean indicates whether the file system needs to be checked for
3751 errors before being mounted.
3753 @item @code{create-mount-point?} (default: @code{#f})
3754 When true, the mount point is created if it does not exist yet.
3759 The @code{(gnu system file-systems)} exports the following useful
3762 @defvr {Scheme Variable} %base-file-systems
3763 These are essential file systems that are required on normal systems,
3764 such as @var{%devtmpfs-file-system} (see below.) Operating system
3765 declarations should always contain at least these.
3768 @defvr {Scheme Variable} %devtmpfs-file-system
3769 The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
3770 requirement for udev (@pxref{Base Services, @code{udev-service}}).
3773 @defvr {Scheme Variable} %pseudo-terminal-file-system
3774 This is the file system to be mounted as @file{/dev/pts}. It supports
3775 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
3776 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
3777 Manual}). Pseudo-terminals are used by terminal emulators such as
3781 @defvr {Scheme Variable} %shared-memory-file-system
3782 This file system is mounted as @file{/dev/shm} and is used to support
3783 memory sharing across processes (@pxref{Memory-mapped I/O,
3784 @code{shm_open},, libc, The GNU C Library Reference Manual}).
3787 @defvr {Scheme Variable} %binary-format-file-system
3788 The @code{binfmt_misc} file system, which allows handling of arbitrary
3789 executable file types to be delegated to user space. This requires the
3790 @code{binfmt.ko} kernel module to be loaded.
3793 @defvr {Scheme Variable} %fuse-control-file-system
3794 The @code{fusectl} file system, which allows unprivileged users to mount
3795 and unmount user-space FUSE file systems. This requires the
3796 @code{fuse.ko} kernel module to be loaded.
3799 @node Mapped Devices
3800 @subsection Mapped Devices
3802 @cindex device mapping
3803 @cindex mapped devices
3804 The Linux kernel has a notion of @dfn{device mapping}: a block device,
3805 such as a hard disk partition, can be @dfn{mapped} into another device,
3806 with additional processing over the data that flows through
3807 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
3808 concept of a ``mapped device'' and that of a file system: both boil down
3809 to @emph{translating} input/output operations made on a file to
3810 operations on its backing store. Thus, the Hurd implements mapped
3811 devices, like file systems, using the generic @dfn{translator} mechanism
3812 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
3813 typical example is encryption device mapping: all writes to the mapped
3814 device are encrypted, and all reads are deciphered, transparently.
3816 Mapped devices are declared using the @code{mapped-device} form:
3820 (source "/dev/sda3")
3822 (type luks-device-mapping))
3826 @cindex disk encryption
3828 This example specifies a mapping from @file{/dev/sda3} to
3829 @file{/dev/mapper/home} using LUKS---the
3830 @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
3831 standard mechanism for disk encryption. The @file{/dev/mapper/home}
3832 device can then be used as the @code{device} of a @code{file-system}
3833 declaration (@pxref{File Systems}). The @code{mapped-device} form is
3836 @deftp {Data Type} mapped-device
3837 Objects of this type represent device mappings that will be made when
3838 the system boots up.
3842 This string specifies the name of the block device to be mapped, such as
3846 This string specifies the name of the mapping to be established. For
3847 example, specifying @code{"my-partition"} will lead to the creation of
3848 the @code{"/dev/mapper/my-partition"} device.
3851 This must be a @code{mapped-device-kind} object, which specifies how
3852 @var{source} is mapped to @var{target}.
3856 @defvr {Scheme Variable} luks-device-mapping
3857 This defines LUKS block device encryption using the @command{cryptsetup}
3858 command, from the same-named package. This relies on the
3859 @code{dm-crypt} Linux kernel module.
3863 @subsection User Accounts
3865 User accounts are specified with the @code{user-account} form:
3871 (supplementary-groups '("wheel" ;allow use of sudo, etc.
3873 "video" ;video devices such as webcams
3874 "cdrom")) ;the good ol' CD-ROM
3875 (comment "Bob's sister")
3876 (home-directory "/home/alice"))
3879 @deftp {Data Type} user-account
3880 Objects of this type represent user accounts. The following members may
3885 The name of the user account.
3888 This is the name (a string) or identifier (a number) of the user group
3889 this account belongs to.
3891 @item @code{supplementary-groups} (default: @code{'()})
3892 Optionally, this can be defined as a list of group names that this
3895 @item @code{uid} (default: @code{#f})
3896 This is the user ID for this account (a number), or @code{#f}. In the
3897 latter case, a number is automatically chosen by the system when the
3900 @item @code{comment} (default: @code{""})
3901 A comment about the account, such as the account's owner full name.
3903 @item @code{home-directory}
3904 This is the name of the home directory for the account.
3906 @item @code{shell} (default: Bash)
3907 This is a G-expression denoting the file name of a program to be used as
3908 the shell (@pxref{G-Expressions}).
3910 @item @code{system?} (default: @code{#f})
3911 This Boolean value indicates whether the account is a ``system''
3912 account. System accounts are sometimes treated specially; for instance,
3913 graphical login managers do not list them.
3915 @item @code{password} (default: @code{#f})
3916 You would normally leave this field to @code{#f}, initialize user
3917 passwords as @code{root} with the @command{passwd} command, and then let
3918 users change it with @command{passwd}.
3920 If you @emph{do} want to have a preset password for an account, then
3921 this field must contain the encrypted password, as a string.
3922 @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
3923 on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
3924 Manual}, for information on Guile's @code{crypt} procedure.
3929 User group declarations are even simpler:
3932 (user-group (name "students"))
3935 @deftp {Data Type} user-group
3936 This type is for, well, user groups. There are just a few fields:
3942 @item @code{id} (default: @code{#f})
3943 The group identifier (a number). If @code{#f}, a new number is
3944 automatically allocated when the group is created.
3946 @item @code{system?} (default: @code{#f})
3947 This Boolean value indicates whether the group is a ``system'' group.
3948 System groups have low numerical IDs.
3950 @item @code{password} (default: @code{#f})
3951 What, user groups can have a password? Well, apparently yes. Unless
3952 @code{#f}, this field specifies the group's password.
3957 For convenience, a variable lists all the basic user groups one may
3960 @defvr {Scheme Variable} %base-groups
3961 This is the list of basic user groups that users and/or packages expect
3962 to be present on the system. This includes groups such as ``root'',
3963 ``wheel'', and ``users'', as well as groups used to control access to
3964 specific devices such as ``audio'', ``disk'', and ``cdrom''.
3971 A @dfn{locale} defines cultural conventions for a particular language
3972 and region of the world (@pxref{Locales,,, libc, The GNU C Library
3973 Reference Manual}). Each locale has a name that typically has the form
3974 @code{@var{language}_@var{territory}.@var{charset}}---e.g.,
3975 @code{fr_LU.utf8} designates the locale for the French language, with
3976 cultural conventions from Luxembourg, and using the UTF-8 encoding.
3978 @cindex locale definition
3979 Usually, you will want to specify the default locale for the machine
3980 using the @code{locale} field of the @code{operating-system} declaration
3981 (@pxref{operating-system Reference, @code{locale}}).
3983 That locale must be among the @dfn{locale definitions} that are known to
3984 the system---and these are specified in the @code{locale-definitions}
3985 slot of @code{operating-system}. The default value includes locale
3986 definition for some widely used locales, but not for all the available
3987 locales, in order to save space.
3989 If the locale specified in the @code{locale} field is not among the
3990 definitions listed in @code{locale-definitions}, @command{guix system}
3991 raises an error. In that case, you should add the locale definition to
3992 the @code{locale-definitions} field. For instance, to add the North
3993 Frisian locale for Germany, the value of that field may be:
3996 (cons (locale-definition
3997 (name "fy_DE.utf8") (source "fy_DE"))
3998 %default-locale-definitions)
4001 Likewise, to save space, one might want @code{locale-definitions} to
4002 list only the locales that are actually used, as in:
4005 (list (locale-definition
4006 (name "ja_JP.eucjp") (source "ja_JP")
4007 (charset "EUC-JP")))
4010 The @code{locale-definition} form is provided by the @code{(gnu system
4011 locale)} module. Details are given below.
4013 @deftp {Data Type} locale-definition
4014 This is the data type of a locale definition.
4019 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
4020 Reference Manual}, for more information on locale names.
4023 The name of the source for that locale. This is typically the
4024 @code{@var{language}_@var{territory}} part of the locale name.
4026 @item @code{charset} (default: @code{"UTF-8"})
4027 The ``character set'' or ``code set'' for that locale,
4028 @uref{http://www.iana.org/assignments/character-sets, as defined by
4034 @defvr {Scheme Variable} %default-locale-definitions
4035 An arbitrary list of commonly used locales, used as the default value of
4036 the @code{locale-definitions} field of @code{operating-system}
4041 @subsection Services
4043 @cindex system services
4044 An important part of preparing an @code{operating-system} declaration is
4045 listing @dfn{system services} and their configuration (@pxref{Using the
4046 Configuration System}). System services are typically daemons launched
4047 when the system boots, or other actions needed at that time---e.g.,
4048 configuring network access. They are managed by GNU@tie{}dmd
4049 (@pxref{Introduction,,, dmd, GNU dmd Manual}).
4051 The following sections document the available services, starting with
4055 * Base Services:: Essential system services.
4056 * Networking Services:: Network setup, SSH daemon, etc.
4057 * X Window:: Graphical display.
4061 @subsubsection Base Services
4063 The @code{(gnu services base)} module provides definitions for the basic
4064 services that one expects from the system. The services exported by
4065 this module are listed below.
4067 @defvr {Scheme Variable} %base-services
4068 This variable contains a list of basic services@footnote{Technically,
4069 this is a list of monadic services. @xref{The Store Monad}.} one would
4070 expect from the system: a login service (mingetty) on each tty, syslogd,
4071 libc's name service cache daemon (nscd), the udev device manager, and
4074 This is the default value of the @code{services} field of
4075 @code{operating-system} declarations. Usually, when customizing a
4076 system, you will want to append services to @var{%base-services}, like
4080 (cons* (avahi-service) (lsh-service) %base-services)
4084 @deffn {Monadic Procedure} host-name-service @var{name}
4085 Return a service that sets the host name to @var{name}.
4088 @deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
4089 [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
4090 [#:allow-empty-passwords? #f]
4091 Return a service to run mingetty on @var{tty}.
4093 When @var{allow-empty-passwords?} is true, allow empty log-in password. When
4094 @var{auto-login} is true, it must be a user name under which to log-in
4095 automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
4096 @var{auto-login}, in which case the user will have to press a key before the
4097 login shell is launched.
4099 When true, @var{login-program} is a gexp or a monadic gexp denoting the name
4100 of the log-in program (the default is the @code{login} program from the Shadow
4103 @var{motd} is a monadic value containing a text file to use as
4104 the ``message of the day''.
4107 @deffn {Monadic Procedure} nscd-service [#:glibc glibc]
4108 Return a service that runs libc's name service cache daemon (nscd).
4111 @deffn {Monadic Procedure} syslog-service
4112 Return a service that runs @code{syslogd} with reasonable default
4116 @deffn {Monadic Procedure} guix-service [#:guix guix] @
4117 [#:builder-group "guixbuild"] [#:build-accounts 10] @
4118 [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @
4119 [#:extra-options '()]
4120 Return a service that runs the build daemon from @var{guix}, and has
4121 @var{build-accounts} user accounts available under @var{builder-group}.
4123 When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
4124 provided by @var{guix} is authorized upon activation, meaning that substitutes
4125 from @code{hydra.gnu.org} are used by default.
4127 If @var{use-substitutes?} is false, the daemon is run with
4128 @option{--no-substitutes} (@pxref{Invoking guix-daemon,
4129 @option{--no-substitutes}}).
4131 Finally, @var{extra-options} is a list of additional command-line options
4132 passed to @command{guix-daemon}.
4135 @deffn {Monadic Procedure} udev-service [#:udev udev]
4136 Run @var{udev}, which populates the @file{/dev} directory dynamically.
4140 @node Networking Services
4141 @subsubsection Networking Services
4143 The @code{(gnu services networking)} module provides services to configure
4144 the network interface.
4146 @cindex DHCP, networking service
4147 @deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
4148 Return a service that runs @var{dhcp}, a Dynamic Host Configuration
4149 Protocol (DHCP) client, on all the non-loopback network interfaces.
4152 @deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
4153 [#:gateway #f] [#:name-services @code{'()}]
4154 Return a service that starts @var{interface} with address @var{ip}. If
4155 @var{gateway} is true, it must be a string specifying the default network
4159 @deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
4160 [#:name-service @var{%ntp-servers}]
4161 Return a service that runs the daemon from @var{ntp}, the
4162 @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
4163 keep the system clock synchronized with that of @var{servers}.
4166 @defvr {Scheme Variable} %ntp-servers
4167 List of host names used as the default NTP servers.
4170 @deffn {Monadic Procedure} tor-service [#:tor tor]
4171 Return a service to run the @uref{https://torproject.org,Tor} daemon.
4173 The daemon runs with the default settings (in particular the default exit
4174 policy) as the @code{tor} unprivileged user.
4177 @deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
4178 [#:interface "127.0.0.1"] [#:port 6667] @
4179 [#:extra-settings ""]
4180 Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
4181 acts as a gateway between IRC and chat networks.
4183 The daemon will listen to the interface corresponding to the IP address
4184 specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
4185 local clients can connect, whereas @code{0.0.0.0} means that connections can
4186 come from any networking interface.
4188 In addition, @var{extra-settings} specifies a string to append to the
4192 Furthermore, @code{(gnu services ssh)} provides the following service.
4194 @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
4195 [#:interfaces '()] [#:port-number 22] @
4196 [#:allow-empty-passwords? #f] [#:root-login? #f] @
4197 [#:syslog-output? #t] [#:x11-forwarding? #t] @
4198 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
4199 [public-key-authentication? #t] [#:initialize? #f]
4200 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
4201 @var{host-key} must designate a file containing the host key, and readable
4204 When @var{initialize?} is true, automatically create the seed and host key
4205 upon service activation if they do not exist yet. This may take long and
4206 require interaction.
4208 When @var{initialize?} is false, it is up to the user to initialize the
4209 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
4210 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
4211 basics,,, lsh, LSH Manual}).
4213 When @var{interfaces} is empty, lshd listens for connections on all the
4214 network interfaces; otherwise, @var{interfaces} must be a list of host names
4217 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
4218 passwords, and @var{root-login?} specifies whether to accept log-ins as
4221 The other options should be self-descriptive.
4224 @defvr {Scheme Variable} %facebook-host-aliases
4225 This variable contains a string for use in @file{/etc/hosts}
4226 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
4227 line contains a entry that maps a known server name of the Facebook
4228 on-line service---e.g., @code{www.facebook.com}---to the local
4229 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
4231 This variable is typically used in the @code{hosts-file} field of an
4232 @code{operating-system} declaration (@pxref{operating-system Reference,
4233 @file{/etc/hosts}}):
4236 (use-modules (gnu) (guix))
4239 (host-name "mymachine")
4242 ;; Create a /etc/hosts file with aliases for "localhost"
4243 ;; and "mymachine", as well as for Facebook servers.
4245 (string-append (local-host-aliases host-name)
4246 %facebook-host-aliases))))
4249 This mechanism can prevent programs running locally, such as Web
4250 browsers, from accessing Facebook.
4254 @subsubsection X Window
4256 Support for the X Window graphical display system---specifically
4257 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
4258 there is no @code{xorg-service} procedure. Instead, the X server is
4259 started by the @dfn{login manager}, currently SLiM.
4261 @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
4262 [#:auto-login? #f] [#:default-user ""] [#:startx] @
4263 [#:theme @var{%default-slim-theme}] @
4264 [#:theme-name @var{%default-slim-theme-name}]
4265 Return a service that spawns the SLiM graphical login manager, which in
4266 turn starts the X display server with @var{startx}, a command as returned by
4267 @code{xorg-start-command}.
4269 When @var{allow-empty-passwords?} is true, allow logins with an empty
4270 password. When @var{auto-login?} is true, log in automatically as
4273 If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
4274 @var{theme} must be a gexp denoting the name of a directory containing the
4275 theme to use. In that case, @var{theme-name} specifies the name of the
4279 @defvr {Scheme Variable} %default-theme
4280 @defvrx {Scheme Variable} %default-theme-name
4281 The G-Expression denoting the default SLiM theme and its name.
4284 @deffn {Monadic Procedure} xorg-start-command [#:guile] @
4285 [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
4286 Return a derivation that builds a @var{guile} script to start the X server
4287 from @var{xorg-server}. Usually the X server is started by a login manager.
4289 @var{drivers} must be either the empty list, in which case Xorg chooses a
4290 graphics driver automatically, or a list of driver names that will be tried in
4291 this order---e.g., @code{("modesetting" "vesa")}.
4293 Likewise, when @var{resolutions} is the empty list, Xorg chooses an
4294 appropriate screen resolution; otherwise, it must be a list of
4295 resolutions---e.g., @code{((1024 768) (640 480))}.
4298 @node Setuid Programs
4299 @subsection Setuid Programs
4301 @cindex setuid programs
4302 Some programs need to run with ``root'' privileges, even when they are
4303 launched by unprivileged users. A notorious example is the
4304 @command{passwd} programs, which can users can run to change their
4305 password, and which requires write access to the @file{/etc/passwd} and
4306 @file{/etc/shadow} files---something normally restricted to root, for
4307 obvious security reasons. To address that, these executables are
4308 @dfn{setuid-root}, meaning that they always run with root privileges
4309 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
4310 for more info about the setuid mechanisms.)
4312 The store itself @emph{cannot} contain setuid programs: that would be a
4313 security issue since any user on the system can write derivations that
4314 populate the store (@pxref{The Store}). Thus, a different mechanism is
4315 used: instead of changing the setuid bit directly on files that are in
4316 the store, we let the system administrator @emph{declare} which programs
4317 should be setuid root.
4319 The @code{setuid-programs} field of an @code{operating-system}
4320 declaration contains a list of G-expressions denoting the names of
4321 programs to be setuid-root (@pxref{Using the Configuration System}).
4322 For instance, the @command{passwd} program, which is part of the Shadow
4323 package, can be designated by this G-expression (@pxref{G-Expressions}):
4326 #~(string-append #$shadow "/bin/passwd")
4329 A default set of setuid programs is defined by the
4330 @code{%setuid-programs} variable of the @code{(gnu system)} module.
4332 @defvr {Scheme Variable} %setuid-programs
4333 A list of G-expressions denoting common programs that are setuid-root.
4335 The list includes commands such as @command{passwd}, @command{ping},
4336 @command{su}, and @command{sudo}.
4339 Under the hood, the actual setuid programs are created in the
4340 @file{/run/setuid-programs} directory at system activation time. The
4341 files in this directory refer to the ``real'' binaries, which are in the
4345 @node Initial RAM Disk
4346 @subsection Initial RAM Disk
4348 @cindex initial RAM disk (initrd)
4349 @cindex initrd (initial RAM disk)
4350 For bootstrapping purposes, the Linux-Libre kernel is passed an
4351 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
4352 root file system, as well as an initialization script. The latter is
4353 responsible for mounting the real root file system, and for loading any
4354 kernel modules that may be needed to achieve that.
4356 The @code{initrd} field of an @code{operating-system} declaration allows
4357 you to specify which initrd you would like to use. The @code{(gnu
4358 system linux-initrd)} module provides two ways to build an initrd: the
4359 high-level @code{base-initrd} procedure, and the low-level
4360 @code{expression->initrd} procedure.
4362 The @code{base-initrd} procedure is intended to cover most common uses.
4363 For example, if you want to add a bunch of kernel modules to be loaded
4364 at boot time, you can define the @code{initrd} field of the operating
4365 system declaration like this:
4368 (initrd (lambda (file-systems . rest)
4369 (apply base-initrd file-systems
4370 #:extra-modules '("my.ko" "modules.ko")
4374 The @code{base-initrd} procedure also handles common use cases that
4375 involves using the system as a QEMU guest, or as a ``live'' system whose
4376 root file system is volatile.
4378 @deffn {Monadic Procedure} base-initrd @var{file-systems} @
4379 [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
4380 [#:extra-modules '()] [#:mapped-devices '()]
4381 Return a monadic derivation that builds a generic initrd. @var{file-systems} is
4382 a list of file-systems to be mounted by the initrd, possibly in addition to
4383 the root file system specified on the kernel command line via @code{--root}.
4384 @var{mapped-devices} is a list of device mappings to realize before
4385 @var{file-systems} are mounted (@pxref{Mapped Devices}).
4387 When @var{qemu-networking?} is true, set up networking with the standard QEMU
4388 parameters. When @var{virtio?} is true, load additional modules so the initrd can
4389 be used as a QEMU guest with para-virtualized I/O drivers.
4391 When @var{volatile-root?} is true, the root file system is writable but any changes
4394 The initrd is automatically populated with all the kernel modules necessary
4395 for @var{file-systems} and for the given options. However, additional kernel
4396 modules can be listed in @var{extra-modules}. They will be added to the initrd, and
4397 loaded at boot time in the order in which they appear.
4400 Needless to say, the initrds we produce and use embed a
4401 statically-linked Guile, and the initialization program is a Guile
4402 program. That gives a lot of flexibility. The
4403 @code{expression->initrd} procedure builds such an initrd, given the
4404 program to run in that initrd.
4406 @deffn {Monadic Procedure} expression->initrd @var{exp} @
4407 [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
4409 Return a derivation that builds a Linux initrd (a gzipped cpio archive)
4410 containing @var{guile} and that evaluates @var{exp}, a G-expression,
4411 upon booting. All the derivations referenced by @var{exp} are
4412 automatically copied to the initrd.
4414 @var{modules} is a list of Guile module names to be embedded in the
4418 @node GRUB Configuration
4419 @subsection GRUB Configuration
4424 The operating system uses GNU@tie{}GRUB as its boot loader
4425 (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
4426 configured using @code{grub-configuration} declarations. This data type
4427 is exported by the @code{(gnu system grub)} module, and described below.
4429 @deftp {Data Type} grub-configuration
4430 The type of a GRUB configuration declaration.
4435 This is a string denoting the boot device. It must be a device name
4436 understood by the @command{grub-install} command, such as
4437 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
4440 @item @code{menu-entries} (default: @code{()})
4441 A possibly empty list of @code{menu-entry} objects (see below), denoting
4442 entries to appear in the GRUB boot menu, in addition to the current
4443 system entry and the entry pointing to previous system generations.
4445 @item @code{default-entry} (default: @code{0})
4446 The index of the default boot menu entry. Index 0 is for the current
4449 @item @code{timeout} (default: @code{5})
4450 The number of seconds to wait for keyboard input before booting. Set to
4451 0 to boot immediately, and to -1 to wait indefinitely.
4453 @item @code{theme} (default: @var{%default-theme})
4454 The @code{grub-theme} object describing the theme to use.
4459 Should you want to list additional boot menu entries @i{via} the
4460 @code{menu-entries} field above, you will need to create them with the
4461 @code{menu-entry} form:
4463 @deftp {Data Type} menu-entry
4464 The type of an entry in the GRUB boot menu.
4469 The label to show in the menu---e.g., @code{"GNU System"}.
4472 The Linux kernel to boot.
4474 @item @code{linux-arguments} (default: @code{()})
4475 The list of extra Linux kernel command-line arguments---e.g.,
4476 @code{("console=ttyS0")}.
4479 A G-Expression or string denoting the file name of the initial RAM disk
4480 to use (@pxref{G-Expressions}).
4485 @c FIXME: Write documentation once it's stable.
4486 Themes are created using the @code{grub-theme} form, which is not
4489 @defvr {Scheme Variable} %default-theme
4490 This is the default GRUB theme used by the operating system, with a
4491 fancy background image displaying the GNU and Guix logos.
4495 @node Invoking guix system
4496 @subsection Invoking @code{guix system}
4498 Once you have written an operating system declaration, as seen in the
4499 previous section, it can be @dfn{instantiated} using the @command{guix
4500 system} command. The synopsis is:
4503 guix system @var{options}@dots{} @var{action} @var{file}
4506 @var{file} must be the name of a file containing an
4507 @code{operating-system} declaration. @var{action} specifies how the
4508 operating system is instantiate. Currently the following values are
4513 Build the operating system described in @var{file}, activate it, and
4514 switch to it@footnote{This action is usable only on systems already
4517 This effects all the configuration specified in @var{file}: user
4518 accounts, system services, global package list, setuid programs, etc.
4520 It also adds a GRUB menu entry for the new OS configuration, and moves
4521 entries for older configurations to a submenu---unless
4522 @option{--no-grub} is passed.
4524 @c The paragraph below refers to the problem discussed at
4525 @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
4526 It is highly recommended to run @command{guix pull} once before you run
4527 @command{guix system reconfigure} for the first time (@pxref{Invoking
4528 guix pull}). Failing to do that you would see an older version of Guix
4529 once @command{reconfigure} has completed.
4532 Build the operating system's derivation, which includes all the
4533 configuration files and programs needed to boot and run the system.
4534 This action does not actually install anything.
4537 Populate the given directory with all the files necessary to run the
4538 operating system specified in @var{file}. This is useful for first-time
4539 installations of the GNU system. For instance:
4542 guix system init my-os-config.scm /mnt
4545 copies to @file{/mnt} all the store items required by the configuration
4546 specified in @file{my-os-config.scm}. This includes configuration
4547 files, packages, and so on. It also creates other essential files
4548 needed for the system to operate correctly---e.g., the @file{/etc},
4549 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
4551 This command also installs GRUB on the device specified in
4552 @file{my-os-config}, unless the @option{--no-grub} option was passed.
4555 @cindex virtual machine
4557 Build a virtual machine that contain the operating system declared in
4558 @var{file}, and return a script to run that virtual machine (VM).
4559 Arguments given to the script are passed as is to QEMU.
4561 The VM shares its store with the host system.
4563 Additional file systems can be shared between the host and the VM using
4564 the @code{--share} and @code{--expose} command-line options: the former
4565 specifies a directory to be shared with write access, while the latter
4566 provides read-only access to the shared directory.
4568 The example below creates a VM in which the user's home directory is
4569 accessible read-only, and where the @file{/exchange} directory is a
4570 read-write mapping of the host's @file{$HOME/tmp}:
4573 guix system vm my-config.scm \
4574 --expose=$HOME --share=$HOME/tmp=/exchange
4577 On GNU/Linux, the default is to boot directly to the kernel; this has
4578 the advantage of requiring only a very tiny root disk image since the
4579 host's store can then be mounted.
4581 The @code{--full-boot} option forces a complete boot sequence, starting
4582 with the bootloader. This requires more disk space since a root image
4583 containing at least the kernel, initrd, and bootloader data files must
4584 be created. The @code{--image-size} option can be used to specify the
4589 Return a virtual machine or disk image of the operating system declared
4590 in @var{file} that stands alone. Use the @option{--image-size} option
4591 to specify the size of the image.
4593 When using @code{vm-image}, the returned image is in qcow2 format, which
4594 the QEMU emulator can efficiently use.
4596 When using @code{disk-image}, a raw disk image is produced; it can be
4597 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
4598 the device corresponding to a USB stick, one can copy the image on it
4599 using the following command:
4602 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
4607 @var{options} can contain any of the common build options provided by
4608 @command{guix build} (@pxref{Invoking guix build}). In addition,
4609 @var{options} can contain one of the following:
4612 @item --system=@var{system}
4613 @itemx -s @var{system}
4614 Attempt to build for @var{system} instead of the host's system type.
4615 This works as per @command{guix build} (@pxref{Invoking guix build}).
4617 @item --image-size=@var{size}
4618 For the @code{vm-image} and @code{disk-image} actions, create an image
4619 of the given @var{size}. @var{size} may be a number of bytes, or it may
4620 include a unit as a suffix (@pxref{Block size, size specifications,,
4621 coreutils, GNU Coreutils}).
4624 Note that all the actions above, except @code{build} and @code{init},
4625 rely on KVM support in the Linux-Libre kernel. Specifically, the
4626 machine should have hardware virtualization support, the corresponding
4627 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
4628 must exist and be readable and writable by the user and by the daemon's
4631 @node Defining Services
4632 @subsection Defining Services
4634 The @code{(gnu services @dots{})} modules define several procedures that allow
4635 users to declare the operating system's services (@pxref{Using the
4636 Configuration System}). These procedures are @emph{monadic
4637 procedures}---i.e., procedures that return a monadic value in the store
4638 monad (@pxref{The Store Monad}). For examples of such procedures,
4641 @cindex service definition
4642 The monadic value returned by those procedures is a @dfn{service
4643 definition}---a structure as returned by the @code{service} form.
4644 Service definitions specifies the inputs the service depends on, and an
4645 expression to start and stop the service. Behind the scenes, service
4646 definitions are ``translated'' into the form suitable for the
4647 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
4650 As an example, here is what the @code{nscd-service} procedure looks
4654 (define (nscd-service)
4655 (with-monad %store-monad
4657 (documentation "Run libc's name service cache daemon.")
4660 (use-modules (guix build utils))
4661 (mkdir-p "/var/run/nscd")))
4662 (start #~(make-forkexec-constructor
4663 (string-append #$glibc "/sbin/nscd")
4664 "-f" "/dev/null" "--foreground"))
4665 (stop #~(make-kill-destructor))
4670 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
4671 (@pxref{G-Expressions}). The @code{activate} field contains a script to
4672 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
4673 directory exists before @command{nscd} is started.
4675 The @code{start} and @code{stop} fields refer to dmd's facilities to
4676 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
4677 GNU dmd Manual}). The @code{provision} field specifies the name under
4678 which this service is known to dmd, and @code{documentation} specifies
4679 on-line documentation. Thus, the commands @command{deco start ncsd},
4680 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
4681 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
4684 @node Installing Debugging Files
4685 @section Installing Debugging Files
4687 @cindex debugging files
4688 Program binaries, as produced by the GCC compilers for instance, are
4689 typically written in the ELF format, with a section containing
4690 @dfn{debugging information}. Debugging information is what allows the
4691 debugger, GDB, to map binary code to source code; it is required to
4692 debug a compiled program in good conditions.
4694 The problem with debugging information is that is takes up a fair amount
4695 of disk space. For example, debugging information for the GNU C Library
4696 weighs in at more than 60 MiB. Thus, as a user, keeping all the
4697 debugging info of all the installed programs is usually not an option.
4698 Yet, space savings should not come at the cost of an impediment to
4699 debugging---especially in the GNU system, which should make it easier
4700 for users to exert their computing freedom (@pxref{GNU Distribution}).
4702 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
4703 mechanism that allows users to get the best of both worlds: debugging
4704 information can be stripped from the binaries and stored in separate
4705 files. GDB is then able to load debugging information from those files,
4706 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
4709 The GNU distribution takes advantage of this by storing debugging
4710 information in the @code{lib/debug} sub-directory of a separate package
4711 output unimaginatively called @code{debug} (@pxref{Packages with
4712 Multiple Outputs}). Users can choose to install the @code{debug} output
4713 of a package when they need it. For instance, the following command
4714 installs the debugging information for the GNU C Library and for GNU
4718 guix package -i glibc:debug guile:debug
4721 GDB must then be told to look for debug files in the user's profile, by
4722 setting the @code{debug-file-directory} variable (consider setting it
4723 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
4727 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
4730 From there on, GDB will pick up debugging information from the
4731 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
4733 In addition, you will most likely want GDB to be able to show the source
4734 code being debugged. To do that, you will have to unpack the source
4735 code of the package of interest (obtained with @code{guix build
4736 --source}, @pxref{Invoking guix build}), and to point GDB to that source
4737 directory using the @code{directory} command (@pxref{Source Path,
4738 @code{directory},, gdb, Debugging with GDB}).
4740 @c XXX: keep me up-to-date
4741 The @code{debug} output mechanism in Guix is implemented by the
4742 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
4743 opt-in---debugging information is available only for those packages
4744 whose definition explicitly declares a @code{debug} output. This may be
4745 changed to opt-out in the future, if our build farm servers can handle
4746 the load. To check whether a package has a @code{debug} output, use
4747 @command{guix package --list-available} (@pxref{Invoking guix package}).
4750 @node Security Updates
4751 @section Security Updates
4754 As of version @value{VERSION}, the feature described in this section is
4758 @cindex security updates
4759 Occasionally, important security vulnerabilities are discovered in core
4760 software packages and must be patched. Guix follows a functional
4761 package management discipline (@pxref{Introduction}), which implies
4762 that, when a package is changed, @emph{every package that depends on it}
4763 must be rebuilt. This can significantly slow down the deployment of
4764 fixes in core packages such as libc or Bash, since basically the whole
4765 distribution would need to be rebuilt. Using pre-built binaries helps
4766 (@pxref{Substitutes}), but deployment may still take more time than
4770 To address that, Guix implements @dfn{grafts}, a mechanism that allows
4771 for fast deployment of critical updates without the costs associated
4772 with a whole-distribution rebuild. The idea is to rebuild only the
4773 package that needs to be patched, and then to ``graft'' it onto packages
4774 explicitly installed by the user and that were previously referring to
4775 the original package. The cost of grafting is typically very low, and
4776 order of magnitudes lower than a full rebuild of the dependency chain.
4778 @cindex replacements of packages, for grafts
4779 For instance, suppose a security update needs to be applied to Bash.
4780 Guix developers will provide a package definition for the ``fixed''
4781 Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
4782 Packages}). Then, the original package definition is augmented with a
4783 @code{replacement} field pointing to the package containing the bug fix:
4790 (replacement bash-fixed)))
4793 From there on, any package depending directly or indirectly on Bash that
4794 is installed will automatically be ``rewritten'' to refer to
4795 @var{bash-fixed} instead of @var{bash}. This grafting process takes
4796 time proportional to the size of the package, but expect less than a
4797 minute for an ``average'' package on a recent machine.
4799 Currently, the graft and the package it replaces (@var{bash-fixed} and
4800 @var{bash} in the example above) must have the exact same @code{name}
4801 and @code{version} fields. This restriction mostly comes from the fact
4802 that grafting works by patching files, including binary files, directly.
4803 Other restrictions may apply: for instance, when adding a graft to a
4804 package providing a shared library, the original shared library and its
4805 replacement must have the same @code{SONAME} and be binary-compatible.
4808 @node Package Modules
4809 @section Package Modules
4811 From a programming viewpoint, the package definitions of the
4812 GNU distribution are provided by Guile modules in the @code{(gnu packages
4813 @dots{})} name space@footnote{Note that packages under the @code{(gnu
4814 packages @dots{})} module name space are not necessarily ``GNU
4815 packages''. This module naming scheme follows the usual Guile module
4816 naming convention: @code{gnu} means that these modules are distributed
4817 as part of the GNU system, and @code{packages} identifies modules that
4818 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
4819 Reference Manual}). For instance, the @code{(gnu packages emacs)}
4820 module exports a variable named @code{emacs}, which is bound to a
4821 @code{<package>} object (@pxref{Defining Packages}).
4823 The @code{(gnu packages @dots{})} module name space is
4824 automatically scanned for packages by the command-line tools. For
4825 instance, when running @code{guix package -i emacs}, all the @code{(gnu
4826 packages @dots{})} modules are scanned until one that exports a package
4827 object whose name is @code{emacs} is found. This package search
4828 facility is implemented in the @code{(gnu packages)} module.
4830 @cindex customization, of packages
4831 @cindex package module search path
4832 Users can store package definitions in modules with different
4833 names---e.g., @code{(my-packages emacs)}. These package definitions
4834 will not be visible by default. Thus, users can invoke commands such as
4835 @command{guix package} and @command{guix build} have to be used with the
4836 @code{-e} option so that they know where to find the package, or use the
4837 @code{-L} option of these commands to make those modules visible
4838 (@pxref{Invoking guix build, @code{--load-path}}), or define the
4839 @code{GUIX_PACKAGE_PATH} environment variable. This environment
4840 variable makes it easy to extend or customize the distribution and is
4841 honored by all the user interfaces.
4843 @defvr {Environment Variable} GUIX_PACKAGE_PATH
4844 This is a colon-separated list of directories to search for package
4845 modules. Directories listed in this variable take precedence over the
4846 distribution's own modules.
4849 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
4850 each package is built based solely on other packages in the
4851 distribution. The root of this dependency graph is a small set of
4852 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
4853 bootstrap)} module. For more information on bootstrapping,
4854 @pxref{Bootstrapping}.
4856 @node Packaging Guidelines
4857 @section Packaging Guidelines
4859 The GNU distribution is nascent and may well lack some of your favorite
4860 packages. This section describes how you can help make the distribution
4861 grow. @xref{Contributing}, for additional information on how you can
4864 Free software packages are usually distributed in the form of
4865 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
4866 all the source files. Adding a package to the distribution means
4867 essentially two things: adding a @dfn{recipe} that describes how to
4868 build the package, including a list of other packages required to build
4869 it, and adding @dfn{package meta-data} along with that recipe, such as a
4870 description and licensing information.
4872 In Guix all this information is embodied in @dfn{package definitions}.
4873 Package definitions provide a high-level view of the package. They are
4874 written using the syntax of the Scheme programming language; in fact,
4875 for each package we define a variable bound to the package definition,
4876 and export that variable from a module (@pxref{Package Modules}).
4877 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
4878 creating packages. For more information on package definitions,
4879 @pxref{Defining Packages}.
4881 Once a package definition is in place, stored in a file in the Guix
4882 source tree, it can be tested using the @command{guix build} command
4883 (@pxref{Invoking guix build}). For example, assuming the new package is
4884 called @code{gnew}, you may run this command from the Guix build tree:
4887 ./pre-inst-env guix build gnew --keep-failed
4890 Using @code{--keep-failed} makes it easier to debug build failures since
4891 it provides access to the failed build tree. Another useful
4892 command-line option when debugging is @code{--log-file}, to access the
4895 If the package is unknown to the @command{guix} command, it may be that
4896 the source file contains a syntax error, or lacks a @code{define-public}
4897 clause to export the package variable. To figure it out, you may load
4898 the module from Guile to get more information about the actual error:
4901 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
4904 Once your package builds correctly, please send us a patch
4905 (@pxref{Contributing}). Well, if you need help, we will be happy to
4906 help you too. Once the patch is committed in the Guix repository, the
4907 new package automatically gets built on the supported platforms by
4908 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
4912 Users can obtain the new package definition simply by running
4913 @command{guix pull} (@pxref{Invoking guix pull}). When
4914 @code{hydra.gnu.org} is done building the package, installing the
4915 package automatically downloads binaries from there
4916 (@pxref{Substitutes}). The only place where human intervention is
4917 needed is to review and apply the patch.
4921 * Software Freedom:: What may go into the distribution.
4922 * Package Naming:: What's in a name?
4923 * Version Numbers:: When the name is not enough.
4924 * Python Modules:: Taming the snake.
4925 * Perl Modules:: Little pearls.
4926 * Fonts:: Fond of fonts.
4929 @node Software Freedom
4930 @subsection Software Freedom
4932 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
4934 The GNU operating system has been developed so that users can have
4935 freedom in their computing. GNU is @dfn{free software}, meaning that
4936 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
4937 essential freedoms}: to run the program, to study and change the program
4938 in source code form, to redistribute exact copies, and to distribute
4939 modified versions. Packages found in the GNU distribution provide only
4940 software that conveys these four freedoms.
4942 In addition, the GNU distribution follow the
4943 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
4944 software distribution guidelines}. Among other things, these guidelines
4945 reject non-free firmware, recommendations of non-free software, and
4946 discuss ways to deal with trademarks and patents.
4948 Some packages contain a small and optional subset that violates the
4949 above guidelines, for instance because this subset is itself non-free
4950 code. When that happens, the offending items are removed with
4951 appropriate patches or code snippets in the package definition's
4952 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
4953 build --source} returns the ``freed'' source rather than the unmodified
4957 @node Package Naming
4958 @subsection Package Naming
4960 A package has actually two names associated with it:
4961 First, there is the name of the @emph{Scheme variable}, the one following
4962 @code{define-public}. By this name, the package can be made known in the
4963 Scheme code, for instance as input to another package. Second, there is
4964 the string in the @code{name} field of a package definition. This name
4965 is used by package management commands such as
4966 @command{guix package} and @command{guix build}.
4968 Both are usually the same and correspond to the lowercase conversion of
4969 the project name chosen upstream, with underscores replaced with
4970 hyphens. For instance, GNUnet is available as @code{gnunet}, and
4971 SDL_net as @code{sdl-net}.
4973 We do not add @code{lib} prefixes for library packages, unless these are
4974 already part of the official project name. But @pxref{Python
4975 Modules} and @ref{Perl Modules} for special rules concerning modules for
4976 the Python and Perl languages.
4978 Font package names are handled differently, @pxref{Fonts}.
4981 @node Version Numbers
4982 @subsection Version Numbers
4984 We usually package only the latest version of a given free software
4985 project. But sometimes, for instance for incompatible library versions,
4986 two (or more) versions of the same package are needed. These require
4987 different Scheme variable names. We use the name as defined
4988 in @ref{Package Naming}
4989 for the most recent version; previous versions use the same name, suffixed
4990 by @code{-} and the smallest prefix of the version number that may
4991 distinguish the two versions.
4993 The name inside the package definition is the same for all versions of a
4994 package and does not contain any version number.
4996 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
5004 (define-public gtk+-2
5010 If we also wanted GTK+ 3.8.2, this would be packaged as
5012 (define-public gtk+-3.8
5020 @node Python Modules
5021 @subsection Python Modules
5023 We currently package Python 2 and Python 3, under the Scheme variable names
5024 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
5025 To avoid confusion and naming clashes with other programming languages, it
5026 seems desirable that the name of a package for a Python module contains
5027 the word @code{python}.
5029 Some modules are compatible with only one version of Python, others with both.
5030 If the package Foo compiles only with Python 3, we name it
5031 @code{python-foo}; if it compiles only with Python 2, we name it
5032 @code{python2-foo}. If it is compatible with both versions, we create two
5033 packages with the corresponding names.
5035 If a project already contains the word @code{python}, we drop this;
5036 for instance, the module python-dateutil is packaged under the names
5037 @code{python-dateutil} and @code{python2-dateutil}.
5041 @subsection Perl Modules
5043 Perl programs standing for themselves are named as any other package,
5044 using the lowercase upstream name.
5045 For Perl packages containing a single class, we use the lowercase class name,
5046 replace all occurrences of @code{::} by dashes and prepend the prefix
5048 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
5049 Modules containing several classes keep their lowercase upstream name and
5050 are also prepended by @code{perl-}. Such modules tend to have the word
5051 @code{perl} somewhere in their name, which gets dropped in favor of the
5052 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
5058 For fonts that are in general not installed by a user for typesetting
5059 purposes, or that are distributed as part of a larger software package,
5060 we rely on the general packaging rules for software; for instance, this
5061 applies to the fonts delivered as part of the X.Org system or fonts that
5062 are part of TeX Live.
5064 To make it easier for a user to search for fonts, names for other packages
5065 containing only fonts are constructed as follows, independently of the
5066 upstream package name.
5068 The name of a package containing only one font family starts with
5069 @code{font-}; it is followed by the foundry name and a dash @code{-}
5070 if the foundry is known, and the font family name, in which spaces are
5071 replaced by dashes (and as usual, all upper case letters are transformed
5073 For example, the Gentium font family by SIL is packaged under the name
5074 @code{font-sil-gentium}.
5076 For a package containing several font families, the name of the collection
5077 is used in the place of the font family name.
5078 For instance, the Liberation fonts consist of three families,
5079 Liberation Sans, Liberation Serif and Liberation Mono.
5080 These could be packaged separately under the names
5081 @code{font-liberation-sans} and so on; but as they are distributed together
5082 under a common name, we prefer to package them together as
5083 @code{font-liberation}.
5085 In the case where several formats of the same font family or font collection
5086 are packaged separately, a short form of the format, prepended by a dash,
5087 is added to the package name. We use @code{-ttf} for TrueType fonts,
5088 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
5094 @section Bootstrapping
5096 @c Adapted from the ELS 2013 paper.
5098 @cindex bootstrapping
5100 Bootstrapping in our context refers to how the distribution gets built
5101 ``from nothing''. Remember that the build environment of a derivation
5102 contains nothing but its declared inputs (@pxref{Introduction}). So
5103 there's an obvious chicken-and-egg problem: how does the first package
5104 get built? How does the first compiler get compiled? Note that this is
5105 a question of interest only to the curious hacker, not to the regular
5106 user, so you can shamelessly skip this section if you consider yourself
5109 @cindex bootstrap binaries
5110 The GNU system is primarily made of C code, with libc at its core. The
5111 GNU build system itself assumes the availability of a Bourne shell and
5112 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
5113 `grep'. Furthermore, build programs---programs that run
5114 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
5115 (@pxref{Derivations}). Consequently, to be able to build anything at
5116 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
5117 Binutils, libc, and the other packages mentioned above---the
5118 @dfn{bootstrap binaries}.
5120 These bootstrap binaries are ``taken for granted'', though we can also
5121 re-create them if needed (more on that later).
5123 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
5125 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
5126 @c large image, it's hard to scroll. Oh well.
5127 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
5129 The figure above shows the very beginning of the dependency graph of the
5130 distribution, corresponding to the package definitions of the @code{(gnu
5131 packages bootstrap)} module. At this level of detail, things are
5132 slightly complex. First, Guile itself consists of an ELF executable,
5133 along with many source and compiled Scheme files that are dynamically
5134 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
5135 tarball shown in this graph. This tarball is part of Guix's ``source''
5136 distribution, and gets inserted into the store with @code{add-to-store}
5137 (@pxref{The Store}).
5139 But how do we write a derivation that unpacks this tarball and adds it
5140 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
5141 derivation---the first one that gets built---uses @code{bash} as its
5142 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
5143 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
5144 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
5145 the Guix source distribution, whose sole purpose is to allow the Guile
5146 tarball to be unpacked.
5148 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
5149 Guile that can be used to run subsequent build programs. Its first task
5150 is to download tarballs containing the other pre-built binaries---this
5151 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
5152 @code{ftp-client.scm} are used for this purpose. The
5153 @code{module-import.drv} derivations import those modules in a directory
5154 in the store, using the original layout. The
5155 @code{module-import-compiled.drv} derivations compile those modules, and
5156 write them in an output directory with the right layout. This
5157 corresponds to the @code{#:modules} argument of
5158 @code{build-expression->derivation} (@pxref{Derivations}).
5160 Finally, the various tarballs are unpacked by the
5161 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
5162 etc., at which point we have a working C tool chain.
5165 @unnumberedsubsec Building the Build Tools
5167 @c TODO: Add a package-level dependency graph generated from (gnu
5170 Bootstrapping is complete when we have a full tool chain that does not
5171 depend on the pre-built bootstrap tools discussed above. This
5172 no-dependency requirement is verified by checking whether the files of
5173 the final tool chain contain references to the @file{/gnu/store}
5174 directories of the bootstrap inputs. The process that leads to this
5175 ``final'' tool chain is described by the package definitions found in
5176 the @code{(gnu packages commencement)} module.
5178 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
5179 The first tool that gets built with the bootstrap binaries is
5180 GNU Make, which is a prerequisite for all the following packages.
5181 From there Findutils and Diffutils get built.
5183 Then come the first-stage Binutils and GCC, built as pseudo cross
5184 tools---i.e., with @code{--target} equal to @code{--host}. They are
5185 used to build libc. Thanks to this cross-build trick, this libc is
5186 guaranteed not to hold any reference to the initial tool chain.
5188 From there the final Binutils and GCC are built. GCC uses @code{ld}
5189 from the final Binutils, and links programs against the just-built libc.
5190 This tool chain is used to build the other packages used by Guix and by
5191 the GNU Build System: Guile, Bash, Coreutils, etc.
5193 And voilà! At this point we have the complete set of build tools that
5194 the GNU Build System expects. These are in the @code{%final-inputs}
5195 variable of the @code{(gnu packages commencement)} module, and are
5196 implicitly used by any package that uses @code{gnu-build-system}
5197 (@pxref{Build Systems, @code{gnu-build-system}}).
5200 @unnumberedsubsec Building the Bootstrap Binaries
5202 Because the final tool chain does not depend on the bootstrap binaries,
5203 those rarely need to be updated. Nevertheless, it is useful to have an
5204 automated way to produce them, should an update occur, and this is what
5205 the @code{(gnu packages make-bootstrap)} module provides.
5207 The following command builds the tarballs containing the bootstrap
5208 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
5209 of Coreutils and other basic command-line tools):
5212 guix build bootstrap-tarballs
5215 The generated tarballs are those that should be referred to in the
5216 @code{(gnu packages bootstrap)} module mentioned at the beginning of
5219 Still here? Then perhaps by now you've started to wonder: when do we
5220 reach a fixed point? That is an interesting question! The answer is
5221 unknown, but if you would like to investigate further (and have
5222 significant computational and storage resources to do so), then let us
5226 @section Porting to a New Platform
5228 As discussed above, the GNU distribution is self-contained, and
5229 self-containment is achieved by relying on pre-built ``bootstrap
5230 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
5231 operating system kernel, CPU architecture, and application binary
5232 interface (ABI). Thus, to port the distribution to a platform that is
5233 not yet supported, one must build those bootstrap binaries, and update
5234 the @code{(gnu packages bootstrap)} module to use them on that platform.
5236 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
5237 When everything goes well, and assuming the GNU tool chain supports the
5238 target platform, this can be as simple as running a command like this
5242 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
5245 For this to work, the @code{glibc-dynamic-linker} procedure in
5246 @code{(gnu packages bootstrap)} must be augmented to return the right
5247 file name for libc's dynamic linker on that platform; likewise,
5248 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
5249 taught about the new platform.
5251 Once these are built, the @code{(gnu packages bootstrap)} module needs
5252 to be updated to refer to these binaries on the target platform. That
5253 is, the hashes and URLs of the bootstrap tarballs for the new platform
5254 must be added alongside those of the currently supported platforms. The
5255 bootstrap Guile tarball is treated specially: it is expected to be
5256 available locally, and @file{gnu-system.am} has rules do download it for
5257 the supported architectures; a rule for the new platform must be added
5260 In practice, there may be some complications. First, it may be that the
5261 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
5262 above) is not recognized by all the GNU tools. Typically, glibc
5263 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
5264 configure flag (see @code{gcc.scm} for examples of how to handle this).
5265 Second, some of the required packages could fail to build for that
5266 platform. Lastly, the generated binaries could be broken for some
5270 @c *********************************************************************
5272 @chapter Contributing
5274 This project is a cooperative effort, and we need your help to make it
5275 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
5276 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
5277 reports, patches, and anything that may be helpful to the project. We
5278 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
5281 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
5282 @file{HACKING} file} that comes with the Guix source code for practical
5283 details about contributions.
5286 @c *********************************************************************
5287 @node Acknowledgments
5288 @chapter Acknowledgments
5290 Guix is based on the Nix package manager, which was designed and
5291 implemented by Eelco Dolstra, with contributions from other people (see
5292 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
5293 management, and promoted unprecedented features, such as transactional
5294 package upgrades and rollbacks, per-user profiles, and referentially
5295 transparent build processes. Without this work, Guix would not exist.
5297 The Nix-based software distributions, Nixpkgs and NixOS, have also been
5298 an inspiration for Guix.
5300 GNU@tie{}Guix itself is a collective work with contributions from a
5301 number of people. See the @file{AUTHORS} file in Guix for more
5302 information on these fine people. The @file{THANKS} file lists people
5303 who have helped by reporting bugs, taking care of the infrastructure,
5304 providing artwork and themes, making suggestions, and more---thank you!
5307 @c *********************************************************************
5308 @node GNU Free Documentation License
5309 @appendix GNU Free Documentation License
5311 @include fdl-1.3.texi
5313 @c *********************************************************************
5315 @unnumbered Concept Index
5318 @node Programming Index
5319 @unnumbered Programming Index
5327 @c ispell-local-dictionary: "american";