6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
14 Copyright @copyright{} 2013, 2014 Andreas Enge@*
15 Copyright @copyright{} 2013 Nikita Karetnikov
17 Permission is granted to copy, distribute and/or modify this document
18 under the terms of the GNU Free Documentation License, Version 1.3 or
19 any later version published by the Free Software Foundation; with no
20 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
21 copy of the license is included in the section entitled ``GNU Free
22 Documentation License''.
25 @dircategory Package management
27 * guix: (guix). Guix, the functional package manager.
28 * guix package: (guix)Invoking guix package
29 Managing packages with Guix.
30 * guix build: (guix)Invoking guix build
31 Building packages with Guix.
32 * guix system: (guix)Invoking guix system
33 Managing the operating system configuration.
36 @dircategory Software development
38 * guix environment: (guix)Invoking guix environment
39 Building development environments with Guix.
43 @title GNU Guix Reference Manual
44 @subtitle Using the GNU Guix Functional Package Manager
45 @author Ludovic Courtès
47 @author Nikita Karetnikov
50 @vskip 0pt plus 1filll
51 Edition @value{EDITION} @*
59 @c *********************************************************************
63 This document describes GNU Guix version @value{VERSION}, a functional
64 package management tool written for the GNU system.
67 * Introduction:: What is Guix about?
68 * Installation:: Installing Guix.
69 * Package Management:: Package installation, upgrade, etc.
70 * Programming Interface:: Using Guix in Scheme.
71 * Utilities:: Package management commands.
72 * GNU Distribution:: Software for your friendly GNU system.
73 * Contributing:: Your help needed!
75 * Acknowledgments:: Thanks!
76 * GNU Free Documentation License:: The license of this manual.
77 * Concept Index:: Concepts.
78 * Programming Index:: Data types, functions, and variables.
81 --- The Detailed Node Listing ---
85 * Binary Installation:: Getting Guix running in no time!
86 * Requirements:: Software needed to build and run Guix.
87 * Running the Test Suite:: Testing Guix.
88 * Setting Up the Daemon:: Preparing the build daemon's environment.
89 * Invoking guix-daemon:: Running the build daemon.
93 * Build Environment Setup:: Preparing the isolated build environment.
94 * Daemon Offload Setup:: Offloading builds to remote machines.
98 * Features:: How Guix will make your life brighter.
99 * Invoking guix package:: Package installation, removal, etc.
100 * Emacs Interface:: Package management from Emacs.
101 * Substitutes:: Downloading pre-built binaries.
102 * Packages with Multiple Outputs:: Single source package, multiple outputs.
103 * Invoking guix gc:: Running the garbage collector.
104 * Invoking guix pull:: Fetching the latest Guix and distribution.
105 * Invoking guix archive:: Exporting and importing store files.
107 Programming Interface
109 * Defining Packages:: Defining new packages.
110 * Build Systems:: Specifying how packages are built.
111 * The Store:: Manipulating the package store.
112 * Derivations:: Low-level interface to package derivations.
113 * The Store Monad:: Purely functional interface to the store.
114 * G-Expressions:: Manipulating build expressions.
118 * Invoking guix build:: Building packages from the command line.
119 * Invoking guix download:: Downloading a file and printing its hash.
120 * Invoking guix hash:: Computing the cryptographic hash of a file.
121 * Invoking guix import:: Importing package definitions.
122 * Invoking guix refresh:: Updating package definitions.
123 * Invoking guix lint:: Finding errors in package definitions.
124 * Invoking guix environment:: Setting up development environments.
125 * Invoking guix publish:: Sharing substitutes.
129 * System Installation:: Installing the whole operating system.
130 * System Configuration:: Configuring the operating system.
131 * Installing Debugging Files:: Feeding the debugger.
132 * Security Updates:: Deploying security fixes quickly.
133 * Package Modules:: Packages from the programmer's viewpoint.
134 * Packaging Guidelines:: Growing the distribution.
135 * Bootstrapping:: GNU/Linux built from scratch.
136 * Porting:: Targeting another platform or kernel.
140 * Using the Configuration System:: Customizing your GNU system.
141 * operating-system Reference:: Detail of operating-system declarations.
142 * File Systems:: Configuring file system mounts.
143 * Mapped Devices:: Block device extra processing.
144 * User Accounts:: Specifying user accounts.
145 * Locales:: Language and cultural convention settings.
146 * Services:: Specifying system services.
147 * Setuid Programs:: Programs running with root privileges.
148 * X.509 Certificates:: Authenticating HTTPS servers.
149 * Name Service Switch:: Configuring libc's name service switch.
150 * Initial RAM Disk:: Linux-Libre bootstrapping.
151 * GRUB Configuration:: Configuring the boot loader.
152 * Invoking guix system:: Instantiating a system configuration.
153 * Defining Services:: Adding new service definitions.
157 * Base Services:: Essential system services.
158 * Networking Services:: Network setup, SSH daemon, etc.
159 * X Window:: Graphical display.
160 * Desktop Services:: D-Bus and desktop services.
161 * Database Services:: SQL databases.
162 * Various Services:: Other services.
166 * Software Freedom:: What may go into the distribution.
167 * Package Naming:: What's in a name?
168 * Version Numbers:: When the name is not enough.
169 * Python Modules:: Taming the snake.
170 * Perl Modules:: Little pearls.
171 * Fonts:: Fond of fonts.
176 @c *********************************************************************
178 @chapter Introduction
180 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
181 using the international phonetic alphabet (IPA).} is a functional
182 package management tool for the GNU system. Package management consists
183 of all activities that relate to building packages from sources,
184 honoring their build-time and run-time dependencies,
185 installing packages in user environments, upgrading installed packages
186 to new versions or rolling back to a previous set, removing unused
187 software packages, etc.
189 @cindex functional package management
190 The term @dfn{functional} refers to a specific package management
191 discipline. In Guix, the package build and installation process is seen
192 as a function, in the mathematical sense. That function takes inputs,
193 such as build scripts, a compiler, and libraries, and
194 returns an installed package. As a pure function, its result depends
195 solely on its inputs---for instance, it cannot refer to software or
196 scripts that were not explicitly passed as inputs. A build function
197 always produces the same result when passed a given set of inputs. It
198 cannot alter the system's environment in
199 any way; for instance, it cannot create, modify, or delete files outside
200 of its build and installation directories. This is achieved by running
201 build processes in isolated environments (or @dfn{containers}), where only their
202 explicit inputs are visible.
205 The result of package build functions is @dfn{cached} in the file
206 system, in a special directory called @dfn{the store} (@pxref{The
207 Store}). Each package is installed in a directory of its own, in the
208 store---by default under @file{/gnu/store}. The directory name contains
209 a hash of all the inputs used to build that package; thus, changing an
210 input yields a different directory name.
212 This approach is the foundation of Guix's salient features: support for
213 transactional package upgrade and rollback, per-user installation, and
214 garbage collection of packages (@pxref{Features}).
216 Guix has a command-line interface, which allows users to build, install,
217 upgrade, and remove packages, as well as a Scheme programming interface.
219 @cindex Guix System Distribution
221 Last but not least, Guix is used to build a distribution of the GNU
222 system, with many GNU and non-GNU free software packages. The Guix
223 System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
224 properties of Guix at the system level. With GuixSD, users
225 @emph{declare} all aspects of the operating system configuration, and
226 Guix takes care of instantiating that configuration in a reproducible,
227 stateless fashion. @xref{GNU Distribution}.
229 @c *********************************************************************
231 @chapter Installation
233 GNU Guix is available for download from its website at
234 @url{http://www.gnu.org/software/guix/}. This section describes the
235 software requirements of Guix, as well as how to install it and get
238 Note that this section is concerned with the installation of the package
239 manager, which can be done on top of a running GNU/Linux system. If,
240 instead, you want to install the complete GNU operating system,
241 @pxref{System Installation}.
244 * Binary Installation:: Getting Guix running in no time!
245 * Requirements:: Software needed to build and run Guix.
246 * Running the Test Suite:: Testing Guix.
247 * Setting Up the Daemon:: Preparing the build daemon's environment.
248 * Invoking guix-daemon:: Running the build daemon.
251 @node Binary Installation
252 @section Binary Installation
254 This section describes how to install Guix on an arbitrary system from a
255 self-contained tarball providing binaries for Guix and for all its
256 dependencies. This is often quicker than installing from source, which
257 is described in the next sections. The only requirement is to have
260 Installing goes along these lines:
264 Download the binary tarball from
265 @indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
266 usual, make sure to download the associated @file{.sig} file and to
267 verify the authenticity of the tarball against it!}, where @var{system}
268 is @code{x86_64-linux} for an @code{x86_64} machine already running the
269 kernel Linux, and so on.
276 # tar --skip-old-files -xf \
277 guix-binary-@value{VERSION}.@var{system}.tar.xz
280 This creates @file{/gnu/store} (@pxref{The Store}), @file{/var/guix},
281 and @file{/root/.guix-profile}. @file{/root/.guix-profile} is a
282 ready-to-use profile for @code{root} where Guix is installed.
283 @c '--skip-old-files' does the right thing with tar 1.28. The manual
284 @c does not clearly document the behavior we describe here, though.
285 The @code{--skip-old-files} option allows you to make sure the owner and
286 permissions on @file{/var} and @file{/root} are preserved (@pxref{Option
287 Summary, @code{--skip-old-files},, tar, GNU tar: an archiver tool}).
289 Do @emph{not} unpack the tarball on a working Guix system since that
290 would overwrite its own essential files.
296 # /root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
300 Make the @command{guix} command available to other users on the machine,
304 # mkdir -p /usr/local/bin
306 # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
310 To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
314 # guix archive --authorize < /root/.guix-profile/share/guix/hydra.gnu.org.pub
320 The @code{guix} package must remain available in @code{root}'s
321 profile, or it would become subject to garbage collection---in which
322 case you would find yourself badly handicapped by the lack of the
323 @command{guix} command.
325 The tarball in question can be (re)produced and verified simply by
326 running the following command in the Guix source tree:
329 make guix-binary.@var{system}.tar.xz
334 @section Requirements
336 This section lists requirements when building Guix from source. The
337 build procedure for Guix is the same as for other GNU software, and is
338 not covered here. Please see the files @file{README} and @file{INSTALL}
339 in the Guix source tree for additional details.
341 GNU Guix depends on the following packages:
344 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
345 @item @url{http://gnupg.org/, GNU libgcrypt};
346 @item @url{http://www.gnu.org/software/make/, GNU Make}.
349 The following dependencies are optional:
354 @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
355 allow you to use the @command{guix import pypi} command (@pxref{Invoking
356 guix import}). It is of
357 interest primarily for developers and not for casual users.
359 Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
360 allow you to access @code{https} URLs with the @command{guix download}
361 command (@pxref{Invoking guix download}), the @command{guix import pypi}
362 command, and the @command{guix import cpan} command. This is primarily
363 of interest to developers. @xref{Guile Preparations, how to install the
364 GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
367 Unless @code{--disable-daemon} was passed to @command{configure}, the
368 following packages are also needed:
371 @item @url{http://sqlite.org, SQLite 3};
372 @item @url{http://www.bzip.org, libbz2};
373 @item @url{http://gcc.gnu.org, GCC's g++}, with support for the
377 When a working installation of @url{http://nixos.org/nix/, the Nix package
378 manager} is available, you
379 can instead configure Guix with @code{--disable-daemon}. In that case,
380 Nix replaces the three dependencies above.
382 Guix is compatible with Nix, so it is possible to share the same store
383 between both. To do so, you must pass @command{configure} not only the
384 same @code{--with-store-dir} value, but also the same
385 @code{--localstatedir} value. The latter is essential because it
386 specifies where the database that stores metadata about the store is
387 located, among other things. The default values for Nix are
388 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
389 Note that @code{--disable-daemon} is not required if
390 your goal is to share the store with Nix.
392 @node Running the Test Suite
393 @section Running the Test Suite
395 After a successful @command{configure} and @code{make} run, it is a good
396 idea to run the test suite. It can help catch issues with the setup or
397 environment, or bugs in Guix itself---and really, reporting test
398 failures is a good way to help improve the software. To run the test
405 Test cases can run in parallel: you can use the @code{-j} option of
406 GNU@tie{}make to speed things up. The first run may take a few minutes
407 on a recent machine; subsequent runs will be faster because the store
408 that is created for test purposes will already have various things in
411 Upon failure, please email @email{bug-guix@@gnu.org} and attach the
412 @file{test-suite.log} file. When @file{tests/@var{something}.scm}
413 fails, please also attach the @file{@var{something}.log} file available
414 in the top-level build directory. Please specify the Guix version being
415 used as well as version numbers of the dependencies
416 (@pxref{Requirements}) in your message.
418 @node Setting Up the Daemon
419 @section Setting Up the Daemon
422 Operations such as building a package or running the garbage collector
423 are all performed by a specialized process, the @dfn{build daemon}, on
424 behalf of clients. Only the daemon may access the store and its
425 associated database. Thus, any operation that manipulates the store
426 goes through the daemon. For instance, command-line tools such as
427 @command{guix package} and @command{guix build} communicate with the
428 daemon (@i{via} remote procedure calls) to instruct it what to do.
430 The following sections explain how to prepare the build daemon's
431 environment. Also @ref{Substitutes}, for information on how to allow
432 the daemon to download pre-built binaries.
435 * Build Environment Setup:: Preparing the isolated build environment.
436 * Daemon Offload Setup:: Offloading builds to remote machines.
439 @node Build Environment Setup
440 @subsection Build Environment Setup
442 In a standard multi-user setup, Guix and its daemon---the
443 @command{guix-daemon} program---are installed by the system
444 administrator; @file{/gnu/store} is owned by @code{root} and
445 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
446 Guix tools to build packages or otherwise access the store, and the
447 daemon will do it on their behalf, ensuring that the store is kept in a
448 consistent state, and allowing built packages to be shared among users.
451 When @command{guix-daemon} runs as @code{root}, you may not want package
452 build processes themselves to run as @code{root} too, for obvious
453 security reasons. To avoid that, a special pool of @dfn{build users}
454 should be created for use by build processes started by the daemon.
455 These build users need not have a shell and a home directory: they will
456 just be used when the daemon drops @code{root} privileges in build
457 processes. Having several such users allows the daemon to launch
458 distinct build processes under separate UIDs, which guarantees that they
459 do not interfere with each other---an essential feature since builds are
460 regarded as pure functions (@pxref{Introduction}).
462 On a GNU/Linux system, a build user pool may be created like this (using
463 Bash syntax and the @code{shadow} commands):
465 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
466 @c for why `-G' is needed.
468 # groupadd --system guixbuild
469 # for i in `seq -w 1 10`;
471 useradd -g guixbuild -G guixbuild \
472 -d /var/empty -s `which nologin` \
473 -c "Guix build user $i" --system \
479 The @code{guix-daemon} program may then be run as @code{root} with:
482 # guix-daemon --build-users-group=guixbuild
487 This way, the daemon starts build processes in a chroot, under one of
488 the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
489 environment contains nothing but:
491 @c Keep this list in sync with libstore/build.cc! -----------------------
494 a minimal @code{/dev} directory, created mostly independently from the
495 host @code{/dev}@footnote{``Mostly'', because while the set of files
496 that appear in the chroot's @code{/dev} is fixed, most of these files
497 can only be created if the host has them.};
500 the @code{/proc} directory; it only shows the container's processes
501 since a separate PID name space is used;
504 @file{/etc/passwd} with an entry for the current user and an entry for
508 @file{/etc/group} with an entry for the user's group;
511 @file{/etc/hosts} with an entry that maps @code{localhost} to
515 a writable @file{/tmp} directory.
518 If you are installing Guix as an unprivileged user, it is still
519 possible to run @command{guix-daemon}. However, build processes will
520 not be isolated from one another, and not from the rest of the system.
521 Thus, build processes may interfere with each other, and may access
522 programs, libraries, and other files available on the system---making it
523 much harder to view them as @emph{pure} functions.
526 @node Daemon Offload Setup
527 @subsection Using the Offload Facility
531 When desired, the build daemon can @dfn{offload}
532 derivation builds to other machines
533 running Guix, using the @code{offload} @dfn{build hook}. When that
534 feature is enabled, a list of user-specified build machines is read from
535 @file{/etc/guix/machines.scm}; anytime a build is requested, for
536 instance via @code{guix build}, the daemon attempts to offload it to one
537 of the machines that satisfies the derivation's constraints, in
538 particular its system type---e.g., @file{x86_64-linux}. Missing
539 prerequisites for the build are copied over SSH to the target machine,
540 which then proceeds with the build; upon success the output(s) of the
541 build are copied back to the initial machine.
543 The @file{/etc/guix/machines.scm} file typically looks like this:
547 (name "eightysix.example.org")
548 (system "x86_64-linux")
550 (speed 2.)) ; incredibly fast!
553 (name "meeps.example.org")
554 (system "mips64el-linux")
557 (string-append (getenv "HOME")
558 "/.ssh/id-rsa-for-guix"))))
562 In the example above we specify a list of two build machines, one for
563 the @code{x86_64} architecture and one for the @code{mips64el}
566 In fact, this file is---not surprisingly!---a Scheme file that is
567 evaluated when the @code{offload} hook is started. Its return value
568 must be a list of @code{build-machine} objects. While this example
569 shows a fixed list of build machines, one could imagine, say, using
570 DNS-SD to return a list of potential build machines discovered in the
571 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
572 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
575 @deftp {Data Type} build-machine
576 This data type represents build machines the daemon may offload builds
577 to. The important fields are:
582 The remote machine's host name.
585 The remote machine's system type---e.g., @code{"x86_64-linux"}.
588 The user account to use when connecting to the remote machine over SSH.
589 Note that the SSH key pair must @emph{not} be passphrase-protected, to
590 allow non-interactive logins.
594 A number of optional fields may be specified:
599 Port number of the machine's SSH server (default: 22).
602 The SSH private key file to use when connecting to the machine.
604 @item parallel-builds
605 The number of builds that may run in parallel on the machine (1 by
609 A ``relative speed factor''. The offload scheduler will tend to prefer
610 machines with a higher speed factor.
613 A list of strings denoting specific features supported by the machine.
614 An example is @code{"kvm"} for machines that have the KVM Linux modules
615 and corresponding hardware support. Derivations can request features by
616 name, and they will be scheduled on matching build machines.
621 The @code{guix} command must be in the search path on the build
622 machines, since offloading works by invoking the @code{guix archive} and
623 @code{guix build} commands.
625 There's one last thing to do once @file{machines.scm} is in place. As
626 explained above, when offloading, files are transferred back and forth
627 between the machine stores. For this to work, you need to generate a
628 key pair to allow the daemon to export signed archives of files from the
629 store (@pxref{Invoking guix archive}):
632 # guix archive --generate-key
636 Thus, when receiving files, a machine's build daemon can make sure they
637 are genuine, have not been tampered with, and that they are signed by an
641 @node Invoking guix-daemon
642 @section Invoking @command{guix-daemon}
644 The @command{guix-daemon} program implements all the functionality to
645 access the store. This includes launching build processes, running the
646 garbage collector, querying the availability of a build result, etc. It
647 is normally run as @code{root} like this:
650 # guix-daemon --build-users-group=guixbuild
654 For details on how to set it up, @pxref{Setting Up the Daemon}.
657 @cindex container, build environment
658 @cindex build environment
659 @cindex reproducible builds
660 By default, @command{guix-daemon} launches build processes under
661 different UIDs, taken from the build group specified with
662 @code{--build-users-group}. In addition, each build process is run in a
663 chroot environment that only contains the subset of the store that the
664 build process depends on, as specified by its derivation
665 (@pxref{Programming Interface, derivation}), plus a set of specific
666 system directories. By default, the latter contains @file{/dev} and
667 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
668 @dfn{container}: in addition to having its own file system tree, it has
669 a separate mount name space, its own PID name space, network name space,
670 etc. This helps achieve reproducible builds (@pxref{Features}).
672 When the daemon performs a build on behalf of the user, it creates a
673 build directory under @file{/tmp} or under the directory specified by
674 its @code{TMPDIR} environment variable; this directory is shared with
675 the container for the duration of the build. Be aware that using a
676 directory other than @file{/tmp} can affect build results---for example,
677 with a longer directory name, a build process that uses Unix-domain
678 sockets might hit the name length limitation for @code{sun_path}, which
679 it would otherwise not hit.
681 The build directory is automatically deleted upon completion, unless the
682 build failed and the client specified @option{--keep-failed}
683 (@pxref{Invoking guix build, @option{--keep-failed}}).
685 The following command-line options are supported:
688 @item --build-users-group=@var{group}
689 Take users from @var{group} to run build processes (@pxref{Setting Up
690 the Daemon, build users}).
692 @item --no-substitutes
694 Do not use substitutes for build products. That is, always build things
695 locally instead of allowing downloads of pre-built binaries
696 (@pxref{Substitutes}).
698 By default substitutes are used, unless the client---such as the
699 @command{guix package} command---is explicitly invoked with
700 @code{--no-substitutes}.
702 When the daemon runs with @code{--no-substitutes}, clients can still
703 explicitly enable substitution @i{via} the @code{set-build-options}
704 remote procedure call (@pxref{The Store}).
706 @item --substitute-urls=@var{urls}
707 Consider @var{urls} the default whitespace-separated list of substitute
708 source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
711 This means that substitutes may be downloaded from @var{urls}, as long
712 as they are signed by a trusted signature (@pxref{Substitutes}).
715 @item --no-build-hook
716 Do not use the @dfn{build hook}.
718 The build hook is a helper program that the daemon can start and to
719 which it submits build requests. This mechanism is used to offload
720 builds to other machines (@pxref{Daemon Offload Setup}).
722 @item --cache-failures
723 Cache build failures. By default, only successful builds are cached.
725 @item --cores=@var{n}
727 Use @var{n} CPU cores to build each derivation; @code{0} means as many
730 The default value is @code{0}, but it may be overridden by clients, such
731 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
734 The effect is to define the @code{NIX_BUILD_CORES} environment variable
735 in the build process, which can then use it to exploit internal
736 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
738 @item --max-jobs=@var{n}
740 Allow at most @var{n} build jobs in parallel. The default value is
741 @code{1}. Setting it to @code{0} means that no builds will be performed
742 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
743 Setup}), or simply fail.
746 Produce debugging output.
748 This is useful to debug daemon start-up issues, but then it may be
749 overridden by clients, for example the @code{--verbosity} option of
750 @command{guix build} (@pxref{Invoking guix build}).
752 @item --chroot-directory=@var{dir}
753 Add @var{dir} to the build chroot.
755 Doing this may change the result of build processes---for instance if
756 they use optional dependencies found in @var{dir} when it is available,
757 and not otherwise. For that reason, it is not recommended to do so.
758 Instead, make sure that each derivation declares all the inputs that it
761 @item --disable-chroot
762 Disable chroot builds.
764 Using this option is not recommended since, again, it would allow build
765 processes to gain access to undeclared dependencies.
767 @item --disable-log-compression
768 Disable compression of the build logs.
770 Unless @code{--lose-logs} is used, all the build logs are kept in the
771 @var{localstatedir}. To save space, the daemon automatically compresses
772 them with bzip2 by default. This option disables that.
774 @item --disable-deduplication
775 @cindex deduplication
776 Disable automatic file ``deduplication'' in the store.
778 By default, files added to the store are automatically ``deduplicated'':
779 if a newly added file is identical to another one found in the store,
780 the daemon makes the new file a hard link to the other file. This can
781 noticeably reduce disk usage, at the expense of slightly increasde
782 input/output load at the end of a build process. This option disables
785 @item --gc-keep-outputs[=yes|no]
786 Tell whether the garbage collector (GC) must keep outputs of live
789 When set to ``yes'', the GC will keep the outputs of any live derivation
790 available in the store---the @code{.drv} files. The default is ``no'',
791 meaning that derivation outputs are kept only if they are GC roots.
793 @item --gc-keep-derivations[=yes|no]
794 Tell whether the garbage collector (GC) must keep derivations
795 corresponding to live outputs.
797 When set to ``yes'', as is the case by default, the GC keeps
798 derivations---i.e., @code{.drv} files---as long as at least one of their
799 outputs is live. This allows users to keep track of the origins of
800 items in their store. Setting it to ``no'' saves a bit of disk space.
802 Note that when both @code{--gc-keep-derivations} and
803 @code{--gc-keep-outputs} are used, the effect is to keep all the build
804 prerequisites (the sources, compiler, libraries, and other build-time
805 tools) of live objects in the store, regardless of whether these
806 prerequisites are live. This is convenient for developers since it
807 saves rebuilds or downloads.
809 @item --impersonate-linux-2.6
810 On Linux-based systems, impersonate Linux 2.6. This means that the
811 kernel's @code{uname} system call will report 2.6 as the release number.
813 This might be helpful to build programs that (usually wrongfully) depend
814 on the kernel version number.
817 Do not keep build logs. By default they are kept under
818 @code{@var{localstatedir}/guix/log}.
820 @item --system=@var{system}
821 Assume @var{system} as the current system type. By default it is the
822 architecture/kernel pair found at configure time, such as
825 @item --listen=@var{socket}
826 Listen for connections on @var{socket}, the file name of a Unix-domain
827 socket. The default socket is
828 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
829 useful in exceptional circumstances, such as if you need to run several
830 daemons on the same machine.
834 @c *********************************************************************
835 @node Package Management
836 @chapter Package Management
838 The purpose of GNU Guix is to allow users to easily install, upgrade, and
839 remove software packages, without having to know about their build
840 procedure or dependencies. Guix also goes beyond this obvious set of
843 This chapter describes the main features of Guix, as well as the package
844 management tools it provides. Two user interfaces are provided for
845 routine package management tasks: a command-line interface
846 (@pxref{Invoking guix package, @code{guix package}}), and a visual user
847 interface in Emacs (@pxref{Emacs Interface}).
850 * Features:: How Guix will make your life brighter.
851 * Invoking guix package:: Package installation, removal, etc.
852 * Emacs Interface:: Package management from Emacs.
853 * Substitutes:: Downloading pre-built binaries.
854 * Packages with Multiple Outputs:: Single source package, multiple outputs.
855 * Invoking guix gc:: Running the garbage collector.
856 * Invoking guix pull:: Fetching the latest Guix and distribution.
857 * Invoking guix archive:: Exporting and importing store files.
863 When using Guix, each package ends up in the @dfn{package store}, in its
864 own directory---something that resembles
865 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
866 (note that Guix comes with an Emacs extension to shorten those file
867 names, @pxref{Emacs Prettify}.)
869 Instead of referring to these directories, users have their own
870 @dfn{profile}, which points to the packages that they actually want to
871 use. These profiles are stored within each user's home directory, at
872 @code{$HOME/.guix-profile}.
874 For example, @code{alice} installs GCC 4.7.2. As a result,
875 @file{/home/alice/.guix-profile/bin/gcc} points to
876 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
877 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
878 simply continues to point to
879 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
880 coexist on the same system without any interference.
882 The @command{guix package} command is the central tool to manage
883 packages (@pxref{Invoking guix package}). It operates on those per-user
884 profiles, and can be used @emph{with normal user privileges}.
886 The command provides the obvious install, remove, and upgrade
887 operations. Each invocation is actually a @emph{transaction}: either
888 the specified operation succeeds, or nothing happens. Thus, if the
889 @command{guix package} process is terminated during the transaction,
890 or if a power outage occurs during the transaction, then the user's
891 profile remains in its previous state, and remains usable.
893 In addition, any package transaction may be @emph{rolled back}. So, if,
894 for example, an upgrade installs a new version of a package that turns
895 out to have a serious bug, users may roll back to the previous instance
896 of their profile, which was known to work well. Similarly, the global
897 system configuration is subject to transactional upgrades and roll-back
898 (@pxref{Using the Configuration System}).
900 All those packages in the package store may be @emph{garbage-collected}.
901 Guix can determine which packages are still referenced by the user
902 profiles, and remove those that are provably no longer referenced
903 (@pxref{Invoking guix gc}). Users may also explicitly remove old
904 generations of their profile so that the packages they refer to can be
907 @cindex reproducibility
908 @cindex reproducible builds
909 Finally, Guix takes a @dfn{purely functional} approach to package
910 management, as described in the introduction (@pxref{Introduction}).
911 Each @file{/gnu/store} package directory name contains a hash of all the
912 inputs that were used to build that package---compiler, libraries, build
913 scripts, etc. This direct correspondence allows users to make sure a
914 given package installation matches the current state of their
915 distribution. It also helps maximize @dfn{build reproducibility}:
916 thanks to the isolated build environments that are used, a given build
917 is likely to yield bit-identical files when performed on different
918 machines (@pxref{Invoking guix-daemon, container}).
921 This foundation allows Guix to support @dfn{transparent binary/source
922 deployment}. When a pre-built binary for a @file{/gnu/store} item is
923 available from an external source---a @dfn{substitute}, Guix just
924 downloads it and unpacks it;
925 otherwise, it builds the package from source, locally
926 (@pxref{Substitutes}).
928 Control over the build environment is a feature that is also useful for
929 developers. The @command{guix environment} command allows developers of
930 a package to quickly set up the right development environment for their
931 package, without having to manually install the package's dependencies
932 in their profile (@pxref{Invoking guix environment}).
934 @node Invoking guix package
935 @section Invoking @command{guix package}
937 The @command{guix package} command is the tool that allows users to
938 install, upgrade, and remove packages, as well as rolling back to
939 previous configurations. It operates only on the user's own profile,
940 and works with normal user privileges (@pxref{Features}). Its syntax
944 guix package @var{options}
947 Primarily, @var{options} specifies the operations to be performed during
948 the transaction. Upon completion, a new profile is created, but
949 previous generations of the profile remain available, should the user
952 For example, to remove @code{lua} and install @code{guile} and
953 @code{guile-cairo} in a single transaction:
956 guix package -r lua -i guile guile-cairo
959 For each user, a symlink to the user's default profile is automatically
960 created in @file{$HOME/.guix-profile}. This symlink always points to the
961 current generation of the user's default profile. Thus, users can add
962 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
965 If you are not using the Guix System Distribution, consider adding the
966 following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
967 Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
968 shells get all the right environment variable definitions:
971 GUIX_PROFILE="$HOME/.guix-profile" \
972 source "$HOME/.guix-profile/etc/profile"
975 In a multi-user setup, user profiles are stored in a place registered as
976 a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
977 to (@pxref{Invoking guix gc}). That directory is normally
978 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
979 @var{localstatedir} is the value passed to @code{configure} as
980 @code{--localstatedir}, and @var{user} is the user name. The
981 @file{per-user} directory is created when @command{guix-daemon} is
982 started, and the @var{user} sub-directory is created by @command{guix
985 The @var{options} can be among the following:
989 @item --install=@var{package} @dots{}
990 @itemx -i @var{package} @dots{}
991 Install the specified @var{package}s.
993 Each @var{package} may specify either a simple package name, such as
994 @code{guile}, or a package name followed by a hyphen and version number,
995 such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
996 case, the newest version prefixed by @code{1.8} is selected.)
998 If no version number is specified, the
999 newest available version will be selected. In addition, @var{package}
1000 may contain a colon, followed by the name of one of the outputs of the
1001 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
1002 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
1003 name (and optionally version) are searched for among the GNU
1004 distribution modules (@pxref{Package Modules}).
1006 @cindex propagated inputs
1007 Sometimes packages have @dfn{propagated inputs}: these are dependencies
1008 that automatically get installed along with the required package.
1010 An example is the GNU MPC library: its C header files refer to those of
1011 the GNU MPFR library, which in turn refer to those of the GMP library.
1012 Thus, when installing MPC, the MPFR and GMP libraries also get installed
1013 in the profile; removing MPC also removes MPFR and GMP---unless they had
1014 also been explicitly installed independently.
1016 Besides, packages sometimes rely on the definition of environment
1017 variables for their search paths (see explanation of
1018 @code{--search-paths} below). Any missing or possibly incorrect
1019 environment variable definitions are reported here.
1021 @c XXX: keep me up-to-date
1022 Finally, when installing a GNU package, the tool reports the
1023 availability of a newer upstream version. In the future, it may provide
1024 the option of installing directly from the upstream version, even if
1025 that version is not yet in the distribution.
1027 @item --install-from-expression=@var{exp}
1029 Install the package @var{exp} evaluates to.
1031 @var{exp} must be a Scheme expression that evaluates to a
1032 @code{<package>} object. This option is notably useful to disambiguate
1033 between same-named variants of a package, with expressions such as
1034 @code{(@@ (gnu packages base) guile-final)}.
1036 Note that this option installs the first output of the specified
1037 package, which may be insufficient when needing a specific output of a
1038 multiple-output package.
1040 @item --remove=@var{package} @dots{}
1041 @itemx -r @var{package} @dots{}
1042 Remove the specified @var{package}s.
1044 As for @code{--install}, each @var{package} may specify a version number
1045 and/or output name in addition to the package name. For instance,
1046 @code{-r glibc:debug} would remove the @code{debug} output of
1049 @item --upgrade[=@var{regexp} @dots{}]
1050 @itemx -u [@var{regexp} @dots{}]
1051 Upgrade all the installed packages. If one or more @var{regexp}s are
1052 specified, upgrade only installed packages whose name matches a
1053 @var{regexp}. Also see the @code{--do-not-upgrade} option below.
1055 Note that this upgrades package to the latest version of packages found
1056 in the distribution currently installed. To update your distribution,
1057 you should regularly run @command{guix pull} (@pxref{Invoking guix
1060 @item --do-not-upgrade[=@var{regexp} @dots{}]
1061 When used together with the @code{--upgrade} option, do @emph{not}
1062 upgrade any packages whose name matches a @var{regexp}. For example, to
1063 upgrade all packages in the current profile except those containing the
1064 substring ``emacs'':
1067 $ guix package --upgrade . --do-not-upgrade emacs
1071 Roll back to the previous @dfn{generation} of the profile---i.e., undo
1072 the last transaction.
1074 When combined with options such as @code{--install}, roll back occurs
1075 before any other actions.
1077 When rolling back from the first generation that actually contains
1078 installed packages, the profile is made to point to the @dfn{zeroth
1079 generation}, which contains no files apart from its own meta-data.
1081 Installing, removing, or upgrading packages from a generation that has
1082 been rolled back to overwrites previous future generations. Thus, the
1083 history of a profile's generations is always linear.
1085 @item --switch-generation=@var{pattern}
1086 @itemx -S @var{pattern}
1087 Switch to a particular generation defined by @var{pattern}.
1089 @var{pattern} may be either a generation number or a number prefixed
1090 with ``+'' or ``-''. The latter means: move forward/backward by a
1091 specified number of generations. For example, if you want to return to
1092 the latest generation after @code{--roll-back}, use
1093 @code{--switch-generation=+1}.
1095 The difference between @code{--roll-back} and
1096 @code{--switch-generation=-1} is that @code{--switch-generation} will
1097 not make a zeroth generation, so if a specified generation does not
1098 exist, the current generation will not be changed.
1100 @item --search-paths
1101 @cindex search paths
1102 Report environment variable definitions, in Bash syntax, that may be
1103 needed in order to use the set of installed packages. These environment
1104 variables are used to specify @dfn{search paths} for files used by some
1105 of the installed packages.
1107 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
1108 environment variables to be defined so it can look for headers and
1109 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
1110 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
1111 library are installed in the profile, then @code{--search-paths} will
1112 suggest setting these variables to @code{@var{profile}/include} and
1113 @code{@var{profile}/lib}, respectively.
1115 @item --profile=@var{profile}
1116 @itemx -p @var{profile}
1117 Use @var{profile} instead of the user's default profile.
1120 Produce verbose output. In particular, emit the environment's build log
1121 on the standard error port.
1124 Use the bootstrap Guile to build the profile. This option is only
1125 useful to distribution developers.
1129 In addition to these actions @command{guix package} supports the
1130 following options to query the current state of a profile, or the
1131 availability of packages:
1135 @item --search=@var{regexp}
1136 @itemx -s @var{regexp}
1137 List the available packages whose name, synopsis, or description matches
1138 @var{regexp}. Print all the meta-data of matching packages in
1139 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
1140 GNU recutils manual}).
1142 This allows specific fields to be extracted using the @command{recsel}
1143 command, for instance:
1146 $ guix package -s malloc | recsel -p name,version
1154 Similarly, to show the name of all the packages available under the
1155 terms of the GNU@tie{}LGPL version 3:
1158 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
1165 @item --show=@var{package}
1166 Show details about @var{package}, taken from the list of available packages, in
1167 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
1171 $ guix package --show=python | recsel -p name,version
1179 You may also specify the full name of a package to only get details about a
1180 specific version of it:
1182 $ guix package --show=python-3.3.5 | recsel -p name,version
1189 @item --list-installed[=@var{regexp}]
1190 @itemx -I [@var{regexp}]
1191 List the currently installed packages in the specified profile, with the
1192 most recently installed packages shown last. When @var{regexp} is
1193 specified, list only installed packages whose name matches @var{regexp}.
1195 For each installed package, print the following items, separated by
1196 tabs: the package name, its version string, the part of the package that
1197 is installed (for instance, @code{out} for the default output,
1198 @code{include} for its headers, etc.), and the path of this package in
1201 @item --list-available[=@var{regexp}]
1202 @itemx -A [@var{regexp}]
1203 List packages currently available in the distribution for this system
1204 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
1205 installed packages whose name matches @var{regexp}.
1207 For each package, print the following items separated by tabs: its name,
1208 its version string, the parts of the package (@pxref{Packages with
1209 Multiple Outputs}), and the source location of its definition.
1211 @item --list-generations[=@var{pattern}]
1212 @itemx -l [@var{pattern}]
1213 Return a list of generations along with their creation dates; for each
1214 generation, show the installed packages, with the most recently
1215 installed packages shown last. Note that the zeroth generation is never
1218 For each installed package, print the following items, separated by
1219 tabs: the name of a package, its version string, the part of the package
1220 that is installed (@pxref{Packages with Multiple Outputs}), and the
1221 location of this package in the store.
1223 When @var{pattern} is used, the command returns only matching
1224 generations. Valid patterns include:
1227 @item @emph{Integers and comma-separated integers}. Both patterns denote
1228 generation numbers. For instance, @code{--list-generations=1} returns
1231 And @code{--list-generations=1,8,2} outputs three generations in the
1232 specified order. Neither spaces nor trailing commas are allowed.
1234 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
1235 specified generations and everything in between. Note that the start of
1236 a range must be lesser than its end.
1238 It is also possible to omit the endpoint. For example,
1239 @code{--list-generations=2..}, returns all generations starting from the
1242 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
1243 or months by passing an integer along with the first letter of the
1244 duration. For example, @code{--list-generations=20d} lists generations
1245 that are up to 20 days old.
1248 @item --delete-generations[=@var{pattern}]
1249 @itemx -d [@var{pattern}]
1250 When @var{pattern} is omitted, delete all generations except the current
1253 This command accepts the same patterns as @option{--list-generations}.
1254 When @var{pattern} is specified, delete the matching generations. When
1255 @var{pattern} specifies a duration, generations @emph{older} than the
1256 specified duration match. For instance, @code{--delete-generations=1m}
1257 deletes generations that are more than one month old.
1259 If the current generation matches, it is @emph{not} deleted. Also, the
1260 zeroth generation is never deleted.
1262 Note that deleting generations prevents roll-back to them.
1263 Consequently, this command must be used with care.
1267 Finally, since @command{guix package} may actually start build
1268 processes, it supports all the common build options that @command{guix
1269 build} supports (@pxref{Invoking guix build, common build options}).
1274 @section Substitutes
1277 @cindex pre-built binaries
1278 Guix supports transparent source/binary deployment, which means that it
1279 can either build things locally, or download pre-built items from a
1280 server. We call these pre-built items @dfn{substitutes}---they are
1281 substitutes for local build results. In many cases, downloading a
1282 substitute is much faster than building things locally.
1284 Substitutes can be anything resulting from a derivation build
1285 (@pxref{Derivations}). Of course, in the common case, they are
1286 pre-built package binaries, but source tarballs, for instance, which
1287 also result from derivation builds, can be available as substitutes.
1289 The @code{hydra.gnu.org} server is a front-end to a build farm that
1290 builds packages from the GNU distribution continuously for some
1291 architectures, and makes them available as substitutes. This is the
1292 default source of substitutes; it can be overridden by passing
1293 @command{guix-daemon} the @code{--substitute-urls} option
1294 (@pxref{Invoking guix-daemon}).
1297 @cindex digital signatures
1298 To allow Guix to download substitutes from @code{hydra.gnu.org}, you
1299 must add its public key to the access control list (ACL) of archive
1300 imports, using the @command{guix archive} command (@pxref{Invoking guix
1301 archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
1302 be compromised and to serve genuine substitutes.
1304 This public key is installed along with Guix, in
1305 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
1306 the installation prefix of Guix. If you installed Guix from source,
1307 make sure you checked the GPG signature of
1308 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
1309 Then, you can run something like this:
1312 # guix archive --authorize < hydra.gnu.org.pub
1315 Once this is in place, the output of a command like @code{guix build}
1316 should change from something like:
1319 $ guix build emacs --dry-run
1320 The following derivations would be built:
1321 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
1322 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
1323 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
1324 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
1332 $ guix build emacs --dry-run
1333 The following files would be downloaded:
1334 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
1335 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
1336 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
1337 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
1342 This indicates that substitutes from @code{hydra.gnu.org} are usable and
1343 will be downloaded, when possible, for future builds.
1345 Guix ignores substitutes that are not signed, or that are not signed by
1346 one of the keys listed in the ACL. It also detects and raises an error
1347 when attempting to use a substitute that has been tampered with.
1349 The substitute mechanism can be disabled globally by running
1350 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1351 guix-daemon}). It can also be disabled temporarily by passing the
1352 @code{--no-substitutes} option to @command{guix package}, @command{guix
1353 build}, and other command-line tools.
1356 Today, each individual's control over their own computing is at the
1357 mercy of institutions, corporations, and groups with enough power and
1358 determination to subvert the computing infrastructure and exploit its
1359 weaknesses. While using @code{hydra.gnu.org} substitutes can be
1360 convenient, we encourage users to also build on their own, or even run
1361 their own build farm, such that @code{hydra.gnu.org} is less of an
1362 interesting target. One way to help is by publishing the software you
1363 build using @command{guix publish} so that others have one more choice
1364 of server to download substitutes from (@pxref{Invoking guix publish}).
1366 Guix has the foundations to maximize build reproducibility
1367 (@pxref{Features}). In most cases, independent builds of a given
1368 package or derivation should yield bit-identical results. Thus, through
1369 a diverse set of independent package builds, we can strengthen the
1370 integrity of our systems.
1372 In the future, we want Guix to have support to publish and retrieve
1373 binaries to/from other users, in a peer-to-peer fashion. If you would
1374 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1377 @node Packages with Multiple Outputs
1378 @section Packages with Multiple Outputs
1380 @cindex multiple-output packages
1381 @cindex package outputs
1383 Often, packages defined in Guix have a single @dfn{output}---i.e., the
1384 source package leads exactly one directory in the store. When running
1385 @command{guix package -i glibc}, one installs the default output of the
1386 GNU libc package; the default output is called @code{out}, but its name
1387 can be omitted as shown in this command. In this particular case, the
1388 default output of @code{glibc} contains all the C header files, shared
1389 libraries, static libraries, Info documentation, and other supporting
1392 Sometimes it is more appropriate to separate the various types of files
1393 produced from a single source package into separate outputs. For
1394 instance, the GLib C library (used by GTK+ and related packages)
1395 installs more than 20 MiB of reference documentation as HTML pages.
1396 To save space for users who do not need it, the documentation goes to a
1397 separate output, called @code{doc}. To install the main GLib output,
1398 which contains everything but the documentation, one would run:
1401 guix package -i glib
1404 The command to install its documentation is:
1407 guix package -i glib:doc
1410 Some packages install programs with different ``dependency footprints''.
1411 For instance, the WordNet package install both command-line tools and
1412 graphical user interfaces (GUIs). The former depend solely on the C
1413 library, whereas the latter depend on Tcl/Tk and the underlying X
1414 libraries. In this case, we leave the command-line tools in the default
1415 output, whereas the GUIs are in a separate output. This allows users
1416 who do not need the GUIs to save space.
1418 There are several such multiple-output packages in the GNU distribution.
1419 Other conventional output names include @code{lib} for libraries and
1420 possibly header files, @code{bin} for stand-alone programs, and
1421 @code{debug} for debugging information (@pxref{Installing Debugging
1422 Files}). The outputs of a packages are listed in the third column of
1423 the output of @command{guix package --list-available} (@pxref{Invoking
1427 @node Invoking guix gc
1428 @section Invoking @command{guix gc}
1430 @cindex garbage collector
1431 Packages that are installed but not used may be @dfn{garbage-collected}.
1432 The @command{guix gc} command allows users to explicitly run the garbage
1433 collector to reclaim space from the @file{/gnu/store} directory. It is
1434 the @emph{only} way to remove files from @file{/gnu/store}---removing
1435 files or directories manually may break it beyond repair!
1437 The garbage collector has a set of known @dfn{roots}: any file under
1438 @file{/gnu/store} reachable from a root is considered @dfn{live} and
1439 cannot be deleted; any other file is considered @dfn{dead} and may be
1440 deleted. The set of garbage collector roots includes default user
1441 profiles, and may be augmented with @command{guix build --root}, for
1442 example (@pxref{Invoking guix build}).
1444 Prior to running @code{guix gc --collect-garbage} to make space, it is
1445 often useful to remove old generations from user profiles; that way, old
1446 package builds referenced by those generations can be reclaimed. This
1447 is achieved by running @code{guix package --delete-generations}
1448 (@pxref{Invoking guix package}).
1450 The @command{guix gc} command has three modes of operation: it can be
1451 used to garbage-collect any dead files (the default), to delete specific
1452 files (the @code{--delete} option), or to print garbage-collector
1453 information. The available options are listed below:
1456 @item --collect-garbage[=@var{min}]
1457 @itemx -C [@var{min}]
1458 Collect garbage---i.e., unreachable @file{/gnu/store} files and
1459 sub-directories. This is the default operation when no option is
1462 When @var{min} is given, stop once @var{min} bytes have been collected.
1463 @var{min} may be a number of bytes, or it may include a unit as a
1464 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
1465 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
1467 When @var{min} is omitted, collect all the garbage.
1471 Attempt to delete all the store files and directories specified as
1472 arguments. This fails if some of the files are not in the store, or if
1473 they are still live.
1476 Show the list of dead files and directories still present in the
1477 store---i.e., files and directories no longer reachable from any root.
1480 Show the list of live store files and directories.
1484 In addition, the references among existing store files can be queried:
1490 List the references (respectively, the referrers) of store files given
1495 List the requisites of the store files passed as arguments. Requisites
1496 include the store files themselves, their references, and the references
1497 of these, recursively. In other words, the returned list is the
1498 @dfn{transitive closure} of the store files.
1503 @node Invoking guix pull
1504 @section Invoking @command{guix pull}
1506 Packages are installed or upgraded to the latest version available in
1507 the distribution currently available on your local machine. To update
1508 that distribution, along with the Guix tools, you must run @command{guix
1509 pull}: the command downloads the latest Guix source code and package
1510 descriptions, and deploys it.
1512 On completion, @command{guix package} will use packages and package
1513 versions from this just-retrieved copy of Guix. Not only that, but all
1514 the Guix commands and Scheme modules will also be taken from that latest
1515 version. New @command{guix} sub-commands added by the update also
1518 The @command{guix pull} command is usually invoked with no arguments,
1519 but it supports the following options:
1523 Produce verbose output, writing build logs to the standard error output.
1525 @item --url=@var{url}
1526 Download the source tarball of Guix from @var{url}.
1528 By default, the tarball is taken from its canonical address at
1529 @code{gnu.org}, for the stable branch of Guix.
1532 Use the bootstrap Guile to build the latest Guix. This option is only
1533 useful to Guix developers.
1537 @node Invoking guix archive
1538 @section Invoking @command{guix archive}
1540 The @command{guix archive} command allows users to @dfn{export} files
1541 from the store into a single archive, and to later @dfn{import} them.
1542 In particular, it allows store files to be transferred from one machine
1543 to another machine's store. For example, to transfer the @code{emacs}
1544 package to a machine connected over SSH, one would run:
1547 guix archive --export -r emacs | ssh the-machine guix archive --import
1551 Similarly, a complete user profile may be transferred from one machine
1552 to another like this:
1555 guix archive --export -r $(readlink -f ~/.guix-profile) | \
1556 ssh the-machine guix-archive --import
1560 However, note that, in both examples, all of @code{emacs} and the
1561 profile as well as all of their dependencies are transferred (due to
1562 @code{-r}), regardless of what is already available in the target
1563 machine's store. The @code{--missing} option can help figure out which
1564 items are missing from the target's store.
1566 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1567 comparable in spirit to `tar', but with a few noteworthy differences
1568 that make it more appropriate for our purposes. First, rather than
1569 recording all Unix meta-data for each file, the Nar format only mentions
1570 the file type (regular, directory, or symbolic link); Unix permissions
1571 and owner/group are dismissed. Second, the order in which directory
1572 entries are stored always follows the order of file names according to
1573 the C locale collation order. This makes archive production fully
1576 When exporting, the daemon digitally signs the contents of the archive,
1577 and that digital signature is appended. When importing, the daemon
1578 verifies the signature and rejects the import in case of an invalid
1579 signature or if the signing key is not authorized.
1580 @c FIXME: Add xref to daemon doc about signatures.
1582 The main options are:
1586 Export the specified store files or packages (see below.) Write the
1587 resulting archive to the standard output.
1589 Dependencies are @emph{not} included in the output, unless
1590 @code{--recursive} is passed.
1594 When combined with @code{--export}, this instructs @command{guix
1595 archive} to include dependencies of the given items in the archive.
1596 Thus, the resulting archive is self-contained: it contains the closure
1597 of the exported store items.
1600 Read an archive from the standard input, and import the files listed
1601 therein into the store. Abort if the archive has an invalid digital
1602 signature, or if it is signed by a public key not among the authorized
1603 keys (see @code{--authorize} below.)
1606 Read a list of store file names from the standard input, one per line,
1607 and write on the standard output the subset of these files missing from
1610 @item --generate-key[=@var{parameters}]
1611 @cindex signing, archives
1612 Generate a new key pair for the daemons. This is a prerequisite before
1613 archives can be exported with @code{--export}. Note that this operation
1614 usually takes time, because it needs to gather enough entropy to
1615 generate the key pair.
1617 The generated key pair is typically stored under @file{/etc/guix}, in
1618 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1619 key, which must be kept secret.) When @var{parameters} is omitted,
1620 an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
1621 versions before 1.6.0, it is a 4096-bit RSA key.
1622 Alternately, @var{parameters} can specify
1623 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1624 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1625 Libgcrypt Reference Manual}).
1628 @cindex authorizing, archives
1629 Authorize imports signed by the public key passed on standard input.
1630 The public key must be in ``s-expression advanced format''---i.e., the
1631 same format as the @file{signing-key.pub} file.
1633 The list of authorized keys is kept in the human-editable file
1634 @file{/etc/guix/acl}. The file contains
1635 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1636 s-expressions''} and is structured as an access-control list in the
1637 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1641 To export store files as an archive to the standard output, run:
1644 guix archive --export @var{options} @var{specifications}...
1647 @var{specifications} may be either store file names or package
1648 specifications, as for @command{guix package} (@pxref{Invoking guix
1649 package}). For instance, the following command creates an archive
1650 containing the @code{gui} output of the @code{git} package and the main
1651 output of @code{emacs}:
1654 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
1657 If the specified packages are not built yet, @command{guix archive}
1658 automatically builds them. The build process may be controlled with the
1659 same options that can be passed to the @command{guix build} command
1660 (@pxref{Invoking guix build, common build options}).
1663 @c *********************************************************************
1664 @node Programming Interface
1665 @chapter Programming Interface
1667 GNU Guix provides several Scheme programming interfaces (APIs) to
1668 define, build, and query packages. The first interface allows users to
1669 write high-level package definitions. These definitions refer to
1670 familiar packaging concepts, such as the name and version of a package,
1671 its build system, and its dependencies. These definitions can then be
1672 turned into concrete build actions.
1674 Build actions are performed by the Guix daemon, on behalf of users. In a
1675 standard setup, the daemon has write access to the store---the
1676 @file{/gnu/store} directory---whereas users do not. The recommended
1677 setup also has the daemon perform builds in chroots, under a specific
1678 build users, to minimize interference with the rest of the system.
1681 Lower-level APIs are available to interact with the daemon and the
1682 store. To instruct the daemon to perform a build action, users actually
1683 provide it with a @dfn{derivation}. A derivation is a low-level
1684 representation of the build actions to be taken, and the environment in
1685 which they should occur---derivations are to package definitions what
1686 assembly is to C programs. The term ``derivation'' comes from the fact
1687 that build results @emph{derive} from them.
1689 This chapter describes all these APIs in turn, starting from high-level
1690 package definitions.
1693 * Defining Packages:: Defining new packages.
1694 * Build Systems:: Specifying how packages are built.
1695 * The Store:: Manipulating the package store.
1696 * Derivations:: Low-level interface to package derivations.
1697 * The Store Monad:: Purely functional interface to the store.
1698 * G-Expressions:: Manipulating build expressions.
1701 @node Defining Packages
1702 @section Defining Packages
1704 The high-level interface to package definitions is implemented in the
1705 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1706 example, the package definition, or @dfn{recipe}, for the GNU Hello
1707 package looks like this:
1710 (define-module (gnu packages hello)
1711 #:use-module (guix packages)
1712 #:use-module (guix download)
1713 #:use-module (guix build-system gnu)
1714 #:use-module (guix licenses))
1716 (define-public hello
1722 (uri (string-append "mirror://gnu/hello/hello-" version
1725 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1726 (build-system gnu-build-system)
1727 (arguments `(#:configure-flags '("--enable-silent-rules")))
1728 (inputs `(("gawk" ,gawk)))
1729 (synopsis "Hello, GNU world: An example GNU package")
1730 (description "Guess what GNU Hello prints!")
1731 (home-page "http://www.gnu.org/software/hello/")
1736 Without being a Scheme expert, the reader may have guessed the meaning
1737 of the various fields here. This expression binds variable @code{hello}
1738 to a @code{<package>} object, which is essentially a record
1739 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1740 This package object can be inspected using procedures found in the
1741 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1742 returns---surprise!---@code{"hello"}.
1744 With luck, you may be able to import part or all of the definition of
1745 the package you are interested in from another repository, using the
1746 @code{guix import} command (@pxref{Invoking guix import}).
1748 In the example above, @var{hello} is defined into a module of its own,
1749 @code{(gnu packages hello)}. Technically, this is not strictly
1750 necessary, but it is convenient to do so: all the packages defined in
1751 modules under @code{(gnu packages @dots{})} are automatically known to
1752 the command-line tools (@pxref{Package Modules}).
1754 There are a few points worth noting in the above package definition:
1758 The @code{source} field of the package is an @code{<origin>} object.
1759 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1760 meaning that the source is a file to be downloaded over FTP or HTTP.
1762 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1763 the GNU mirrors defined in @code{(guix download)}.
1765 The @code{sha256} field specifies the expected SHA256 hash of the file
1766 being downloaded. It is mandatory, and allows Guix to check the
1767 integrity of the file. The @code{(base32 @dots{})} form introduces the
1768 base32 representation of the hash. You can obtain this information with
1769 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1770 hash} (@pxref{Invoking guix hash}).
1773 When needed, the @code{origin} form can also have a @code{patches} field
1774 listing patches to be applied, and a @code{snippet} field giving a
1775 Scheme expression to modify the source code.
1778 @cindex GNU Build System
1779 The @code{build-system} field specifies the procedure to build the
1780 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1781 represents the familiar GNU Build System, where packages may be
1782 configured, built, and installed with the usual @code{./configure &&
1783 make && make check && make install} command sequence.
1786 The @code{arguments} field specifies options for the build system
1787 (@pxref{Build Systems}). Here it is interpreted by
1788 @var{gnu-build-system} as a request run @file{configure} with the
1789 @code{--enable-silent-rules} flag.
1792 The @code{inputs} field specifies inputs to the build process---i.e.,
1793 build-time or run-time dependencies of the package. Here, we define an
1794 input called @code{"gawk"} whose value is that of the @var{gawk}
1795 variable; @var{gawk} is itself bound to a @code{<package>} object.
1797 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1798 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1799 of ensuring that they are present (@pxref{Build Systems}).
1801 However, any other dependencies need to be specified in the
1802 @code{inputs} field. Any dependency not specified here will simply be
1803 unavailable to the build process, possibly leading to a build failure.
1806 Once a package definition is in place, the
1807 package may actually be built using the @code{guix build} command-line
1808 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1809 more information on how to test package definitions, and
1810 @ref{Invoking guix lint}, for information on how to check a definition
1811 for style conformance.
1813 Eventually, updating the package definition to a new upstream version
1814 can be partly automated by the @command{guix refresh} command
1815 (@pxref{Invoking guix refresh}).
1817 Behind the scenes, a derivation corresponding to the @code{<package>}
1818 object is first computed by the @code{package-derivation} procedure.
1819 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1820 The build actions it prescribes may then be realized by using the
1821 @code{build-derivations} procedure (@pxref{The Store}).
1823 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1824 Return the @code{<derivation>} object of @var{package} for @var{system}
1825 (@pxref{Derivations}).
1827 @var{package} must be a valid @code{<package>} object, and @var{system}
1828 must be a string denoting the target system type---e.g.,
1829 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1830 must be a connection to the daemon, which operates on the store
1831 (@pxref{The Store}).
1835 @cindex cross-compilation
1836 Similarly, it is possible to compute a derivation that cross-builds a
1837 package for some other system:
1839 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1840 @var{package} @var{target} [@var{system}]
1841 Return the @code{<derivation>} object of @var{package} cross-built from
1842 @var{system} to @var{target}.
1844 @var{target} must be a valid GNU triplet denoting the target hardware
1845 and operating system, such as @code{"mips64el-linux-gnu"}
1846 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1847 Configure and Build System}).
1852 @section Build Systems
1854 @cindex build system
1855 Each package definition specifies a @dfn{build system} and arguments for
1856 that build system (@pxref{Defining Packages}). This @code{build-system}
1857 field represents the build procedure of the package, as well implicit
1858 dependencies of that build procedure.
1860 Build systems are @code{<build-system>} objects. The interface to
1861 create and manipulate them is provided by the @code{(guix build-system)}
1862 module, and actual build systems are exported by specific modules.
1864 @cindex bag (low-level package representation)
1865 Under the hood, build systems first compile package objects to
1866 @dfn{bags}. A @dfn{bag} is like a package, but with less
1867 ornamentation---in other words, a bag is a lower-level representation of
1868 a package, which includes all the inputs of that package, including some
1869 that were implicitly added by the build system. This intermediate
1870 representation is then compiled to a derivation (@pxref{Derivations}).
1872 Build systems accept an optional list of @dfn{arguments}. In package
1873 definitions, these are passed @i{via} the @code{arguments} field
1874 (@pxref{Defining Packages}). They are typically keyword arguments
1875 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
1876 Guile Reference Manual}). The value of these arguments is usually
1877 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
1878 by the daemon (@pxref{Derivations}).
1880 The main build system is @var{gnu-build-system}, which implements the
1881 standard build procedure for GNU packages and many other packages. It
1882 is provided by the @code{(guix build-system gnu)} module.
1884 @defvr {Scheme Variable} gnu-build-system
1885 @var{gnu-build-system} represents the GNU Build System, and variants
1886 thereof (@pxref{Configuration, configuration and makefile conventions,,
1887 standards, GNU Coding Standards}).
1889 @cindex build phases
1890 In a nutshell, packages using it configured, built, and installed with
1891 the usual @code{./configure && make && make check && make install}
1892 command sequence. In practice, a few additional steps are often needed.
1893 All these steps are split up in separate @dfn{phases},
1894 notably@footnote{Please see the @code{(guix build gnu-build-system)}
1895 modules for more details about the build phases.}:
1899 Unpack the source tarball, and change the current directory to the
1900 extracted source tree. If the source is actually a directory, copy it
1901 to the build tree, and enter that directory.
1903 @item patch-source-shebangs
1904 Patch shebangs encountered in source files so they refer to the right
1905 store file names. For instance, this changes @code{#!/bin/sh} to
1906 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
1909 Run the @file{configure} script with a number of default options, such
1910 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
1911 by the @code{#:configure-flags} argument.
1914 Run @code{make} with the list of flags specified with
1915 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
1916 (the default), build with @code{make -j}.
1919 Run @code{make check}, or some other target specified with
1920 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
1921 @code{#:parallel-tests?} argument is true (the default), run @code{make
1925 Run @code{make install} with the flags listed in @code{#:make-flags}.
1927 @item patch-shebangs
1928 Patch shebangs on the installed executable files.
1931 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
1932 is false), copying them to the @code{debug} output when available
1933 (@pxref{Installing Debugging Files}).
1936 @vindex %standard-phases
1937 The build-side module @code{(guix build gnu-build-system)} defines
1938 @var{%standard-phases} as the default list of build phases.
1939 @var{%standard-phases} is a list of symbol/procedure pairs, where the
1940 procedure implements the actual phase.
1942 The list of phases used for a particular package can be changed with the
1943 @code{#:phases} parameter. For instance, passing:
1946 #:phases (alist-delete 'configure %standard-phases)
1949 means that all the phases described above will be used, except the
1950 @code{configure} phase.
1952 In addition, this build system ensures that the ``standard'' environment
1953 for GNU packages is available. This includes tools such as GCC, libc,
1954 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
1955 build-system gnu)} module for a complete list.) We call these the
1956 @dfn{implicit inputs} of a package, because package definitions don't
1957 have to mention them.
1960 Other @code{<build-system>} objects are defined to support other
1961 conventions and tools used by free software packages. They inherit most
1962 of @var{gnu-build-system}, and differ mainly in the set of inputs
1963 implicitly added to the build process, and in the list of phases
1964 executed. Some of these build systems are listed below.
1966 @defvr {Scheme Variable} cmake-build-system
1967 This variable is exported by @code{(guix build-system cmake)}. It
1968 implements the build procedure for packages using the
1969 @url{http://www.cmake.org, CMake build tool}.
1971 It automatically adds the @code{cmake} package to the set of inputs.
1972 Which package is used can be specified with the @code{#:cmake}
1975 The @code{#:configure-flags} parameter is taken as a list of flags
1976 passed to the @command{cmake} command. The @code{#:build-type}
1977 parameter specifies in abstract terms the flags passed to the compiler;
1978 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
1979 debugging information''), which roughly means that code is compiled with
1980 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
1983 @defvr {Scheme Variable} glib-or-gtk-build-system
1984 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
1985 is intended for use with packages making use of GLib or GTK+.
1987 This build system adds the following two phases to the ones defined by
1988 @var{gnu-build-system}:
1991 @item glib-or-gtk-wrap
1992 The phase @code{glib-or-gtk-wrap} ensures that programs found under
1993 @file{bin/} are able to find GLib's ``schemas'' and
1994 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
1995 modules}. This is achieved by wrapping the programs in launch scripts
1996 that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
1997 environment variables.
1999 It is possible to exclude specific package outputs from that wrapping
2000 process by listing their names in the
2001 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
2002 when an output is known not to contain any GLib or GTK+ binaries, and
2003 where wrapping would gratuitously add a dependency of that output on
2006 @item glib-or-gtk-compile-schemas
2007 The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
2008 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
2009 GSettings schemas} are compiled. Compilation is performed by the
2010 @command{glib-compile-schemas} program. It is provided by the package
2011 @code{glib:bin} which is automatically imported by the build system.
2012 The @code{glib} package providing @command{glib-compile-schemas} can be
2013 specified with the @code{#:glib} parameter.
2016 Both phases are executed after the @code{install} phase.
2019 @defvr {Scheme Variable} python-build-system
2020 This variable is exported by @code{(guix build-system python)}. It
2021 implements the more or less standard build procedure used by Python
2022 packages, which consists in running @code{python setup.py build} and
2023 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
2025 For packages that install stand-alone Python programs under @code{bin/},
2026 it takes care of wrapping these programs so their @code{PYTHONPATH}
2027 environment variable points to all the Python libraries they depend on.
2029 Which Python package is used can be specified with the @code{#:python}
2033 @defvr {Scheme Variable} perl-build-system
2034 This variable is exported by @code{(guix build-system perl)}. It
2035 implements the standard build procedure for Perl packages, which either
2036 consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
2037 followed by @code{Build} and @code{Build install}; or in running
2038 @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
2039 @code{make} and @code{make install}; depending on which of
2040 @code{Build.PL} or @code{Makefile.PL} is present in the package
2041 distribution. Preference is given to the former if both @code{Build.PL}
2042 and @code{Makefile.PL} exist in the package distribution. This
2043 preference can be reversed by specifying @code{#t} for the
2044 @code{#:make-maker?} parameter.
2046 The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
2047 passes flags specified by the @code{#:make-maker-flags} or
2048 @code{#:module-build-flags} parameter, respectively.
2050 Which Perl package is used can be specified with @code{#:perl}.
2053 @defvr {Scheme Variable} ruby-build-system
2054 This variable is exported by @code{(guix build-system ruby)}. It
2055 implements the RubyGems build procedure used by Ruby packages, which
2056 involves running @code{gem build} followed by @code{gem install}.
2058 Which Ruby package is used can be specified with the @code{#:ruby}
2062 @defvr {Scheme Variable} waf-build-system
2063 This variable is exported by @code{(guix build-system waf)}. It
2064 implements a build procedure around the @code{waf} script. The common
2065 phases---@code{configure}, @code{build}, and @code{install}---are
2066 implemented by passing their names as arguments to the @code{waf}
2069 The @code{waf} script is executed by the Python interpreter. Which
2070 Python package is used to run the script can be specified with the
2071 @code{#:python} parameter.
2074 @defvr {Scheme Variable} haskell-build-system
2075 This variable is exported by @code{(guix build-system haskell)}. It
2076 implements the Cabal build procedure used by Haskell packages, which
2077 involves running @code{runhaskell Setup.hs configure
2078 --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
2079 Instead of installing the package by running @code{runhaskell Setup.hs
2080 install}, to avoid trying to register libraries in the read-only
2081 compiler store directory, the build system uses @code{runhaskell
2082 Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
2083 addition, the build system generates the package documentation by
2084 running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
2085 is passed. Optional Haddock parameters can be passed with the help of
2086 the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
2087 not found, the build system looks for @code{Setup.lhs} instead.
2089 Which Haskell compiler is used can be specified with the @code{#:haskell}
2090 parameter which defaults to @code{ghc}.
2093 Lastly, for packages that do not need anything as sophisticated, a
2094 ``trivial'' build system is provided. It is trivial in the sense that
2095 it provides basically no support: it does not pull any implicit inputs,
2096 and does not have a notion of build phases.
2098 @defvr {Scheme Variable} trivial-build-system
2099 This variable is exported by @code{(guix build-system trivial)}.
2101 This build system requires a @code{#:builder} argument. This argument
2102 must be a Scheme expression that builds the package's output(s)---as
2103 with @code{build-expression->derivation} (@pxref{Derivations,
2104 @code{build-expression->derivation}}).
2113 Conceptually, the @dfn{store} is where derivations that have been
2114 successfully built are stored---by default, under @file{/gnu/store}.
2115 Sub-directories in the store are referred to as @dfn{store paths}. The
2116 store has an associated database that contains information such has the
2117 store paths referred to by each store path, and the list of @emph{valid}
2118 store paths---paths that result from a successful build.
2120 The store is always accessed by the daemon on behalf of its clients
2121 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
2122 connect to the daemon over a Unix-domain socket, send it requests, and
2123 read the result---these are remote procedure calls, or RPCs.
2125 The @code{(guix store)} module provides procedures to connect to the
2126 daemon, and to perform RPCs. These are described below.
2128 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
2129 Connect to the daemon over the Unix-domain socket at @var{file}. When
2130 @var{reserve-space?} is true, instruct it to reserve a little bit of
2131 extra space on the file system so that the garbage collector can still
2132 operate, should the disk become full. Return a server object.
2134 @var{file} defaults to @var{%default-socket-path}, which is the normal
2135 location given the options that were passed to @command{configure}.
2138 @deffn {Scheme Procedure} close-connection @var{server}
2139 Close the connection to @var{server}.
2142 @defvr {Scheme Variable} current-build-output-port
2143 This variable is bound to a SRFI-39 parameter, which refers to the port
2144 where build and error logs sent by the daemon should be written.
2147 Procedures that make RPCs all take a server object as their first
2150 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
2151 Return @code{#t} when @var{path} is a valid store path.
2154 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
2155 Add @var{text} under file @var{name} in the store, and return its store
2156 path. @var{references} is the list of store paths referred to by the
2157 resulting store path.
2160 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
2161 Build @var{derivations} (a list of @code{<derivation>} objects or
2162 derivation paths), and return when the worker is done building them.
2163 Return @code{#t} on success.
2166 Note that the @code{(guix monads)} module provides a monad as well as
2167 monadic versions of the above procedures, with the goal of making it
2168 more convenient to work with code that accesses the store (@pxref{The
2172 @i{This section is currently incomplete.}
2175 @section Derivations
2178 Low-level build actions and the environment in which they are performed
2179 are represented by @dfn{derivations}. A derivation contain the
2180 following pieces of information:
2184 The outputs of the derivation---derivations produce at least one file or
2185 directory in the store, but may produce more.
2188 The inputs of the derivations, which may be other derivations or plain
2189 files in the store (patches, build scripts, etc.)
2192 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
2195 The file name of a build script in the store, along with the arguments
2199 A list of environment variables to be defined.
2203 @cindex derivation path
2204 Derivations allow clients of the daemon to communicate build actions to
2205 the store. They exist in two forms: as an in-memory representation,
2206 both on the client- and daemon-side, and as files in the store whose
2207 name end in @code{.drv}---these files are referred to as @dfn{derivation
2208 paths}. Derivations paths can be passed to the @code{build-derivations}
2209 procedure to perform the build actions they prescribe (@pxref{The
2212 The @code{(guix derivations)} module provides a representation of
2213 derivations as Scheme objects, along with procedures to create and
2214 otherwise manipulate derivations. The lowest-level primitive to create
2215 a derivation is the @code{derivation} procedure:
2217 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
2218 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2219 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
2220 [#:system (%current-system)] [#:references-graphs #f] @
2221 [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
2222 Build a derivation with the given arguments, and return the resulting
2223 @code{<derivation>} object.
2225 When @var{hash} and @var{hash-algo} are given, a
2226 @dfn{fixed-output derivation} is created---i.e., one whose result is
2227 known in advance, such as a file download. If, in addition,
2228 @var{recursive?} is true, then that fixed output may be an executable
2229 file or a directory and @var{hash} must be the hash of an archive
2230 containing this output.
2232 When @var{references-graphs} is true, it must be a list of file
2233 name/store path pairs. In that case, the reference graph of each store
2234 path is exported in the build environment in the corresponding file, in
2235 a simple text format.
2237 When @var{allowed-references} is true, it must be a list of store items
2238 or outputs that the derivation's output may refer to.
2240 When @var{leaked-env-vars} is true, it must be a list of strings
2241 denoting environment variables that are allowed to ``leak'' from the
2242 daemon's environment to the build environment. This is only applicable
2243 to fixed-output derivations---i.e., when @var{hash} is true. The main
2244 use is to allow variables such as @code{http_proxy} to be passed to
2245 derivations that download files.
2247 When @var{local-build?} is true, declare that the derivation is not a
2248 good candidate for offloading and should rather be built locally
2249 (@pxref{Daemon Offload Setup}). This is the case for small derivations
2250 where the costs of data transfers would outweigh the benefits.
2254 Here's an example with a shell script as its builder, assuming
2255 @var{store} is an open connection to the daemon, and @var{bash} points
2256 to a Bash executable in the store:
2259 (use-modules (guix utils)
2263 (let ((builder ; add the Bash script to the store
2264 (add-text-to-store store "my-builder.sh"
2265 "echo hello world > $out\n" '())))
2266 (derivation store "foo"
2267 bash `("-e" ,builder)
2268 #:inputs `((,bash) (,builder))
2269 #:env-vars '(("HOME" . "/homeless"))))
2270 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
2273 As can be guessed, this primitive is cumbersome to use directly. A
2274 better approach is to write build scripts in Scheme, of course! The
2275 best course of action for that is to write the build code as a
2276 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
2277 information, @pxref{G-Expressions}.
2279 Once upon a time, @code{gexp->derivation} did not exist and constructing
2280 derivations with build code written in Scheme was achieved with
2281 @code{build-expression->derivation}, documented below. This procedure
2282 is now deprecated in favor of the much nicer @code{gexp->derivation}.
2284 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
2285 @var{name} @var{exp} @
2286 [#:system (%current-system)] [#:inputs '()] @
2287 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2288 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2289 [#:references-graphs #f] [#:allowed-references #f] @
2290 [#:local-build? #f] [#:guile-for-build #f]
2291 Return a derivation that executes Scheme expression @var{exp} as a
2292 builder for derivation @var{name}. @var{inputs} must be a list of
2293 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
2294 @code{"out"} is assumed. @var{modules} is a list of names of Guile
2295 modules from the current search path to be copied in the store,
2296 compiled, and made available in the load path during the execution of
2297 @var{exp}---e.g., @code{((guix build utils) (guix build
2298 gnu-build-system))}.
2300 @var{exp} is evaluated in an environment where @code{%outputs} is bound
2301 to a list of output/path pairs, and where @code{%build-inputs} is bound
2302 to a list of string/output-path pairs made from @var{inputs}.
2303 Optionally, @var{env-vars} is a list of string pairs specifying the name
2304 and value of environment variables visible to the builder. The builder
2305 terminates by passing the result of @var{exp} to @code{exit}; thus, when
2306 @var{exp} returns @code{#f}, the build is considered to have failed.
2308 @var{exp} is built using @var{guile-for-build} (a derivation). When
2309 @var{guile-for-build} is omitted or is @code{#f}, the value of the
2310 @code{%guile-for-build} fluid is used instead.
2312 See the @code{derivation} procedure for the meaning of
2313 @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
2317 Here's an example of a single-output derivation that creates a directory
2318 containing one file:
2321 (let ((builder '(let ((out (assoc-ref %outputs "out")))
2322 (mkdir out) ; create /gnu/store/@dots{}-goo
2323 (call-with-output-file (string-append out "/test")
2325 (display '(hello guix) p))))))
2326 (build-expression->derivation store "goo" builder))
2328 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
2332 @node The Store Monad
2333 @section The Store Monad
2337 The procedures that operate on the store described in the previous
2338 sections all take an open connection to the build daemon as their first
2339 argument. Although the underlying model is functional, they either have
2340 side effects or depend on the current state of the store.
2342 The former is inconvenient: the connection to the build daemon has to be
2343 carried around in all those functions, making it impossible to compose
2344 functions that do not take that parameter with functions that do. The
2345 latter can be problematic: since store operations have side effects
2346 and/or depend on external state, they have to be properly sequenced.
2348 @cindex monadic values
2349 @cindex monadic functions
2350 This is where the @code{(guix monads)} module comes in. This module
2351 provides a framework for working with @dfn{monads}, and a particularly
2352 useful monad for our uses, the @dfn{store monad}. Monads are a
2353 construct that allows two things: associating ``context'' with values
2354 (in our case, the context is the store), and building sequences of
2355 computations (here computations include accesses to the store.) Values
2356 in a monad---values that carry this additional context---are called
2357 @dfn{monadic values}; procedures that return such values are called
2358 @dfn{monadic procedures}.
2360 Consider this ``normal'' procedure:
2363 (define (sh-symlink store)
2364 ;; Return a derivation that symlinks the 'bash' executable.
2365 (let* ((drv (package-derivation store bash))
2366 (out (derivation->output-path drv))
2367 (sh (string-append out "/bin/bash")))
2368 (build-expression->derivation store "sh"
2369 `(symlink ,sh %output))))
2372 Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
2373 as a monadic function:
2376 (define (sh-symlink)
2377 ;; Same, but return a monadic value.
2378 (mlet %store-monad ((drv (package->derivation bash)))
2379 (gexp->derivation "sh"
2380 #~(symlink (string-append #$drv "/bin/bash")
2384 There several things to note in the second version: the @code{store}
2385 parameter is now implicit and is ``threaded'' in the calls to the
2386 @code{package->derivation} and @code{gexp->derivation} monadic
2387 procedures, and the monadic value returned by @code{package->derivation}
2388 is @dfn{bound} using @code{mlet} instead of plain @code{let}.
2390 As it turns out, the call to @code{package->derivation} can even be
2391 omitted since it will take place implicitly, as we will see later
2392 (@pxref{G-Expressions}):
2395 (define (sh-symlink)
2396 (gexp->derivation "sh"
2397 #~(symlink (string-append #$bash "/bin/bash")
2401 Calling the monadic @code{sh-symlink} has no effect. To get the desired
2402 effect, one must use @code{run-with-store}:
2405 (run-with-store (open-connection) (sh-symlink))
2406 @result{} /gnu/store/...-sh-symlink
2409 Note that the @code{(guix monad-repl)} module extends Guile's REPL with
2410 new ``meta-commands'' to make it easier to deal with monadic procedures:
2411 @code{run-in-store}, and @code{enter-store-monad}. The former, is used
2412 to ``run'' a single monadic value through the store:
2415 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
2416 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2419 The latter enters a recursive REPL, where all the return values are
2420 automatically run through the store:
2423 scheme@@(guile-user)> ,enter-store-monad
2424 store-monad@@(guile-user) [1]> (package->derivation hello)
2425 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2426 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
2427 $3 = "/gnu/store/@dots{}-foo"
2428 store-monad@@(guile-user) [1]> ,q
2429 scheme@@(guile-user)>
2433 Note that non-monadic values cannot be returned in the
2434 @code{store-monad} REPL.
2436 The main syntactic forms to deal with monads in general are provided by
2437 the @code{(guix monads)} module and are described below.
2439 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
2440 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
2444 @deffn {Scheme Syntax} return @var{val}
2445 Return a monadic value that encapsulates @var{val}.
2448 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
2449 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
2450 procedure @var{mproc}@footnote{This operation is commonly referred to as
2451 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
2452 we use this somewhat cryptic symbol inherited from the Haskell
2456 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
2458 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
2460 Bind the variables @var{var} to the monadic values @var{mval} in
2461 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
2462 ``normal'' value @var{val}, as per @code{let}.
2464 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
2465 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
2468 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
2469 Bind @var{mexp} and the following monadic expressions in sequence,
2470 returning the result of the last expression.
2472 This is akin to @code{mlet}, except that the return values of the
2473 monadic expressions are ignored. In that sense, it is analogous to
2474 @code{begin}, but applied to monadic expressions.
2478 The @code{(guix monads)} module provides the @dfn{state monad}, which
2479 allows an additional value---the state---to be @emph{threaded} through
2480 monadic procedure calls.
2482 @defvr {Scheme Variable} %state-monad
2483 The state monad. Procedures in the state monad can access and change
2484 the state that is threaded.
2486 Consider the example below. The @code{square} procedure returns a value
2487 in the state monad. It returns the square of its argument, but also
2488 increments the current state value:
2492 (mlet %state-monad ((count (current-state)))
2493 (mbegin %state-monad
2494 (set-current-state (+ 1 count))
2497 (run-with-state (sequence %state-monad (map square (iota 3))) 0)
2502 When ``run'' through @var{%state-monad}, we obtain that additional state
2503 value, which is the number of @code{square} calls.
2506 @deffn {Monadic Procedure} current-state
2507 Return the current state as a monadic value.
2510 @deffn {Monadic Procedure} set-current-state @var{value}
2511 Set the current state to @var{value} and return the previous state as a
2515 @deffn {Monadic Procedure} state-push @var{value}
2516 Push @var{value} to the current state, which is assumed to be a list,
2517 and return the previous state as a monadic value.
2520 @deffn {Monadic Procedure} state-pop
2521 Pop a value from the current state and return it as a monadic value.
2522 The state is assumed to be a list.
2525 @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
2526 Run monadic value @var{mval} starting with @var{state} as the initial
2527 state. Return two values: the resulting value, and the resulting state.
2530 The main interface to the store monad, provided by the @code{(guix
2531 store)} module, is as follows.
2533 @defvr {Scheme Variable} %store-monad
2534 The store monad---an alias for @var{%state-monad}.
2536 Values in the store monad encapsulate accesses to the store. When its
2537 effect is needed, a value of the store monad must be ``evaluated'' by
2538 passing it to the @code{run-with-store} procedure (see below.)
2541 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
2542 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
2543 open store connection.
2546 @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
2547 Return as a monadic value the absolute file name in the store of the file
2548 containing @var{text}, a string. @var{references} is a list of store items that the
2549 resulting text file refers to; it defaults to the empty list.
2552 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
2554 Return the name of @var{file} once interned in the store. Use
2555 @var{name} as its store name, or the basename of @var{file} if
2556 @var{name} is omitted.
2558 When @var{recursive?} is true, the contents of @var{file} are added
2559 recursively; if @var{file} designates a flat file and @var{recursive?}
2560 is true, its contents are added, and its permission bits are kept.
2562 The example below adds a file to the store, under two different names:
2565 (run-with-store (open-connection)
2566 (mlet %store-monad ((a (interned-file "README"))
2567 (b (interned-file "README" "LEGU-MIN")))
2568 (return (list a b))))
2570 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
2575 The @code{(guix packages)} module exports the following package-related
2578 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
2579 [#:system (%current-system)] [#:target #f] @
2580 [#:output "out"] Return as a monadic
2581 value in the absolute file name of @var{file} within the @var{output}
2582 directory of @var{package}. When @var{file} is omitted, return the name
2583 of the @var{output} directory of @var{package}. When @var{target} is
2584 true, use it as a cross-compilation target triplet.
2587 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
2588 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
2589 @var{target} [@var{system}]
2590 Monadic version of @code{package-derivation} and
2591 @code{package-cross-derivation} (@pxref{Defining Packages}).
2596 @section G-Expressions
2598 @cindex G-expression
2599 @cindex build code quoting
2600 So we have ``derivations'', which represent a sequence of build actions
2601 to be performed to produce an item in the store (@pxref{Derivations}).
2602 Those build actions are performed when asking the daemon to actually
2603 build the derivations; they are run by the daemon in a container
2604 (@pxref{Invoking guix-daemon}).
2606 @cindex strata of code
2607 It should come as no surprise that we like to write those build actions
2608 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2609 code@footnote{The term @dfn{stratum} in this context was coined by
2610 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2611 Kiselyov, who has written insightful
2612 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2613 on this topic}, refers to this kind of code generation as
2614 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2615 to the daemon, etc.---and the ``build code''---code that actually
2616 performs build actions, such as making directories, invoking
2617 @command{make}, etc.
2619 To describe a derivation and its build actions, one typically needs to
2620 embed build code inside host code. It boils down to manipulating build
2621 code as data, and Scheme's homoiconicity---code has a direct
2622 representation as data---comes in handy for that. But we need more than
2623 Scheme's normal @code{quasiquote} mechanism to construct build
2626 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2627 S-expressions adapted to build expressions. G-expressions, or
2628 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2629 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2630 @code{#$}, and @code{#$@@}), which are comparable respectively to
2631 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2632 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2633 Reference Manual}). However, there are major differences:
2637 Gexps are meant to be written to a file and run or manipulated by other
2641 When a high-level object such as a package or derivation is unquoted
2642 inside a gexp, the result is as if its output file name had been
2646 Gexps carry information about the packages or derivations they refer to,
2647 and these dependencies are automatically added as inputs to the build
2648 processes that use them.
2651 Actually this mechanism is not limited to package and derivation
2652 objects; @dfn{compilers} able to ``lower'' other high-level objects to
2653 derivations can be defined, such that these objects can also be inserted
2654 into gexps. Another useful type of high-level object that can be
2655 inserted in a gexp is @dfn{local files}, which allows files from the
2656 local file system to be added to the store and referred to by
2657 derivations and such (see @code{local-file} below.)
2659 To illustrate the idea, here is an example of a gexp:
2666 (symlink (string-append #$coreutils "/bin/ls")
2670 This gexp can be passed to @code{gexp->derivation}; we obtain a
2671 derivation that builds a directory containing exactly one symlink to
2672 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2675 (gexp->derivation "the-thing" build-exp)
2678 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
2679 substituted to the reference to the @var{coreutils} package in the
2680 actual build code, and @var{coreutils} is automatically made an input to
2681 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2682 output)}) is replaced by a string containing the derivation's output
2685 @cindex cross compilation
2686 In a cross-compilation context, it is useful to distinguish between
2687 references to the @emph{native} build of a package---that can run on the
2688 host---versus references to cross builds of a package. To that end, the
2689 @code{#+} plays the same role as @code{#$}, but is a reference to a
2690 native package build:
2693 (gexp->derivation "vi"
2696 (system* (string-append #+coreutils "/bin/ln")
2698 (string-append #$emacs "/bin/emacs")
2699 (string-append #$output "/bin/vi")))
2700 #:target "mips64el-linux")
2704 In the example above, the native build of @var{coreutils} is used, so
2705 that @command{ln} can actually run on the host; but then the
2706 cross-compiled build of @var{emacs} is referenced.
2708 The syntactic form to construct gexps is summarized below.
2710 @deffn {Scheme Syntax} #~@var{exp}
2711 @deffnx {Scheme Syntax} (gexp @var{exp})
2712 Return a G-expression containing @var{exp}. @var{exp} may contain one
2713 or more of the following forms:
2717 @itemx (ungexp @var{obj})
2718 Introduce a reference to @var{obj}. @var{obj} may have one of the
2719 supported types, for example a package or a
2720 derivation, in which case the @code{ungexp} form is replaced by its
2721 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2723 If @var{obj} is a list, it is traversed and references to supported
2724 objects are substituted similarly.
2726 If @var{obj} is another gexp, its contents are inserted and its
2727 dependencies are added to those of the containing gexp.
2729 If @var{obj} is another kind of object, it is inserted as is.
2731 @item #$@var{obj}:@var{output}
2732 @itemx (ungexp @var{obj} @var{output})
2733 This is like the form above, but referring explicitly to the
2734 @var{output} of @var{obj}---this is useful when @var{obj} produces
2735 multiple outputs (@pxref{Packages with Multiple Outputs}).
2738 @itemx #+@var{obj}:output
2739 @itemx (ungexp-native @var{obj})
2740 @itemx (ungexp-native @var{obj} @var{output})
2741 Same as @code{ungexp}, but produces a reference to the @emph{native}
2742 build of @var{obj} when used in a cross compilation context.
2744 @item #$output[:@var{output}]
2745 @itemx (ungexp output [@var{output}])
2746 Insert a reference to derivation output @var{output}, or to the main
2747 output when @var{output} is omitted.
2749 This only makes sense for gexps passed to @code{gexp->derivation}.
2752 @itemx (ungexp-splicing @var{lst})
2753 Like the above, but splices the contents of @var{lst} inside the
2757 @itemx (ungexp-native-splicing @var{lst})
2758 Like the above, but refers to native builds of the objects listed in
2763 G-expressions created by @code{gexp} or @code{#~} are run-time objects
2764 of the @code{gexp?} type (see below.)
2767 @deffn {Scheme Procedure} gexp? @var{obj}
2768 Return @code{#t} if @var{obj} is a G-expression.
2771 G-expressions are meant to be written to disk, either as code building
2772 some derivation, or as plain files in the store. The monadic procedures
2773 below allow you to do that (@pxref{The Store Monad}, for more
2774 information about monads.)
2776 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
2777 [#:system (%current-system)] [#:target #f] [#:graft? #t] @
2778 [#:hash #f] [#:hash-algo #f] @
2779 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2780 [#:module-path @var{%load-path}] @
2781 [#:references-graphs #f] [#:allowed-references #f] @
2782 [#:leaked-env-vars #f] @
2783 [#:local-build? #f] [#:guile-for-build #f]
2784 Return a derivation @var{name} that runs @var{exp} (a gexp) with
2785 @var{guile-for-build} (a derivation) on @var{system}. When @var{target}
2786 is true, it is used as the cross-compilation target triplet for packages
2787 referred to by @var{exp}.
2789 Make @var{modules} available in the evaluation context of @var{exp};
2790 @var{modules} is a list of names of Guile modules searched in
2791 @var{module-path} to be copied in the store, compiled, and made available in
2792 the load path during the execution of @var{exp}---e.g., @code{((guix
2793 build utils) (guix build gnu-build-system))}.
2795 @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
2798 When @var{references-graphs} is true, it must be a list of tuples of one of the
2802 (@var{file-name} @var{package})
2803 (@var{file-name} @var{package} @var{output})
2804 (@var{file-name} @var{derivation})
2805 (@var{file-name} @var{derivation} @var{output})
2806 (@var{file-name} @var{store-item})
2809 The right-hand-side of each element of @var{references-graphs} is automatically made
2810 an input of the build process of @var{exp}. In the build environment, each
2811 @var{file-name} contains the reference graph of the corresponding item, in a simple
2814 @var{allowed-references} must be either @code{#f} or a list of output names and packages.
2815 In the latter case, the list denotes store items that the result is allowed to
2816 refer to. Any reference to another store item will lead to a build error.
2818 The other arguments are as for @code{derivation} (@pxref{Derivations}).
2821 @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
2823 Return an object representing local file @var{file} to add to the store; this
2824 object can be used in a gexp. @var{file} will be added to the store under @var{name}--by
2825 default the base name of @var{file}.
2827 When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
2828 designates a flat file and @var{recursive?} is true, its contents are added, and its
2829 permission bits are kept.
2831 This is the declarative counterpart of the @code{interned-file} monadic
2832 procedure (@pxref{The Store Monad, @code{interned-file}}).
2835 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
2836 Return an executable script @var{name} that runs @var{exp} using
2837 @var{guile} with @var{modules} in its search path.
2839 The example below builds a script that simply invokes the @command{ls}
2843 (use-modules (guix gexp) (gnu packages base))
2845 (gexp->script "list-files"
2846 #~(execl (string-append #$coreutils "/bin/ls")
2850 When ``running'' it through the store (@pxref{The Store Monad,
2851 @code{run-with-store}}), we obtain a derivation that produces an
2852 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
2855 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
2857 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
2862 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
2863 Return a derivation that builds a file @var{name} containing @var{exp}.
2865 The resulting file holds references to all the dependencies of @var{exp}
2866 or a subset thereof.
2869 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
2870 Return as a monadic value a derivation that builds a text file
2871 containing all of @var{text}. @var{text} may list, in addition to
2872 strings, objects of any type that can be used in a gexp: packages,
2873 derivations, local file objects, etc. The resulting store file holds
2874 references to all these.
2876 This variant should be preferred over @code{text-file} anytime the file
2877 to create will reference items from the store. This is typically the
2878 case when building a configuration file that embeds store file names,
2882 (define (profile.sh)
2883 ;; Return the name of a shell script in the store that
2884 ;; initializes the 'PATH' environment variable.
2885 (text-file* "profile.sh"
2886 "export PATH=" coreutils "/bin:"
2887 grep "/bin:" sed "/bin\n"))
2890 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
2891 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
2892 preventing them from being garbage-collected during its lifetime.
2895 Of course, in addition to gexps embedded in ``host'' code, there are
2896 also modules containing build tools. To make it clear that they are
2897 meant to be used in the build stratum, these modules are kept in the
2898 @code{(guix build @dots{})} name space.
2901 @c *********************************************************************
2905 This section describes tools primarily targeted at developers and users
2906 who write new package definitions. They complement the Scheme
2907 programming interface of Guix in a convenient way.
2910 * Invoking guix build:: Building packages from the command line.
2911 * Invoking guix download:: Downloading a file and printing its hash.
2912 * Invoking guix hash:: Computing the cryptographic hash of a file.
2913 * Invoking guix import:: Importing package definitions.
2914 * Invoking guix refresh:: Updating package definitions.
2915 * Invoking guix lint:: Finding errors in package definitions.
2916 * Invoking guix environment:: Setting up development environments.
2917 * Invoking guix publish:: Sharing substitutes.
2920 @node Invoking guix build
2921 @section Invoking @command{guix build}
2923 The @command{guix build} command builds packages or derivations and
2924 their dependencies, and prints the resulting store paths. Note that it
2925 does not modify the user's profile---this is the job of the
2926 @command{guix package} command (@pxref{Invoking guix package}). Thus,
2927 it is mainly useful for distribution developers.
2929 The general syntax is:
2932 guix build @var{options} @var{package-or-derivation}@dots{}
2935 @var{package-or-derivation} may be either the name of a package found in
2936 the software distribution such as @code{coreutils} or
2937 @code{coreutils-8.20}, or a derivation such as
2938 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
2939 package with the corresponding name (and optionally version) is searched
2940 for among the GNU distribution modules (@pxref{Package Modules}).
2942 Alternatively, the @code{--expression} option may be used to specify a
2943 Scheme expression that evaluates to a package; this is useful when
2944 disambiguation among several same-named packages or package variants is
2947 The @var{options} may be zero or more of the following:
2951 @item --expression=@var{expr}
2952 @itemx -e @var{expr}
2953 Build the package or derivation @var{expr} evaluates to.
2955 For example, @var{expr} may be @code{(@@ (gnu packages guile)
2956 guile-1.8)}, which unambiguously designates this specific variant of
2957 version 1.8 of Guile.
2959 Alternately, @var{expr} may be a G-expression, in which case it is used
2960 as a build program passed to @code{gexp->derivation}
2961 (@pxref{G-Expressions}).
2963 Lastly, @var{expr} may refer to a zero-argument monadic procedure
2964 (@pxref{The Store Monad}). The procedure must return a derivation as a
2965 monadic value, which is then passed through @code{run-with-store}.
2969 Build the packages' source derivations, rather than the packages
2972 For instance, @code{guix build -S gcc} returns something like
2973 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
2975 The returned source tarball is the result of applying any patches and
2976 code snippets specified in the package's @code{origin} (@pxref{Defining
2980 Fetch and return the source of @var{package-or-derivation} and all their
2981 dependencies, recursively. This is a handy way to obtain a local copy
2982 of all the source code needed to build @var{packages}, allowing you to
2983 eventually build them even without network access. It is an extension
2984 of the @code{--source} option and can accept one of the following
2985 optional argument values:
2989 This value causes the @code{--sources} option to behave in the same way
2990 as the @code{--source} option.
2993 Build all packages' source derivations, including any source that might
2994 be listed as @code{inputs}. This is the default value.
2997 $ guix build --sources tzdata
2998 The following derivations will be built:
2999 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
3000 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3004 Build all packages' source derivations, as well as all source
3005 derivations for packages' transitive inputs. This can be used e.g. to
3006 prefetch package source for later offline building.
3009 $ guix build --sources=transitive tzdata
3010 The following derivations will be built:
3011 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3012 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
3013 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
3014 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
3015 /gnu/store/@dots{}-make-4.1.tar.xz.drv
3016 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
3022 @item --system=@var{system}
3023 @itemx -s @var{system}
3024 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
3025 the host's system type.
3027 An example use of this is on Linux-based systems, which can emulate
3028 different personalities. For instance, passing
3029 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
3030 to build packages in a complete 32-bit environment.
3032 @item --target=@var{triplet}
3033 @cindex cross-compilation
3034 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
3035 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
3036 configuration triplets,, configure, GNU Configure and Build System}).
3038 @item --with-source=@var{source}
3039 Use @var{source} as the source of the corresponding package.
3040 @var{source} must be a file name or a URL, as for @command{guix
3041 download} (@pxref{Invoking guix download}).
3043 The ``corresponding package'' is taken to be one specified on the
3044 command line whose name matches the base of @var{source}---e.g., if
3045 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
3046 package is @code{guile}. Likewise, the version string is inferred from
3047 @var{source}; in the previous example, it's @code{2.0.10}.
3049 This option allows users to try out versions of packages other than the
3050 one provided by the distribution. The example below downloads
3051 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
3052 the @code{ed} package:
3055 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
3058 As a developer, @code{--with-source} makes it easy to test release
3062 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
3066 Do not ``graft'' packages. In practice, this means that package updates
3067 available as grafts are not applied. @xref{Security Updates}, for more
3068 information on grafts.
3072 Return the derivation paths, not the output paths, of the given
3075 @item --root=@var{file}
3076 @itemx -r @var{file}
3077 Make @var{file} a symlink to the result, and register it as a garbage
3081 Return the build log file names for the given
3082 @var{package-or-derivation}s, or raise an error if build logs are
3085 This works regardless of how packages or derivations are specified. For
3086 instance, the following invocations are equivalent:
3089 guix build --log-file `guix build -d guile`
3090 guix build --log-file `guix build guile`
3091 guix build --log-file guile
3092 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
3098 @cindex common build options
3099 In addition, a number of options that control the build process are
3100 common to @command{guix build} and other commands that can spawn builds,
3101 such as @command{guix package} or @command{guix archive}. These are the
3106 @item --load-path=@var{directory}
3107 @itemx -L @var{directory}
3108 Add @var{directory} to the front of the package module search path
3109 (@pxref{Package Modules}).
3111 This allows users to define their own packages and make them visible to
3112 the command-line tools.
3116 Keep the build tree of failed builds. Thus, if a build fail, its build
3117 tree is kept under @file{/tmp}, in a directory whose name is shown at
3118 the end of the build log. This is useful when debugging build issues.
3122 Do not build the derivations.
3125 When substituting a pre-built binary fails, fall back to building
3128 @item --no-substitutes
3129 Do not use substitutes for build products. That is, always build things
3130 locally instead of allowing downloads of pre-built binaries
3131 (@pxref{Substitutes}).
3133 @item --no-build-hook
3134 Do not attempt to offload builds @i{via} the daemon's ``build hook''
3135 (@pxref{Daemon Offload Setup}). That is, always build things locally
3136 instead of offloading builds to remote machines.
3138 @item --max-silent-time=@var{seconds}
3139 When the build or substitution process remains silent for more than
3140 @var{seconds}, terminate it and report a build failure.
3142 @item --timeout=@var{seconds}
3143 Likewise, when the build or substitution process lasts for more than
3144 @var{seconds}, terminate it and report a build failure.
3146 By default there is no timeout. This behavior can be restored with
3149 @item --verbosity=@var{level}
3150 Use the given verbosity level. @var{level} must be an integer between 0
3151 and 5; higher means more verbose output. Setting a level of 4 or more
3152 may be helpful when debugging setup issues with the build daemon.
3154 @item --cores=@var{n}
3156 Allow the use of up to @var{n} CPU cores for the build. The special
3157 value @code{0} means to use as many CPU cores as available.
3159 @item --max-jobs=@var{n}
3161 Allow at most @var{n} build jobs in parallel. @xref{Invoking
3162 guix-daemon, @code{--max-jobs}}, for details about this option and the
3163 equivalent @command{guix-daemon} option.
3167 Behind the scenes, @command{guix build} is essentially an interface to
3168 the @code{package-derivation} procedure of the @code{(guix packages)}
3169 module, and to the @code{build-derivations} procedure of the @code{(guix
3170 derivations)} module.
3172 In addition to options explicitly passed on the command line,
3173 @command{guix build} and other @command{guix} commands that support
3174 building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
3176 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
3177 Users can define this variable to a list of command line options that
3178 will automatically be used by @command{guix build} and other
3179 @command{guix} commands that can perform builds, as in the example
3183 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
3186 These options are parsed independently, and the result is appended to
3187 the parsed command-line options.
3191 @node Invoking guix download
3192 @section Invoking @command{guix download}
3194 When writing a package definition, developers typically need to download
3195 the package's source tarball, compute its SHA256 hash, and write that
3196 hash in the package definition (@pxref{Defining Packages}). The
3197 @command{guix download} tool helps with this task: it downloads a file
3198 from the given URI, adds it to the store, and prints both its file name
3199 in the store and its SHA256 hash.
3201 The fact that the downloaded file is added to the store saves bandwidth:
3202 when the developer eventually tries to build the newly defined package
3203 with @command{guix build}, the source tarball will not have to be
3204 downloaded again because it is already in the store. It is also a
3205 convenient way to temporarily stash files, which may be deleted
3206 eventually (@pxref{Invoking guix gc}).
3208 The @command{guix download} command supports the same URIs as used in
3209 package definitions. In particular, it supports @code{mirror://} URIs.
3210 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
3211 Guile bindings for GnuTLS are available in the user's environment; when
3212 they are not available, an error is raised. @xref{Guile Preparations,
3213 how to install the GnuTLS bindings for Guile,, gnutls-guile,
3214 GnuTLS-Guile}, for more information.
3216 The following option is available:
3219 @item --format=@var{fmt}
3221 Write the hash in the format specified by @var{fmt}. For more
3222 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
3225 @node Invoking guix hash
3226 @section Invoking @command{guix hash}
3228 The @command{guix hash} command computes the SHA256 hash of a file.
3229 It is primarily a convenience tool for anyone contributing to the
3230 distribution: it computes the cryptographic hash of a file, which can be
3231 used in the definition of a package (@pxref{Defining Packages}).
3233 The general syntax is:
3236 guix hash @var{option} @var{file}
3239 @command{guix hash} has the following option:
3243 @item --format=@var{fmt}
3245 Write the hash in the format specified by @var{fmt}.
3247 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
3248 (@code{hex} and @code{hexadecimal} can be used as well).
3250 If the @option{--format} option is not specified, @command{guix hash}
3251 will output the hash in @code{nix-base32}. This representation is used
3252 in the definitions of packages.
3256 Compute the hash on @var{file} recursively.
3258 In this case, the hash is computed on an archive containing @var{file},
3259 including its children if it is a directory. Some of @var{file}'s
3260 meta-data is part of the archive; for instance, when @var{file} is a
3261 regular file, the hash is different depending on whether @var{file} is
3262 executable or not. Meta-data such as time stamps has no impact on the
3263 hash (@pxref{Invoking guix archive}).
3264 @c FIXME: Replace xref above with xref to an ``Archive'' section when
3269 @node Invoking guix import
3270 @section Invoking @command{guix import}
3272 @cindex importing packages
3273 @cindex package import
3274 @cindex package conversion
3275 The @command{guix import} command is useful for people willing to add a
3276 package to the distribution but who'd rather do as little work as
3277 possible to get there---a legitimate demand. The command knows of a few
3278 repositories from which it can ``import'' package meta-data. The result
3279 is a package definition, or a template thereof, in the format we know
3280 (@pxref{Defining Packages}).
3282 The general syntax is:
3285 guix import @var{importer} @var{options}@dots{}
3288 @var{importer} specifies the source from which to import package
3289 meta-data, and @var{options} specifies a package identifier and other
3290 options specific to @var{importer}. Currently, the available
3295 Import meta-data for the given GNU package. This provides a template
3296 for the latest version of that GNU package, including the hash of its
3297 source tarball, and its canonical synopsis and description.
3299 Additional information such as the package's dependencies and its
3300 license needs to be figured out manually.
3302 For example, the following command returns a package definition for
3306 guix import gnu hello
3309 Specific command-line options are:
3312 @item --key-download=@var{policy}
3313 As for @code{guix refresh}, specify the policy to handle missing OpenPGP
3314 keys when verifying the package's signature. @xref{Invoking guix
3315 refresh, @code{--key-download}}.
3320 Import meta-data from the @uref{https://pypi.python.org/, Python Package
3321 Index}@footnote{This functionality requires Guile-JSON to be installed.
3322 @xref{Requirements}.}. Information is taken from the JSON-formatted
3323 description available at @code{pypi.python.org} and usually includes all
3324 the relevant information, including package dependencies.
3326 The command below imports meta-data for the @code{itsdangerous} Python
3330 guix import pypi itsdangerous
3335 Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
3336 Information is taken from the JSON-formatted meta-data provided through
3337 @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
3338 relevant information, such as module dependencies. License information
3339 should be checked closely. If Perl is available in the store, then the
3340 @code{corelist} utility will be used to filter core modules out of the
3341 list of dependencies.
3343 The command command below imports meta-data for the @code{Acme::Boolean}
3347 guix import cpan Acme::Boolean
3351 Import meta-data from a local copy of the source of the
3352 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
3353 relies on the @command{nix-instantiate} command of
3354 @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
3355 typically written in a mixture of Nix-language and Bash code. This
3356 command only imports the high-level package structure that is written in
3357 the Nix language. It normally includes all the basic fields of a
3360 When importing a GNU package, the synopsis and descriptions are replaced
3361 by their canonical upstream variant.
3363 As an example, the command below imports the package definition of
3364 LibreOffice (more precisely, it imports the definition of the package
3365 bound to the @code{libreoffice} top-level attribute):
3368 guix import nix ~/path/to/nixpkgs libreoffice
3373 Import meta-data from Haskell community's central package archive
3374 @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
3375 Cabal files and includes all the relevant information, including package
3378 Specific command-line options are:
3381 @item --no-test-dependencies
3383 Do not include dependencies only required to run the test suite.
3386 The command below imports meta-data for the latest version of the
3387 @code{HTTP} Haskell package without including test dependencies:
3390 guix import hackage -t HTTP
3393 A specific package version may optionally be specified by following the
3394 package name by a hyphen and a version number as in the following example:
3397 guix import hackage mtl-2.1.3.1
3400 Currently only indentation structured Cabal files are supported.
3403 The structure of the @command{guix import} code is modular. It would be
3404 useful to have more importers for other package formats, and your help
3405 is welcome here (@pxref{Contributing}).
3407 @node Invoking guix refresh
3408 @section Invoking @command{guix refresh}
3410 The primary audience of the @command{guix refresh} command is developers
3411 of the GNU software distribution. By default, it reports any packages
3412 provided by the distribution that are outdated compared to the latest
3413 upstream version, like this:
3417 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
3418 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
3421 It does so by browsing each package's FTP directory and determining the
3422 highest version number of the source tarballs
3423 therein@footnote{Currently, this only works for GNU packages.}.
3425 When passed @code{--update}, it modifies distribution source files to
3426 update the version numbers and source tarball hashes of those packages'
3427 recipes (@pxref{Defining Packages}). This is achieved by downloading
3428 each package's latest source tarball and its associated OpenPGP
3429 signature, authenticating the downloaded tarball against its signature
3430 using @command{gpg}, and finally computing its hash. When the public
3431 key used to sign the tarball is missing from the user's keyring, an
3432 attempt is made to automatically retrieve it from a public key server;
3433 when it's successful, the key is added to the user's keyring; otherwise,
3434 @command{guix refresh} reports an error.
3436 The following options are supported:
3442 Update distribution source files (package recipes) in place.
3443 @xref{Defining Packages}, for more information on package definitions.
3445 @item --select=[@var{subset}]
3446 @itemx -s @var{subset}
3447 Select all the packages in @var{subset}, one of @code{core} or
3450 The @code{core} subset refers to all the packages at the core of the
3451 distribution---i.e., packages that are used to build ``everything
3452 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
3453 changing one of these packages in the distribution entails a rebuild of
3454 all the others. Thus, such updates are an inconvenience to users in
3455 terms of build time or bandwidth used to achieve the upgrade.
3457 The @code{non-core} subset refers to the remaining packages. It is
3458 typically useful in cases where an update of the core packages would be
3463 In addition, @command{guix refresh} can be passed one or more package
3464 names, as in this example:
3467 guix refresh -u emacs idutils gcc-4.8.4
3471 The command above specifically updates the @code{emacs} and
3472 @code{idutils} packages. The @code{--select} option would have no
3473 effect in this case.
3475 When considering whether to upgrade a package, it is sometimes
3476 convenient to know which packages would be affected by the upgrade and
3477 should be checked for compatibility. For this the following option may
3478 be used when passing @command{guix refresh} one or more package names:
3482 @item --list-dependent
3484 List top-level dependent packages that would need to be rebuilt as a
3485 result of upgrading one or more packages.
3489 Be aware that the @code{--list-dependent} option only
3490 @emph{approximates} the rebuilds that would be required as a result of
3491 an upgrade. More rebuilds might be required under some circumstances.
3494 $ guix refresh --list-dependent flex
3495 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
3496 hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
3499 The command above lists a set of packages that could be built to check
3500 for compatibility with an upgraded @code{flex} package.
3502 The following options can be used to customize GnuPG operation:
3506 @item --gpg=@var{command}
3507 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
3508 for in @code{$PATH}.
3510 @item --key-download=@var{policy}
3511 Handle missing OpenPGP keys according to @var{policy}, which may be one
3516 Always download missing OpenPGP keys from the key server, and add them
3517 to the user's GnuPG keyring.
3520 Never try to download missing OpenPGP keys. Instead just bail out.
3523 When a package signed with an unknown OpenPGP key is encountered, ask
3524 the user whether to download it or not. This is the default behavior.
3527 @item --key-server=@var{host}
3528 Use @var{host} as the OpenPGP key server when importing a public key.
3532 @node Invoking guix lint
3533 @section Invoking @command{guix lint}
3534 The @command{guix lint} is meant to help package developers avoid common
3535 errors and use a consistent style. It runs a number of checks on a
3536 given set of packages in order to find common mistakes in their
3537 definitions. Available @dfn{checkers} include (see
3538 @code{--list-checkers} for a complete list):
3543 Validate certain typographical and stylistic rules about package
3544 descriptions and synopses.
3546 @item inputs-should-be-native
3547 Identify inputs that should most likely be native inputs.
3551 Probe @code{home-page} and @code{source} URLs and report those that are
3555 The general syntax is:
3558 guix lint @var{options} @var{package}@dots{}
3561 If no package is given on the command line, then all packages are checked.
3562 The @var{options} may be zero or more of the following:
3568 Only enable the checkers specified in a comma-separated list using the
3569 names returned by @code{--list-checkers}.
3571 @item --list-checkers
3573 List and describe all the available checkers that will be run on packages
3578 @node Invoking guix environment
3579 @section Invoking @command{guix environment}
3581 @cindex reproducible build environments
3582 The purpose of @command{guix environment} is to assist hackers in
3583 creating reproducible development environments without polluting their
3584 package profile. The @command{guix environment} tool takes one or more
3585 packages, builds all of the necessary inputs, and creates a shell
3586 environment to use them.
3588 The general syntax is:
3591 guix environment @var{options} @var{package}@dots{}
3594 The following examples spawns a new shell that is capable of building
3595 the GNU Guile source code:
3598 guix environment guile
3601 If the specified packages are not built yet, @command{guix environment}
3602 automatically builds them. The new shell's environment is an augmented
3603 version of the environment that @command{guix environment} was run in.
3604 It contains the necessary search paths for building the given package
3605 added to the existing environment variables. To create a ``pure''
3606 environment in which the original environment variables have been unset,
3607 use the @code{--pure} option.
3609 Additionally, more than one package may be specified, in which case the
3610 union of the inputs for the given packages are used. For example, the
3611 command below spawns a shell where all of the dependencies of both Guile
3612 and Emacs are available:
3615 guix environment guile emacs
3618 Sometimes an interactive shell session is not desired. The
3619 @code{--exec} option can be used to specify the command to run instead.
3622 guix environment guile --exec=make
3625 The following options are available:
3628 @item --expression=@var{expr}
3629 @itemx -e @var{expr}
3630 Create an environment for the package that @var{expr} evaluates to.
3632 @item --load=@var{file}
3633 @itemx -l @var{file}
3634 Create an environment for the package that the code within @var{file}
3637 @item --exec=@var{command}
3638 @item -E @var{command}
3639 Execute @var{command} in the new environment.
3642 Unset existing environment variables when building the new environment.
3643 This has the effect of creating an environment in which search paths
3644 only contain package inputs.
3646 @item --search-paths
3647 Display the environment variable definitions that make up the
3651 It also supports all of the common build options that @command{guix
3652 build} supports (@pxref{Invoking guix build, common build options}).
3654 @node Invoking guix publish
3655 @section Invoking @command{guix publish}
3657 The purpose of @command{guix publish} is to enable users to easily share
3658 their store with others, which can then use it as a substitute server
3659 (@pxref{Substitutes}).
3661 When @command{guix publish} runs, it spawns an HTTP server which allows
3662 anyone with network access to obtain substitutes from it. This means
3663 that any machine running Guix can also act as if it were a build farm,
3664 since the HTTP interface is compatible with Hydra, the software behind
3665 the @code{hydra.gnu.org} build farm.
3667 For security, each substitute is signed, allowing recipients to check
3668 their authenticity and integrity (@pxref{Substitutes}). Because
3669 @command{guix publish} uses the system's signing key, which is only
3670 readable by the system administrator, it must be started as root; the
3671 @code{--user} option makes it drop root privileges early on.
3673 The general syntax is:
3676 guix publish @var{options}@dots{}
3679 Running @command{guix publish} without any additional arguments will
3680 spawn an HTTP server on port 8080:
3686 Once a publishing server has been authorized (@pxref{Invoking guix
3687 archive}), the daemon may download substitutes from it:
3690 guix-daemon --substitute-urls=http://example.org:8080
3693 The following options are available:
3696 @item --port=@var{port}
3697 @itemx -p @var{port}
3698 Listen for HTTP requests on @var{port}.
3700 @item --listen=@var{host}
3701 Listen on the network interface for @var{host}. The default is to
3702 accept connections from any interface.
3704 @item --user=@var{user}
3705 @itemx -u @var{user}
3706 Change privileges to @var{user} as soon as possible---i.e., once the
3707 server socket is open and the signing key has been read.
3709 @item --repl[=@var{port}]
3710 @itemx -r [@var{port}]
3711 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
3712 Reference Manual}) on @var{port} (37146 by default). This is used
3713 primarily for debugging a running @command{guix publish} server.
3716 @c *********************************************************************
3717 @node GNU Distribution
3718 @chapter GNU Distribution
3720 @cindex Guix System Distribution
3722 Guix comes with a distribution of the GNU system consisting entirely of
3723 free software@footnote{The term ``free'' here refers to the
3724 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
3725 users of that software}.}. The
3726 distribution can be installed on its own (@pxref{System Installation}),
3727 but it is also possible to install Guix as a package manager on top of
3728 an installed GNU/Linux system (@pxref{Installation}). To distinguish
3729 between the two, we refer to the standalone distribution as the Guix
3730 System Distribution, or GuixSD.
3732 The distribution provides core GNU packages such as GNU libc, GCC, and
3733 Binutils, as well as many GNU and non-GNU applications. The complete
3734 list of available packages can be browsed
3735 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
3736 running @command{guix package} (@pxref{Invoking guix package}):
3739 guix package --list-available
3742 Our goal has been to provide a practical 100% free software distribution of
3743 Linux-based and other variants of GNU, with a focus on the promotion and
3744 tight integration of GNU components, and an emphasis on programs and
3745 tools that help users exert that freedom.
3747 Packages are currently available on the following platforms:
3752 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
3755 Intel 32-bit architecture (IA32), Linux-Libre kernel;
3758 ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
3759 using the EABI hard-float ABI, and Linux-Libre kernel.
3761 @item mips64el-linux
3762 little-endian 64-bit MIPS processors, specifically the Loongson series,
3763 n32 application binary interface (ABI), and Linux-Libre kernel.
3767 GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
3770 For information on porting to other architectures or kernels,
3774 * System Installation:: Installing the whole operating system.
3775 * System Configuration:: Configuring the operating system.
3776 * Installing Debugging Files:: Feeding the debugger.
3777 * Security Updates:: Deploying security fixes quickly.
3778 * Package Modules:: Packages from the programmer's viewpoint.
3779 * Packaging Guidelines:: Growing the distribution.
3780 * Bootstrapping:: GNU/Linux built from scratch.
3781 * Porting:: Targeting another platform or kernel.
3784 Building this distribution is a cooperative effort, and you are invited
3785 to join! @xref{Contributing}, for information about how you can help.
3787 @node System Installation
3788 @section System Installation
3790 @cindex Guix System Distribution
3791 This section explains how to install the Guix System Distribution
3792 on a machine. The Guix package manager can
3793 also be installed on top of a running GNU/Linux system,
3794 @pxref{Installation}.
3797 @c This paragraph is for people reading this from tty2 of the
3798 @c installation image.
3799 You're reading this documentation with an Info reader. For details on
3800 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
3801 link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
3802 @kbd{l} afterwards to come back here.
3805 @subsection Limitations
3807 As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
3808 not production-ready. It may contain bugs and lack important
3809 features. Thus, if you are looking for a stable production system that
3810 respects your freedom as a computer user, a good solution at this point
3811 is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
3812 more established GNU/Linux distributions}. We hope you can soon switch
3813 to the GuixSD without fear, of course. In the meantime, you can
3814 also keep using your distribution and try out the package manager on top
3815 of it (@pxref{Installation}).
3817 Before you proceed with the installation, be aware of the following
3818 noteworthy limitations applicable to version @value{VERSION}:
3822 The installation process does not include a graphical user interface and
3823 requires familiarity with GNU/Linux (see the following subsections to
3824 get a feel of what that means.)
3827 The system does not yet provide GNOME and KDE; it provides Xfce, though,
3828 if graphical desktop environments are your thing.
3831 Support for the Logical Volume Manager (LVM) is missing.
3834 Few system services are currently supported out-of-the-box
3838 On the order of 1,900 packages are available, which means that you may
3839 occasionally find that a useful package is missing.
3842 You've been warned. But more than a disclaimer, this is an invitation
3843 to report issues (and success stories!), and join us in improving it.
3844 @xref{Contributing}, for more info.
3846 @subsection USB Stick Installation
3848 An installation image for USB sticks can be downloaded from
3849 @indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
3850 where @var{system} is one of:
3854 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
3857 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
3860 This image contains a single partition with the tools necessary for an
3861 installation. It is meant to be copied @emph{as is} to a large-enough
3864 To copy the image to a USB stick, follow these steps:
3868 Decompress the image using the @command{xz} command:
3871 xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
3875 Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
3876 its device name. Assuming that USB stick is known as @file{/dev/sdX},
3877 copy the image with:
3880 dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
3883 Access to @file{/dev/sdX} usually requires root privileges.
3886 Once this is done, you should be able to reboot the system and boot from
3887 the USB stick. The latter usually requires you to get in the BIOS' boot
3888 menu, where you can choose to boot from the USB stick.
3890 @subsection Preparing for Installation
3892 Once you have successfully booted the image on the USB stick, you should
3893 end up with a root prompt. Several console TTYs are configured and can
3894 be used to run commands as root. TTY2 shows this documentation,
3895 browsable using the Info reader commands (@pxref{Help,,, info, Info: An
3898 To install the system, you would:
3903 Configure the network, by running @command{ifconfig eno1 up && dhclient
3904 eno1} (to get an automatically assigned IP address from the wired
3905 network interface controller@footnote{
3906 @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
3907 The name @code{eno1} is for the first on-board Ethernet controller. The
3908 interface name for an Ethernet controller that is in the first slot of
3909 the first PCI bus, for instance, would be @code{enp1s0}. Use
3910 @command{ifconfig -a} to list all the available network interfaces.}),
3911 or using the @command{ifconfig} command.
3913 The system automatically loads drivers for your network interface
3916 Setting up network access is almost always a requirement because the
3917 image does not contain all the software and tools that may be needed.
3920 Unless this has already been done, you must partition and format the
3923 Preferably, assign partitions a label so that you can easily and
3924 reliably refer to them in @code{file-system} declarations (@pxref{File
3925 Systems}). This is typically done using the @code{-L} option of
3926 @command{mkfs.ext4} and related commands.
3928 The installation image includes Parted (@pxref{Overview,,, parted, GNU
3929 Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
3930 encryption, and e2fsprogs, the suite of tools to manipulate
3931 ext2/ext3/ext4 file systems.
3934 Once that is done, mount the target root partition under @file{/mnt}.
3937 Lastly, run @code{deco start cow-store /mnt}.
3939 This will make @file{/gnu/store} copy-on-write, such that packages added
3940 to it during the installation phase will be written to the target disk
3941 rather than kept in memory.
3946 @subsection Proceeding with the Installation
3948 With the target partitions ready, you now have to edit a file and
3949 provide the declaration of the operating system to be installed. To
3950 that end, the installation system comes with two text editors: GNU nano
3951 (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
3952 It is better to store that file on the target root file system, say, as
3953 @file{/mnt/etc/config.scm}.
3955 @xref{Using the Configuration System}, for examples of operating system
3956 configurations. These examples are available under
3957 @file{/etc/configuration} in the installation image, so you can copy
3958 them and use them as a starting point for your own configuration.
3960 Once you are done preparing the configuration file, the new system must
3961 be initialized (remember that the target root file system is mounted
3965 guix system init /mnt/etc/config.scm /mnt
3969 This will copy all the necessary files, and install GRUB on
3970 @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
3971 more information, @pxref{Invoking guix system}. This command may trigger
3972 downloads or builds of missing packages, which can take some time.
3974 Once that command has completed---and hopefully succeeded!---you can
3975 run @command{reboot} and boot into the new system. Cross fingers, and
3976 join us on @code{#guix} on the Freenode IRC network or on
3977 @file{guix-devel@@gnu.org} to share your experience---good or not so
3980 @subsection Building the Installation Image
3982 The installation image described above was built using the @command{guix
3983 system} command, specifically:
3986 guix system disk-image --image-size=850MiB gnu/system/install.scm
3989 @xref{Invoking guix system}, for more information. See
3990 @file{gnu/system/install.scm} in the source tree for more information
3991 about the installation image.
3993 @node System Configuration
3994 @section System Configuration
3996 @cindex system configuration
3997 The Guix System Distribution supports a consistent whole-system configuration
3998 mechanism. By that we mean that all aspects of the global system
3999 configuration---such as the available system services, timezone and
4000 locale settings, user accounts---are declared in a single place. Such
4001 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
4003 One of the advantages of putting all the system configuration under the
4004 control of Guix is that it supports transactional system upgrades, and
4005 makes it possible to roll-back to a previous system instantiation,
4006 should something go wrong with the new one (@pxref{Features}). Another
4007 one is that it makes it easy to replicate the exact same configuration
4008 across different machines, or at different points in time, without
4009 having to resort to additional administration tools layered on top of
4010 the system's own tools.
4011 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
4013 This section describes this mechanism. First we focus on the system
4014 administrator's viewpoint---explaining how the system is configured and
4015 instantiated. Then we show how this mechanism can be extended, for
4016 instance to support new system services.
4019 * Using the Configuration System:: Customizing your GNU system.
4020 * operating-system Reference:: Detail of operating-system declarations.
4021 * File Systems:: Configuring file system mounts.
4022 * Mapped Devices:: Block device extra processing.
4023 * User Accounts:: Specifying user accounts.
4024 * Locales:: Language and cultural convention settings.
4025 * Services:: Specifying system services.
4026 * Setuid Programs:: Programs running with root privileges.
4027 * X.509 Certificates:: Authenticating HTTPS servers.
4028 * Name Service Switch:: Configuring libc's name service switch.
4029 * Initial RAM Disk:: Linux-Libre bootstrapping.
4030 * GRUB Configuration:: Configuring the boot loader.
4031 * Invoking guix system:: Instantiating a system configuration.
4032 * Defining Services:: Adding new service definitions.
4035 @node Using the Configuration System
4036 @subsection Using the Configuration System
4038 The operating system is configured by providing an
4039 @code{operating-system} declaration in a file that can then be passed to
4040 the @command{guix system} command (@pxref{Invoking guix system}). A
4041 simple setup, with the default system services, the default Linux-Libre
4042 kernel, initial RAM disk, and boot loader looks like this:
4044 @findex operating-system
4046 @include os-config-bare-bones.texi
4049 This example should be self-describing. Some of the fields defined
4050 above, such as @code{host-name} and @code{bootloader}, are mandatory.
4051 Others, such as @code{packages} and @code{services}, can be omitted, in
4052 which case they get a default value.
4054 @vindex %base-packages
4055 The @code{packages} field lists
4056 packages that will be globally visible on the system, for all user
4057 accounts---i.e., in every user's @code{PATH} environment variable---in
4058 addition to the per-user profiles (@pxref{Invoking guix package}). The
4059 @var{%base-packages} variable provides all the tools one would expect
4060 for basic user and administrator tasks---including the GNU Core
4061 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
4062 editor, @command{find}, @command{grep}, etc. The example above adds
4063 Emacs to those, taken from the @code{(gnu packages emacs)} module
4064 (@pxref{Package Modules}).
4066 @vindex %base-services
4067 The @code{services} field lists @dfn{system services} to be made
4068 available when the system starts (@pxref{Services}).
4069 The @code{operating-system} declaration above specifies that, in
4070 addition to the basic services, we want the @command{lshd} secure shell
4071 daemon listening on port 2222, and allowing remote @code{root} logins
4072 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
4073 @code{lsh-service} arranges so that @code{lshd} is started with the
4074 right command-line options, possibly with supporting configuration files
4075 generated as needed (@pxref{Defining Services}). @xref{operating-system
4076 Reference}, for details about the available @code{operating-system}
4079 The configuration for a typical ``desktop'' usage, with the X11 display
4080 server, a desktop environment, network management, an SSH server, and
4081 more, would look like this:
4084 @include os-config-desktop.texi
4087 @xref{Desktop Services}, for the exact list of services provided by
4088 @var{%desktop-services}. @xref{X.509 Certificates}, for background
4089 information about the @code{nss-certs} package that is used here.
4091 Assuming the above snippet is stored in the @file{my-system-config.scm}
4092 file, the @command{guix system reconfigure my-system-config.scm} command
4093 instantiates that configuration, and makes it the default GRUB boot
4094 entry (@pxref{Invoking guix system}). The normal way to change the
4095 system's configuration is by updating this file and re-running the
4096 @command{guix system} command.
4098 At the Scheme level, the bulk of an @code{operating-system} declaration
4099 is instantiated with the following monadic procedure (@pxref{The Store
4102 @deffn {Monadic Procedure} operating-system-derivation os
4103 Return a derivation that builds @var{os}, an @code{operating-system}
4104 object (@pxref{Derivations}).
4106 The output of the derivation is a single directory that refers to all
4107 the packages, configuration files, and other supporting files needed to
4108 instantiate @var{os}.
4111 @node operating-system Reference
4112 @subsection @code{operating-system} Reference
4114 This section summarizes all the options available in
4115 @code{operating-system} declarations (@pxref{Using the Configuration
4118 @deftp {Data Type} operating-system
4119 This is the data type representing an operating system configuration.
4120 By that, we mean all the global system configuration, not per-user
4121 configuration (@pxref{Using the Configuration System}).
4124 @item @code{kernel} (default: @var{linux-libre})
4125 The package object of the operating system to use@footnote{Currently
4126 only the Linux-libre kernel is supported. In the future, it will be
4127 possible to use the GNU@tie{}Hurd.}.
4129 @item @code{bootloader}
4130 The system bootloader configuration object. @xref{GRUB Configuration}.
4132 @item @code{initrd} (default: @code{base-initrd})
4133 A two-argument monadic procedure that returns an initial RAM disk for
4134 the Linux kernel. @xref{Initial RAM Disk}.
4136 @item @code{firmware} (default: @var{%base-firmware})
4138 List of firmware packages loadable by the operating system kernel.
4140 The default includes firmware needed for Atheros-based WiFi devices
4141 (Linux-libre module @code{ath9k}.)
4143 @item @code{host-name}
4146 @item @code{hosts-file}
4148 A zero-argument monadic procedure that returns a text file for use as
4149 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
4150 Reference Manual}). The default is to produce a file with entries for
4151 @code{localhost} and @var{host-name}.
4153 @item @code{mapped-devices} (default: @code{'()})
4154 A list of mapped devices. @xref{Mapped Devices}.
4156 @item @code{file-systems}
4157 A list of file systems. @xref{File Systems}.
4159 @item @code{swap-devices} (default: @code{'()})
4160 @cindex swap devices
4161 A list of strings identifying devices to be used for ``swap space''
4162 (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
4163 For example, @code{'("/dev/sda3")}.
4165 @item @code{users} (default: @code{'()})
4166 @itemx @code{groups} (default: @var{%base-groups})
4167 List of user accounts and groups. @xref{User Accounts}.
4169 @item @code{skeletons} (default: @code{(default-skeletons)})
4170 A monadic list of pairs of target file name and files. These are the
4171 files that will be used as skeletons as new accounts are created.
4173 For instance, a valid value may look like this:
4176 (mlet %store-monad ((bashrc (text-file "bashrc" "\
4177 export PATH=$HOME/.guix-profile/bin")))
4178 (return `((".bashrc" ,bashrc))))
4181 @item @code{issue} (default: @var{%default-issue})
4182 A string denoting the contents of the @file{/etc/issue} file, which is
4183 what displayed when users log in on a text console.
4185 @item @code{packages} (default: @var{%base-packages})
4186 The set of packages installed in the global profile, which is accessible
4187 at @file{/run/current-system/profile}.
4189 The default set includes core utilities, but it is good practice to
4190 install non-core utilities in user profiles (@pxref{Invoking guix
4193 @item @code{timezone}
4194 A timezone identifying string---e.g., @code{"Europe/Paris"}.
4196 @item @code{locale} (default: @code{"en_US.utf8"})
4197 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
4198 Library Reference Manual}). @xref{Locales}, for more information.
4200 @item @code{locale-definitions} (default: @var{%default-locale-definitions})
4201 The list of locale definitions to be compiled and that may be used at
4202 run time. @xref{Locales}.
4204 @item @code{name-service-switch} (default: @var{%default-nss})
4205 Configuration of libc's name service switch (NSS)---a
4206 @code{<name-service-switch>} object. @xref{Name Service Switch}, for
4209 @item @code{services} (default: @var{%base-services})
4210 A list of monadic values denoting system services. @xref{Services}.
4212 @item @code{pam-services} (default: @code{(base-pam-services)})
4214 @cindex pluggable authentication modules
4215 Linux @dfn{pluggable authentication module} (PAM) services.
4216 @c FIXME: Add xref to PAM services section.
4218 @item @code{setuid-programs} (default: @var{%setuid-programs})
4219 List of string-valued G-expressions denoting setuid programs.
4220 @xref{Setuid Programs}.
4222 @item @code{sudoers} (default: @var{%sudoers-specification})
4224 The contents of the @file{/etc/sudoers} file as a string.
4226 This file specifies which users can use the @command{sudo} command, what
4227 they are allowed to do, and what privileges they may gain. The default
4228 is that only @code{root} and members of the @code{wheel} group may use
4235 @subsection File Systems
4237 The list of file systems to be mounted is specified in the
4238 @code{file-systems} field of the operating system's declaration
4239 (@pxref{Using the Configuration System}). Each file system is declared
4240 using the @code{file-system} form, like this:
4244 (mount-point "/home")
4245 (device "/dev/sda3")
4249 As usual, some of the fields are mandatory---those shown in the example
4250 above---while others can be omitted. These are described below.
4252 @deftp {Data Type} file-system
4253 Objects of this type represent file systems to be mounted. They
4254 contain the following members:
4258 This is a string specifying the type of the file system---e.g.,
4261 @item @code{mount-point}
4262 This designates the place where the file system is to be mounted.
4265 This names the ``source'' of the file system. By default it is the name
4266 of a node under @file{/dev}, but its meaning depends on the @code{title}
4267 field described below.
4269 @item @code{title} (default: @code{'device})
4270 This is a symbol that specifies how the @code{device} field is to be
4273 When it is the symbol @code{device}, then the @code{device} field is
4274 interpreted as a file name; when it is @code{label}, then @code{device}
4275 is interpreted as a partition label name; when it is @code{uuid},
4276 @code{device} is interpreted as a partition unique identifier (UUID).
4278 The @code{label} and @code{uuid} options offer a way to refer to disk
4279 partitions without having to hard-code their actual device name.
4281 However, when a file system's source is a mapped device (@pxref{Mapped
4282 Devices}), its @code{device} field @emph{must} refer to the mapped
4283 device name---e.g., @file{/dev/mapper/root-partition}---and consequently
4284 @code{title} must be set to @code{'device}. This is required so that
4285 the system knows that mounting the file system depends on having the
4286 corresponding device mapping established.
4288 @item @code{flags} (default: @code{'()})
4289 This is a list of symbols denoting mount flags. Recognized flags
4290 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
4291 access to special files), @code{no-suid} (ignore setuid and setgid
4292 bits), and @code{no-exec} (disallow program execution.)
4294 @item @code{options} (default: @code{#f})
4295 This is either @code{#f}, or a string denoting mount options.
4297 @item @code{needed-for-boot?} (default: @code{#f})
4298 This Boolean value indicates whether the file system is needed when
4299 booting. If that is true, then the file system is mounted when the
4300 initial RAM disk (initrd) is loaded. This is always the case, for
4301 instance, for the root file system.
4303 @item @code{check?} (default: @code{#t})
4304 This Boolean indicates whether the file system needs to be checked for
4305 errors before being mounted.
4307 @item @code{create-mount-point?} (default: @code{#f})
4308 When true, the mount point is created if it does not exist yet.
4313 The @code{(gnu system file-systems)} exports the following useful
4316 @defvr {Scheme Variable} %base-file-systems
4317 These are essential file systems that are required on normal systems,
4318 such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
4319 below.) Operating system declarations should always contain at least
4323 @defvr {Scheme Variable} %devtmpfs-file-system
4324 The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
4325 requirement for udev (@pxref{Base Services, @code{udev-service}}).
4328 @defvr {Scheme Variable} %pseudo-terminal-file-system
4329 This is the file system to be mounted as @file{/dev/pts}. It supports
4330 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
4331 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
4332 Manual}). Pseudo-terminals are used by terminal emulators such as
4336 @defvr {Scheme Variable} %shared-memory-file-system
4337 This file system is mounted as @file{/dev/shm} and is used to support
4338 memory sharing across processes (@pxref{Memory-mapped I/O,
4339 @code{shm_open},, libc, The GNU C Library Reference Manual}).
4342 @defvr {Scheme Variable} %immutable-store
4343 This file system performs a read-only ``bind mount'' of
4344 @file{/gnu/store}, making it read-only for all the users including
4345 @code{root}. This prevents against accidental modification by software
4346 running as @code{root} or by system administrators.
4348 The daemon itself is still able to write to the store: it remounts it
4349 read-write in its own ``name space.''
4352 @defvr {Scheme Variable} %binary-format-file-system
4353 The @code{binfmt_misc} file system, which allows handling of arbitrary
4354 executable file types to be delegated to user space. This requires the
4355 @code{binfmt.ko} kernel module to be loaded.
4358 @defvr {Scheme Variable} %fuse-control-file-system
4359 The @code{fusectl} file system, which allows unprivileged users to mount
4360 and unmount user-space FUSE file systems. This requires the
4361 @code{fuse.ko} kernel module to be loaded.
4364 @node Mapped Devices
4365 @subsection Mapped Devices
4367 @cindex device mapping
4368 @cindex mapped devices
4369 The Linux kernel has a notion of @dfn{device mapping}: a block device,
4370 such as a hard disk partition, can be @dfn{mapped} into another device,
4371 with additional processing over the data that flows through
4372 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
4373 concept of a ``mapped device'' and that of a file system: both boil down
4374 to @emph{translating} input/output operations made on a file to
4375 operations on its backing store. Thus, the Hurd implements mapped
4376 devices, like file systems, using the generic @dfn{translator} mechanism
4377 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
4378 typical example is encryption device mapping: all writes to the mapped
4379 device are encrypted, and all reads are deciphered, transparently.
4381 Mapped devices are declared using the @code{mapped-device} form:
4385 (source "/dev/sda3")
4387 (type luks-device-mapping))
4391 @cindex disk encryption
4393 This example specifies a mapping from @file{/dev/sda3} to
4394 @file{/dev/mapper/home} using LUKS---the
4395 @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
4396 standard mechanism for disk encryption. The @file{/dev/mapper/home}
4397 device can then be used as the @code{device} of a @code{file-system}
4398 declaration (@pxref{File Systems}). The @code{mapped-device} form is
4401 @deftp {Data Type} mapped-device
4402 Objects of this type represent device mappings that will be made when
4403 the system boots up.
4407 This string specifies the name of the block device to be mapped, such as
4411 This string specifies the name of the mapping to be established. For
4412 example, specifying @code{"my-partition"} will lead to the creation of
4413 the @code{"/dev/mapper/my-partition"} device.
4416 This must be a @code{mapped-device-kind} object, which specifies how
4417 @var{source} is mapped to @var{target}.
4421 @defvr {Scheme Variable} luks-device-mapping
4422 This defines LUKS block device encryption using the @command{cryptsetup}
4423 command, from the same-named package. This relies on the
4424 @code{dm-crypt} Linux kernel module.
4428 @subsection User Accounts
4430 User accounts and groups are entirely managed through the
4431 @code{operating-system} declaration. They are specified with the
4432 @code{user-account} and @code{user-group} forms:
4438 (supplementary-groups '("wheel" ;allow use of sudo, etc.
4440 "video" ;video devices such as webcams
4441 "cdrom")) ;the good ol' CD-ROM
4442 (comment "Bob's sister")
4443 (home-directory "/home/alice"))
4446 When booting or upon completion of @command{guix system reconfigure},
4447 the system ensures that only the user accounts and groups specified in
4448 the @code{operating-system} declaration exist, and with the specified
4449 properties. Thus, account or group creations or modifications made by
4450 directly invoking commands such as @command{useradd} are lost upon
4451 reconfiguration or reboot. This ensures that the system remains exactly
4454 @deftp {Data Type} user-account
4455 Objects of this type represent user accounts. The following members may
4460 The name of the user account.
4463 This is the name (a string) or identifier (a number) of the user group
4464 this account belongs to.
4466 @item @code{supplementary-groups} (default: @code{'()})
4467 Optionally, this can be defined as a list of group names that this
4470 @item @code{uid} (default: @code{#f})
4471 This is the user ID for this account (a number), or @code{#f}. In the
4472 latter case, a number is automatically chosen by the system when the
4475 @item @code{comment} (default: @code{""})
4476 A comment about the account, such as the account's owner full name.
4478 @item @code{home-directory}
4479 This is the name of the home directory for the account.
4481 @item @code{shell} (default: Bash)
4482 This is a G-expression denoting the file name of a program to be used as
4483 the shell (@pxref{G-Expressions}).
4485 @item @code{system?} (default: @code{#f})
4486 This Boolean value indicates whether the account is a ``system''
4487 account. System accounts are sometimes treated specially; for instance,
4488 graphical login managers do not list them.
4490 @item @code{password} (default: @code{#f})
4491 You would normally leave this field to @code{#f}, initialize user
4492 passwords as @code{root} with the @command{passwd} command, and then let
4493 users change it with @command{passwd}. Passwords set with
4494 @command{passwd} are of course preserved across reboot and
4497 If you @emph{do} want to have a preset password for an account, then
4498 this field must contain the encrypted password, as a string.
4499 @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
4500 on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
4501 Manual}, for information on Guile's @code{crypt} procedure.
4506 User group declarations are even simpler:
4509 (user-group (name "students"))
4512 @deftp {Data Type} user-group
4513 This type is for, well, user groups. There are just a few fields:
4519 @item @code{id} (default: @code{#f})
4520 The group identifier (a number). If @code{#f}, a new number is
4521 automatically allocated when the group is created.
4523 @item @code{system?} (default: @code{#f})
4524 This Boolean value indicates whether the group is a ``system'' group.
4525 System groups have low numerical IDs.
4527 @item @code{password} (default: @code{#f})
4528 What, user groups can have a password? Well, apparently yes. Unless
4529 @code{#f}, this field specifies the group's password.
4534 For convenience, a variable lists all the basic user groups one may
4537 @defvr {Scheme Variable} %base-groups
4538 This is the list of basic user groups that users and/or packages expect
4539 to be present on the system. This includes groups such as ``root'',
4540 ``wheel'', and ``users'', as well as groups used to control access to
4541 specific devices such as ``audio'', ``disk'', and ``cdrom''.
4548 A @dfn{locale} defines cultural conventions for a particular language
4549 and region of the world (@pxref{Locales,,, libc, The GNU C Library
4550 Reference Manual}). Each locale has a name that typically has the form
4551 @code{@var{language}_@var{territory}.@var{charset}}---e.g.,
4552 @code{fr_LU.utf8} designates the locale for the French language, with
4553 cultural conventions from Luxembourg, and using the UTF-8 encoding.
4555 @cindex locale definition
4556 Usually, you will want to specify the default locale for the machine
4557 using the @code{locale} field of the @code{operating-system} declaration
4558 (@pxref{operating-system Reference, @code{locale}}).
4560 That locale must be among the @dfn{locale definitions} that are known to
4561 the system---and these are specified in the @code{locale-definitions}
4562 slot of @code{operating-system}. The default value includes locale
4563 definition for some widely used locales, but not for all the available
4564 locales, in order to save space.
4566 If the locale specified in the @code{locale} field is not among the
4567 definitions listed in @code{locale-definitions}, @command{guix system}
4568 raises an error. In that case, you should add the locale definition to
4569 the @code{locale-definitions} field. For instance, to add the North
4570 Frisian locale for Germany, the value of that field may be:
4573 (cons (locale-definition
4574 (name "fy_DE.utf8") (source "fy_DE"))
4575 %default-locale-definitions)
4578 Likewise, to save space, one might want @code{locale-definitions} to
4579 list only the locales that are actually used, as in:
4582 (list (locale-definition
4583 (name "ja_JP.eucjp") (source "ja_JP")
4584 (charset "EUC-JP")))
4587 The @code{locale-definition} form is provided by the @code{(gnu system
4588 locale)} module. Details are given below.
4590 @deftp {Data Type} locale-definition
4591 This is the data type of a locale definition.
4596 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
4597 Reference Manual}, for more information on locale names.
4600 The name of the source for that locale. This is typically the
4601 @code{@var{language}_@var{territory}} part of the locale name.
4603 @item @code{charset} (default: @code{"UTF-8"})
4604 The ``character set'' or ``code set'' for that locale,
4605 @uref{http://www.iana.org/assignments/character-sets, as defined by
4611 @defvr {Scheme Variable} %default-locale-definitions
4612 An arbitrary list of commonly used locales, used as the default value of
4613 the @code{locale-definitions} field of @code{operating-system}
4618 @subsection Services
4620 @cindex system services
4621 An important part of preparing an @code{operating-system} declaration is
4622 listing @dfn{system services} and their configuration (@pxref{Using the
4623 Configuration System}). System services are typically daemons launched
4624 when the system boots, or other actions needed at that time---e.g.,
4625 configuring network access.
4627 Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
4628 dmd Manual}). On a running system, the @command{deco} command allows
4629 you to list the available services, show their status, start and stop
4630 them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
4631 Manual}). For example:
4637 The above command, run as @code{root}, lists the currently defined
4638 services. The @command{deco doc} command shows a synopsis of the given
4643 Run libc's name service cache daemon (nscd).
4646 The @command{start}, @command{stop}, and @command{restart} sub-commands
4647 have the effect you would expect. For instance, the commands below stop
4648 the nscd service and restart the Xorg display server:
4652 Service nscd has been stopped.
4653 # deco restart xorg-server
4654 Service xorg-server has been stopped.
4655 Service xorg-server has been started.
4658 The following sections document the available services, starting with
4659 the core services, that may be used in an @code{operating-system}
4663 * Base Services:: Essential system services.
4664 * Networking Services:: Network setup, SSH daemon, etc.
4665 * X Window:: Graphical display.
4666 * Desktop Services:: D-Bus and desktop services.
4667 * Database Services:: SQL databases.
4668 * Various Services:: Other services.
4672 @subsubsection Base Services
4674 The @code{(gnu services base)} module provides definitions for the basic
4675 services that one expects from the system. The services exported by
4676 this module are listed below.
4678 @defvr {Scheme Variable} %base-services
4679 This variable contains a list of basic services@footnote{Technically,
4680 this is a list of monadic services. @xref{The Store Monad}.} one would
4681 expect from the system: a login service (mingetty) on each tty, syslogd,
4682 libc's name service cache daemon (nscd), the udev device manager, and
4685 This is the default value of the @code{services} field of
4686 @code{operating-system} declarations. Usually, when customizing a
4687 system, you will want to append services to @var{%base-services}, like
4691 (cons* (avahi-service) (lsh-service) %base-services)
4695 @deffn {Monadic Procedure} host-name-service @var{name}
4696 Return a service that sets the host name to @var{name}.
4699 @deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
4700 [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
4701 [#:allow-empty-passwords? #f]
4702 Return a service to run mingetty on @var{tty}.
4704 When @var{allow-empty-passwords?} is true, allow empty log-in password. When
4705 @var{auto-login} is true, it must be a user name under which to log-in
4706 automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
4707 @var{auto-login}, in which case the user will have to press a key before the
4708 login shell is launched.
4710 When true, @var{login-program} is a gexp or a monadic gexp denoting the name
4711 of the log-in program (the default is the @code{login} program from the Shadow
4714 @var{motd} is a monadic value containing a text file to use as
4715 the ``message of the day''.
4718 @cindex name service cache daemon
4720 @deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
4721 [#:name-services '()]
4722 Return a service that runs libc's name service cache daemon (nscd) with
4723 the given @var{config}---an @code{<nscd-configuration>} object.
4724 Optionally, @code{#:name-services} is a list of packages that provide
4725 name service switch (NSS) modules needed by nscd. @xref{Name Service
4726 Switch}, for an example.
4729 @defvr {Scheme Variable} %nscd-default-configuration
4730 This is the default @code{<nscd-configuration>} value (see below) used
4731 by @code{nscd-service}. This uses the caches defined by
4732 @var{%nscd-default-caches}; see below.
4735 @deftp {Data Type} nscd-configuration
4736 This is the type representing the name service cache daemon (nscd)
4741 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
4742 Name of nscd's log file. This is where debugging output goes when
4743 @code{debug-level} is strictly positive.
4745 @item @code{debug-level} (default: @code{0})
4746 Integer denoting the debugging levels. Higher numbers mean more
4747 debugging output is logged.
4749 @item @code{caches} (default: @var{%nscd-default-caches})
4750 List of @code{<nscd-cache>} objects denoting things to be cached; see
4756 @deftp {Data Type} nscd-cache
4757 Data type representing a cache database of nscd and its parameters.
4761 @item @code{database}
4762 This is a symbol representing the name of the database to be cached.
4763 Valid values are @code{passwd}, @code{group}, @code{hosts}, and
4764 @code{services}, which designate the corresponding NSS database
4765 (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
4767 @item @code{positive-time-to-live}
4768 @itemx @code{negative-time-to-live} (default: @code{20})
4769 A number representing the number of seconds during which a positive or
4770 negative lookup result remains in cache.
4772 @item @code{check-files?} (default: @code{#t})
4773 Whether to check for updates of the files corresponding to
4776 For instance, when @var{database} is @code{hosts}, setting this flag
4777 instructs nscd to check for updates in @file{/etc/hosts} and to take
4780 @item @code{persistent?} (default: @code{#t})
4781 Whether the cache should be stored persistently on disk.
4783 @item @code{shared?} (default: @code{#t})
4784 Whether the cache should be shared among users.
4786 @item @code{max-database-size} (default: 32@tie{}MiB)
4787 Maximum size in bytes of the database cache.
4789 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
4790 @c settings, so leave them out.
4795 @defvr {Scheme Variable} %nscd-default-caches
4796 List of @code{<nscd-cache>} objects used by default by
4797 @code{nscd-configuration} (see above.)
4799 It enables persistent and aggressive caching of service and host name
4800 lookups. The latter provides better host name lookup performance,
4801 resilience in the face of unreliable name servers, and also better
4802 privacy---often the result of host name lookups is in local cache, so
4803 external name servers do not even need to be queried.
4807 @deffn {Monadic Procedure} syslog-service [#:config-file #f]
4808 Return a service that runs @code{syslogd}. If configuration file name
4809 @var{config-file} is not specified, use some reasonable default
4813 @deffn {Monadic Procedure} guix-service [#:guix guix] @
4814 [#:builder-group "guixbuild"] [#:build-accounts 10] @
4815 [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
4816 [#:extra-options '()]
4817 Return a service that runs the build daemon from @var{guix}, and has
4818 @var{build-accounts} user accounts available under @var{builder-group}.
4820 When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
4821 provided by @var{guix} is authorized upon activation, meaning that substitutes
4822 from @code{hydra.gnu.org} are used by default.
4824 If @var{use-substitutes?} is false, the daemon is run with
4825 @option{--no-substitutes} (@pxref{Invoking guix-daemon,
4826 @option{--no-substitutes}}).
4828 Finally, @var{extra-options} is a list of additional command-line options
4829 passed to @command{guix-daemon}.
4832 @deffn {Monadic Procedure} udev-service [#:udev udev]
4833 Run @var{udev}, which populates the @file{/dev} directory dynamically.
4836 @deffn {Monadic Procedure} console-keymap-service @var{file}
4837 Return a service to load console keymap from @var{file} using
4838 @command{loadkeys} command.
4842 @node Networking Services
4843 @subsubsection Networking Services
4845 The @code{(gnu services networking)} module provides services to configure
4846 the network interface.
4848 @cindex DHCP, networking service
4849 @deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
4850 Return a service that runs @var{dhcp}, a Dynamic Host Configuration
4851 Protocol (DHCP) client, on all the non-loopback network interfaces.
4854 @deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
4855 [#:gateway #f] [#:name-services @code{'()}]
4856 Return a service that starts @var{interface} with address @var{ip}. If
4857 @var{gateway} is true, it must be a string specifying the default network
4862 @deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
4863 Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
4864 network manager that aims to simplify wired and wireless networking.
4867 @deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
4868 [#:name-service @var{%ntp-servers}]
4869 Return a service that runs the daemon from @var{ntp}, the
4870 @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
4871 keep the system clock synchronized with that of @var{servers}.
4874 @defvr {Scheme Variable} %ntp-servers
4875 List of host names used as the default NTP servers.
4878 @deffn {Monadic Procedure} tor-service [#:tor tor]
4879 Return a service to run the @uref{https://torproject.org,Tor} daemon.
4881 The daemon runs with the default settings (in particular the default exit
4882 policy) as the @code{tor} unprivileged user.
4885 @deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
4886 [#:interface "127.0.0.1"] [#:port 6667] @
4887 [#:extra-settings ""]
4888 Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
4889 acts as a gateway between IRC and chat networks.
4891 The daemon will listen to the interface corresponding to the IP address
4892 specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
4893 local clients can connect, whereas @code{0.0.0.0} means that connections can
4894 come from any networking interface.
4896 In addition, @var{extra-settings} specifies a string to append to the
4900 Furthermore, @code{(gnu services ssh)} provides the following service.
4902 @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
4903 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
4904 [#:allow-empty-passwords? #f] [#:root-login? #f] @
4905 [#:syslog-output? #t] [#:x11-forwarding? #t] @
4906 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
4907 [#:public-key-authentication? #t] [#:initialize? #t]
4908 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
4909 @var{host-key} must designate a file containing the host key, and readable
4912 When @var{daemonic?} is true, @command{lshd} will detach from the
4913 controlling terminal and log its output to syslogd, unless one sets
4914 @var{syslog-output?} to false. Obviously, it also makes lsh-service
4915 depend on existence of syslogd service. When @var{pid-file?} is true,
4916 @command{lshd} writes its PID to the file called @var{pid-file}.
4918 When @var{initialize?} is true, automatically create the seed and host key
4919 upon service activation if they do not exist yet. This may take long and
4920 require interaction.
4922 When @var{initialize?} is false, it is up to the user to initialize the
4923 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
4924 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
4925 basics,,, lsh, LSH Manual}).
4927 When @var{interfaces} is empty, lshd listens for connections on all the
4928 network interfaces; otherwise, @var{interfaces} must be a list of host names
4931 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
4932 passwords, and @var{root-login?} specifies whether to accept log-ins as
4935 The other options should be self-descriptive.
4938 @defvr {Scheme Variable} %facebook-host-aliases
4939 This variable contains a string for use in @file{/etc/hosts}
4940 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
4941 line contains a entry that maps a known server name of the Facebook
4942 on-line service---e.g., @code{www.facebook.com}---to the local
4943 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
4945 This variable is typically used in the @code{hosts-file} field of an
4946 @code{operating-system} declaration (@pxref{operating-system Reference,
4947 @file{/etc/hosts}}):
4950 (use-modules (gnu) (guix))
4953 (host-name "mymachine")
4956 ;; Create a /etc/hosts file with aliases for "localhost"
4957 ;; and "mymachine", as well as for Facebook servers.
4959 (string-append (local-host-aliases host-name)
4960 %facebook-host-aliases))))
4963 This mechanism can prevent programs running locally, such as Web
4964 browsers, from accessing Facebook.
4967 The @code{(gnu services avahi)} provides the following definition.
4969 @deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
4970 [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
4971 [#:ipv6? #t] [#:wide-area? #f] @
4972 [#:domains-to-browse '()]
4973 Return a service that runs @command{avahi-daemon}, a system-wide
4974 mDNS/DNS-SD responder that allows for service discovery and
4975 "zero-configuration" host name lookups (see @uref{http://avahi.org/}).
4977 If @var{host-name} is different from @code{#f}, use that as the host name to
4978 publish for this machine; otherwise, use the machine's actual host name.
4980 When @var{publish?} is true, publishing of host names and services is allowed;
4981 in particular, avahi-daemon will publish the machine's host name and IP
4982 address via mDNS on the local network.
4984 When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
4986 Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
4992 @subsubsection X Window
4994 Support for the X Window graphical display system---specifically
4995 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
4996 there is no @code{xorg-service} procedure. Instead, the X server is
4997 started by the @dfn{login manager}, currently SLiM.
4999 @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
5000 [#:auto-login? #f] [#:default-user ""] [#:startx] @
5001 [#:theme @var{%default-slim-theme}] @
5002 [#:theme-name @var{%default-slim-theme-name}]
5003 Return a service that spawns the SLiM graphical login manager, which in
5004 turn starts the X display server with @var{startx}, a command as returned by
5005 @code{xorg-start-command}.
5009 SLiM automatically looks for session types described by the @file{.desktop}
5010 files in @file{/run/current-system/profile/share/xsessions} and allows users
5011 to choose a session from the log-in screen using @kbd{F1}. Packages such as
5012 @var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
5013 adding them to the system-wide set of packages automatically makes them
5014 available at the log-in screen.
5016 In addition, @file{~/.xsession} files are honored. When available,
5017 @file{~/.xsession} must be an executable that starts a window manager
5018 and/or other X clients.
5020 When @var{allow-empty-passwords?} is true, allow logins with an empty
5021 password. When @var{auto-login?} is true, log in automatically as
5024 If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
5025 @var{theme} must be a gexp denoting the name of a directory containing the
5026 theme to use. In that case, @var{theme-name} specifies the name of the
5030 @defvr {Scheme Variable} %default-theme
5031 @defvrx {Scheme Variable} %default-theme-name
5032 The G-Expression denoting the default SLiM theme and its name.
5035 @deffn {Monadic Procedure} xorg-start-command [#:guile] @
5036 [#:drivers '()] [#:resolutions '()] [#:xorg-server @var{xorg-server}]
5037 Return a derivation that builds a @var{guile} script to start the X server
5038 from @var{xorg-server}. Usually the X server is started by a login manager.
5040 @var{drivers} must be either the empty list, in which case Xorg chooses a
5041 graphics driver automatically, or a list of driver names that will be tried in
5042 this order---e.g., @code{("modesetting" "vesa")}.
5044 Likewise, when @var{resolutions} is the empty list, Xorg chooses an
5045 appropriate screen resolution; otherwise, it must be a list of
5046 resolutions---e.g., @code{((1024 768) (640 480))}.
5049 @node Desktop Services
5050 @subsubsection Desktop Services
5052 The @code{(gnu services desktop)} module provides services that are
5053 usually useful in the context of a ``desktop'' setup---that is, on a
5054 machine running a graphical display server, possibly with graphical user
5057 To simplify things, the module defines a variable containing the set of
5058 services that users typically expect on a machine with a graphical
5059 environment and networking:
5061 @defvr {Scheme Variable} %desktop-services
5062 This is a list of services that builds upon @var{%base-services} and
5063 adds or adjust services for a typical ``desktop'' setup.
5065 In particular, it adds a graphical login manager (@pxref{X Window,
5066 @code{slim-service}}), a network management tool (@pxref{Networking
5067 Services, @code{wicd-service}}), energy and color management services,
5068 an NTP client and an SSH server (@pxref{Networking Services}), the Avahi
5069 daemon, and has the name service switch service configured to be able to
5070 use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
5073 The @var{%desktop-services} variable can be used as the @code{services}
5074 field of an @code{operating-system} declaration (@pxref{operating-system
5075 Reference, @code{services}}).
5077 The actual service definitions provided by @code{(gnu services desktop)}
5078 are described below.
5080 @deffn {Monadic Procedure} dbus-service @var{services} @
5082 Return a service that runs the ``system bus'', using @var{dbus}, with
5083 support for @var{services}.
5085 @uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
5086 facility. Its system bus is used to allow system services to communicate
5087 and be notified of system-wide events.
5089 @var{services} must be a list of packages that provide an
5090 @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
5091 and policy files. For example, to allow avahi-daemon to use the system bus,
5092 @var{services} must be equal to @code{(list avahi)}.
5095 @deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
5096 [#:watts-up-pro? #f] @
5097 [#:poll-batteries? #t] @
5098 [#:ignore-lid? #f] @
5099 [#:use-percentage-for-policy? #f] @
5100 [#:percentage-low 10] @
5101 [#:percentage-critical 3] @
5102 [#:percentage-action 2] @
5104 [#:time-critical 300] @
5105 [#:time-action 120] @
5106 [#:critical-power-action 'hybrid-sleep]
5107 Return a service that runs @uref{http://upower.freedesktop.org/,
5108 @command{upowerd}}, a system-wide monitor for power consumption and battery
5109 levels, with the given configuration settings. It implements the
5110 @code{org.freedesktop.UPower} D-Bus interface, and is notably used by
5114 @deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
5115 Return a service that runs @command{colord}, a system service with a D-Bus
5116 interface to manage the color profiles of input and output devices such as
5117 screens and scanners. It is notably used by the GNOME Color Manager graphical
5118 tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
5119 site} for more information.
5122 @node Database Services
5123 @subsubsection Database Services
5125 The @code{(gnu services databases)} module provides the following service.
5127 @deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
5128 [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
5129 Return a service that runs @var{postgresql}, the PostgreSQL database
5132 The PostgreSQL daemon loads its runtime configuration from
5133 @var{config-file} and stores the database cluster in
5134 @var{data-directory}.
5137 @node Various Services
5138 @subsubsection Various Services
5140 The @code{(gnu services lirc)} module provides the following service.
5142 @deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
5143 [#:device #f] [#:driver #f] [#:config-file #f] @
5144 [#:extra-options '()]
5145 Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
5146 decodes infrared signals from remote controls.
5148 Optionally, @var{device}, @var{driver} and @var{config-file}
5149 (configuration file name) may be specified. See @command{lircd} manual
5152 Finally, @var{extra-options} is a list of additional command-line options
5153 passed to @command{lircd}.
5157 @node Setuid Programs
5158 @subsection Setuid Programs
5160 @cindex setuid programs
5161 Some programs need to run with ``root'' privileges, even when they are
5162 launched by unprivileged users. A notorious example is the
5163 @command{passwd} programs, which can users can run to change their
5164 password, and which requires write access to the @file{/etc/passwd} and
5165 @file{/etc/shadow} files---something normally restricted to root, for
5166 obvious security reasons. To address that, these executables are
5167 @dfn{setuid-root}, meaning that they always run with root privileges
5168 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
5169 for more info about the setuid mechanisms.)
5171 The store itself @emph{cannot} contain setuid programs: that would be a
5172 security issue since any user on the system can write derivations that
5173 populate the store (@pxref{The Store}). Thus, a different mechanism is
5174 used: instead of changing the setuid bit directly on files that are in
5175 the store, we let the system administrator @emph{declare} which programs
5176 should be setuid root.
5178 The @code{setuid-programs} field of an @code{operating-system}
5179 declaration contains a list of G-expressions denoting the names of
5180 programs to be setuid-root (@pxref{Using the Configuration System}).
5181 For instance, the @command{passwd} program, which is part of the Shadow
5182 package, can be designated by this G-expression (@pxref{G-Expressions}):
5185 #~(string-append #$shadow "/bin/passwd")
5188 A default set of setuid programs is defined by the
5189 @code{%setuid-programs} variable of the @code{(gnu system)} module.
5191 @defvr {Scheme Variable} %setuid-programs
5192 A list of G-expressions denoting common programs that are setuid-root.
5194 The list includes commands such as @command{passwd}, @command{ping},
5195 @command{su}, and @command{sudo}.
5198 Under the hood, the actual setuid programs are created in the
5199 @file{/run/setuid-programs} directory at system activation time. The
5200 files in this directory refer to the ``real'' binaries, which are in the
5203 @node X.509 Certificates
5204 @subsection X.509 Certificates
5206 @cindex HTTPS, certificates
5207 @cindex X.509 certificates
5209 Web servers available over HTTPS (that is, HTTP over the transport-layer
5210 security mechanism, TLS) send client programs an @dfn{X.509 certificate}
5211 that the client can then use to @emph{authenticate} the server. To do
5212 that, clients verify that the server's certificate is signed by a
5213 so-called @dfn{certificate authority} (CA). But to verify the CA's
5214 signature, clients must have first acquired the CA's certificate.
5216 Web browsers such as GNU@tie{}IceCat include their own set of CA
5217 certificates, such that they are able to verify CA signatures
5220 However, most other programs that can talk HTTPS---@command{wget},
5221 @command{git}, @command{w3m}, etc.---need to be told where CA
5222 certificates can be found.
5224 @cindex @code{nss-certs}
5225 In GuixSD, this is done by adding a package that provides certificates
5226 to the @code{packages} field of the @code{operating-system} declaration
5227 (@pxref{operating-system Reference}). GuixSD includes one such package,
5228 @code{nss-certs}, which is a set of CA certificates provided as part of
5229 Mozilla's Network Security Services.
5231 Note that it is @emph{not} part of @var{%base-packages}, so you need to
5232 explicitly add it. The @file{/etc/ssl/certs} directory, which is where
5233 most applications and libraries look for certificates by default, points
5234 to the certificates installed globally.
5236 Unprivileged users can also install their own certificate package in
5237 their profile. A number of environment variables need to be defined so
5238 that applications and libraries know where to find them. Namely, the
5239 OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
5240 variables. Some applications add their own environment variables; for
5241 instance, the Git version control system honors the certificate bundle
5242 pointed to by the @code{GIT_SSL_CAINFO} environment variable.
5245 @node Name Service Switch
5246 @subsection Name Service Switch
5248 @cindex name service switch
5250 The @code{(gnu system nss)} module provides bindings to the
5251 configuration file of libc's @dfn{name service switch} or @dfn{NSS}
5252 (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
5253 Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
5254 extended with new ``name'' lookup methods for system databases, which
5255 includes host names, service names, user accounts, and more (@pxref{Name
5256 Service Switch, System Databases and Name Service Switch,, libc, The GNU
5257 C Library Reference Manual}).
5259 The NSS configuration specifies, for each system database, which lookup
5260 method is to be used, and how the various methods are chained
5261 together---for instance, under which circumstances NSS should try the
5262 next method in the list. The NSS configuration is given in the
5263 @code{name-service-switch} field of @code{operating-system} declarations
5264 (@pxref{operating-system Reference, @code{name-service-switch}}).
5267 @cindex .local, host name lookup
5268 As an example, the declaration below configures the NSS to use the
5269 @uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
5270 back-end}, which supports host name lookups over multicast DNS (mDNS)
5271 for host names ending in @code{.local}:
5274 (name-service-switch
5275 (hosts (list %files ;first, check /etc/hosts
5277 ;; If the above did not succeed, try
5278 ;; with 'mdns_minimal'.
5280 (name "mdns_minimal")
5282 ;; 'mdns_minimal' is authoritative for
5283 ;; '.local'. When it returns "not found",
5284 ;; no need to try the next methods.
5285 (reaction (lookup-specification
5286 (not-found => return))))
5288 ;; Then fall back to DNS.
5292 ;; Finally, try with the "full" 'mdns'.
5297 Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
5298 contains this configuration, so you won't have to type it if all you
5299 want is to have @code{.local} host lookup working.
5301 Note that, in this case, in addition to setting the
5302 @code{name-service-switch} of the @code{operating-system} declaration,
5303 @code{nscd-service} must be told where to find the @code{nss-mdns}
5304 shared library (@pxref{Base Services, @code{nscd-service}}). Since the
5305 @code{nscd} service is part of @var{%base-services}, you may want to
5306 customize it by adding this snippet in the operating system
5310 (use-modules (guix) (gnu))
5312 (define %my-base-services
5313 ;; Replace the default nscd service with one that knows
5315 (map (lambda (mservice)
5316 ;; "Bind" the MSERVICE monadic value to inspect it.
5317 (mlet %store-monad ((service mservice))
5318 (if (member 'nscd (service-provision service))
5319 (nscd-service (nscd-configuration)
5320 #:name-services (list nss-mdns))
5326 @dots{} and then refer to @var{%my-base-services} instead of
5327 @var{%base-services} in the @code{operating-system} declaration.
5328 Lastly, this relies on the availability of the Avahi service
5329 (@pxref{Networking Services, @code{avahi-service}}).
5331 For convenience, the following variables provide typical NSS
5334 @defvr {Scheme Variable} %default-nss
5335 This is the default name service switch configuration, a
5336 @code{name-service-switch} object.
5339 @defvr {Scheme Variable} %mdns-host-lookup-nss
5340 This is the name service switch configuration with support for host name
5341 lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
5344 The reference for name service switch configuration is given below. It
5345 is a direct mapping of the C library's configuration file format, so
5346 please refer to the C library manual for more information (@pxref{NSS
5347 Configuration File,,, libc, The GNU C Library Reference Manual}).
5348 Compared to libc's NSS configuration file format, it has the advantage
5349 not only of adding this warm parenthetic feel that we like, but also
5350 static checks: you'll know about syntax errors and typos as soon as you
5351 run @command{guix system}.
5353 @deftp {Data Type} name-service-switch
5355 This is the data type representation the configuration of libc's name
5356 service switch (NSS). Each field below represents one of the supported
5373 The system databases handled by the NSS. Each of these fields must be a
5374 list of @code{<name-service>} objects (see below.)
5378 @deftp {Data Type} name-service
5380 This is the data type representing an actual name service and the
5381 associated lookup action.
5385 A string denoting the name service (@pxref{Services in the NSS
5386 configuration,,, libc, The GNU C Library Reference Manual}).
5388 Note that name services listed here must be visible to nscd. This is
5389 achieved by passing the @code{#:name-services} argument to
5390 @code{nscd-service} the list of packages providing the needed name
5391 services (@pxref{Base Services, @code{nscd-service}}).
5394 An action specified using the @code{lookup-specification} macro
5395 (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
5396 Reference Manual}). For example:
5399 (lookup-specification (unavailable => continue)
5400 (success => return))
5405 @node Initial RAM Disk
5406 @subsection Initial RAM Disk
5408 @cindex initial RAM disk (initrd)
5409 @cindex initrd (initial RAM disk)
5410 For bootstrapping purposes, the Linux-Libre kernel is passed an
5411 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
5412 root file system, as well as an initialization script. The latter is
5413 responsible for mounting the real root file system, and for loading any
5414 kernel modules that may be needed to achieve that.
5416 The @code{initrd} field of an @code{operating-system} declaration allows
5417 you to specify which initrd you would like to use. The @code{(gnu
5418 system linux-initrd)} module provides two ways to build an initrd: the
5419 high-level @code{base-initrd} procedure, and the low-level
5420 @code{expression->initrd} procedure.
5422 The @code{base-initrd} procedure is intended to cover most common uses.
5423 For example, if you want to add a bunch of kernel modules to be loaded
5424 at boot time, you can define the @code{initrd} field of the operating
5425 system declaration like this:
5428 (initrd (lambda (file-systems . rest)
5429 ;; Create a standard initrd that has modules "foo.ko"
5430 ;; and "bar.ko", as well as their dependencies, in
5431 ;; addition to the modules available by default.
5432 (apply base-initrd file-systems
5433 #:extra-modules '("foo" "bar")
5437 The @code{base-initrd} procedure also handles common use cases that
5438 involves using the system as a QEMU guest, or as a ``live'' system whose
5439 root file system is volatile.
5441 @deffn {Monadic Procedure} base-initrd @var{file-systems} @
5442 [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
5443 [#:extra-modules '()] [#:mapped-devices '()]
5444 Return a monadic derivation that builds a generic initrd. @var{file-systems} is
5445 a list of file-systems to be mounted by the initrd, possibly in addition to
5446 the root file system specified on the kernel command line via @code{--root}.
5447 @var{mapped-devices} is a list of device mappings to realize before
5448 @var{file-systems} are mounted (@pxref{Mapped Devices}).
5450 When @var{qemu-networking?} is true, set up networking with the standard QEMU
5451 parameters. When @var{virtio?} is true, load additional modules so the initrd can
5452 be used as a QEMU guest with para-virtualized I/O drivers.
5454 When @var{volatile-root?} is true, the root file system is writable but any changes
5457 The initrd is automatically populated with all the kernel modules necessary
5458 for @var{file-systems} and for the given options. However, additional kernel
5459 modules can be listed in @var{extra-modules}. They will be added to the initrd, and
5460 loaded at boot time in the order in which they appear.
5463 Needless to say, the initrds we produce and use embed a
5464 statically-linked Guile, and the initialization program is a Guile
5465 program. That gives a lot of flexibility. The
5466 @code{expression->initrd} procedure builds such an initrd, given the
5467 program to run in that initrd.
5469 @deffn {Monadic Procedure} expression->initrd @var{exp} @
5470 [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
5472 Return a derivation that builds a Linux initrd (a gzipped cpio archive)
5473 containing @var{guile} and that evaluates @var{exp}, a G-expression,
5474 upon booting. All the derivations referenced by @var{exp} are
5475 automatically copied to the initrd.
5477 @var{modules} is a list of Guile module names to be embedded in the
5481 @node GRUB Configuration
5482 @subsection GRUB Configuration
5487 The operating system uses GNU@tie{}GRUB as its boot loader
5488 (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
5489 configured using @code{grub-configuration} declarations. This data type
5490 is exported by the @code{(gnu system grub)} module, and described below.
5492 @deftp {Data Type} grub-configuration
5493 The type of a GRUB configuration declaration.
5498 This is a string denoting the boot device. It must be a device name
5499 understood by the @command{grub-install} command, such as
5500 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
5503 @item @code{menu-entries} (default: @code{()})
5504 A possibly empty list of @code{menu-entry} objects (see below), denoting
5505 entries to appear in the GRUB boot menu, in addition to the current
5506 system entry and the entry pointing to previous system generations.
5508 @item @code{default-entry} (default: @code{0})
5509 The index of the default boot menu entry. Index 0 is for the current
5512 @item @code{timeout} (default: @code{5})
5513 The number of seconds to wait for keyboard input before booting. Set to
5514 0 to boot immediately, and to -1 to wait indefinitely.
5516 @item @code{theme} (default: @var{%default-theme})
5517 The @code{grub-theme} object describing the theme to use.
5522 Should you want to list additional boot menu entries @i{via} the
5523 @code{menu-entries} field above, you will need to create them with the
5524 @code{menu-entry} form:
5526 @deftp {Data Type} menu-entry
5527 The type of an entry in the GRUB boot menu.
5532 The label to show in the menu---e.g., @code{"GNU"}.
5535 The Linux kernel to boot.
5537 @item @code{linux-arguments} (default: @code{()})
5538 The list of extra Linux kernel command-line arguments---e.g.,
5539 @code{("console=ttyS0")}.
5542 A G-Expression or string denoting the file name of the initial RAM disk
5543 to use (@pxref{G-Expressions}).
5548 @c FIXME: Write documentation once it's stable.
5549 Themes are created using the @code{grub-theme} form, which is not
5552 @defvr {Scheme Variable} %default-theme
5553 This is the default GRUB theme used by the operating system, with a
5554 fancy background image displaying the GNU and Guix logos.
5558 @node Invoking guix system
5559 @subsection Invoking @code{guix system}
5561 Once you have written an operating system declaration, as seen in the
5562 previous section, it can be @dfn{instantiated} using the @command{guix
5563 system} command. The synopsis is:
5566 guix system @var{options}@dots{} @var{action} @var{file}
5569 @var{file} must be the name of a file containing an
5570 @code{operating-system} declaration. @var{action} specifies how the
5571 operating system is instantiate. Currently the following values are
5576 Build the operating system described in @var{file}, activate it, and
5577 switch to it@footnote{This action is usable only on systems already
5580 This effects all the configuration specified in @var{file}: user
5581 accounts, system services, global package list, setuid programs, etc.
5583 It also adds a GRUB menu entry for the new OS configuration, and moves
5584 entries for older configurations to a submenu---unless
5585 @option{--no-grub} is passed.
5587 @c The paragraph below refers to the problem discussed at
5588 @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
5589 It is highly recommended to run @command{guix pull} once before you run
5590 @command{guix system reconfigure} for the first time (@pxref{Invoking
5591 guix pull}). Failing to do that you would see an older version of Guix
5592 once @command{reconfigure} has completed.
5595 Build the operating system's derivation, which includes all the
5596 configuration files and programs needed to boot and run the system.
5597 This action does not actually install anything.
5600 Populate the given directory with all the files necessary to run the
5601 operating system specified in @var{file}. This is useful for first-time
5602 installations of GuixSD. For instance:
5605 guix system init my-os-config.scm /mnt
5608 copies to @file{/mnt} all the store items required by the configuration
5609 specified in @file{my-os-config.scm}. This includes configuration
5610 files, packages, and so on. It also creates other essential files
5611 needed for the system to operate correctly---e.g., the @file{/etc},
5612 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
5614 This command also installs GRUB on the device specified in
5615 @file{my-os-config}, unless the @option{--no-grub} option was passed.
5618 @cindex virtual machine
5620 Build a virtual machine that contain the operating system declared in
5621 @var{file}, and return a script to run that virtual machine (VM).
5622 Arguments given to the script are passed as is to QEMU.
5624 The VM shares its store with the host system.
5626 Additional file systems can be shared between the host and the VM using
5627 the @code{--share} and @code{--expose} command-line options: the former
5628 specifies a directory to be shared with write access, while the latter
5629 provides read-only access to the shared directory.
5631 The example below creates a VM in which the user's home directory is
5632 accessible read-only, and where the @file{/exchange} directory is a
5633 read-write mapping of the host's @file{$HOME/tmp}:
5636 guix system vm my-config.scm \
5637 --expose=$HOME --share=$HOME/tmp=/exchange
5640 On GNU/Linux, the default is to boot directly to the kernel; this has
5641 the advantage of requiring only a very tiny root disk image since the
5642 host's store can then be mounted.
5644 The @code{--full-boot} option forces a complete boot sequence, starting
5645 with the bootloader. This requires more disk space since a root image
5646 containing at least the kernel, initrd, and bootloader data files must
5647 be created. The @code{--image-size} option can be used to specify the
5652 Return a virtual machine or disk image of the operating system declared
5653 in @var{file} that stands alone. Use the @option{--image-size} option
5654 to specify the size of the image.
5656 When using @code{vm-image}, the returned image is in qcow2 format, which
5657 the QEMU emulator can efficiently use.
5659 When using @code{disk-image}, a raw disk image is produced; it can be
5660 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
5661 the device corresponding to a USB stick, one can copy the image on it
5662 using the following command:
5665 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
5670 @var{options} can contain any of the common build options provided by
5671 @command{guix build} (@pxref{Invoking guix build}). In addition,
5672 @var{options} can contain one of the following:
5675 @item --system=@var{system}
5676 @itemx -s @var{system}
5677 Attempt to build for @var{system} instead of the host's system type.
5678 This works as per @command{guix build} (@pxref{Invoking guix build}).
5680 @item --image-size=@var{size}
5681 For the @code{vm-image} and @code{disk-image} actions, create an image
5682 of the given @var{size}. @var{size} may be a number of bytes, or it may
5683 include a unit as a suffix (@pxref{Block size, size specifications,,
5684 coreutils, GNU Coreutils}).
5687 Note that all the actions above, except @code{build} and @code{init},
5688 rely on KVM support in the Linux-Libre kernel. Specifically, the
5689 machine should have hardware virtualization support, the corresponding
5690 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
5691 must exist and be readable and writable by the user and by the daemon's
5694 @node Defining Services
5695 @subsection Defining Services
5697 The @code{(gnu services @dots{})} modules define several procedures that allow
5698 users to declare the operating system's services (@pxref{Using the
5699 Configuration System}). These procedures are @emph{monadic
5700 procedures}---i.e., procedures that return a monadic value in the store
5701 monad (@pxref{The Store Monad}). For examples of such procedures,
5704 @cindex service definition
5705 The monadic value returned by those procedures is a @dfn{service
5706 definition}---a structure as returned by the @code{service} form.
5707 Service definitions specifies the inputs the service depends on, and an
5708 expression to start and stop the service. Behind the scenes, service
5709 definitions are ``translated'' into the form suitable for the
5710 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
5713 As an example, here is what the @code{nscd-service} procedure looks
5717 (define (nscd-service)
5718 (with-monad %store-monad
5720 (documentation "Run libc's name service cache daemon.")
5723 (use-modules (guix build utils))
5724 (mkdir-p "/var/run/nscd")))
5725 (start #~(make-forkexec-constructor
5726 (string-append #$glibc "/sbin/nscd")
5727 "-f" "/dev/null" "--foreground"))
5728 (stop #~(make-kill-destructor))
5733 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
5734 (@pxref{G-Expressions}). The @code{activate} field contains a script to
5735 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
5736 directory exists before @command{nscd} is started.
5738 The @code{start} and @code{stop} fields refer to dmd's facilities to
5739 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
5740 GNU dmd Manual}). The @code{provision} field specifies the name under
5741 which this service is known to dmd, and @code{documentation} specifies
5742 on-line documentation. Thus, the commands @command{deco start ncsd},
5743 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
5744 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
5747 @node Installing Debugging Files
5748 @section Installing Debugging Files
5750 @cindex debugging files
5751 Program binaries, as produced by the GCC compilers for instance, are
5752 typically written in the ELF format, with a section containing
5753 @dfn{debugging information}. Debugging information is what allows the
5754 debugger, GDB, to map binary code to source code; it is required to
5755 debug a compiled program in good conditions.
5757 The problem with debugging information is that is takes up a fair amount
5758 of disk space. For example, debugging information for the GNU C Library
5759 weighs in at more than 60 MiB. Thus, as a user, keeping all the
5760 debugging info of all the installed programs is usually not an option.
5761 Yet, space savings should not come at the cost of an impediment to
5762 debugging---especially in the GNU system, which should make it easier
5763 for users to exert their computing freedom (@pxref{GNU Distribution}).
5765 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
5766 mechanism that allows users to get the best of both worlds: debugging
5767 information can be stripped from the binaries and stored in separate
5768 files. GDB is then able to load debugging information from those files,
5769 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
5772 The GNU distribution takes advantage of this by storing debugging
5773 information in the @code{lib/debug} sub-directory of a separate package
5774 output unimaginatively called @code{debug} (@pxref{Packages with
5775 Multiple Outputs}). Users can choose to install the @code{debug} output
5776 of a package when they need it. For instance, the following command
5777 installs the debugging information for the GNU C Library and for GNU
5781 guix package -i glibc:debug guile:debug
5784 GDB must then be told to look for debug files in the user's profile, by
5785 setting the @code{debug-file-directory} variable (consider setting it
5786 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
5790 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
5793 From there on, GDB will pick up debugging information from the
5794 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
5796 In addition, you will most likely want GDB to be able to show the source
5797 code being debugged. To do that, you will have to unpack the source
5798 code of the package of interest (obtained with @code{guix build
5799 --source}, @pxref{Invoking guix build}), and to point GDB to that source
5800 directory using the @code{directory} command (@pxref{Source Path,
5801 @code{directory},, gdb, Debugging with GDB}).
5803 @c XXX: keep me up-to-date
5804 The @code{debug} output mechanism in Guix is implemented by the
5805 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
5806 opt-in---debugging information is available only for those packages
5807 whose definition explicitly declares a @code{debug} output. This may be
5808 changed to opt-out in the future, if our build farm servers can handle
5809 the load. To check whether a package has a @code{debug} output, use
5810 @command{guix package --list-available} (@pxref{Invoking guix package}).
5813 @node Security Updates
5814 @section Security Updates
5817 As of version @value{VERSION}, the feature described in this section is
5821 @cindex security updates
5822 Occasionally, important security vulnerabilities are discovered in core
5823 software packages and must be patched. Guix follows a functional
5824 package management discipline (@pxref{Introduction}), which implies
5825 that, when a package is changed, @emph{every package that depends on it}
5826 must be rebuilt. This can significantly slow down the deployment of
5827 fixes in core packages such as libc or Bash, since basically the whole
5828 distribution would need to be rebuilt. Using pre-built binaries helps
5829 (@pxref{Substitutes}), but deployment may still take more time than
5833 To address that, Guix implements @dfn{grafts}, a mechanism that allows
5834 for fast deployment of critical updates without the costs associated
5835 with a whole-distribution rebuild. The idea is to rebuild only the
5836 package that needs to be patched, and then to ``graft'' it onto packages
5837 explicitly installed by the user and that were previously referring to
5838 the original package. The cost of grafting is typically very low, and
5839 order of magnitudes lower than a full rebuild of the dependency chain.
5841 @cindex replacements of packages, for grafts
5842 For instance, suppose a security update needs to be applied to Bash.
5843 Guix developers will provide a package definition for the ``fixed''
5844 Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
5845 Packages}). Then, the original package definition is augmented with a
5846 @code{replacement} field pointing to the package containing the bug fix:
5853 (replacement bash-fixed)))
5856 From there on, any package depending directly or indirectly on Bash that
5857 is installed will automatically be ``rewritten'' to refer to
5858 @var{bash-fixed} instead of @var{bash}. This grafting process takes
5859 time proportional to the size of the package, but expect less than a
5860 minute for an ``average'' package on a recent machine.
5862 Currently, the graft and the package it replaces (@var{bash-fixed} and
5863 @var{bash} in the example above) must have the exact same @code{name}
5864 and @code{version} fields. This restriction mostly comes from the fact
5865 that grafting works by patching files, including binary files, directly.
5866 Other restrictions may apply: for instance, when adding a graft to a
5867 package providing a shared library, the original shared library and its
5868 replacement must have the same @code{SONAME} and be binary-compatible.
5871 @node Package Modules
5872 @section Package Modules
5874 From a programming viewpoint, the package definitions of the
5875 GNU distribution are provided by Guile modules in the @code{(gnu packages
5876 @dots{})} name space@footnote{Note that packages under the @code{(gnu
5877 packages @dots{})} module name space are not necessarily ``GNU
5878 packages''. This module naming scheme follows the usual Guile module
5879 naming convention: @code{gnu} means that these modules are distributed
5880 as part of the GNU system, and @code{packages} identifies modules that
5881 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
5882 Reference Manual}). For instance, the @code{(gnu packages emacs)}
5883 module exports a variable named @code{emacs}, which is bound to a
5884 @code{<package>} object (@pxref{Defining Packages}).
5886 The @code{(gnu packages @dots{})} module name space is
5887 automatically scanned for packages by the command-line tools. For
5888 instance, when running @code{guix package -i emacs}, all the @code{(gnu
5889 packages @dots{})} modules are scanned until one that exports a package
5890 object whose name is @code{emacs} is found. This package search
5891 facility is implemented in the @code{(gnu packages)} module.
5893 @cindex customization, of packages
5894 @cindex package module search path
5895 Users can store package definitions in modules with different
5896 names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
5897 name and module name must match. @xref{Modules and the File System,,,
5898 guile, GNU Guile Reference Manual}, for details.} These package definitions
5899 will not be visible by default. Thus, users can invoke commands such as
5900 @command{guix package} and @command{guix build} have to be used with the
5901 @code{-e} option so that they know where to find the package, or use the
5902 @code{-L} option of these commands to make those modules visible
5903 (@pxref{Invoking guix build, @code{--load-path}}), or define the
5904 @code{GUIX_PACKAGE_PATH} environment variable. This environment
5905 variable makes it easy to extend or customize the distribution and is
5906 honored by all the user interfaces.
5908 @defvr {Environment Variable} GUIX_PACKAGE_PATH
5909 This is a colon-separated list of directories to search for package
5910 modules. Directories listed in this variable take precedence over the
5911 distribution's own modules.
5914 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
5915 each package is built based solely on other packages in the
5916 distribution. The root of this dependency graph is a small set of
5917 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
5918 bootstrap)} module. For more information on bootstrapping,
5919 @pxref{Bootstrapping}.
5921 @node Packaging Guidelines
5922 @section Packaging Guidelines
5924 The GNU distribution is nascent and may well lack some of your favorite
5925 packages. This section describes how you can help make the distribution
5926 grow. @xref{Contributing}, for additional information on how you can
5929 Free software packages are usually distributed in the form of
5930 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
5931 all the source files. Adding a package to the distribution means
5932 essentially two things: adding a @dfn{recipe} that describes how to
5933 build the package, including a list of other packages required to build
5934 it, and adding @dfn{package meta-data} along with that recipe, such as a
5935 description and licensing information.
5937 In Guix all this information is embodied in @dfn{package definitions}.
5938 Package definitions provide a high-level view of the package. They are
5939 written using the syntax of the Scheme programming language; in fact,
5940 for each package we define a variable bound to the package definition,
5941 and export that variable from a module (@pxref{Package Modules}).
5942 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
5943 creating packages. For more information on package definitions,
5944 @pxref{Defining Packages}.
5946 Once a package definition is in place, stored in a file in the Guix
5947 source tree, it can be tested using the @command{guix build} command
5948 (@pxref{Invoking guix build}). For example, assuming the new package is
5949 called @code{gnew}, you may run this command from the Guix build tree:
5952 ./pre-inst-env guix build gnew --keep-failed
5955 Using @code{--keep-failed} makes it easier to debug build failures since
5956 it provides access to the failed build tree. Another useful
5957 command-line option when debugging is @code{--log-file}, to access the
5960 If the package is unknown to the @command{guix} command, it may be that
5961 the source file contains a syntax error, or lacks a @code{define-public}
5962 clause to export the package variable. To figure it out, you may load
5963 the module from Guile to get more information about the actual error:
5966 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
5969 Once your package builds correctly, please send us a patch
5970 (@pxref{Contributing}). Well, if you need help, we will be happy to
5971 help you too. Once the patch is committed in the Guix repository, the
5972 new package automatically gets built on the supported platforms by
5973 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
5977 Users can obtain the new package definition simply by running
5978 @command{guix pull} (@pxref{Invoking guix pull}). When
5979 @code{hydra.gnu.org} is done building the package, installing the
5980 package automatically downloads binaries from there
5981 (@pxref{Substitutes}). The only place where human intervention is
5982 needed is to review and apply the patch.
5986 * Software Freedom:: What may go into the distribution.
5987 * Package Naming:: What's in a name?
5988 * Version Numbers:: When the name is not enough.
5989 * Python Modules:: Taming the snake.
5990 * Perl Modules:: Little pearls.
5991 * Fonts:: Fond of fonts.
5994 @node Software Freedom
5995 @subsection Software Freedom
5997 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
5999 The GNU operating system has been developed so that users can have
6000 freedom in their computing. GNU is @dfn{free software}, meaning that
6001 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
6002 essential freedoms}: to run the program, to study and change the program
6003 in source code form, to redistribute exact copies, and to distribute
6004 modified versions. Packages found in the GNU distribution provide only
6005 software that conveys these four freedoms.
6007 In addition, the GNU distribution follow the
6008 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
6009 software distribution guidelines}. Among other things, these guidelines
6010 reject non-free firmware, recommendations of non-free software, and
6011 discuss ways to deal with trademarks and patents.
6013 Some packages contain a small and optional subset that violates the
6014 above guidelines, for instance because this subset is itself non-free
6015 code. When that happens, the offending items are removed with
6016 appropriate patches or code snippets in the package definition's
6017 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
6018 build --source} returns the ``freed'' source rather than the unmodified
6022 @node Package Naming
6023 @subsection Package Naming
6025 A package has actually two names associated with it:
6026 First, there is the name of the @emph{Scheme variable}, the one following
6027 @code{define-public}. By this name, the package can be made known in the
6028 Scheme code, for instance as input to another package. Second, there is
6029 the string in the @code{name} field of a package definition. This name
6030 is used by package management commands such as
6031 @command{guix package} and @command{guix build}.
6033 Both are usually the same and correspond to the lowercase conversion of
6034 the project name chosen upstream, with underscores replaced with
6035 hyphens. For instance, GNUnet is available as @code{gnunet}, and
6036 SDL_net as @code{sdl-net}.
6038 We do not add @code{lib} prefixes for library packages, unless these are
6039 already part of the official project name. But @pxref{Python
6040 Modules} and @ref{Perl Modules} for special rules concerning modules for
6041 the Python and Perl languages.
6043 Font package names are handled differently, @pxref{Fonts}.
6046 @node Version Numbers
6047 @subsection Version Numbers
6049 We usually package only the latest version of a given free software
6050 project. But sometimes, for instance for incompatible library versions,
6051 two (or more) versions of the same package are needed. These require
6052 different Scheme variable names. We use the name as defined
6053 in @ref{Package Naming}
6054 for the most recent version; previous versions use the same name, suffixed
6055 by @code{-} and the smallest prefix of the version number that may
6056 distinguish the two versions.
6058 The name inside the package definition is the same for all versions of a
6059 package and does not contain any version number.
6061 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
6069 (define-public gtk+-2
6075 If we also wanted GTK+ 3.8.2, this would be packaged as
6077 (define-public gtk+-3.8
6085 @node Python Modules
6086 @subsection Python Modules
6088 We currently package Python 2 and Python 3, under the Scheme variable names
6089 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
6090 To avoid confusion and naming clashes with other programming languages, it
6091 seems desirable that the name of a package for a Python module contains
6092 the word @code{python}.
6094 Some modules are compatible with only one version of Python, others with both.
6095 If the package Foo compiles only with Python 3, we name it
6096 @code{python-foo}; if it compiles only with Python 2, we name it
6097 @code{python2-foo}. If it is compatible with both versions, we create two
6098 packages with the corresponding names.
6100 If a project already contains the word @code{python}, we drop this;
6101 for instance, the module python-dateutil is packaged under the names
6102 @code{python-dateutil} and @code{python2-dateutil}.
6106 @subsection Perl Modules
6108 Perl programs standing for themselves are named as any other package,
6109 using the lowercase upstream name.
6110 For Perl packages containing a single class, we use the lowercase class name,
6111 replace all occurrences of @code{::} by dashes and prepend the prefix
6113 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
6114 Modules containing several classes keep their lowercase upstream name and
6115 are also prepended by @code{perl-}. Such modules tend to have the word
6116 @code{perl} somewhere in their name, which gets dropped in favor of the
6117 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
6123 For fonts that are in general not installed by a user for typesetting
6124 purposes, or that are distributed as part of a larger software package,
6125 we rely on the general packaging rules for software; for instance, this
6126 applies to the fonts delivered as part of the X.Org system or fonts that
6127 are part of TeX Live.
6129 To make it easier for a user to search for fonts, names for other packages
6130 containing only fonts are constructed as follows, independently of the
6131 upstream package name.
6133 The name of a package containing only one font family starts with
6134 @code{font-}; it is followed by the foundry name and a dash @code{-}
6135 if the foundry is known, and the font family name, in which spaces are
6136 replaced by dashes (and as usual, all upper case letters are transformed
6138 For example, the Gentium font family by SIL is packaged under the name
6139 @code{font-sil-gentium}.
6141 For a package containing several font families, the name of the collection
6142 is used in the place of the font family name.
6143 For instance, the Liberation fonts consist of three families,
6144 Liberation Sans, Liberation Serif and Liberation Mono.
6145 These could be packaged separately under the names
6146 @code{font-liberation-sans} and so on; but as they are distributed together
6147 under a common name, we prefer to package them together as
6148 @code{font-liberation}.
6150 In the case where several formats of the same font family or font collection
6151 are packaged separately, a short form of the format, prepended by a dash,
6152 is added to the package name. We use @code{-ttf} for TrueType fonts,
6153 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
6159 @section Bootstrapping
6161 @c Adapted from the ELS 2013 paper.
6163 @cindex bootstrapping
6165 Bootstrapping in our context refers to how the distribution gets built
6166 ``from nothing''. Remember that the build environment of a derivation
6167 contains nothing but its declared inputs (@pxref{Introduction}). So
6168 there's an obvious chicken-and-egg problem: how does the first package
6169 get built? How does the first compiler get compiled? Note that this is
6170 a question of interest only to the curious hacker, not to the regular
6171 user, so you can shamelessly skip this section if you consider yourself
6174 @cindex bootstrap binaries
6175 The GNU system is primarily made of C code, with libc at its core. The
6176 GNU build system itself assumes the availability of a Bourne shell and
6177 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
6178 `grep'. Furthermore, build programs---programs that run
6179 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
6180 (@pxref{Derivations}). Consequently, to be able to build anything at
6181 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
6182 Binutils, libc, and the other packages mentioned above---the
6183 @dfn{bootstrap binaries}.
6185 These bootstrap binaries are ``taken for granted'', though we can also
6186 re-create them if needed (more on that later).
6188 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
6190 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
6191 @c large image, it's hard to scroll. Oh well.
6192 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
6194 The figure above shows the very beginning of the dependency graph of the
6195 distribution, corresponding to the package definitions of the @code{(gnu
6196 packages bootstrap)} module. At this level of detail, things are
6197 slightly complex. First, Guile itself consists of an ELF executable,
6198 along with many source and compiled Scheme files that are dynamically
6199 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
6200 tarball shown in this graph. This tarball is part of Guix's ``source''
6201 distribution, and gets inserted into the store with @code{add-to-store}
6202 (@pxref{The Store}).
6204 But how do we write a derivation that unpacks this tarball and adds it
6205 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
6206 derivation---the first one that gets built---uses @code{bash} as its
6207 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
6208 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
6209 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
6210 the Guix source distribution, whose sole purpose is to allow the Guile
6211 tarball to be unpacked.
6213 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
6214 Guile that can be used to run subsequent build programs. Its first task
6215 is to download tarballs containing the other pre-built binaries---this
6216 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
6217 @code{ftp-client.scm} are used for this purpose. The
6218 @code{module-import.drv} derivations import those modules in a directory
6219 in the store, using the original layout. The
6220 @code{module-import-compiled.drv} derivations compile those modules, and
6221 write them in an output directory with the right layout. This
6222 corresponds to the @code{#:modules} argument of
6223 @code{build-expression->derivation} (@pxref{Derivations}).
6225 Finally, the various tarballs are unpacked by the
6226 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
6227 etc., at which point we have a working C tool chain.
6230 @unnumberedsubsec Building the Build Tools
6232 @c TODO: Add a package-level dependency graph generated from (gnu
6235 Bootstrapping is complete when we have a full tool chain that does not
6236 depend on the pre-built bootstrap tools discussed above. This
6237 no-dependency requirement is verified by checking whether the files of
6238 the final tool chain contain references to the @file{/gnu/store}
6239 directories of the bootstrap inputs. The process that leads to this
6240 ``final'' tool chain is described by the package definitions found in
6241 the @code{(gnu packages commencement)} module.
6243 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
6244 The first tool that gets built with the bootstrap binaries is
6245 GNU Make, which is a prerequisite for all the following packages.
6246 From there Findutils and Diffutils get built.
6248 Then come the first-stage Binutils and GCC, built as pseudo cross
6249 tools---i.e., with @code{--target} equal to @code{--host}. They are
6250 used to build libc. Thanks to this cross-build trick, this libc is
6251 guaranteed not to hold any reference to the initial tool chain.
6253 From there the final Binutils and GCC are built. GCC uses @code{ld}
6254 from the final Binutils, and links programs against the just-built libc.
6255 This tool chain is used to build the other packages used by Guix and by
6256 the GNU Build System: Guile, Bash, Coreutils, etc.
6258 And voilà! At this point we have the complete set of build tools that
6259 the GNU Build System expects. These are in the @code{%final-inputs}
6260 variable of the @code{(gnu packages commencement)} module, and are
6261 implicitly used by any package that uses @code{gnu-build-system}
6262 (@pxref{Build Systems, @code{gnu-build-system}}).
6265 @unnumberedsubsec Building the Bootstrap Binaries
6267 Because the final tool chain does not depend on the bootstrap binaries,
6268 those rarely need to be updated. Nevertheless, it is useful to have an
6269 automated way to produce them, should an update occur, and this is what
6270 the @code{(gnu packages make-bootstrap)} module provides.
6272 The following command builds the tarballs containing the bootstrap
6273 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
6274 of Coreutils and other basic command-line tools):
6277 guix build bootstrap-tarballs
6280 The generated tarballs are those that should be referred to in the
6281 @code{(gnu packages bootstrap)} module mentioned at the beginning of
6284 Still here? Then perhaps by now you've started to wonder: when do we
6285 reach a fixed point? That is an interesting question! The answer is
6286 unknown, but if you would like to investigate further (and have
6287 significant computational and storage resources to do so), then let us
6291 @section Porting to a New Platform
6293 As discussed above, the GNU distribution is self-contained, and
6294 self-containment is achieved by relying on pre-built ``bootstrap
6295 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
6296 operating system kernel, CPU architecture, and application binary
6297 interface (ABI). Thus, to port the distribution to a platform that is
6298 not yet supported, one must build those bootstrap binaries, and update
6299 the @code{(gnu packages bootstrap)} module to use them on that platform.
6301 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
6302 When everything goes well, and assuming the GNU tool chain supports the
6303 target platform, this can be as simple as running a command like this
6307 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
6310 For this to work, the @code{glibc-dynamic-linker} procedure in
6311 @code{(gnu packages bootstrap)} must be augmented to return the right
6312 file name for libc's dynamic linker on that platform; likewise,
6313 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
6314 taught about the new platform.
6316 Once these are built, the @code{(gnu packages bootstrap)} module needs
6317 to be updated to refer to these binaries on the target platform. That
6318 is, the hashes and URLs of the bootstrap tarballs for the new platform
6319 must be added alongside those of the currently supported platforms. The
6320 bootstrap Guile tarball is treated specially: it is expected to be
6321 available locally, and @file{gnu-system.am} has rules do download it for
6322 the supported architectures; a rule for the new platform must be added
6325 In practice, there may be some complications. First, it may be that the
6326 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
6327 above) is not recognized by all the GNU tools. Typically, glibc
6328 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
6329 configure flag (see @code{gcc.scm} for examples of how to handle this).
6330 Second, some of the required packages could fail to build for that
6331 platform. Lastly, the generated binaries could be broken for some
6335 @c *********************************************************************
6337 @chapter Contributing
6339 This project is a cooperative effort, and we need your help to make it
6340 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6341 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
6342 reports, patches, and anything that may be helpful to the project. We
6343 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
6346 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
6347 @file{HACKING} file} that comes with the Guix source code for practical
6348 details about contributions.
6351 @c *********************************************************************
6352 @node Acknowledgments
6353 @chapter Acknowledgments
6355 Guix is based on the Nix package manager, which was designed and
6356 implemented by Eelco Dolstra, with contributions from other people (see
6357 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
6358 management, and promoted unprecedented features, such as transactional
6359 package upgrades and rollbacks, per-user profiles, and referentially
6360 transparent build processes. Without this work, Guix would not exist.
6362 The Nix-based software distributions, Nixpkgs and NixOS, have also been
6363 an inspiration for Guix.
6365 GNU@tie{}Guix itself is a collective work with contributions from a
6366 number of people. See the @file{AUTHORS} file in Guix for more
6367 information on these fine people. The @file{THANKS} file lists people
6368 who have helped by reporting bugs, taking care of the infrastructure,
6369 providing artwork and themes, making suggestions, and more---thank you!
6372 @c *********************************************************************
6373 @node GNU Free Documentation License
6374 @appendix GNU Free Documentation License
6376 @include fdl-1.3.texi
6378 @c *********************************************************************
6380 @unnumbered Concept Index
6383 @node Programming Index
6384 @unnumbered Programming Index
6392 @c ispell-local-dictionary: "american";