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@*
16 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.3 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
22 copy of the license is included in the section entitled ``GNU Free
23 Documentation License''.
26 @dircategory Package management
28 * guix: (guix). Guix, the functional package manager.
29 * guix package: (guix)Invoking guix package
30 Managing packages with Guix.
31 * guix build: (guix)Invoking guix build
32 Building packages with Guix.
33 * guix system: (guix)Invoking guix system
34 Managing the operating system configuration.
37 @dircategory Software development
39 * guix environment: (guix)Invoking guix environment
40 Building development environments with Guix.
44 @title GNU Guix Reference Manual
45 @subtitle Using the GNU Guix Functional Package Manager
46 @author Ludovic Courtès
48 @author Nikita Karetnikov
51 @vskip 0pt plus 1filll
52 Edition @value{EDITION} @*
60 @c *********************************************************************
64 This document describes GNU Guix version @value{VERSION}, a functional
65 package management tool written for the GNU system.
68 * Introduction:: What is Guix about?
69 * Installation:: Installing Guix.
70 * Package Management:: Package installation, upgrade, etc.
71 * Programming Interface:: Using Guix in Scheme.
72 * Utilities:: Package management commands.
73 * GNU Distribution:: Software for your friendly GNU system.
74 * Contributing:: Your help needed!
76 * Acknowledgments:: Thanks!
77 * GNU Free Documentation License:: The license of this manual.
78 * Concept Index:: Concepts.
79 * Programming Index:: Data types, functions, and variables.
82 --- The Detailed Node Listing ---
86 * Binary Installation:: Getting Guix running in no time!
87 * Requirements:: Software needed to build and run Guix.
88 * Running the Test Suite:: Testing Guix.
89 * Setting Up the Daemon:: Preparing the build daemon's environment.
90 * Invoking guix-daemon:: Running the build daemon.
91 * Running Guix Before It Is Installed:: Hacker tricks.
95 * Build Environment Setup:: Preparing the isolated build environment.
96 * Daemon Offload Setup:: Offloading builds to remote machines.
100 * Features:: How Guix will make your life brighter.
101 * Invoking guix package:: Package installation, removal, etc.
102 * Emacs Interface:: Package management from Emacs.
103 * Substitutes:: Downloading pre-built binaries.
104 * Packages with Multiple Outputs:: Single source package, multiple outputs.
105 * Invoking guix gc:: Running the garbage collector.
106 * Invoking guix pull:: Fetching the latest Guix and distribution.
107 * Invoking guix archive:: Exporting and importing store files.
109 Programming Interface
111 * Defining Packages:: Defining new packages.
112 * Build Systems:: Specifying how packages are built.
113 * The Store:: Manipulating the package store.
114 * Derivations:: Low-level interface to package derivations.
115 * The Store Monad:: Purely functional interface to the store.
116 * G-Expressions:: Manipulating build expressions.
120 * package Reference:: The package data type.
121 * origin Reference:: The origin data type.
125 * Invoking guix build:: Building packages from the command line.
126 * Invoking guix download:: Downloading a file and printing its hash.
127 * Invoking guix hash:: Computing the cryptographic hash of a file.
128 * Invoking guix import:: Importing package definitions.
129 * Invoking guix refresh:: Updating package definitions.
130 * Invoking guix lint:: Finding errors in package definitions.
131 * Invoking guix environment:: Setting up development environments.
132 * Invoking guix publish:: Sharing substitutes.
136 * System Installation:: Installing the whole operating system.
137 * System Configuration:: Configuring the operating system.
138 * Installing Debugging Files:: Feeding the debugger.
139 * Security Updates:: Deploying security fixes quickly.
140 * Package Modules:: Packages from the programmer's viewpoint.
141 * Packaging Guidelines:: Growing the distribution.
142 * Bootstrapping:: GNU/Linux built from scratch.
143 * Porting:: Targeting another platform or kernel.
147 * Using the Configuration System:: Customizing your GNU system.
148 * operating-system Reference:: Detail of operating-system declarations.
149 * File Systems:: Configuring file system mounts.
150 * Mapped Devices:: Block device extra processing.
151 * User Accounts:: Specifying user accounts.
152 * Locales:: Language and cultural convention settings.
153 * Services:: Specifying system services.
154 * Setuid Programs:: Programs running with root privileges.
155 * X.509 Certificates:: Authenticating HTTPS servers.
156 * Name Service Switch:: Configuring libc's name service switch.
157 * Initial RAM Disk:: Linux-Libre bootstrapping.
158 * GRUB Configuration:: Configuring the boot loader.
159 * Invoking guix system:: Instantiating a system configuration.
160 * Defining Services:: Adding new service definitions.
164 * Base Services:: Essential system services.
165 * Networking Services:: Network setup, SSH daemon, etc.
166 * X Window:: Graphical display.
167 * Desktop Services:: D-Bus and desktop services.
168 * Database Services:: SQL databases.
169 * Various Services:: Other services.
173 * Software Freedom:: What may go into the distribution.
174 * Package Naming:: What's in a name?
175 * Version Numbers:: When the name is not enough.
176 * Python Modules:: Taming the snake.
177 * Perl Modules:: Little pearls.
178 * Fonts:: Fond of fonts.
183 @c *********************************************************************
185 @chapter Introduction
187 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
188 using the international phonetic alphabet (IPA).} is a functional
189 package management tool for the GNU system. Package management consists
190 of all activities that relate to building packages from sources,
191 honoring their build-time and run-time dependencies,
192 installing packages in user environments, upgrading installed packages
193 to new versions or rolling back to a previous set, removing unused
194 software packages, etc.
196 @cindex functional package management
197 The term @dfn{functional} refers to a specific package management
198 discipline. In Guix, the package build and installation process is seen
199 as a function, in the mathematical sense. That function takes inputs,
200 such as build scripts, a compiler, and libraries, and
201 returns an installed package. As a pure function, its result depends
202 solely on its inputs---for instance, it cannot refer to software or
203 scripts that were not explicitly passed as inputs. A build function
204 always produces the same result when passed a given set of inputs. It
205 cannot alter the system's environment in
206 any way; for instance, it cannot create, modify, or delete files outside
207 of its build and installation directories. This is achieved by running
208 build processes in isolated environments (or @dfn{containers}), where only their
209 explicit inputs are visible.
212 The result of package build functions is @dfn{cached} in the file
213 system, in a special directory called @dfn{the store} (@pxref{The
214 Store}). Each package is installed in a directory of its own, in the
215 store---by default under @file{/gnu/store}. The directory name contains
216 a hash of all the inputs used to build that package; thus, changing an
217 input yields a different directory name.
219 This approach is the foundation of Guix's salient features: support for
220 transactional package upgrade and rollback, per-user installation, and
221 garbage collection of packages (@pxref{Features}).
223 Guix has a command-line interface, which allows users to build, install,
224 upgrade, and remove packages, as well as a Scheme programming interface.
226 @cindex Guix System Distribution
228 Last but not least, Guix is used to build a distribution of the GNU
229 system, with many GNU and non-GNU free software packages. The Guix
230 System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
231 properties of Guix at the system level. With GuixSD, users
232 @emph{declare} all aspects of the operating system configuration, and
233 Guix takes care of instantiating that configuration in a reproducible,
234 stateless fashion. @xref{GNU Distribution}.
236 @c *********************************************************************
238 @chapter Installation
240 GNU Guix is available for download from its website at
241 @url{http://www.gnu.org/software/guix/}. This section describes the
242 software requirements of Guix, as well as how to install it and get
245 Note that this section is concerned with the installation of the package
246 manager, which can be done on top of a running GNU/Linux system. If,
247 instead, you want to install the complete GNU operating system,
248 @pxref{System Installation}.
251 * Binary Installation:: Getting Guix running in no time!
252 * Requirements:: Software needed to build and run Guix.
253 * Running the Test Suite:: Testing Guix.
254 * Setting Up the Daemon:: Preparing the build daemon's environment.
255 * Invoking guix-daemon:: Running the build daemon.
256 * Running Guix Before It Is Installed:: Hacker tricks.
259 @node Binary Installation
260 @section Binary Installation
262 This section describes how to install Guix on an arbitrary system from a
263 self-contained tarball providing binaries for Guix and for all its
264 dependencies. This is often quicker than installing from source, which
265 is described in the next sections. The only requirement is to have
268 Installing goes along these lines:
272 Download the binary tarball from
273 @indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
274 usual, make sure to download the associated @file{.sig} file and to
275 verify the authenticity of the tarball against it!}, where @var{system}
276 is @code{x86_64-linux} for an @code{x86_64} machine already running the
277 kernel Linux, and so on.
284 # tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
287 This creates @file{/gnu/store} (@pxref{The Store}), @file{/var/guix},
288 and @file{/root/.guix-profile}. @file{/root/.guix-profile} is a
289 ready-to-use profile for @code{root} where Guix is installed.
291 Do @emph{not} unpack the tarball on a working Guix system since that
292 would overwrite its own essential files.
298 # /root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
302 Make the @command{guix} command available to other users on the machine,
306 # mkdir -p /usr/local/bin
308 # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
312 To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
316 # guix archive --authorize < /root/.guix-profile/share/guix/hydra.gnu.org.pub
322 The @code{guix} package must remain available in @code{root}'s
323 profile, or it would become subject to garbage collection---in which
324 case you would find yourself badly handicapped by the lack of the
325 @command{guix} command.
327 The tarball in question can be (re)produced and verified simply by
328 running the following command in the Guix source tree:
331 make guix-binary.@var{system}.tar.xz
336 @section Requirements
338 This section lists requirements when building Guix from source. The
339 build procedure for Guix is the same as for other GNU software, and is
340 not covered here. Please see the files @file{README} and @file{INSTALL}
341 in the Guix source tree for additional details.
343 GNU Guix depends on the following packages:
346 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
347 @item @url{http://gnupg.org/, GNU libgcrypt};
348 @item @url{http://www.gnu.org/software/make/, GNU Make}.
351 The following dependencies are optional:
356 @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
357 allow you to use the @command{guix import pypi} command (@pxref{Invoking
358 guix import}). It is of
359 interest primarily for developers and not for casual users.
361 Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
362 allow you to access @code{https} URLs with the @command{guix download}
363 command (@pxref{Invoking guix download}), the @command{guix import pypi}
364 command, and the @command{guix import cpan} command. This is primarily
365 of interest to developers. @xref{Guile Preparations, how to install the
366 GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
369 Unless @code{--disable-daemon} was passed to @command{configure}, the
370 following packages are also needed:
373 @item @url{http://sqlite.org, SQLite 3};
374 @item @url{http://www.bzip.org, libbz2};
375 @item @url{http://gcc.gnu.org, GCC's g++}, with support for the
379 When a working installation of @url{http://nixos.org/nix/, the Nix package
380 manager} is available, you
381 can instead configure Guix with @code{--disable-daemon}. In that case,
382 Nix replaces the three dependencies above.
384 Guix is compatible with Nix, so it is possible to share the same store
385 between both. To do so, you must pass @command{configure} not only the
386 same @code{--with-store-dir} value, but also the same
387 @code{--localstatedir} value. The latter is essential because it
388 specifies where the database that stores metadata about the store is
389 located, among other things. The default values for Nix are
390 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
391 Note that @code{--disable-daemon} is not required if
392 your goal is to share the store with Nix.
394 @node Running the Test Suite
395 @section Running the Test Suite
397 After a successful @command{configure} and @code{make} run, it is a good
398 idea to run the test suite. It can help catch issues with the setup or
399 environment, or bugs in Guix itself---and really, reporting test
400 failures is a good way to help improve the software. To run the test
407 Test cases can run in parallel: you can use the @code{-j} option of
408 GNU@tie{}make to speed things up. The first run may take a few minutes
409 on a recent machine; subsequent runs will be faster because the store
410 that is created for test purposes will already have various things in
413 Upon failure, please email @email{bug-guix@@gnu.org} and attach the
414 @file{test-suite.log} file. When @file{tests/@var{something}.scm}
415 fails, please also attach the @file{@var{something}.log} file available
416 in the top-level build directory. Please specify the Guix version being
417 used as well as version numbers of the dependencies
418 (@pxref{Requirements}) in your message.
420 @node Setting Up the Daemon
421 @section Setting Up the Daemon
424 Operations such as building a package or running the garbage collector
425 are all performed by a specialized process, the @dfn{build daemon}, on
426 behalf of clients. Only the daemon may access the store and its
427 associated database. Thus, any operation that manipulates the store
428 goes through the daemon. For instance, command-line tools such as
429 @command{guix package} and @command{guix build} communicate with the
430 daemon (@i{via} remote procedure calls) to instruct it what to do.
432 The following sections explain how to prepare the build daemon's
433 environment. Also @ref{Substitutes}, for information on how to allow
434 the daemon to download pre-built binaries.
437 * Build Environment Setup:: Preparing the isolated build environment.
438 * Daemon Offload Setup:: Offloading builds to remote machines.
441 @node Build Environment Setup
442 @subsection Build Environment Setup
444 In a standard multi-user setup, Guix and its daemon---the
445 @command{guix-daemon} program---are installed by the system
446 administrator; @file{/gnu/store} is owned by @code{root} and
447 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
448 Guix tools to build packages or otherwise access the store, and the
449 daemon will do it on their behalf, ensuring that the store is kept in a
450 consistent state, and allowing built packages to be shared among users.
453 When @command{guix-daemon} runs as @code{root}, you may not want package
454 build processes themselves to run as @code{root} too, for obvious
455 security reasons. To avoid that, a special pool of @dfn{build users}
456 should be created for use by build processes started by the daemon.
457 These build users need not have a shell and a home directory: they will
458 just be used when the daemon drops @code{root} privileges in build
459 processes. Having several such users allows the daemon to launch
460 distinct build processes under separate UIDs, which guarantees that they
461 do not interfere with each other---an essential feature since builds are
462 regarded as pure functions (@pxref{Introduction}).
464 On a GNU/Linux system, a build user pool may be created like this (using
465 Bash syntax and the @code{shadow} commands):
467 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
468 @c for why `-G' is needed.
470 # groupadd --system guixbuild
471 # for i in `seq -w 1 10`;
473 useradd -g guixbuild -G guixbuild \
474 -d /var/empty -s `which nologin` \
475 -c "Guix build user $i" --system \
481 The number of build users determines how many build jobs may run in
482 parallel, as specified by the @option{--max-jobs} option
483 (@pxref{Invoking guix-daemon, @option{--max-jobs}}).
484 The @code{guix-daemon} program may then be run as @code{root} with:
487 # guix-daemon --build-users-group=guixbuild
492 This way, the daemon starts build processes in a chroot, under one of
493 the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
494 environment contains nothing but:
496 @c Keep this list in sync with libstore/build.cc! -----------------------
499 a minimal @code{/dev} directory, created mostly independently from the
500 host @code{/dev}@footnote{``Mostly'', because while the set of files
501 that appear in the chroot's @code{/dev} is fixed, most of these files
502 can only be created if the host has them.};
505 the @code{/proc} directory; it only shows the container's processes
506 since a separate PID name space is used;
509 @file{/etc/passwd} with an entry for the current user and an entry for
513 @file{/etc/group} with an entry for the user's group;
516 @file{/etc/hosts} with an entry that maps @code{localhost} to
520 a writable @file{/tmp} directory.
523 If you are installing Guix as an unprivileged user, it is still possible
524 to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
525 However, build processes will not be isolated from one another, and not
526 from the rest of the system. Thus, build processes may interfere with
527 each other, and may access programs, libraries, and other files
528 available on the system---making it much harder to view them as
529 @emph{pure} functions.
532 @node Daemon Offload Setup
533 @subsection Using the Offload Facility
537 When desired, the build daemon can @dfn{offload}
538 derivation builds to other machines
539 running Guix, using the @code{offload} @dfn{build hook}. When that
540 feature is enabled, a list of user-specified build machines is read from
541 @file{/etc/guix/machines.scm}; anytime a build is requested, for
542 instance via @code{guix build}, the daemon attempts to offload it to one
543 of the machines that satisfies the derivation's constraints, in
544 particular its system type---e.g., @file{x86_64-linux}. Missing
545 prerequisites for the build are copied over SSH to the target machine,
546 which then proceeds with the build; upon success the output(s) of the
547 build are copied back to the initial machine.
549 The @file{/etc/guix/machines.scm} file typically looks like this:
553 (name "eightysix.example.org")
554 (system "x86_64-linux")
556 (speed 2.)) ; incredibly fast!
559 (name "meeps.example.org")
560 (system "mips64el-linux")
563 (string-append (getenv "HOME")
564 "/.ssh/id-rsa-for-guix"))))
568 In the example above we specify a list of two build machines, one for
569 the @code{x86_64} architecture and one for the @code{mips64el}
572 In fact, this file is---not surprisingly!---a Scheme file that is
573 evaluated when the @code{offload} hook is started. Its return value
574 must be a list of @code{build-machine} objects. While this example
575 shows a fixed list of build machines, one could imagine, say, using
576 DNS-SD to return a list of potential build machines discovered in the
577 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
578 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
581 @deftp {Data Type} build-machine
582 This data type represents build machines the daemon may offload builds
583 to. The important fields are:
588 The remote machine's host name.
591 The remote machine's system type---e.g., @code{"x86_64-linux"}.
594 The user account to use when connecting to the remote machine over SSH.
595 Note that the SSH key pair must @emph{not} be passphrase-protected, to
596 allow non-interactive logins.
600 A number of optional fields may be specified:
605 Port number of the machine's SSH server (default: 22).
608 The SSH private key file to use when connecting to the machine.
610 @item parallel-builds
611 The number of builds that may run in parallel on the machine (1 by
615 A ``relative speed factor''. The offload scheduler will tend to prefer
616 machines with a higher speed factor.
619 A list of strings denoting specific features supported by the machine.
620 An example is @code{"kvm"} for machines that have the KVM Linux modules
621 and corresponding hardware support. Derivations can request features by
622 name, and they will be scheduled on matching build machines.
627 The @code{guix} command must be in the search path on the build
628 machines, since offloading works by invoking the @code{guix archive} and
629 @code{guix build} commands.
631 There's one last thing to do once @file{machines.scm} is in place. As
632 explained above, when offloading, files are transferred back and forth
633 between the machine stores. For this to work, you need to generate a
634 key pair to allow the daemon to export signed archives of files from the
635 store (@pxref{Invoking guix archive}):
638 # guix archive --generate-key
642 Thus, when receiving files, a machine's build daemon can make sure they
643 are genuine, have not been tampered with, and that they are signed by an
647 @node Invoking guix-daemon
648 @section Invoking @command{guix-daemon}
650 The @command{guix-daemon} program implements all the functionality to
651 access the store. This includes launching build processes, running the
652 garbage collector, querying the availability of a build result, etc. It
653 is normally run as @code{root} like this:
656 # guix-daemon --build-users-group=guixbuild
660 For details on how to set it up, @pxref{Setting Up the Daemon}.
663 @cindex container, build environment
664 @cindex build environment
665 @cindex reproducible builds
666 By default, @command{guix-daemon} launches build processes under
667 different UIDs, taken from the build group specified with
668 @code{--build-users-group}. In addition, each build process is run in a
669 chroot environment that only contains the subset of the store that the
670 build process depends on, as specified by its derivation
671 (@pxref{Programming Interface, derivation}), plus a set of specific
672 system directories. By default, the latter contains @file{/dev} and
673 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
674 @dfn{container}: in addition to having its own file system tree, it has
675 a separate mount name space, its own PID name space, network name space,
676 etc. This helps achieve reproducible builds (@pxref{Features}).
678 When the daemon performs a build on behalf of the user, it creates a
679 build directory under @file{/tmp} or under the directory specified by
680 its @code{TMPDIR} environment variable; this directory is shared with
681 the container for the duration of the build. Be aware that using a
682 directory other than @file{/tmp} can affect build results---for example,
683 with a longer directory name, a build process that uses Unix-domain
684 sockets might hit the name length limitation for @code{sun_path}, which
685 it would otherwise not hit.
687 The build directory is automatically deleted upon completion, unless the
688 build failed and the client specified @option{--keep-failed}
689 (@pxref{Invoking guix build, @option{--keep-failed}}).
691 The following command-line options are supported:
694 @item --build-users-group=@var{group}
695 Take users from @var{group} to run build processes (@pxref{Setting Up
696 the Daemon, build users}).
698 @item --no-substitutes
700 Do not use substitutes for build products. That is, always build things
701 locally instead of allowing downloads of pre-built binaries
702 (@pxref{Substitutes}).
704 By default substitutes are used, unless the client---such as the
705 @command{guix package} command---is explicitly invoked with
706 @code{--no-substitutes}.
708 When the daemon runs with @code{--no-substitutes}, clients can still
709 explicitly enable substitution @i{via} the @code{set-build-options}
710 remote procedure call (@pxref{The Store}).
712 @item --substitute-urls=@var{urls}
713 Consider @var{urls} the default whitespace-separated list of substitute
714 source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
717 This means that substitutes may be downloaded from @var{urls}, as long
718 as they are signed by a trusted signature (@pxref{Substitutes}).
721 @item --no-build-hook
722 Do not use the @dfn{build hook}.
724 The build hook is a helper program that the daemon can start and to
725 which it submits build requests. This mechanism is used to offload
726 builds to other machines (@pxref{Daemon Offload Setup}).
728 @item --cache-failures
729 Cache build failures. By default, only successful builds are cached.
731 @item --cores=@var{n}
733 Use @var{n} CPU cores to build each derivation; @code{0} means as many
736 The default value is @code{0}, but it may be overridden by clients, such
737 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
740 The effect is to define the @code{NIX_BUILD_CORES} environment variable
741 in the build process, which can then use it to exploit internal
742 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
744 @item --max-jobs=@var{n}
746 Allow at most @var{n} build jobs in parallel. The default value is
747 @code{1}. Setting it to @code{0} means that no builds will be performed
748 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
749 Setup}), or simply fail.
752 Produce debugging output.
754 This is useful to debug daemon start-up issues, but then it may be
755 overridden by clients, for example the @code{--verbosity} option of
756 @command{guix build} (@pxref{Invoking guix build}).
758 @item --chroot-directory=@var{dir}
759 Add @var{dir} to the build chroot.
761 Doing this may change the result of build processes---for instance if
762 they use optional dependencies found in @var{dir} when it is available,
763 and not otherwise. For that reason, it is not recommended to do so.
764 Instead, make sure that each derivation declares all the inputs that it
767 @item --disable-chroot
768 Disable chroot builds.
770 Using this option is not recommended since, again, it would allow build
771 processes to gain access to undeclared dependencies. It is necessary,
772 though, when @command{guix-daemon} is running under an unprivileged user
775 @item --disable-log-compression
776 Disable compression of the build logs.
778 Unless @code{--lose-logs} is used, all the build logs are kept in the
779 @var{localstatedir}. To save space, the daemon automatically compresses
780 them with bzip2 by default. This option disables that.
782 @item --disable-deduplication
783 @cindex deduplication
784 Disable automatic file ``deduplication'' in the store.
786 By default, files added to the store are automatically ``deduplicated'':
787 if a newly added file is identical to another one found in the store,
788 the daemon makes the new file a hard link to the other file. This can
789 noticeably reduce disk usage, at the expense of slightly increasde
790 input/output load at the end of a build process. This option disables
793 @item --gc-keep-outputs[=yes|no]
794 Tell whether the garbage collector (GC) must keep outputs of live
797 When set to ``yes'', the GC will keep the outputs of any live derivation
798 available in the store---the @code{.drv} files. The default is ``no'',
799 meaning that derivation outputs are kept only if they are GC roots.
801 @item --gc-keep-derivations[=yes|no]
802 Tell whether the garbage collector (GC) must keep derivations
803 corresponding to live outputs.
805 When set to ``yes'', as is the case by default, the GC keeps
806 derivations---i.e., @code{.drv} files---as long as at least one of their
807 outputs is live. This allows users to keep track of the origins of
808 items in their store. Setting it to ``no'' saves a bit of disk space.
810 Note that when both @code{--gc-keep-derivations} and
811 @code{--gc-keep-outputs} are used, the effect is to keep all the build
812 prerequisites (the sources, compiler, libraries, and other build-time
813 tools) of live objects in the store, regardless of whether these
814 prerequisites are live. This is convenient for developers since it
815 saves rebuilds or downloads.
817 @item --impersonate-linux-2.6
818 On Linux-based systems, impersonate Linux 2.6. This means that the
819 kernel's @code{uname} system call will report 2.6 as the release number.
821 This might be helpful to build programs that (usually wrongfully) depend
822 on the kernel version number.
825 Do not keep build logs. By default they are kept under
826 @code{@var{localstatedir}/guix/log}.
828 @item --system=@var{system}
829 Assume @var{system} as the current system type. By default it is the
830 architecture/kernel pair found at configure time, such as
833 @item --listen=@var{socket}
834 Listen for connections on @var{socket}, the file name of a Unix-domain
835 socket. The default socket is
836 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
837 useful in exceptional circumstances, such as if you need to run several
838 daemons on the same machine.
841 @node Running Guix Before It Is Installed
842 @section Running Guix Before It Is Installed
844 If you are hacking Guix itself---which is a good idea!---you will find
845 it useful to test the changes made in your local source tree checkout
846 without actually installing them.
848 To that end, all the command-line tools can be used even if you have not
849 run @command{make install}. To do that, prefix each command with
850 @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the
851 top build tree of Guix), as in:
854 $ sudo ./pre-inst-env guix-daemon --build-users-group=guixbuild
855 $ ./pre-inst-env guix build hello
859 Similarly, for a Guile session using the Guix modules:
862 $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))'
865 The @command{pre-inst-env} script sets up all the environment variables
866 necessary to support this, including @code{PATH} and
867 @code{GUILE_LOAD_PATH}.
869 If you are hacking Guix from Emacs using the wonderful Geiser
870 (@pxref{Introduction,,, geiser, Geiser User Manual}), make sure to
871 augment Guile's load path so that it finds source files from your
875 ;; Assuming the Guix checkout is in ~/src/guix.
876 (add-to-list 'geiser-guile-load-path "~/src/guix")
880 @c *********************************************************************
881 @node Package Management
882 @chapter Package Management
884 The purpose of GNU Guix is to allow users to easily install, upgrade, and
885 remove software packages, without having to know about their build
886 procedure or dependencies. Guix also goes beyond this obvious set of
889 This chapter describes the main features of Guix, as well as the package
890 management tools it provides. Two user interfaces are provided for
891 routine package management tasks: a command-line interface
892 (@pxref{Invoking guix package, @code{guix package}}), and a visual user
893 interface in Emacs (@pxref{Emacs Interface}).
896 * Features:: How Guix will make your life brighter.
897 * Invoking guix package:: Package installation, removal, etc.
898 * Emacs Interface:: Package management from Emacs.
899 * Substitutes:: Downloading pre-built binaries.
900 * Packages with Multiple Outputs:: Single source package, multiple outputs.
901 * Invoking guix gc:: Running the garbage collector.
902 * Invoking guix pull:: Fetching the latest Guix and distribution.
903 * Invoking guix archive:: Exporting and importing store files.
909 When using Guix, each package ends up in the @dfn{package store}, in its
910 own directory---something that resembles
911 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
912 (note that Guix comes with an Emacs extension to shorten those file
913 names, @pxref{Emacs Prettify}.)
915 Instead of referring to these directories, users have their own
916 @dfn{profile}, which points to the packages that they actually want to
917 use. These profiles are stored within each user's home directory, at
918 @code{$HOME/.guix-profile}.
920 For example, @code{alice} installs GCC 4.7.2. As a result,
921 @file{/home/alice/.guix-profile/bin/gcc} points to
922 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
923 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
924 simply continues to point to
925 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
926 coexist on the same system without any interference.
928 The @command{guix package} command is the central tool to manage
929 packages (@pxref{Invoking guix package}). It operates on those per-user
930 profiles, and can be used @emph{with normal user privileges}.
932 The command provides the obvious install, remove, and upgrade
933 operations. Each invocation is actually a @emph{transaction}: either
934 the specified operation succeeds, or nothing happens. Thus, if the
935 @command{guix package} process is terminated during the transaction,
936 or if a power outage occurs during the transaction, then the user's
937 profile remains in its previous state, and remains usable.
939 In addition, any package transaction may be @emph{rolled back}. So, if,
940 for example, an upgrade installs a new version of a package that turns
941 out to have a serious bug, users may roll back to the previous instance
942 of their profile, which was known to work well. Similarly, the global
943 system configuration is subject to transactional upgrades and roll-back
944 (@pxref{Using the Configuration System}).
946 All those packages in the package store may be @emph{garbage-collected}.
947 Guix can determine which packages are still referenced by the user
948 profiles, and remove those that are provably no longer referenced
949 (@pxref{Invoking guix gc}). Users may also explicitly remove old
950 generations of their profile so that the packages they refer to can be
953 @cindex reproducibility
954 @cindex reproducible builds
955 Finally, Guix takes a @dfn{purely functional} approach to package
956 management, as described in the introduction (@pxref{Introduction}).
957 Each @file{/gnu/store} package directory name contains a hash of all the
958 inputs that were used to build that package---compiler, libraries, build
959 scripts, etc. This direct correspondence allows users to make sure a
960 given package installation matches the current state of their
961 distribution. It also helps maximize @dfn{build reproducibility}:
962 thanks to the isolated build environments that are used, a given build
963 is likely to yield bit-identical files when performed on different
964 machines (@pxref{Invoking guix-daemon, container}).
967 This foundation allows Guix to support @dfn{transparent binary/source
968 deployment}. When a pre-built binary for a @file{/gnu/store} item is
969 available from an external source---a @dfn{substitute}, Guix just
970 downloads it and unpacks it;
971 otherwise, it builds the package from source, locally
972 (@pxref{Substitutes}).
974 Control over the build environment is a feature that is also useful for
975 developers. The @command{guix environment} command allows developers of
976 a package to quickly set up the right development environment for their
977 package, without having to manually install the package's dependencies
978 in their profile (@pxref{Invoking guix environment}).
980 @node Invoking guix package
981 @section Invoking @command{guix package}
983 The @command{guix package} command is the tool that allows users to
984 install, upgrade, and remove packages, as well as rolling back to
985 previous configurations. It operates only on the user's own profile,
986 and works with normal user privileges (@pxref{Features}). Its syntax
990 guix package @var{options}
993 Primarily, @var{options} specifies the operations to be performed during
994 the transaction. Upon completion, a new profile is created, but
995 previous @dfn{generations} of the profile remain available, should the user
998 For example, to remove @code{lua} and install @code{guile} and
999 @code{guile-cairo} in a single transaction:
1002 guix package -r lua -i guile guile-cairo
1005 @command{guix package} also supports a @dfn{declarative approach}
1006 whereby the user specifies the exact set of packages to be available and
1007 passes it @i{via} the @option{--manifest} option
1008 (@pxref{profile-manifest, @option{--manifest}}).
1010 For each user, a symlink to the user's default profile is automatically
1011 created in @file{$HOME/.guix-profile}. This symlink always points to the
1012 current generation of the user's default profile. Thus, users can add
1013 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
1014 variable, and so on.
1015 @cindex search paths
1016 If you are not using the Guix System Distribution, consider adding the
1017 following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
1018 Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
1019 shells get all the right environment variable definitions:
1022 GUIX_PROFILE="$HOME/.guix-profile" \
1023 source "$HOME/.guix-profile/etc/profile"
1026 In a multi-user setup, user profiles are stored in a place registered as
1027 a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
1028 to (@pxref{Invoking guix gc}). That directory is normally
1029 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
1030 @var{localstatedir} is the value passed to @code{configure} as
1031 @code{--localstatedir}, and @var{user} is the user name. The
1032 @file{per-user} directory is created when @command{guix-daemon} is
1033 started, and the @var{user} sub-directory is created by @command{guix
1036 The @var{options} can be among the following:
1040 @item --install=@var{package} @dots{}
1041 @itemx -i @var{package} @dots{}
1042 Install the specified @var{package}s.
1044 Each @var{package} may specify either a simple package name, such as
1045 @code{guile}, or a package name followed by a hyphen and version number,
1046 such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
1047 case, the newest version prefixed by @code{1.8} is selected.)
1049 If no version number is specified, the
1050 newest available version will be selected. In addition, @var{package}
1051 may contain a colon, followed by the name of one of the outputs of the
1052 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
1053 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
1054 name (and optionally version) are searched for among the GNU
1055 distribution modules (@pxref{Package Modules}).
1057 @cindex propagated inputs
1058 Sometimes packages have @dfn{propagated inputs}: these are dependencies
1059 that automatically get installed along with the required package
1060 (@pxref{package-propagated-inputs, @code{propagated-inputs} in
1061 @code{package} objects}, for information about propagated inputs in
1062 package definitions).
1064 @anchor{package-cmd-propagated-inputs}
1065 An example is the GNU MPC library: its C header files refer to those of
1066 the GNU MPFR library, which in turn refer to those of the GMP library.
1067 Thus, when installing MPC, the MPFR and GMP libraries also get installed
1068 in the profile; removing MPC also removes MPFR and GMP---unless they had
1069 also been explicitly installed independently.
1071 Besides, packages sometimes rely on the definition of environment
1072 variables for their search paths (see explanation of
1073 @code{--search-paths} below). Any missing or possibly incorrect
1074 environment variable definitions are reported here.
1076 @c XXX: keep me up-to-date
1077 Finally, when installing a GNU package, the tool reports the
1078 availability of a newer upstream version. In the future, it may provide
1079 the option of installing directly from the upstream version, even if
1080 that version is not yet in the distribution.
1082 @item --install-from-expression=@var{exp}
1084 Install the package @var{exp} evaluates to.
1086 @var{exp} must be a Scheme expression that evaluates to a
1087 @code{<package>} object. This option is notably useful to disambiguate
1088 between same-named variants of a package, with expressions such as
1089 @code{(@@ (gnu packages base) guile-final)}.
1091 Note that this option installs the first output of the specified
1092 package, which may be insufficient when needing a specific output of a
1093 multiple-output package.
1095 @item --remove=@var{package} @dots{}
1096 @itemx -r @var{package} @dots{}
1097 Remove the specified @var{package}s.
1099 As for @code{--install}, each @var{package} may specify a version number
1100 and/or output name in addition to the package name. For instance,
1101 @code{-r glibc:debug} would remove the @code{debug} output of
1104 @item --upgrade[=@var{regexp} @dots{}]
1105 @itemx -u [@var{regexp} @dots{}]
1106 Upgrade all the installed packages. If one or more @var{regexp}s are
1107 specified, upgrade only installed packages whose name matches a
1108 @var{regexp}. Also see the @code{--do-not-upgrade} option below.
1110 Note that this upgrades package to the latest version of packages found
1111 in the distribution currently installed. To update your distribution,
1112 you should regularly run @command{guix pull} (@pxref{Invoking guix
1115 @item --do-not-upgrade[=@var{regexp} @dots{}]
1116 When used together with the @code{--upgrade} option, do @emph{not}
1117 upgrade any packages whose name matches a @var{regexp}. For example, to
1118 upgrade all packages in the current profile except those containing the
1119 substring ``emacs'':
1122 $ guix package --upgrade . --do-not-upgrade emacs
1125 @item @anchor{profile-manifest}--manifest=@var{file}
1126 @itemx -m @var{file}
1127 @cindex profile declaration
1128 @cindex profile manifest
1129 Create a new generation of the profile from the manifest object
1130 returned by the Scheme code in @var{file}.
1132 This allows you to @emph{declare} the profile's contents rather than
1133 constructing it through a sequence of @code{--install} and similar
1134 commands. The advantage is that @var{file} can be put under version
1135 control, copied to different machines to reproduce the same profile, and
1138 @c FIXME: Add reference to (guix profile) documentation when available.
1139 @var{file} must return a @dfn{manifest} object, which is roughly a list
1142 @findex packages->manifest
1144 (use-package-modules guile emacs)
1149 ;; Use a specific package output.
1150 (list guile-2.0 "debug")))
1154 Roll back to the previous @dfn{generation} of the profile---i.e., undo
1155 the last transaction.
1157 When combined with options such as @code{--install}, roll back occurs
1158 before any other actions.
1160 When rolling back from the first generation that actually contains
1161 installed packages, the profile is made to point to the @dfn{zeroth
1162 generation}, which contains no files apart from its own meta-data.
1164 Installing, removing, or upgrading packages from a generation that has
1165 been rolled back to overwrites previous future generations. Thus, the
1166 history of a profile's generations is always linear.
1168 @item --switch-generation=@var{pattern}
1169 @itemx -S @var{pattern}
1170 Switch to a particular generation defined by @var{pattern}.
1172 @var{pattern} may be either a generation number or a number prefixed
1173 with ``+'' or ``-''. The latter means: move forward/backward by a
1174 specified number of generations. For example, if you want to return to
1175 the latest generation after @code{--roll-back}, use
1176 @code{--switch-generation=+1}.
1178 The difference between @code{--roll-back} and
1179 @code{--switch-generation=-1} is that @code{--switch-generation} will
1180 not make a zeroth generation, so if a specified generation does not
1181 exist, the current generation will not be changed.
1183 @item --search-paths[=@var{kind}]
1184 @cindex search paths
1185 Report environment variable definitions, in Bash syntax, that may be
1186 needed in order to use the set of installed packages. These environment
1187 variables are used to specify @dfn{search paths} for files used by some
1188 of the installed packages.
1190 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
1191 environment variables to be defined so it can look for headers and
1192 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
1193 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
1194 library are installed in the profile, then @code{--search-paths} will
1195 suggest setting these variables to @code{@var{profile}/include} and
1196 @code{@var{profile}/lib}, respectively.
1198 The typical use case is to define these environment variables in the
1202 $ eval `guix package --search-paths`
1205 @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
1206 meaning that the returned environment variable definitions will either
1207 be exact settings, or prefixes or suffixes of the current value of these
1208 variables. When omitted, @var{kind} defaults to @code{exact}.
1210 @item --profile=@var{profile}
1211 @itemx -p @var{profile}
1212 Use @var{profile} instead of the user's default profile.
1215 Produce verbose output. In particular, emit the environment's build log
1216 on the standard error port.
1219 Use the bootstrap Guile to build the profile. This option is only
1220 useful to distribution developers.
1224 In addition to these actions @command{guix package} supports the
1225 following options to query the current state of a profile, or the
1226 availability of packages:
1230 @item --search=@var{regexp}
1231 @itemx -s @var{regexp}
1232 List the available packages whose name, synopsis, or description matches
1233 @var{regexp}. Print all the meta-data of matching packages in
1234 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
1235 GNU recutils manual}).
1237 This allows specific fields to be extracted using the @command{recsel}
1238 command, for instance:
1241 $ guix package -s malloc | recsel -p name,version
1249 Similarly, to show the name of all the packages available under the
1250 terms of the GNU@tie{}LGPL version 3:
1253 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
1260 @item --show=@var{package}
1261 Show details about @var{package}, taken from the list of available packages, in
1262 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
1266 $ guix package --show=python | recsel -p name,version
1274 You may also specify the full name of a package to only get details about a
1275 specific version of it:
1277 $ guix package --show=python-3.3.5 | recsel -p name,version
1284 @item --list-installed[=@var{regexp}]
1285 @itemx -I [@var{regexp}]
1286 List the currently installed packages in the specified profile, with the
1287 most recently installed packages shown last. When @var{regexp} is
1288 specified, list only installed packages whose name matches @var{regexp}.
1290 For each installed package, print the following items, separated by
1291 tabs: the package name, its version string, the part of the package that
1292 is installed (for instance, @code{out} for the default output,
1293 @code{include} for its headers, etc.), and the path of this package in
1296 @item --list-available[=@var{regexp}]
1297 @itemx -A [@var{regexp}]
1298 List packages currently available in the distribution for this system
1299 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
1300 installed packages whose name matches @var{regexp}.
1302 For each package, print the following items separated by tabs: its name,
1303 its version string, the parts of the package (@pxref{Packages with
1304 Multiple Outputs}), and the source location of its definition.
1306 @item --list-generations[=@var{pattern}]
1307 @itemx -l [@var{pattern}]
1308 Return a list of generations along with their creation dates; for each
1309 generation, show the installed packages, with the most recently
1310 installed packages shown last. Note that the zeroth generation is never
1313 For each installed package, print the following items, separated by
1314 tabs: the name of a package, its version string, the part of the package
1315 that is installed (@pxref{Packages with Multiple Outputs}), and the
1316 location of this package in the store.
1318 When @var{pattern} is used, the command returns only matching
1319 generations. Valid patterns include:
1322 @item @emph{Integers and comma-separated integers}. Both patterns denote
1323 generation numbers. For instance, @code{--list-generations=1} returns
1326 And @code{--list-generations=1,8,2} outputs three generations in the
1327 specified order. Neither spaces nor trailing commas are allowed.
1329 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
1330 specified generations and everything in between. Note that the start of
1331 a range must be lesser than its end.
1333 It is also possible to omit the endpoint. For example,
1334 @code{--list-generations=2..}, returns all generations starting from the
1337 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
1338 or months by passing an integer along with the first letter of the
1339 duration. For example, @code{--list-generations=20d} lists generations
1340 that are up to 20 days old.
1343 @item --delete-generations[=@var{pattern}]
1344 @itemx -d [@var{pattern}]
1345 When @var{pattern} is omitted, delete all generations except the current
1348 This command accepts the same patterns as @option{--list-generations}.
1349 When @var{pattern} is specified, delete the matching generations. When
1350 @var{pattern} specifies a duration, generations @emph{older} than the
1351 specified duration match. For instance, @code{--delete-generations=1m}
1352 deletes generations that are more than one month old.
1354 If the current generation matches, it is @emph{not} deleted. Also, the
1355 zeroth generation is never deleted.
1357 Note that deleting generations prevents roll-back to them.
1358 Consequently, this command must be used with care.
1362 Finally, since @command{guix package} may actually start build
1363 processes, it supports all the common build options that @command{guix
1364 build} supports (@pxref{Invoking guix build, common build options}).
1369 @section Substitutes
1372 @cindex pre-built binaries
1373 Guix supports transparent source/binary deployment, which means that it
1374 can either build things locally, or download pre-built items from a
1375 server. We call these pre-built items @dfn{substitutes}---they are
1376 substitutes for local build results. In many cases, downloading a
1377 substitute is much faster than building things locally.
1379 Substitutes can be anything resulting from a derivation build
1380 (@pxref{Derivations}). Of course, in the common case, they are
1381 pre-built package binaries, but source tarballs, for instance, which
1382 also result from derivation builds, can be available as substitutes.
1384 The @code{hydra.gnu.org} server is a front-end to a build farm that
1385 builds packages from the GNU distribution continuously for some
1386 architectures, and makes them available as substitutes. This is the
1387 default source of substitutes; it can be overridden by passing
1388 @command{guix-daemon} the @code{--substitute-urls} option
1389 (@pxref{Invoking guix-daemon}).
1392 @cindex digital signatures
1393 To allow Guix to download substitutes from @code{hydra.gnu.org}, you
1394 must add its public key to the access control list (ACL) of archive
1395 imports, using the @command{guix archive} command (@pxref{Invoking guix
1396 archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
1397 be compromised and to serve genuine substitutes.
1399 This public key is installed along with Guix, in
1400 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
1401 the installation prefix of Guix. If you installed Guix from source,
1402 make sure you checked the GPG signature of
1403 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
1404 Then, you can run something like this:
1407 # guix archive --authorize < hydra.gnu.org.pub
1410 Once this is in place, the output of a command like @code{guix build}
1411 should change from something like:
1414 $ guix build emacs --dry-run
1415 The following derivations would be built:
1416 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
1417 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
1418 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
1419 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
1427 $ guix build emacs --dry-run
1428 The following files would be downloaded:
1429 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
1430 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
1431 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
1432 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
1437 This indicates that substitutes from @code{hydra.gnu.org} are usable and
1438 will be downloaded, when possible, for future builds.
1440 Guix ignores substitutes that are not signed, or that are not signed by
1441 one of the keys listed in the ACL. It also detects and raises an error
1442 when attempting to use a substitute that has been tampered with.
1444 The substitute mechanism can be disabled globally by running
1445 @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1446 guix-daemon}). It can also be disabled temporarily by passing the
1447 @code{--no-substitutes} option to @command{guix package}, @command{guix
1448 build}, and other command-line tools.
1451 Today, each individual's control over their own computing is at the
1452 mercy of institutions, corporations, and groups with enough power and
1453 determination to subvert the computing infrastructure and exploit its
1454 weaknesses. While using @code{hydra.gnu.org} substitutes can be
1455 convenient, we encourage users to also build on their own, or even run
1456 their own build farm, such that @code{hydra.gnu.org} is less of an
1457 interesting target. One way to help is by publishing the software you
1458 build using @command{guix publish} so that others have one more choice
1459 of server to download substitutes from (@pxref{Invoking guix publish}).
1461 Guix has the foundations to maximize build reproducibility
1462 (@pxref{Features}). In most cases, independent builds of a given
1463 package or derivation should yield bit-identical results. Thus, through
1464 a diverse set of independent package builds, we can strengthen the
1465 integrity of our systems.
1467 In the future, we want Guix to have support to publish and retrieve
1468 binaries to/from other users, in a peer-to-peer fashion. If you would
1469 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1472 @node Packages with Multiple Outputs
1473 @section Packages with Multiple Outputs
1475 @cindex multiple-output packages
1476 @cindex package outputs
1478 Often, packages defined in Guix have a single @dfn{output}---i.e., the
1479 source package leads exactly one directory in the store. When running
1480 @command{guix package -i glibc}, one installs the default output of the
1481 GNU libc package; the default output is called @code{out}, but its name
1482 can be omitted as shown in this command. In this particular case, the
1483 default output of @code{glibc} contains all the C header files, shared
1484 libraries, static libraries, Info documentation, and other supporting
1487 Sometimes it is more appropriate to separate the various types of files
1488 produced from a single source package into separate outputs. For
1489 instance, the GLib C library (used by GTK+ and related packages)
1490 installs more than 20 MiB of reference documentation as HTML pages.
1491 To save space for users who do not need it, the documentation goes to a
1492 separate output, called @code{doc}. To install the main GLib output,
1493 which contains everything but the documentation, one would run:
1496 guix package -i glib
1499 The command to install its documentation is:
1502 guix package -i glib:doc
1505 Some packages install programs with different ``dependency footprints''.
1506 For instance, the WordNet package install both command-line tools and
1507 graphical user interfaces (GUIs). The former depend solely on the C
1508 library, whereas the latter depend on Tcl/Tk and the underlying X
1509 libraries. In this case, we leave the command-line tools in the default
1510 output, whereas the GUIs are in a separate output. This allows users
1511 who do not need the GUIs to save space.
1513 There are several such multiple-output packages in the GNU distribution.
1514 Other conventional output names include @code{lib} for libraries and
1515 possibly header files, @code{bin} for stand-alone programs, and
1516 @code{debug} for debugging information (@pxref{Installing Debugging
1517 Files}). The outputs of a packages are listed in the third column of
1518 the output of @command{guix package --list-available} (@pxref{Invoking
1522 @node Invoking guix gc
1523 @section Invoking @command{guix gc}
1525 @cindex garbage collector
1526 Packages that are installed but not used may be @dfn{garbage-collected}.
1527 The @command{guix gc} command allows users to explicitly run the garbage
1528 collector to reclaim space from the @file{/gnu/store} directory. It is
1529 the @emph{only} way to remove files from @file{/gnu/store}---removing
1530 files or directories manually may break it beyond repair!
1532 The garbage collector has a set of known @dfn{roots}: any file under
1533 @file{/gnu/store} reachable from a root is considered @dfn{live} and
1534 cannot be deleted; any other file is considered @dfn{dead} and may be
1535 deleted. The set of garbage collector roots includes default user
1536 profiles, and may be augmented with @command{guix build --root}, for
1537 example (@pxref{Invoking guix build}).
1539 Prior to running @code{guix gc --collect-garbage} to make space, it is
1540 often useful to remove old generations from user profiles; that way, old
1541 package builds referenced by those generations can be reclaimed. This
1542 is achieved by running @code{guix package --delete-generations}
1543 (@pxref{Invoking guix package}).
1545 The @command{guix gc} command has three modes of operation: it can be
1546 used to garbage-collect any dead files (the default), to delete specific
1547 files (the @code{--delete} option), to print garbage-collector
1548 information, or for more advanced queries. The garbage collection
1549 options are as follows:
1552 @item --collect-garbage[=@var{min}]
1553 @itemx -C [@var{min}]
1554 Collect garbage---i.e., unreachable @file{/gnu/store} files and
1555 sub-directories. This is the default operation when no option is
1558 When @var{min} is given, stop once @var{min} bytes have been collected.
1559 @var{min} may be a number of bytes, or it may include a unit as a
1560 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
1561 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
1563 When @var{min} is omitted, collect all the garbage.
1567 Attempt to delete all the store files and directories specified as
1568 arguments. This fails if some of the files are not in the store, or if
1569 they are still live.
1572 Show the list of dead files and directories still present in the
1573 store---i.e., files and directories no longer reachable from any root.
1576 Show the list of live store files and directories.
1580 In addition, the references among existing store files can be queried:
1586 List the references (respectively, the referrers) of store files given
1591 List the requisites of the store files passed as arguments. Requisites
1592 include the store files themselves, their references, and the references
1593 of these, recursively. In other words, the returned list is the
1594 @dfn{transitive closure} of the store files.
1598 Lastly, the following options allow you to check the integrity of the
1599 store and to control disk usage.
1603 @item --verify[=@var{options}]
1604 @cindex integrity, of the store
1605 @cindex integrity checking
1606 Verify the integrity of the store.
1608 By default, make sure that all the store items marked as valid in the
1609 daemon's database actually exist in @file{/gnu/store}.
1611 When provided, @var{options} must a comma-separated list containing one
1612 or more of @code{contents} and @code{repair}.
1614 When passing @option{--verify=contents}, the daemon will compute the
1615 content hash of each store item and compare it against its hash in the
1616 database. Hash mismatches are reported as data corruptions. Because it
1617 traverses @emph{all the files in the store}, this command can take a
1618 long time, especially on systems with a slow disk drive.
1620 @cindex repairing the store
1621 Using @option{--verify=repair} or @option{--verify=contents,repair}
1622 causes the daemon to try to repair corrupt store items by fetching
1623 substitutes for them (@pxref{Substitutes}). Because repairing is not
1624 atomic, and thus potentially dangerous, it is available only to the
1625 system administrator.
1628 @cindex deduplication
1629 Optimize the store by hard-linking identical files---this is
1630 @dfn{deduplication}.
1632 The daemon performs deduplication after each successful build or archive
1633 import, unless it was started with @code{--disable-deduplication}
1634 (@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
1635 this option is primarily useful when the daemon was running with
1636 @code{--disable-deduplication}.
1640 @node Invoking guix pull
1641 @section Invoking @command{guix pull}
1643 Packages are installed or upgraded to the latest version available in
1644 the distribution currently available on your local machine. To update
1645 that distribution, along with the Guix tools, you must run @command{guix
1646 pull}: the command downloads the latest Guix source code and package
1647 descriptions, and deploys it.
1649 On completion, @command{guix package} will use packages and package
1650 versions from this just-retrieved copy of Guix. Not only that, but all
1651 the Guix commands and Scheme modules will also be taken from that latest
1652 version. New @command{guix} sub-commands added by the update also
1655 The @command{guix pull} command is usually invoked with no arguments,
1656 but it supports the following options:
1660 Produce verbose output, writing build logs to the standard error output.
1662 @item --url=@var{url}
1663 Download the source tarball of Guix from @var{url}.
1665 By default, the tarball is taken from its canonical address at
1666 @code{gnu.org}, for the stable branch of Guix.
1669 Use the bootstrap Guile to build the latest Guix. This option is only
1670 useful to Guix developers.
1674 @node Invoking guix archive
1675 @section Invoking @command{guix archive}
1677 The @command{guix archive} command allows users to @dfn{export} files
1678 from the store into a single archive, and to later @dfn{import} them.
1679 In particular, it allows store files to be transferred from one machine
1680 to another machine's store. For example, to transfer the @code{emacs}
1681 package to a machine connected over SSH, one would run:
1684 guix archive --export -r emacs | ssh the-machine guix archive --import
1688 Similarly, a complete user profile may be transferred from one machine
1689 to another like this:
1692 guix archive --export -r $(readlink -f ~/.guix-profile) | \
1693 ssh the-machine guix-archive --import
1697 However, note that, in both examples, all of @code{emacs} and the
1698 profile as well as all of their dependencies are transferred (due to
1699 @code{-r}), regardless of what is already available in the target
1700 machine's store. The @code{--missing} option can help figure out which
1701 items are missing from the target's store.
1703 Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
1704 comparable in spirit to `tar', but with a few noteworthy differences
1705 that make it more appropriate for our purposes. First, rather than
1706 recording all Unix meta-data for each file, the Nar format only mentions
1707 the file type (regular, directory, or symbolic link); Unix permissions
1708 and owner/group are dismissed. Second, the order in which directory
1709 entries are stored always follows the order of file names according to
1710 the C locale collation order. This makes archive production fully
1713 When exporting, the daemon digitally signs the contents of the archive,
1714 and that digital signature is appended. When importing, the daemon
1715 verifies the signature and rejects the import in case of an invalid
1716 signature or if the signing key is not authorized.
1717 @c FIXME: Add xref to daemon doc about signatures.
1719 The main options are:
1723 Export the specified store files or packages (see below.) Write the
1724 resulting archive to the standard output.
1726 Dependencies are @emph{not} included in the output, unless
1727 @code{--recursive} is passed.
1731 When combined with @code{--export}, this instructs @command{guix
1732 archive} to include dependencies of the given items in the archive.
1733 Thus, the resulting archive is self-contained: it contains the closure
1734 of the exported store items.
1737 Read an archive from the standard input, and import the files listed
1738 therein into the store. Abort if the archive has an invalid digital
1739 signature, or if it is signed by a public key not among the authorized
1740 keys (see @code{--authorize} below.)
1743 Read a list of store file names from the standard input, one per line,
1744 and write on the standard output the subset of these files missing from
1747 @item --generate-key[=@var{parameters}]
1748 @cindex signing, archives
1749 Generate a new key pair for the daemons. This is a prerequisite before
1750 archives can be exported with @code{--export}. Note that this operation
1751 usually takes time, because it needs to gather enough entropy to
1752 generate the key pair.
1754 The generated key pair is typically stored under @file{/etc/guix}, in
1755 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
1756 key, which must be kept secret.) When @var{parameters} is omitted,
1757 an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
1758 versions before 1.6.0, it is a 4096-bit RSA key.
1759 Alternately, @var{parameters} can specify
1760 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
1761 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1762 Libgcrypt Reference Manual}).
1765 @cindex authorizing, archives
1766 Authorize imports signed by the public key passed on standard input.
1767 The public key must be in ``s-expression advanced format''---i.e., the
1768 same format as the @file{signing-key.pub} file.
1770 The list of authorized keys is kept in the human-editable file
1771 @file{/etc/guix/acl}. The file contains
1772 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1773 s-expressions''} and is structured as an access-control list in the
1774 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1778 To export store files as an archive to the standard output, run:
1781 guix archive --export @var{options} @var{specifications}...
1784 @var{specifications} may be either store file names or package
1785 specifications, as for @command{guix package} (@pxref{Invoking guix
1786 package}). For instance, the following command creates an archive
1787 containing the @code{gui} output of the @code{git} package and the main
1788 output of @code{emacs}:
1791 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
1794 If the specified packages are not built yet, @command{guix archive}
1795 automatically builds them. The build process may be controlled with the
1796 same options that can be passed to the @command{guix build} command
1797 (@pxref{Invoking guix build, common build options}).
1800 @c *********************************************************************
1801 @node Programming Interface
1802 @chapter Programming Interface
1804 GNU Guix provides several Scheme programming interfaces (APIs) to
1805 define, build, and query packages. The first interface allows users to
1806 write high-level package definitions. These definitions refer to
1807 familiar packaging concepts, such as the name and version of a package,
1808 its build system, and its dependencies. These definitions can then be
1809 turned into concrete build actions.
1811 Build actions are performed by the Guix daemon, on behalf of users. In a
1812 standard setup, the daemon has write access to the store---the
1813 @file{/gnu/store} directory---whereas users do not. The recommended
1814 setup also has the daemon perform builds in chroots, under a specific
1815 build users, to minimize interference with the rest of the system.
1818 Lower-level APIs are available to interact with the daemon and the
1819 store. To instruct the daemon to perform a build action, users actually
1820 provide it with a @dfn{derivation}. A derivation is a low-level
1821 representation of the build actions to be taken, and the environment in
1822 which they should occur---derivations are to package definitions what
1823 assembly is to C programs. The term ``derivation'' comes from the fact
1824 that build results @emph{derive} from them.
1826 This chapter describes all these APIs in turn, starting from high-level
1827 package definitions.
1830 * Defining Packages:: Defining new packages.
1831 * Build Systems:: Specifying how packages are built.
1832 * The Store:: Manipulating the package store.
1833 * Derivations:: Low-level interface to package derivations.
1834 * The Store Monad:: Purely functional interface to the store.
1835 * G-Expressions:: Manipulating build expressions.
1838 @node Defining Packages
1839 @section Defining Packages
1841 The high-level interface to package definitions is implemented in the
1842 @code{(guix packages)} and @code{(guix build-system)} modules. As an
1843 example, the package definition, or @dfn{recipe}, for the GNU Hello
1844 package looks like this:
1847 (define-module (gnu packages hello)
1848 #:use-module (guix packages)
1849 #:use-module (guix download)
1850 #:use-module (guix build-system gnu)
1851 #:use-module (guix licenses))
1853 (define-public hello
1859 (uri (string-append "mirror://gnu/hello/hello-" version
1862 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1863 (build-system gnu-build-system)
1864 (arguments `(#:configure-flags '("--enable-silent-rules")))
1865 (inputs `(("gawk" ,gawk)))
1866 (synopsis "Hello, GNU world: An example GNU package")
1867 (description "Guess what GNU Hello prints!")
1868 (home-page "http://www.gnu.org/software/hello/")
1873 Without being a Scheme expert, the reader may have guessed the meaning
1874 of the various fields here. This expression binds variable @code{hello}
1875 to a @code{<package>} object, which is essentially a record
1876 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1877 This package object can be inspected using procedures found in the
1878 @code{(guix packages)} module; for instance, @code{(package-name hello)}
1879 returns---surprise!---@code{"hello"}.
1881 With luck, you may be able to import part or all of the definition of
1882 the package you are interested in from another repository, using the
1883 @code{guix import} command (@pxref{Invoking guix import}).
1885 In the example above, @var{hello} is defined into a module of its own,
1886 @code{(gnu packages hello)}. Technically, this is not strictly
1887 necessary, but it is convenient to do so: all the packages defined in
1888 modules under @code{(gnu packages @dots{})} are automatically known to
1889 the command-line tools (@pxref{Package Modules}).
1891 There are a few points worth noting in the above package definition:
1895 The @code{source} field of the package is an @code{<origin>} object
1896 (@pxref{origin Reference}, for the complete reference).
1897 Here, the @code{url-fetch} method from @code{(guix download)} is used,
1898 meaning that the source is a file to be downloaded over FTP or HTTP.
1900 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1901 the GNU mirrors defined in @code{(guix download)}.
1903 The @code{sha256} field specifies the expected SHA256 hash of the file
1904 being downloaded. It is mandatory, and allows Guix to check the
1905 integrity of the file. The @code{(base32 @dots{})} form introduces the
1906 base32 representation of the hash. You can obtain this information with
1907 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
1908 hash} (@pxref{Invoking guix hash}).
1911 When needed, the @code{origin} form can also have a @code{patches} field
1912 listing patches to be applied, and a @code{snippet} field giving a
1913 Scheme expression to modify the source code.
1916 @cindex GNU Build System
1917 The @code{build-system} field specifies the procedure to build the
1918 package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1919 represents the familiar GNU Build System, where packages may be
1920 configured, built, and installed with the usual @code{./configure &&
1921 make && make check && make install} command sequence.
1924 The @code{arguments} field specifies options for the build system
1925 (@pxref{Build Systems}). Here it is interpreted by
1926 @var{gnu-build-system} as a request run @file{configure} with the
1927 @code{--enable-silent-rules} flag.
1930 The @code{inputs} field specifies inputs to the build process---i.e.,
1931 build-time or run-time dependencies of the package. Here, we define an
1932 input called @code{"gawk"} whose value is that of the @var{gawk}
1933 variable; @var{gawk} is itself bound to a @code{<package>} object.
1935 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1936 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1937 of ensuring that they are present (@pxref{Build Systems}).
1939 However, any other dependencies need to be specified in the
1940 @code{inputs} field. Any dependency not specified here will simply be
1941 unavailable to the build process, possibly leading to a build failure.
1944 @xref{package Reference}, for a full description of possible fields.
1946 Once a package definition is in place, the
1947 package may actually be built using the @code{guix build} command-line
1948 tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
1949 more information on how to test package definitions, and
1950 @ref{Invoking guix lint}, for information on how to check a definition
1951 for style conformance.
1953 Eventually, updating the package definition to a new upstream version
1954 can be partly automated by the @command{guix refresh} command
1955 (@pxref{Invoking guix refresh}).
1957 Behind the scenes, a derivation corresponding to the @code{<package>}
1958 object is first computed by the @code{package-derivation} procedure.
1959 That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
1960 The build actions it prescribes may then be realized by using the
1961 @code{build-derivations} procedure (@pxref{The Store}).
1963 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1964 Return the @code{<derivation>} object of @var{package} for @var{system}
1965 (@pxref{Derivations}).
1967 @var{package} must be a valid @code{<package>} object, and @var{system}
1968 must be a string denoting the target system type---e.g.,
1969 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1970 must be a connection to the daemon, which operates on the store
1971 (@pxref{The Store}).
1975 @cindex cross-compilation
1976 Similarly, it is possible to compute a derivation that cross-builds a
1977 package for some other system:
1979 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1980 @var{package} @var{target} [@var{system}]
1981 Return the @code{<derivation>} object of @var{package} cross-built from
1982 @var{system} to @var{target}.
1984 @var{target} must be a valid GNU triplet denoting the target hardware
1985 and operating system, such as @code{"mips64el-linux-gnu"}
1986 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1987 Configure and Build System}).
1991 * package Reference :: The package data type.
1992 * origin Reference:: The origin data type.
1996 @node package Reference
1997 @subsection @code{package} Reference
1999 This section summarizes all the options available in @code{package}
2000 declarations (@pxref{Defining Packages}).
2002 @deftp {Data Type} package
2003 This is the data type representing a package recipe.
2007 The name of the package, as a string.
2009 @item @code{version}
2010 The version of the package, as a string.
2013 An origin object telling how the source code for the package should be
2014 acquired (@pxref{origin Reference}).
2016 @item @code{build-system}
2017 The build system that should be used to build the package (@pxref{Build
2020 @item @code{arguments} (default: @code{'()})
2021 The arguments that should be passed to the build system. This is a
2022 list, typically containing sequential keyword-value pairs.
2024 @item @code{inputs} (default: @code{'()})
2025 Package or derivation inputs to the build. This is a list of lists,
2026 where each list has the name of the input (a string) as its first
2027 element, a package or derivation object as its second element, and
2028 optionally the name of the output of the package or derivation that
2029 should be used, which defaults to @code{"out"}.
2031 @item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()})
2032 @cindex propagated inputs
2033 This field is like @code{inputs}, but the specified packages will be
2034 force-installed alongside the package they belong to
2035 (@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
2036 information on how @command{guix package} deals with propagated inputs.)
2038 For example this is necessary when a library needs headers of another
2039 library to compile, or needs another shared library to be linked
2040 alongside itself when a program wants to link to it.
2042 @item @code{native-inputs} (default: @code{'()})
2043 This field is like @code{inputs}, but in case of a cross-compilation it
2044 will be ensured that packages for the architecture of the build machine
2045 are present, such that executables from them can be used during the
2048 This is typically where you would list tools needed at build time but
2049 not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
2050 Bison. @command{guix lint} can report likely mistakes in this area
2051 (@pxref{Invoking guix lint}).
2053 @item @code{self-native-input?} (default: @code{#f})
2054 This is a Boolean field telling whether the package should use itself as
2055 a native input when cross-compiling.
2057 @item @code{outputs} (default: @code{'("out")})
2058 The list of output names of the package. @xref{Packages with Multiple
2059 Outputs}, for typical uses of additional outputs.
2061 @item @code{native-search-paths} (default: @code{'()})
2062 @itemx @code{search-paths} (default: @code{'()})
2063 A list of @code{search-path-specification} objects describing
2064 search-path environment variables honored by the package.
2066 @item @code{replacement} (default: @code{#f})
2067 This must either @code{#f} or a package object that will be used as a
2068 @dfn{replacement} for this package. @xref{Security Updates, grafts},
2071 @item @code{synopsis}
2072 A one-line description of the package.
2074 @item @code{description}
2075 A more elaborate description of the package.
2077 @item @code{license}
2078 The license of the package; a value from @code{(guix licenses)}.
2080 @item @code{home-page}
2081 The URL to the home-page of the package, as a string.
2083 @item @code{supported-systems} (default: @var{%supported-systems})
2084 The list of systems supported by the package, as strings of the form
2085 @code{architecture-kernel}, for example @code{"x86_64-linux"}.
2087 @item @code{maintainers} (default: @code{'()})
2088 The list of maintainers of the package, as @code{maintainer} objects.
2090 @item @code{location} (default: source location of the @code{package} form)
2091 The source location of the package. It's useful to override this when
2092 inheriting from another package, in which case this field is not
2093 automatically corrected.
2098 @node origin Reference
2099 @subsection @code{origin} Reference
2101 This section summarizes all the options available in @code{origin}
2102 declarations (@pxref{Defining Packages}).
2104 @deftp {Data Type} origin
2105 This is the data type representing a source code origin.
2109 An object containing the URI of the source. The object type depends on
2110 the @code{method} (see below). For example, when using the
2111 @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
2112 values are: a URL represented as a string, or a list thereof.
2115 A procedure that will handle the URI.
2120 @item @var{url-fetch} from @code{(guix download)}
2121 download a file the HTTP, HTTPS, or FTP URL specified in the
2124 @item @var{git-fetch} from @code{(guix git-download)}
2125 clone the Git version control repository, and check out the revision
2126 specified in the @code{uri} field as a @code{git-reference} object; a
2127 @code{git-reference} looks like this:
2131 (url "git://git.debian.org/git/pkg-shadow/shadow")
2132 (commit "v4.1.5.1"))
2137 A bytevector containing the SHA-256 hash of the source. Typically the
2138 @code{base32} form is used here to generate the bytevector from a
2141 @item @code{file-name} (default: @code{#f})
2142 The file name under which the source code should be saved. When this is
2143 @code{#f}, a sensible default value will be used in most cases. In case
2144 the source is fetched from a URL, the file name from the URL will be
2145 used. For version control checkouts, it's recommended to provide the
2146 file name explicitly because the default is not very descriptive.
2148 @item @code{patches} (default: @code{'()})
2149 A list of file names containing patches to be applied to the source.
2151 @item @code{snippet} (default: @code{#f})
2152 A quoted piece of code that will be run in the source directory to make
2153 any modifications, which is sometimes more convenient than a patch.
2155 @item @code{patch-flags} (default: @code{'("-p1")})
2156 A list of command-line flags that should be passed to the @code{patch}
2159 @item @code{patch-inputs} (default: @code{#f})
2160 Input packages or derivations to the patching process. When this is
2161 @code{#f}, the usual set of inputs necessary for patching are provided,
2162 such as GNU@tie{}Patch.
2164 @item @code{modules} (default: @code{'()})
2165 A list of Guile modules that should be loaded during the patching
2166 process and while running the code in the @code{snippet} field.
2168 @item @code{imported-modules} (default: @code{'()})
2169 The list of Guile modules to import in the patch derivation, for use by
2172 @item @code{patch-guile} (default: @code{#f})
2173 The Guile package that should be used in the patching process. When
2174 this is @code{#f}, a sensible default is used.
2180 @section Build Systems
2182 @cindex build system
2183 Each package definition specifies a @dfn{build system} and arguments for
2184 that build system (@pxref{Defining Packages}). This @code{build-system}
2185 field represents the build procedure of the package, as well implicit
2186 dependencies of that build procedure.
2188 Build systems are @code{<build-system>} objects. The interface to
2189 create and manipulate them is provided by the @code{(guix build-system)}
2190 module, and actual build systems are exported by specific modules.
2192 @cindex bag (low-level package representation)
2193 Under the hood, build systems first compile package objects to
2194 @dfn{bags}. A @dfn{bag} is like a package, but with less
2195 ornamentation---in other words, a bag is a lower-level representation of
2196 a package, which includes all the inputs of that package, including some
2197 that were implicitly added by the build system. This intermediate
2198 representation is then compiled to a derivation (@pxref{Derivations}).
2200 Build systems accept an optional list of @dfn{arguments}. In package
2201 definitions, these are passed @i{via} the @code{arguments} field
2202 (@pxref{Defining Packages}). They are typically keyword arguments
2203 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
2204 Guile Reference Manual}). The value of these arguments is usually
2205 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
2206 by the daemon (@pxref{Derivations}).
2208 The main build system is @var{gnu-build-system}, which implements the
2209 standard build procedure for GNU packages and many other packages. It
2210 is provided by the @code{(guix build-system gnu)} module.
2212 @defvr {Scheme Variable} gnu-build-system
2213 @var{gnu-build-system} represents the GNU Build System, and variants
2214 thereof (@pxref{Configuration, configuration and makefile conventions,,
2215 standards, GNU Coding Standards}).
2217 @cindex build phases
2218 In a nutshell, packages using it configured, built, and installed with
2219 the usual @code{./configure && make && make check && make install}
2220 command sequence. In practice, a few additional steps are often needed.
2221 All these steps are split up in separate @dfn{phases},
2222 notably@footnote{Please see the @code{(guix build gnu-build-system)}
2223 modules for more details about the build phases.}:
2227 Unpack the source tarball, and change the current directory to the
2228 extracted source tree. If the source is actually a directory, copy it
2229 to the build tree, and enter that directory.
2231 @item patch-source-shebangs
2232 Patch shebangs encountered in source files so they refer to the right
2233 store file names. For instance, this changes @code{#!/bin/sh} to
2234 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
2237 Run the @file{configure} script with a number of default options, such
2238 as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
2239 by the @code{#:configure-flags} argument.
2242 Run @code{make} with the list of flags specified with
2243 @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
2244 (the default), build with @code{make -j}.
2247 Run @code{make check}, or some other target specified with
2248 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
2249 @code{#:parallel-tests?} argument is true (the default), run @code{make
2253 Run @code{make install} with the flags listed in @code{#:make-flags}.
2255 @item patch-shebangs
2256 Patch shebangs on the installed executable files.
2259 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
2260 is false), copying them to the @code{debug} output when available
2261 (@pxref{Installing Debugging Files}).
2264 @vindex %standard-phases
2265 The build-side module @code{(guix build gnu-build-system)} defines
2266 @var{%standard-phases} as the default list of build phases.
2267 @var{%standard-phases} is a list of symbol/procedure pairs, where the
2268 procedure implements the actual phase.
2270 The list of phases used for a particular package can be changed with the
2271 @code{#:phases} parameter. For instance, passing:
2274 #:phases (alist-delete 'configure %standard-phases)
2277 means that all the phases described above will be used, except the
2278 @code{configure} phase.
2280 In addition, this build system ensures that the ``standard'' environment
2281 for GNU packages is available. This includes tools such as GCC, libc,
2282 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
2283 build-system gnu)} module for a complete list.) We call these the
2284 @dfn{implicit inputs} of a package, because package definitions don't
2285 have to mention them.
2288 Other @code{<build-system>} objects are defined to support other
2289 conventions and tools used by free software packages. They inherit most
2290 of @var{gnu-build-system}, and differ mainly in the set of inputs
2291 implicitly added to the build process, and in the list of phases
2292 executed. Some of these build systems are listed below.
2294 @defvr {Scheme Variable} cmake-build-system
2295 This variable is exported by @code{(guix build-system cmake)}. It
2296 implements the build procedure for packages using the
2297 @url{http://www.cmake.org, CMake build tool}.
2299 It automatically adds the @code{cmake} package to the set of inputs.
2300 Which package is used can be specified with the @code{#:cmake}
2303 The @code{#:configure-flags} parameter is taken as a list of flags
2304 passed to the @command{cmake} command. The @code{#:build-type}
2305 parameter specifies in abstract terms the flags passed to the compiler;
2306 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
2307 debugging information''), which roughly means that code is compiled with
2308 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
2311 @defvr {Scheme Variable} glib-or-gtk-build-system
2312 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
2313 is intended for use with packages making use of GLib or GTK+.
2315 This build system adds the following two phases to the ones defined by
2316 @var{gnu-build-system}:
2319 @item glib-or-gtk-wrap
2320 The phase @code{glib-or-gtk-wrap} ensures that programs found under
2321 @file{bin/} are able to find GLib's ``schemas'' and
2322 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
2323 modules}. This is achieved by wrapping the programs in launch scripts
2324 that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
2325 environment variables.
2327 It is possible to exclude specific package outputs from that wrapping
2328 process by listing their names in the
2329 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
2330 when an output is known not to contain any GLib or GTK+ binaries, and
2331 where wrapping would gratuitously add a dependency of that output on
2334 @item glib-or-gtk-compile-schemas
2335 The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
2336 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
2337 GSettings schemas} are compiled. Compilation is performed by the
2338 @command{glib-compile-schemas} program. It is provided by the package
2339 @code{glib:bin} which is automatically imported by the build system.
2340 The @code{glib} package providing @command{glib-compile-schemas} can be
2341 specified with the @code{#:glib} parameter.
2344 Both phases are executed after the @code{install} phase.
2347 @defvr {Scheme Variable} python-build-system
2348 This variable is exported by @code{(guix build-system python)}. It
2349 implements the more or less standard build procedure used by Python
2350 packages, which consists in running @code{python setup.py build} and
2351 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
2353 For packages that install stand-alone Python programs under @code{bin/},
2354 it takes care of wrapping these programs so their @code{PYTHONPATH}
2355 environment variable points to all the Python libraries they depend on.
2357 Which Python package is used can be specified with the @code{#:python}
2361 @defvr {Scheme Variable} perl-build-system
2362 This variable is exported by @code{(guix build-system perl)}. It
2363 implements the standard build procedure for Perl packages, which either
2364 consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
2365 followed by @code{Build} and @code{Build install}; or in running
2366 @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
2367 @code{make} and @code{make install}; depending on which of
2368 @code{Build.PL} or @code{Makefile.PL} is present in the package
2369 distribution. Preference is given to the former if both @code{Build.PL}
2370 and @code{Makefile.PL} exist in the package distribution. This
2371 preference can be reversed by specifying @code{#t} for the
2372 @code{#:make-maker?} parameter.
2374 The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
2375 passes flags specified by the @code{#:make-maker-flags} or
2376 @code{#:module-build-flags} parameter, respectively.
2378 Which Perl package is used can be specified with @code{#:perl}.
2381 @defvr {Scheme Variable} ruby-build-system
2382 This variable is exported by @code{(guix build-system ruby)}. It
2383 implements the RubyGems build procedure used by Ruby packages, which
2384 involves running @code{gem build} followed by @code{gem install}.
2386 Which Ruby package is used can be specified with the @code{#:ruby}
2390 @defvr {Scheme Variable} waf-build-system
2391 This variable is exported by @code{(guix build-system waf)}. It
2392 implements a build procedure around the @code{waf} script. The common
2393 phases---@code{configure}, @code{build}, and @code{install}---are
2394 implemented by passing their names as arguments to the @code{waf}
2397 The @code{waf} script is executed by the Python interpreter. Which
2398 Python package is used to run the script can be specified with the
2399 @code{#:python} parameter.
2402 @defvr {Scheme Variable} haskell-build-system
2403 This variable is exported by @code{(guix build-system haskell)}. It
2404 implements the Cabal build procedure used by Haskell packages, which
2405 involves running @code{runhaskell Setup.hs configure
2406 --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
2407 Instead of installing the package by running @code{runhaskell Setup.hs
2408 install}, to avoid trying to register libraries in the read-only
2409 compiler store directory, the build system uses @code{runhaskell
2410 Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
2411 addition, the build system generates the package documentation by
2412 running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
2413 is passed. Optional Haddock parameters can be passed with the help of
2414 the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
2415 not found, the build system looks for @code{Setup.lhs} instead.
2417 Which Haskell compiler is used can be specified with the @code{#:haskell}
2418 parameter which defaults to @code{ghc}.
2421 Lastly, for packages that do not need anything as sophisticated, a
2422 ``trivial'' build system is provided. It is trivial in the sense that
2423 it provides basically no support: it does not pull any implicit inputs,
2424 and does not have a notion of build phases.
2426 @defvr {Scheme Variable} trivial-build-system
2427 This variable is exported by @code{(guix build-system trivial)}.
2429 This build system requires a @code{#:builder} argument. This argument
2430 must be a Scheme expression that builds the package's output(s)---as
2431 with @code{build-expression->derivation} (@pxref{Derivations,
2432 @code{build-expression->derivation}}).
2441 Conceptually, the @dfn{store} is where derivations that have been
2442 successfully built are stored---by default, under @file{/gnu/store}.
2443 Sub-directories in the store are referred to as @dfn{store paths}. The
2444 store has an associated database that contains information such has the
2445 store paths referred to by each store path, and the list of @emph{valid}
2446 store paths---paths that result from a successful build.
2448 The store is always accessed by the daemon on behalf of its clients
2449 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
2450 connect to the daemon over a Unix-domain socket, send it requests, and
2451 read the result---these are remote procedure calls, or RPCs.
2453 The @code{(guix store)} module provides procedures to connect to the
2454 daemon, and to perform RPCs. These are described below.
2456 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
2457 Connect to the daemon over the Unix-domain socket at @var{file}. When
2458 @var{reserve-space?} is true, instruct it to reserve a little bit of
2459 extra space on the file system so that the garbage collector can still
2460 operate, should the disk become full. Return a server object.
2462 @var{file} defaults to @var{%default-socket-path}, which is the normal
2463 location given the options that were passed to @command{configure}.
2466 @deffn {Scheme Procedure} close-connection @var{server}
2467 Close the connection to @var{server}.
2470 @defvr {Scheme Variable} current-build-output-port
2471 This variable is bound to a SRFI-39 parameter, which refers to the port
2472 where build and error logs sent by the daemon should be written.
2475 Procedures that make RPCs all take a server object as their first
2478 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
2479 Return @code{#t} when @var{path} is a valid store path.
2482 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
2483 Add @var{text} under file @var{name} in the store, and return its store
2484 path. @var{references} is the list of store paths referred to by the
2485 resulting store path.
2488 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
2489 Build @var{derivations} (a list of @code{<derivation>} objects or
2490 derivation paths), and return when the worker is done building them.
2491 Return @code{#t} on success.
2494 Note that the @code{(guix monads)} module provides a monad as well as
2495 monadic versions of the above procedures, with the goal of making it
2496 more convenient to work with code that accesses the store (@pxref{The
2500 @i{This section is currently incomplete.}
2503 @section Derivations
2506 Low-level build actions and the environment in which they are performed
2507 are represented by @dfn{derivations}. A derivation contain the
2508 following pieces of information:
2512 The outputs of the derivation---derivations produce at least one file or
2513 directory in the store, but may produce more.
2516 The inputs of the derivations, which may be other derivations or plain
2517 files in the store (patches, build scripts, etc.)
2520 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
2523 The file name of a build script in the store, along with the arguments
2527 A list of environment variables to be defined.
2531 @cindex derivation path
2532 Derivations allow clients of the daemon to communicate build actions to
2533 the store. They exist in two forms: as an in-memory representation,
2534 both on the client- and daemon-side, and as files in the store whose
2535 name end in @code{.drv}---these files are referred to as @dfn{derivation
2536 paths}. Derivations paths can be passed to the @code{build-derivations}
2537 procedure to perform the build actions they prescribe (@pxref{The
2540 The @code{(guix derivations)} module provides a representation of
2541 derivations as Scheme objects, along with procedures to create and
2542 otherwise manipulate derivations. The lowest-level primitive to create
2543 a derivation is the @code{derivation} procedure:
2545 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
2546 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2547 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
2548 [#:system (%current-system)] [#:references-graphs #f] @
2549 [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
2550 Build a derivation with the given arguments, and return the resulting
2551 @code{<derivation>} object.
2553 When @var{hash} and @var{hash-algo} are given, a
2554 @dfn{fixed-output derivation} is created---i.e., one whose result is
2555 known in advance, such as a file download. If, in addition,
2556 @var{recursive?} is true, then that fixed output may be an executable
2557 file or a directory and @var{hash} must be the hash of an archive
2558 containing this output.
2560 When @var{references-graphs} is true, it must be a list of file
2561 name/store path pairs. In that case, the reference graph of each store
2562 path is exported in the build environment in the corresponding file, in
2563 a simple text format.
2565 When @var{allowed-references} is true, it must be a list of store items
2566 or outputs that the derivation's output may refer to.
2568 When @var{leaked-env-vars} is true, it must be a list of strings
2569 denoting environment variables that are allowed to ``leak'' from the
2570 daemon's environment to the build environment. This is only applicable
2571 to fixed-output derivations---i.e., when @var{hash} is true. The main
2572 use is to allow variables such as @code{http_proxy} to be passed to
2573 derivations that download files.
2575 When @var{local-build?} is true, declare that the derivation is not a
2576 good candidate for offloading and should rather be built locally
2577 (@pxref{Daemon Offload Setup}). This is the case for small derivations
2578 where the costs of data transfers would outweigh the benefits.
2582 Here's an example with a shell script as its builder, assuming
2583 @var{store} is an open connection to the daemon, and @var{bash} points
2584 to a Bash executable in the store:
2587 (use-modules (guix utils)
2591 (let ((builder ; add the Bash script to the store
2592 (add-text-to-store store "my-builder.sh"
2593 "echo hello world > $out\n" '())))
2594 (derivation store "foo"
2595 bash `("-e" ,builder)
2596 #:inputs `((,bash) (,builder))
2597 #:env-vars '(("HOME" . "/homeless"))))
2598 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
2601 As can be guessed, this primitive is cumbersome to use directly. A
2602 better approach is to write build scripts in Scheme, of course! The
2603 best course of action for that is to write the build code as a
2604 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
2605 information, @pxref{G-Expressions}.
2607 Once upon a time, @code{gexp->derivation} did not exist and constructing
2608 derivations with build code written in Scheme was achieved with
2609 @code{build-expression->derivation}, documented below. This procedure
2610 is now deprecated in favor of the much nicer @code{gexp->derivation}.
2612 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
2613 @var{name} @var{exp} @
2614 [#:system (%current-system)] [#:inputs '()] @
2615 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2616 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
2617 [#:references-graphs #f] [#:allowed-references #f] @
2618 [#:local-build? #f] [#:guile-for-build #f]
2619 Return a derivation that executes Scheme expression @var{exp} as a
2620 builder for derivation @var{name}. @var{inputs} must be a list of
2621 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
2622 @code{"out"} is assumed. @var{modules} is a list of names of Guile
2623 modules from the current search path to be copied in the store,
2624 compiled, and made available in the load path during the execution of
2625 @var{exp}---e.g., @code{((guix build utils) (guix build
2626 gnu-build-system))}.
2628 @var{exp} is evaluated in an environment where @code{%outputs} is bound
2629 to a list of output/path pairs, and where @code{%build-inputs} is bound
2630 to a list of string/output-path pairs made from @var{inputs}.
2631 Optionally, @var{env-vars} is a list of string pairs specifying the name
2632 and value of environment variables visible to the builder. The builder
2633 terminates by passing the result of @var{exp} to @code{exit}; thus, when
2634 @var{exp} returns @code{#f}, the build is considered to have failed.
2636 @var{exp} is built using @var{guile-for-build} (a derivation). When
2637 @var{guile-for-build} is omitted or is @code{#f}, the value of the
2638 @code{%guile-for-build} fluid is used instead.
2640 See the @code{derivation} procedure for the meaning of
2641 @var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
2645 Here's an example of a single-output derivation that creates a directory
2646 containing one file:
2649 (let ((builder '(let ((out (assoc-ref %outputs "out")))
2650 (mkdir out) ; create /gnu/store/@dots{}-goo
2651 (call-with-output-file (string-append out "/test")
2653 (display '(hello guix) p))))))
2654 (build-expression->derivation store "goo" builder))
2656 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
2660 @node The Store Monad
2661 @section The Store Monad
2665 The procedures that operate on the store described in the previous
2666 sections all take an open connection to the build daemon as their first
2667 argument. Although the underlying model is functional, they either have
2668 side effects or depend on the current state of the store.
2670 The former is inconvenient: the connection to the build daemon has to be
2671 carried around in all those functions, making it impossible to compose
2672 functions that do not take that parameter with functions that do. The
2673 latter can be problematic: since store operations have side effects
2674 and/or depend on external state, they have to be properly sequenced.
2676 @cindex monadic values
2677 @cindex monadic functions
2678 This is where the @code{(guix monads)} module comes in. This module
2679 provides a framework for working with @dfn{monads}, and a particularly
2680 useful monad for our uses, the @dfn{store monad}. Monads are a
2681 construct that allows two things: associating ``context'' with values
2682 (in our case, the context is the store), and building sequences of
2683 computations (here computations include accesses to the store.) Values
2684 in a monad---values that carry this additional context---are called
2685 @dfn{monadic values}; procedures that return such values are called
2686 @dfn{monadic procedures}.
2688 Consider this ``normal'' procedure:
2691 (define (sh-symlink store)
2692 ;; Return a derivation that symlinks the 'bash' executable.
2693 (let* ((drv (package-derivation store bash))
2694 (out (derivation->output-path drv))
2695 (sh (string-append out "/bin/bash")))
2696 (build-expression->derivation store "sh"
2697 `(symlink ,sh %output))))
2700 Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
2701 as a monadic function:
2704 (define (sh-symlink)
2705 ;; Same, but return a monadic value.
2706 (mlet %store-monad ((drv (package->derivation bash)))
2707 (gexp->derivation "sh"
2708 #~(symlink (string-append #$drv "/bin/bash")
2712 There several things to note in the second version: the @code{store}
2713 parameter is now implicit and is ``threaded'' in the calls to the
2714 @code{package->derivation} and @code{gexp->derivation} monadic
2715 procedures, and the monadic value returned by @code{package->derivation}
2716 is @dfn{bound} using @code{mlet} instead of plain @code{let}.
2718 As it turns out, the call to @code{package->derivation} can even be
2719 omitted since it will take place implicitly, as we will see later
2720 (@pxref{G-Expressions}):
2723 (define (sh-symlink)
2724 (gexp->derivation "sh"
2725 #~(symlink (string-append #$bash "/bin/bash")
2729 Calling the monadic @code{sh-symlink} has no effect. To get the desired
2730 effect, one must use @code{run-with-store}:
2733 (run-with-store (open-connection) (sh-symlink))
2734 @result{} /gnu/store/...-sh-symlink
2737 Note that the @code{(guix monad-repl)} module extends Guile's REPL with
2738 new ``meta-commands'' to make it easier to deal with monadic procedures:
2739 @code{run-in-store}, and @code{enter-store-monad}. The former, is used
2740 to ``run'' a single monadic value through the store:
2743 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
2744 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2747 The latter enters a recursive REPL, where all the return values are
2748 automatically run through the store:
2751 scheme@@(guile-user)> ,enter-store-monad
2752 store-monad@@(guile-user) [1]> (package->derivation hello)
2753 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2754 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
2755 $3 = "/gnu/store/@dots{}-foo"
2756 store-monad@@(guile-user) [1]> ,q
2757 scheme@@(guile-user)>
2761 Note that non-monadic values cannot be returned in the
2762 @code{store-monad} REPL.
2764 The main syntactic forms to deal with monads in general are provided by
2765 the @code{(guix monads)} module and are described below.
2767 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
2768 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
2772 @deffn {Scheme Syntax} return @var{val}
2773 Return a monadic value that encapsulates @var{val}.
2776 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
2777 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
2778 procedure @var{mproc}@footnote{This operation is commonly referred to as
2779 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
2780 we use this somewhat cryptic symbol inherited from the Haskell
2784 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
2786 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
2788 Bind the variables @var{var} to the monadic values @var{mval} in
2789 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
2790 ``normal'' value @var{val}, as per @code{let}.
2792 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
2793 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
2796 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
2797 Bind @var{mexp} and the following monadic expressions in sequence,
2798 returning the result of the last expression.
2800 This is akin to @code{mlet}, except that the return values of the
2801 monadic expressions are ignored. In that sense, it is analogous to
2802 @code{begin}, but applied to monadic expressions.
2806 The @code{(guix monads)} module provides the @dfn{state monad}, which
2807 allows an additional value---the state---to be @emph{threaded} through
2808 monadic procedure calls.
2810 @defvr {Scheme Variable} %state-monad
2811 The state monad. Procedures in the state monad can access and change
2812 the state that is threaded.
2814 Consider the example below. The @code{square} procedure returns a value
2815 in the state monad. It returns the square of its argument, but also
2816 increments the current state value:
2820 (mlet %state-monad ((count (current-state)))
2821 (mbegin %state-monad
2822 (set-current-state (+ 1 count))
2825 (run-with-state (sequence %state-monad (map square (iota 3))) 0)
2830 When ``run'' through @var{%state-monad}, we obtain that additional state
2831 value, which is the number of @code{square} calls.
2834 @deffn {Monadic Procedure} current-state
2835 Return the current state as a monadic value.
2838 @deffn {Monadic Procedure} set-current-state @var{value}
2839 Set the current state to @var{value} and return the previous state as a
2843 @deffn {Monadic Procedure} state-push @var{value}
2844 Push @var{value} to the current state, which is assumed to be a list,
2845 and return the previous state as a monadic value.
2848 @deffn {Monadic Procedure} state-pop
2849 Pop a value from the current state and return it as a monadic value.
2850 The state is assumed to be a list.
2853 @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
2854 Run monadic value @var{mval} starting with @var{state} as the initial
2855 state. Return two values: the resulting value, and the resulting state.
2858 The main interface to the store monad, provided by the @code{(guix
2859 store)} module, is as follows.
2861 @defvr {Scheme Variable} %store-monad
2862 The store monad---an alias for @var{%state-monad}.
2864 Values in the store monad encapsulate accesses to the store. When its
2865 effect is needed, a value of the store monad must be ``evaluated'' by
2866 passing it to the @code{run-with-store} procedure (see below.)
2869 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
2870 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
2871 open store connection.
2874 @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
2875 Return as a monadic value the absolute file name in the store of the file
2876 containing @var{text}, a string. @var{references} is a list of store items that the
2877 resulting text file refers to; it defaults to the empty list.
2880 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
2882 Return the name of @var{file} once interned in the store. Use
2883 @var{name} as its store name, or the basename of @var{file} if
2884 @var{name} is omitted.
2886 When @var{recursive?} is true, the contents of @var{file} are added
2887 recursively; if @var{file} designates a flat file and @var{recursive?}
2888 is true, its contents are added, and its permission bits are kept.
2890 The example below adds a file to the store, under two different names:
2893 (run-with-store (open-connection)
2894 (mlet %store-monad ((a (interned-file "README"))
2895 (b (interned-file "README" "LEGU-MIN")))
2896 (return (list a b))))
2898 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
2903 The @code{(guix packages)} module exports the following package-related
2906 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
2907 [#:system (%current-system)] [#:target #f] @
2908 [#:output "out"] Return as a monadic
2909 value in the absolute file name of @var{file} within the @var{output}
2910 directory of @var{package}. When @var{file} is omitted, return the name
2911 of the @var{output} directory of @var{package}. When @var{target} is
2912 true, use it as a cross-compilation target triplet.
2915 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
2916 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
2917 @var{target} [@var{system}]
2918 Monadic version of @code{package-derivation} and
2919 @code{package-cross-derivation} (@pxref{Defining Packages}).
2924 @section G-Expressions
2926 @cindex G-expression
2927 @cindex build code quoting
2928 So we have ``derivations'', which represent a sequence of build actions
2929 to be performed to produce an item in the store (@pxref{Derivations}).
2930 Those build actions are performed when asking the daemon to actually
2931 build the derivations; they are run by the daemon in a container
2932 (@pxref{Invoking guix-daemon}).
2934 @cindex strata of code
2935 It should come as no surprise that we like to write those build actions
2936 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2937 code@footnote{The term @dfn{stratum} in this context was coined by
2938 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2939 Kiselyov, who has written insightful
2940 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2941 on this topic}, refers to this kind of code generation as
2942 @dfn{staging}.}: the ``host code''---code that defines packages, talks
2943 to the daemon, etc.---and the ``build code''---code that actually
2944 performs build actions, such as making directories, invoking
2945 @command{make}, etc.
2947 To describe a derivation and its build actions, one typically needs to
2948 embed build code inside host code. It boils down to manipulating build
2949 code as data, and Scheme's homoiconicity---code has a direct
2950 representation as data---comes in handy for that. But we need more than
2951 Scheme's normal @code{quasiquote} mechanism to construct build
2954 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2955 S-expressions adapted to build expressions. G-expressions, or
2956 @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2957 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2958 @code{#$}, and @code{#$@@}), which are comparable respectively to
2959 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2960 (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2961 Reference Manual}). However, there are major differences:
2965 Gexps are meant to be written to a file and run or manipulated by other
2969 When a high-level object such as a package or derivation is unquoted
2970 inside a gexp, the result is as if its output file name had been
2974 Gexps carry information about the packages or derivations they refer to,
2975 and these dependencies are automatically added as inputs to the build
2976 processes that use them.
2979 This mechanism is not limited to package and derivation
2980 objects: @dfn{compilers} able to ``lower'' other high-level objects to
2981 derivations can be defined, such that these objects can also be inserted
2982 into gexps. For example, a useful type of high-level object that can be
2983 inserted in a gexp is ``file-like objects'', which make it easy to
2984 add files to the store and refer to them in
2985 derivations and such (see @code{local-file} and @code{plain-file}
2988 To illustrate the idea, here is an example of a gexp:
2995 (symlink (string-append #$coreutils "/bin/ls")
2999 This gexp can be passed to @code{gexp->derivation}; we obtain a
3000 derivation that builds a directory containing exactly one symlink to
3001 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
3004 (gexp->derivation "the-thing" build-exp)
3007 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
3008 substituted to the reference to the @var{coreutils} package in the
3009 actual build code, and @var{coreutils} is automatically made an input to
3010 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
3011 output)}) is replaced by a string containing the derivation's output
3014 @cindex cross compilation
3015 In a cross-compilation context, it is useful to distinguish between
3016 references to the @emph{native} build of a package---that can run on the
3017 host---versus references to cross builds of a package. To that end, the
3018 @code{#+} plays the same role as @code{#$}, but is a reference to a
3019 native package build:
3022 (gexp->derivation "vi"
3025 (system* (string-append #+coreutils "/bin/ln")
3027 (string-append #$emacs "/bin/emacs")
3028 (string-append #$output "/bin/vi")))
3029 #:target "mips64el-linux")
3033 In the example above, the native build of @var{coreutils} is used, so
3034 that @command{ln} can actually run on the host; but then the
3035 cross-compiled build of @var{emacs} is referenced.
3037 The syntactic form to construct gexps is summarized below.
3039 @deffn {Scheme Syntax} #~@var{exp}
3040 @deffnx {Scheme Syntax} (gexp @var{exp})
3041 Return a G-expression containing @var{exp}. @var{exp} may contain one
3042 or more of the following forms:
3046 @itemx (ungexp @var{obj})
3047 Introduce a reference to @var{obj}. @var{obj} may have one of the
3048 supported types, for example a package or a
3049 derivation, in which case the @code{ungexp} form is replaced by its
3050 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
3052 If @var{obj} is a list, it is traversed and references to supported
3053 objects are substituted similarly.
3055 If @var{obj} is another gexp, its contents are inserted and its
3056 dependencies are added to those of the containing gexp.
3058 If @var{obj} is another kind of object, it is inserted as is.
3060 @item #$@var{obj}:@var{output}
3061 @itemx (ungexp @var{obj} @var{output})
3062 This is like the form above, but referring explicitly to the
3063 @var{output} of @var{obj}---this is useful when @var{obj} produces
3064 multiple outputs (@pxref{Packages with Multiple Outputs}).
3067 @itemx #+@var{obj}:output
3068 @itemx (ungexp-native @var{obj})
3069 @itemx (ungexp-native @var{obj} @var{output})
3070 Same as @code{ungexp}, but produces a reference to the @emph{native}
3071 build of @var{obj} when used in a cross compilation context.
3073 @item #$output[:@var{output}]
3074 @itemx (ungexp output [@var{output}])
3075 Insert a reference to derivation output @var{output}, or to the main
3076 output when @var{output} is omitted.
3078 This only makes sense for gexps passed to @code{gexp->derivation}.
3081 @itemx (ungexp-splicing @var{lst})
3082 Like the above, but splices the contents of @var{lst} inside the
3086 @itemx (ungexp-native-splicing @var{lst})
3087 Like the above, but refers to native builds of the objects listed in
3092 G-expressions created by @code{gexp} or @code{#~} are run-time objects
3093 of the @code{gexp?} type (see below.)
3096 @deffn {Scheme Procedure} gexp? @var{obj}
3097 Return @code{#t} if @var{obj} is a G-expression.
3100 G-expressions are meant to be written to disk, either as code building
3101 some derivation, or as plain files in the store. The monadic procedures
3102 below allow you to do that (@pxref{The Store Monad}, for more
3103 information about monads.)
3105 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
3106 [#:system (%current-system)] [#:target #f] [#:graft? #t] @
3107 [#:hash #f] [#:hash-algo #f] @
3108 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
3109 [#:module-path @var{%load-path}] @
3110 [#:references-graphs #f] [#:allowed-references #f] @
3111 [#:leaked-env-vars #f] @
3112 [#:local-build? #f] [#:guile-for-build #f]
3113 Return a derivation @var{name} that runs @var{exp} (a gexp) with
3114 @var{guile-for-build} (a derivation) on @var{system}. When @var{target}
3115 is true, it is used as the cross-compilation target triplet for packages
3116 referred to by @var{exp}.
3118 Make @var{modules} available in the evaluation context of @var{exp};
3119 @var{modules} is a list of names of Guile modules searched in
3120 @var{module-path} to be copied in the store, compiled, and made available in
3121 the load path during the execution of @var{exp}---e.g., @code{((guix
3122 build utils) (guix build gnu-build-system))}.
3124 @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
3127 When @var{references-graphs} is true, it must be a list of tuples of one of the
3131 (@var{file-name} @var{package})
3132 (@var{file-name} @var{package} @var{output})
3133 (@var{file-name} @var{derivation})
3134 (@var{file-name} @var{derivation} @var{output})
3135 (@var{file-name} @var{store-item})
3138 The right-hand-side of each element of @var{references-graphs} is automatically made
3139 an input of the build process of @var{exp}. In the build environment, each
3140 @var{file-name} contains the reference graph of the corresponding item, in a simple
3143 @var{allowed-references} must be either @code{#f} or a list of output names and packages.
3144 In the latter case, the list denotes store items that the result is allowed to
3145 refer to. Any reference to another store item will lead to a build error.
3147 The other arguments are as for @code{derivation} (@pxref{Derivations}).
3150 @cindex file-like objects
3151 The @code{local-file} and @code{plain-file} procedures below return
3152 @dfn{file-like objects}. That is, when unquoted in a G-expression,
3153 these objects lead to a file in the store. Consider this G-expression:
3156 #~(system* (string-append #$glibc "/sbin/nscd") "-f"
3157 #$(local-file "/tmp/my-nscd.conf"))
3160 The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
3161 to the store. Once expanded, for instance @i{via}
3162 @code{gexp->derivation}, the G-expression refers to that copy under
3163 @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
3164 does not have any effect on what the G-expression does.
3165 @code{plain-file} can be used similarly; it differs in that the file
3166 content is directly passed as a string.
3168 @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
3170 Return an object representing local file @var{file} to add to the store; this
3171 object can be used in a gexp. @var{file} will be added to the store under @var{name}--by
3172 default the base name of @var{file}.
3174 When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
3175 designates a flat file and @var{recursive?} is true, its contents are added, and its
3176 permission bits are kept.
3178 This is the declarative counterpart of the @code{interned-file} monadic
3179 procedure (@pxref{The Store Monad, @code{interned-file}}).
3182 @deffn {Scheme Procedure} plain-file @var{name} @var{content}
3183 Return an object representing a text file called @var{name} with the given
3184 @var{content} (a string) to be added to the store.
3186 This is the declarative counterpart of @code{text-file}.
3189 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
3190 Return an executable script @var{name} that runs @var{exp} using
3191 @var{guile} with @var{modules} in its search path.
3193 The example below builds a script that simply invokes the @command{ls}
3197 (use-modules (guix gexp) (gnu packages base))
3199 (gexp->script "list-files"
3200 #~(execl (string-append #$coreutils "/bin/ls")
3204 When ``running'' it through the store (@pxref{The Store Monad,
3205 @code{run-with-store}}), we obtain a derivation that produces an
3206 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
3209 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
3211 (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
3216 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
3217 Return a derivation that builds a file @var{name} containing @var{exp}.
3219 The resulting file holds references to all the dependencies of @var{exp}
3220 or a subset thereof.
3223 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
3224 Return as a monadic value a derivation that builds a text file
3225 containing all of @var{text}. @var{text} may list, in addition to
3226 strings, objects of any type that can be used in a gexp: packages,
3227 derivations, local file objects, etc. The resulting store file holds
3228 references to all these.
3230 This variant should be preferred over @code{text-file} anytime the file
3231 to create will reference items from the store. This is typically the
3232 case when building a configuration file that embeds store file names,
3236 (define (profile.sh)
3237 ;; Return the name of a shell script in the store that
3238 ;; initializes the 'PATH' environment variable.
3239 (text-file* "profile.sh"
3240 "export PATH=" coreutils "/bin:"
3241 grep "/bin:" sed "/bin\n"))
3244 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
3245 will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
3246 preventing them from being garbage-collected during its lifetime.
3249 Of course, in addition to gexps embedded in ``host'' code, there are
3250 also modules containing build tools. To make it clear that they are
3251 meant to be used in the build stratum, these modules are kept in the
3252 @code{(guix build @dots{})} name space.
3255 @c *********************************************************************
3259 This section describes tools primarily targeted at developers and users
3260 who write new package definitions. They complement the Scheme
3261 programming interface of Guix in a convenient way.
3264 * Invoking guix build:: Building packages from the command line.
3265 * Invoking guix download:: Downloading a file and printing its hash.
3266 * Invoking guix hash:: Computing the cryptographic hash of a file.
3267 * Invoking guix import:: Importing package definitions.
3268 * Invoking guix refresh:: Updating package definitions.
3269 * Invoking guix lint:: Finding errors in package definitions.
3270 * Invoking guix environment:: Setting up development environments.
3271 * Invoking guix publish:: Sharing substitutes.
3274 @node Invoking guix build
3275 @section Invoking @command{guix build}
3277 The @command{guix build} command builds packages or derivations and
3278 their dependencies, and prints the resulting store paths. Note that it
3279 does not modify the user's profile---this is the job of the
3280 @command{guix package} command (@pxref{Invoking guix package}). Thus,
3281 it is mainly useful for distribution developers.
3283 The general syntax is:
3286 guix build @var{options} @var{package-or-derivation}@dots{}
3289 @var{package-or-derivation} may be either the name of a package found in
3290 the software distribution such as @code{coreutils} or
3291 @code{coreutils-8.20}, or a derivation such as
3292 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
3293 package with the corresponding name (and optionally version) is searched
3294 for among the GNU distribution modules (@pxref{Package Modules}).
3296 Alternatively, the @code{--expression} option may be used to specify a
3297 Scheme expression that evaluates to a package; this is useful when
3298 disambiguation among several same-named packages or package variants is
3301 The @var{options} may be zero or more of the following:
3305 @item --expression=@var{expr}
3306 @itemx -e @var{expr}
3307 Build the package or derivation @var{expr} evaluates to.
3309 For example, @var{expr} may be @code{(@@ (gnu packages guile)
3310 guile-1.8)}, which unambiguously designates this specific variant of
3311 version 1.8 of Guile.
3313 Alternately, @var{expr} may be a G-expression, in which case it is used
3314 as a build program passed to @code{gexp->derivation}
3315 (@pxref{G-Expressions}).
3317 Lastly, @var{expr} may refer to a zero-argument monadic procedure
3318 (@pxref{The Store Monad}). The procedure must return a derivation as a
3319 monadic value, which is then passed through @code{run-with-store}.
3323 Build the packages' source derivations, rather than the packages
3326 For instance, @code{guix build -S gcc} returns something like
3327 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
3329 The returned source tarball is the result of applying any patches and
3330 code snippets specified in the package's @code{origin} (@pxref{Defining
3334 Fetch and return the source of @var{package-or-derivation} and all their
3335 dependencies, recursively. This is a handy way to obtain a local copy
3336 of all the source code needed to build @var{packages}, allowing you to
3337 eventually build them even without network access. It is an extension
3338 of the @code{--source} option and can accept one of the following
3339 optional argument values:
3343 This value causes the @code{--sources} option to behave in the same way
3344 as the @code{--source} option.
3347 Build all packages' source derivations, including any source that might
3348 be listed as @code{inputs}. This is the default value.
3351 $ guix build --sources tzdata
3352 The following derivations will be built:
3353 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
3354 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3358 Build all packages' source derivations, as well as all source
3359 derivations for packages' transitive inputs. This can be used e.g. to
3360 prefetch package source for later offline building.
3363 $ guix build --sources=transitive tzdata
3364 The following derivations will be built:
3365 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3366 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
3367 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
3368 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
3369 /gnu/store/@dots{}-make-4.1.tar.xz.drv
3370 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
3376 @item --system=@var{system}
3377 @itemx -s @var{system}
3378 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
3379 the host's system type.
3381 An example use of this is on Linux-based systems, which can emulate
3382 different personalities. For instance, passing
3383 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
3384 to build packages in a complete 32-bit environment.
3386 @item --target=@var{triplet}
3387 @cindex cross-compilation
3388 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
3389 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
3390 configuration triplets,, configure, GNU Configure and Build System}).
3392 @item --with-source=@var{source}
3393 Use @var{source} as the source of the corresponding package.
3394 @var{source} must be a file name or a URL, as for @command{guix
3395 download} (@pxref{Invoking guix download}).
3397 The ``corresponding package'' is taken to be one specified on the
3398 command line whose name matches the base of @var{source}---e.g., if
3399 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
3400 package is @code{guile}. Likewise, the version string is inferred from
3401 @var{source}; in the previous example, it's @code{2.0.10}.
3403 This option allows users to try out versions of packages other than the
3404 one provided by the distribution. The example below downloads
3405 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
3406 the @code{ed} package:
3409 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
3412 As a developer, @code{--with-source} makes it easy to test release
3416 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
3420 Do not ``graft'' packages. In practice, this means that package updates
3421 available as grafts are not applied. @xref{Security Updates}, for more
3422 information on grafts.
3426 Return the derivation paths, not the output paths, of the given
3429 @item --root=@var{file}
3430 @itemx -r @var{file}
3431 Make @var{file} a symlink to the result, and register it as a garbage
3435 Return the build log file names for the given
3436 @var{package-or-derivation}s, or raise an error if build logs are
3439 This works regardless of how packages or derivations are specified. For
3440 instance, the following invocations are equivalent:
3443 guix build --log-file `guix build -d guile`
3444 guix build --log-file `guix build guile`
3445 guix build --log-file guile
3446 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
3452 @cindex common build options
3453 In addition, a number of options that control the build process are
3454 common to @command{guix build} and other commands that can spawn builds,
3455 such as @command{guix package} or @command{guix archive}. These are the
3460 @item --load-path=@var{directory}
3461 @itemx -L @var{directory}
3462 Add @var{directory} to the front of the package module search path
3463 (@pxref{Package Modules}).
3465 This allows users to define their own packages and make them visible to
3466 the command-line tools.
3470 Keep the build tree of failed builds. Thus, if a build fail, its build
3471 tree is kept under @file{/tmp}, in a directory whose name is shown at
3472 the end of the build log. This is useful when debugging build issues.
3476 Do not build the derivations.
3479 When substituting a pre-built binary fails, fall back to building
3482 @item --no-substitutes
3483 Do not use substitutes for build products. That is, always build things
3484 locally instead of allowing downloads of pre-built binaries
3485 (@pxref{Substitutes}).
3487 @item --no-build-hook
3488 Do not attempt to offload builds @i{via} the daemon's ``build hook''
3489 (@pxref{Daemon Offload Setup}). That is, always build things locally
3490 instead of offloading builds to remote machines.
3492 @item --max-silent-time=@var{seconds}
3493 When the build or substitution process remains silent for more than
3494 @var{seconds}, terminate it and report a build failure.
3496 @item --timeout=@var{seconds}
3497 Likewise, when the build or substitution process lasts for more than
3498 @var{seconds}, terminate it and report a build failure.
3500 By default there is no timeout. This behavior can be restored with
3503 @item --verbosity=@var{level}
3504 Use the given verbosity level. @var{level} must be an integer between 0
3505 and 5; higher means more verbose output. Setting a level of 4 or more
3506 may be helpful when debugging setup issues with the build daemon.
3508 @item --cores=@var{n}
3510 Allow the use of up to @var{n} CPU cores for the build. The special
3511 value @code{0} means to use as many CPU cores as available.
3513 @item --max-jobs=@var{n}
3515 Allow at most @var{n} build jobs in parallel. @xref{Invoking
3516 guix-daemon, @code{--max-jobs}}, for details about this option and the
3517 equivalent @command{guix-daemon} option.
3521 Behind the scenes, @command{guix build} is essentially an interface to
3522 the @code{package-derivation} procedure of the @code{(guix packages)}
3523 module, and to the @code{build-derivations} procedure of the @code{(guix
3524 derivations)} module.
3526 In addition to options explicitly passed on the command line,
3527 @command{guix build} and other @command{guix} commands that support
3528 building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
3530 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
3531 Users can define this variable to a list of command line options that
3532 will automatically be used by @command{guix build} and other
3533 @command{guix} commands that can perform builds, as in the example
3537 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
3540 These options are parsed independently, and the result is appended to
3541 the parsed command-line options.
3545 @node Invoking guix download
3546 @section Invoking @command{guix download}
3548 When writing a package definition, developers typically need to download
3549 the package's source tarball, compute its SHA256 hash, and write that
3550 hash in the package definition (@pxref{Defining Packages}). The
3551 @command{guix download} tool helps with this task: it downloads a file
3552 from the given URI, adds it to the store, and prints both its file name
3553 in the store and its SHA256 hash.
3555 The fact that the downloaded file is added to the store saves bandwidth:
3556 when the developer eventually tries to build the newly defined package
3557 with @command{guix build}, the source tarball will not have to be
3558 downloaded again because it is already in the store. It is also a
3559 convenient way to temporarily stash files, which may be deleted
3560 eventually (@pxref{Invoking guix gc}).
3562 The @command{guix download} command supports the same URIs as used in
3563 package definitions. In particular, it supports @code{mirror://} URIs.
3564 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
3565 Guile bindings for GnuTLS are available in the user's environment; when
3566 they are not available, an error is raised. @xref{Guile Preparations,
3567 how to install the GnuTLS bindings for Guile,, gnutls-guile,
3568 GnuTLS-Guile}, for more information.
3570 The following option is available:
3573 @item --format=@var{fmt}
3575 Write the hash in the format specified by @var{fmt}. For more
3576 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
3579 @node Invoking guix hash
3580 @section Invoking @command{guix hash}
3582 The @command{guix hash} command computes the SHA256 hash of a file.
3583 It is primarily a convenience tool for anyone contributing to the
3584 distribution: it computes the cryptographic hash of a file, which can be
3585 used in the definition of a package (@pxref{Defining Packages}).
3587 The general syntax is:
3590 guix hash @var{option} @var{file}
3593 @command{guix hash} has the following option:
3597 @item --format=@var{fmt}
3599 Write the hash in the format specified by @var{fmt}.
3601 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
3602 (@code{hex} and @code{hexadecimal} can be used as well).
3604 If the @option{--format} option is not specified, @command{guix hash}
3605 will output the hash in @code{nix-base32}. This representation is used
3606 in the definitions of packages.
3610 Compute the hash on @var{file} recursively.
3612 In this case, the hash is computed on an archive containing @var{file},
3613 including its children if it is a directory. Some of @var{file}'s
3614 meta-data is part of the archive; for instance, when @var{file} is a
3615 regular file, the hash is different depending on whether @var{file} is
3616 executable or not. Meta-data such as time stamps has no impact on the
3617 hash (@pxref{Invoking guix archive}).
3618 @c FIXME: Replace xref above with xref to an ``Archive'' section when
3623 @node Invoking guix import
3624 @section Invoking @command{guix import}
3626 @cindex importing packages
3627 @cindex package import
3628 @cindex package conversion
3629 The @command{guix import} command is useful for people willing to add a
3630 package to the distribution but who'd rather do as little work as
3631 possible to get there---a legitimate demand. The command knows of a few
3632 repositories from which it can ``import'' package meta-data. The result
3633 is a package definition, or a template thereof, in the format we know
3634 (@pxref{Defining Packages}).
3636 The general syntax is:
3639 guix import @var{importer} @var{options}@dots{}
3642 @var{importer} specifies the source from which to import package
3643 meta-data, and @var{options} specifies a package identifier and other
3644 options specific to @var{importer}. Currently, the available
3649 Import meta-data for the given GNU package. This provides a template
3650 for the latest version of that GNU package, including the hash of its
3651 source tarball, and its canonical synopsis and description.
3653 Additional information such as the package's dependencies and its
3654 license needs to be figured out manually.
3656 For example, the following command returns a package definition for
3660 guix import gnu hello
3663 Specific command-line options are:
3666 @item --key-download=@var{policy}
3667 As for @code{guix refresh}, specify the policy to handle missing OpenPGP
3668 keys when verifying the package's signature. @xref{Invoking guix
3669 refresh, @code{--key-download}}.
3674 Import meta-data from the @uref{https://pypi.python.org/, Python Package
3675 Index}@footnote{This functionality requires Guile-JSON to be installed.
3676 @xref{Requirements}.}. Information is taken from the JSON-formatted
3677 description available at @code{pypi.python.org} and usually includes all
3678 the relevant information, including package dependencies.
3680 The command below imports meta-data for the @code{itsdangerous} Python
3684 guix import pypi itsdangerous
3689 Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
3690 Information is taken from the JSON-formatted meta-data provided through
3691 @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
3692 relevant information, such as module dependencies. License information
3693 should be checked closely. If Perl is available in the store, then the
3694 @code{corelist} utility will be used to filter core modules out of the
3695 list of dependencies.
3697 The command command below imports meta-data for the @code{Acme::Boolean}
3701 guix import cpan Acme::Boolean
3705 Import meta-data from a local copy of the source of the
3706 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
3707 relies on the @command{nix-instantiate} command of
3708 @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
3709 typically written in a mixture of Nix-language and Bash code. This
3710 command only imports the high-level package structure that is written in
3711 the Nix language. It normally includes all the basic fields of a
3714 When importing a GNU package, the synopsis and descriptions are replaced
3715 by their canonical upstream variant.
3717 As an example, the command below imports the package definition of
3718 LibreOffice (more precisely, it imports the definition of the package
3719 bound to the @code{libreoffice} top-level attribute):
3722 guix import nix ~/path/to/nixpkgs libreoffice
3727 Import meta-data from Haskell community's central package archive
3728 @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
3729 Cabal files and includes all the relevant information, including package
3732 Specific command-line options are:
3735 @item --no-test-dependencies
3737 Do not include dependencies only required to run the test suite.
3740 The command below imports meta-data for the latest version of the
3741 @code{HTTP} Haskell package without including test dependencies:
3744 guix import hackage -t HTTP
3747 A specific package version may optionally be specified by following the
3748 package name by a hyphen and a version number as in the following example:
3751 guix import hackage mtl-2.1.3.1
3754 Currently only indentation structured Cabal files are supported.
3757 The structure of the @command{guix import} code is modular. It would be
3758 useful to have more importers for other package formats, and your help
3759 is welcome here (@pxref{Contributing}).
3761 @node Invoking guix refresh
3762 @section Invoking @command{guix refresh}
3764 The primary audience of the @command{guix refresh} command is developers
3765 of the GNU software distribution. By default, it reports any packages
3766 provided by the distribution that are outdated compared to the latest
3767 upstream version, like this:
3771 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
3772 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
3775 It does so by browsing each package's FTP directory and determining the
3776 highest version number of the source tarballs
3777 therein@footnote{Currently, this only works for GNU packages.}.
3779 When passed @code{--update}, it modifies distribution source files to
3780 update the version numbers and source tarball hashes of those packages'
3781 recipes (@pxref{Defining Packages}). This is achieved by downloading
3782 each package's latest source tarball and its associated OpenPGP
3783 signature, authenticating the downloaded tarball against its signature
3784 using @command{gpg}, and finally computing its hash. When the public
3785 key used to sign the tarball is missing from the user's keyring, an
3786 attempt is made to automatically retrieve it from a public key server;
3787 when it's successful, the key is added to the user's keyring; otherwise,
3788 @command{guix refresh} reports an error.
3790 The following options are supported:
3796 Update distribution source files (package recipes) in place.
3797 @xref{Defining Packages}, for more information on package definitions.
3799 @item --select=[@var{subset}]
3800 @itemx -s @var{subset}
3801 Select all the packages in @var{subset}, one of @code{core} or
3804 The @code{core} subset refers to all the packages at the core of the
3805 distribution---i.e., packages that are used to build ``everything
3806 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
3807 changing one of these packages in the distribution entails a rebuild of
3808 all the others. Thus, such updates are an inconvenience to users in
3809 terms of build time or bandwidth used to achieve the upgrade.
3811 The @code{non-core} subset refers to the remaining packages. It is
3812 typically useful in cases where an update of the core packages would be
3817 In addition, @command{guix refresh} can be passed one or more package
3818 names, as in this example:
3821 guix refresh -u emacs idutils gcc-4.8.4
3825 The command above specifically updates the @code{emacs} and
3826 @code{idutils} packages. The @code{--select} option would have no
3827 effect in this case.
3829 When considering whether to upgrade a package, it is sometimes
3830 convenient to know which packages would be affected by the upgrade and
3831 should be checked for compatibility. For this the following option may
3832 be used when passing @command{guix refresh} one or more package names:
3836 @item --list-dependent
3838 List top-level dependent packages that would need to be rebuilt as a
3839 result of upgrading one or more packages.
3843 Be aware that the @code{--list-dependent} option only
3844 @emph{approximates} the rebuilds that would be required as a result of
3845 an upgrade. More rebuilds might be required under some circumstances.
3848 $ guix refresh --list-dependent flex
3849 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
3850 hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
3853 The command above lists a set of packages that could be built to check
3854 for compatibility with an upgraded @code{flex} package.
3856 The following options can be used to customize GnuPG operation:
3860 @item --gpg=@var{command}
3861 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
3862 for in @code{$PATH}.
3864 @item --key-download=@var{policy}
3865 Handle missing OpenPGP keys according to @var{policy}, which may be one
3870 Always download missing OpenPGP keys from the key server, and add them
3871 to the user's GnuPG keyring.
3874 Never try to download missing OpenPGP keys. Instead just bail out.
3877 When a package signed with an unknown OpenPGP key is encountered, ask
3878 the user whether to download it or not. This is the default behavior.
3881 @item --key-server=@var{host}
3882 Use @var{host} as the OpenPGP key server when importing a public key.
3886 @node Invoking guix lint
3887 @section Invoking @command{guix lint}
3888 The @command{guix lint} is meant to help package developers avoid common
3889 errors and use a consistent style. It runs a number of checks on a
3890 given set of packages in order to find common mistakes in their
3891 definitions. Available @dfn{checkers} include (see
3892 @code{--list-checkers} for a complete list):
3897 Validate certain typographical and stylistic rules about package
3898 descriptions and synopses.
3900 @item inputs-should-be-native
3901 Identify inputs that should most likely be native inputs.
3905 Probe @code{home-page} and @code{source} URLs and report those that are
3909 The general syntax is:
3912 guix lint @var{options} @var{package}@dots{}
3915 If no package is given on the command line, then all packages are checked.
3916 The @var{options} may be zero or more of the following:
3922 Only enable the checkers specified in a comma-separated list using the
3923 names returned by @code{--list-checkers}.
3925 @item --list-checkers
3927 List and describe all the available checkers that will be run on packages
3932 @node Invoking guix environment
3933 @section Invoking @command{guix environment}
3935 @cindex reproducible build environments
3936 The purpose of @command{guix environment} is to assist hackers in
3937 creating reproducible development environments without polluting their
3938 package profile. The @command{guix environment} tool takes one or more
3939 packages, builds all of the necessary inputs, and creates a shell
3940 environment to use them.
3942 The general syntax is:
3945 guix environment @var{options} @var{package}@dots{}
3948 The following examples spawns a new shell that is capable of building
3949 the GNU Guile source code:
3952 guix environment guile
3955 If the specified packages are not built yet, @command{guix environment}
3956 automatically builds them. The new shell's environment is an augmented
3957 version of the environment that @command{guix environment} was run in.
3958 It contains the necessary search paths for building the given package
3959 added to the existing environment variables. To create a ``pure''
3960 environment in which the original environment variables have been unset,
3961 use the @code{--pure} option.
3963 Additionally, more than one package may be specified, in which case the
3964 union of the inputs for the given packages are used. For example, the
3965 command below spawns a shell where all of the dependencies of both Guile
3966 and Emacs are available:
3969 guix environment guile emacs
3972 Sometimes an interactive shell session is not desired. The
3973 @code{--exec} option can be used to specify the command to run instead.
3976 guix environment guile --exec=make
3979 The following options are available:
3982 @item --expression=@var{expr}
3983 @itemx -e @var{expr}
3984 Create an environment for the package that @var{expr} evaluates to.
3986 @item --load=@var{file}
3987 @itemx -l @var{file}
3988 Create an environment for the package that the code within @var{file}
3991 @item --exec=@var{command}
3992 @item -E @var{command}
3993 Execute @var{command} in the new environment.
3996 Include all specified packages in the resulting environment, as if an
3997 @i{ad hoc} package were defined with them as inputs. This option is
3998 useful for quickly creating an environment without having to write a
3999 package expression to contain the desired inputs.
4001 For instance, the command:
4004 guix environment --ad-hoc guile guile-sdl -E guile
4007 runs @command{guile} in an environment where Guile and Guile-SDL are
4011 Unset existing environment variables when building the new environment.
4012 This has the effect of creating an environment in which search paths
4013 only contain package inputs.
4015 @item --search-paths
4016 Display the environment variable definitions that make up the
4020 It also supports all of the common build options that @command{guix
4021 build} supports (@pxref{Invoking guix build, common build options}).
4023 @node Invoking guix publish
4024 @section Invoking @command{guix publish}
4026 The purpose of @command{guix publish} is to enable users to easily share
4027 their store with others, which can then use it as a substitute server
4028 (@pxref{Substitutes}).
4030 When @command{guix publish} runs, it spawns an HTTP server which allows
4031 anyone with network access to obtain substitutes from it. This means
4032 that any machine running Guix can also act as if it were a build farm,
4033 since the HTTP interface is compatible with Hydra, the software behind
4034 the @code{hydra.gnu.org} build farm.
4036 For security, each substitute is signed, allowing recipients to check
4037 their authenticity and integrity (@pxref{Substitutes}). Because
4038 @command{guix publish} uses the system's signing key, which is only
4039 readable by the system administrator, it must be started as root; the
4040 @code{--user} option makes it drop root privileges early on.
4042 The general syntax is:
4045 guix publish @var{options}@dots{}
4048 Running @command{guix publish} without any additional arguments will
4049 spawn an HTTP server on port 8080:
4055 Once a publishing server has been authorized (@pxref{Invoking guix
4056 archive}), the daemon may download substitutes from it:
4059 guix-daemon --substitute-urls=http://example.org:8080
4062 The following options are available:
4065 @item --port=@var{port}
4066 @itemx -p @var{port}
4067 Listen for HTTP requests on @var{port}.
4069 @item --listen=@var{host}
4070 Listen on the network interface for @var{host}. The default is to
4071 accept connections from any interface.
4073 @item --user=@var{user}
4074 @itemx -u @var{user}
4075 Change privileges to @var{user} as soon as possible---i.e., once the
4076 server socket is open and the signing key has been read.
4078 @item --repl[=@var{port}]
4079 @itemx -r [@var{port}]
4080 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
4081 Reference Manual}) on @var{port} (37146 by default). This is used
4082 primarily for debugging a running @command{guix publish} server.
4085 @c *********************************************************************
4086 @node GNU Distribution
4087 @chapter GNU Distribution
4089 @cindex Guix System Distribution
4091 Guix comes with a distribution of the GNU system consisting entirely of
4092 free software@footnote{The term ``free'' here refers to the
4093 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
4094 users of that software}.}. The
4095 distribution can be installed on its own (@pxref{System Installation}),
4096 but it is also possible to install Guix as a package manager on top of
4097 an installed GNU/Linux system (@pxref{Installation}). To distinguish
4098 between the two, we refer to the standalone distribution as the Guix
4099 System Distribution, or GuixSD.
4101 The distribution provides core GNU packages such as GNU libc, GCC, and
4102 Binutils, as well as many GNU and non-GNU applications. The complete
4103 list of available packages can be browsed
4104 @url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
4105 running @command{guix package} (@pxref{Invoking guix package}):
4108 guix package --list-available
4111 Our goal has been to provide a practical 100% free software distribution of
4112 Linux-based and other variants of GNU, with a focus on the promotion and
4113 tight integration of GNU components, and an emphasis on programs and
4114 tools that help users exert that freedom.
4116 Packages are currently available on the following platforms:
4121 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
4124 Intel 32-bit architecture (IA32), Linux-Libre kernel;
4127 ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
4128 using the EABI hard-float ABI, and Linux-Libre kernel.
4130 @item mips64el-linux
4131 little-endian 64-bit MIPS processors, specifically the Loongson series,
4132 n32 application binary interface (ABI), and Linux-Libre kernel.
4136 GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
4139 For information on porting to other architectures or kernels,
4143 * System Installation:: Installing the whole operating system.
4144 * System Configuration:: Configuring the operating system.
4145 * Installing Debugging Files:: Feeding the debugger.
4146 * Security Updates:: Deploying security fixes quickly.
4147 * Package Modules:: Packages from the programmer's viewpoint.
4148 * Packaging Guidelines:: Growing the distribution.
4149 * Bootstrapping:: GNU/Linux built from scratch.
4150 * Porting:: Targeting another platform or kernel.
4153 Building this distribution is a cooperative effort, and you are invited
4154 to join! @xref{Contributing}, for information about how you can help.
4156 @node System Installation
4157 @section System Installation
4159 @cindex Guix System Distribution
4160 This section explains how to install the Guix System Distribution
4161 on a machine. The Guix package manager can
4162 also be installed on top of a running GNU/Linux system,
4163 @pxref{Installation}.
4166 @c This paragraph is for people reading this from tty2 of the
4167 @c installation image.
4168 You're reading this documentation with an Info reader. For details on
4169 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
4170 link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
4171 @kbd{l} afterwards to come back here.
4174 @subsection Limitations
4176 As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
4177 not production-ready. It may contain bugs and lack important
4178 features. Thus, if you are looking for a stable production system that
4179 respects your freedom as a computer user, a good solution at this point
4180 is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
4181 more established GNU/Linux distributions}. We hope you can soon switch
4182 to the GuixSD without fear, of course. In the meantime, you can
4183 also keep using your distribution and try out the package manager on top
4184 of it (@pxref{Installation}).
4186 Before you proceed with the installation, be aware of the following
4187 noteworthy limitations applicable to version @value{VERSION}:
4191 The installation process does not include a graphical user interface and
4192 requires familiarity with GNU/Linux (see the following subsections to
4193 get a feel of what that means.)
4196 The system does not yet provide GNOME and KDE; it provides Xfce, though,
4197 if graphical desktop environments are your thing.
4200 Support for the Logical Volume Manager (LVM) is missing.
4203 Few system services are currently supported out-of-the-box
4207 On the order of 1,900 packages are available, which means that you may
4208 occasionally find that a useful package is missing.
4211 You've been warned. But more than a disclaimer, this is an invitation
4212 to report issues (and success stories!), and join us in improving it.
4213 @xref{Contributing}, for more info.
4215 @subsection USB Stick Installation
4217 An installation image for USB sticks can be downloaded from
4218 @indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
4219 where @var{system} is one of:
4223 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
4226 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
4229 This image contains a single partition with the tools necessary for an
4230 installation. It is meant to be copied @emph{as is} to a large-enough
4233 To copy the image to a USB stick, follow these steps:
4237 Decompress the image using the @command{xz} command:
4240 xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
4244 Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
4245 its device name. Assuming that USB stick is known as @file{/dev/sdX},
4246 copy the image with:
4249 dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
4252 Access to @file{/dev/sdX} usually requires root privileges.
4255 Once this is done, you should be able to reboot the system and boot from
4256 the USB stick. The latter usually requires you to get in the BIOS' boot
4257 menu, where you can choose to boot from the USB stick.
4259 @subsection Preparing for Installation
4261 Once you have successfully booted the image on the USB stick, you should
4262 end up with a root prompt. Several console TTYs are configured and can
4263 be used to run commands as root. TTY2 shows this documentation,
4264 browsable using the Info reader commands (@pxref{Help,,, info, Info: An
4267 To install the system, you would:
4272 Configure the network, by running @command{ifconfig eno1 up && dhclient
4273 eno1} (to get an automatically assigned IP address from the wired
4274 network interface controller@footnote{
4275 @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
4276 The name @code{eno1} is for the first on-board Ethernet controller. The
4277 interface name for an Ethernet controller that is in the first slot of
4278 the first PCI bus, for instance, would be @code{enp1s0}. Use
4279 @command{ifconfig -a} to list all the available network interfaces.}),
4280 or using the @command{ifconfig} command.
4282 The system automatically loads drivers for your network interface
4285 Setting up network access is almost always a requirement because the
4286 image does not contain all the software and tools that may be needed.
4289 Unless this has already been done, you must partition and format the
4292 Preferably, assign partitions a label so that you can easily and
4293 reliably refer to them in @code{file-system} declarations (@pxref{File
4294 Systems}). This is typically done using the @code{-L} option of
4295 @command{mkfs.ext4} and related commands.
4297 The installation image includes Parted (@pxref{Overview,,, parted, GNU
4298 Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
4299 encryption, and e2fsprogs, the suite of tools to manipulate
4300 ext2/ext3/ext4 file systems.
4303 Once that is done, mount the target root partition under @file{/mnt}.
4306 Lastly, run @code{deco start cow-store /mnt}.
4308 This will make @file{/gnu/store} copy-on-write, such that packages added
4309 to it during the installation phase will be written to the target disk
4310 rather than kept in memory.
4315 @subsection Proceeding with the Installation
4317 With the target partitions ready, you now have to edit a file and
4318 provide the declaration of the operating system to be installed. To
4319 that end, the installation system comes with two text editors: GNU nano
4320 (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
4321 It is better to store that file on the target root file system, say, as
4322 @file{/mnt/etc/config.scm}.
4324 @xref{Using the Configuration System}, for examples of operating system
4325 configurations. These examples are available under
4326 @file{/etc/configuration} in the installation image, so you can copy
4327 them and use them as a starting point for your own configuration.
4329 Once you are done preparing the configuration file, the new system must
4330 be initialized (remember that the target root file system is mounted
4334 guix system init /mnt/etc/config.scm /mnt
4338 This will copy all the necessary files, and install GRUB on
4339 @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
4340 more information, @pxref{Invoking guix system}. This command may trigger
4341 downloads or builds of missing packages, which can take some time.
4343 Once that command has completed---and hopefully succeeded!---you can
4344 run @command{reboot} and boot into the new system. Cross fingers, and
4345 join us on @code{#guix} on the Freenode IRC network or on
4346 @file{guix-devel@@gnu.org} to share your experience---good or not so
4349 @subsection Building the Installation Image
4351 The installation image described above was built using the @command{guix
4352 system} command, specifically:
4355 guix system disk-image --image-size=850MiB gnu/system/install.scm
4358 @xref{Invoking guix system}, for more information. See
4359 @file{gnu/system/install.scm} in the source tree for more information
4360 about the installation image.
4362 @node System Configuration
4363 @section System Configuration
4365 @cindex system configuration
4366 The Guix System Distribution supports a consistent whole-system configuration
4367 mechanism. By that we mean that all aspects of the global system
4368 configuration---such as the available system services, timezone and
4369 locale settings, user accounts---are declared in a single place. Such
4370 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
4372 One of the advantages of putting all the system configuration under the
4373 control of Guix is that it supports transactional system upgrades, and
4374 makes it possible to roll-back to a previous system instantiation,
4375 should something go wrong with the new one (@pxref{Features}). Another
4376 one is that it makes it easy to replicate the exact same configuration
4377 across different machines, or at different points in time, without
4378 having to resort to additional administration tools layered on top of
4379 the system's own tools.
4380 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
4382 This section describes this mechanism. First we focus on the system
4383 administrator's viewpoint---explaining how the system is configured and
4384 instantiated. Then we show how this mechanism can be extended, for
4385 instance to support new system services.
4388 * Using the Configuration System:: Customizing your GNU system.
4389 * operating-system Reference:: Detail of operating-system declarations.
4390 * File Systems:: Configuring file system mounts.
4391 * Mapped Devices:: Block device extra processing.
4392 * User Accounts:: Specifying user accounts.
4393 * Locales:: Language and cultural convention settings.
4394 * Services:: Specifying system services.
4395 * Setuid Programs:: Programs running with root privileges.
4396 * X.509 Certificates:: Authenticating HTTPS servers.
4397 * Name Service Switch:: Configuring libc's name service switch.
4398 * Initial RAM Disk:: Linux-Libre bootstrapping.
4399 * GRUB Configuration:: Configuring the boot loader.
4400 * Invoking guix system:: Instantiating a system configuration.
4401 * Defining Services:: Adding new service definitions.
4404 @node Using the Configuration System
4405 @subsection Using the Configuration System
4407 The operating system is configured by providing an
4408 @code{operating-system} declaration in a file that can then be passed to
4409 the @command{guix system} command (@pxref{Invoking guix system}). A
4410 simple setup, with the default system services, the default Linux-Libre
4411 kernel, initial RAM disk, and boot loader looks like this:
4413 @findex operating-system
4415 @include os-config-bare-bones.texi
4418 This example should be self-describing. Some of the fields defined
4419 above, such as @code{host-name} and @code{bootloader}, are mandatory.
4420 Others, such as @code{packages} and @code{services}, can be omitted, in
4421 which case they get a default value.
4423 @vindex %base-packages
4424 The @code{packages} field lists
4425 packages that will be globally visible on the system, for all user
4426 accounts---i.e., in every user's @code{PATH} environment variable---in
4427 addition to the per-user profiles (@pxref{Invoking guix package}). The
4428 @var{%base-packages} variable provides all the tools one would expect
4429 for basic user and administrator tasks---including the GNU Core
4430 Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
4431 editor, @command{find}, @command{grep}, etc. The example above adds
4432 Emacs to those, taken from the @code{(gnu packages emacs)} module
4433 (@pxref{Package Modules}).
4435 @vindex %base-services
4436 The @code{services} field lists @dfn{system services} to be made
4437 available when the system starts (@pxref{Services}).
4438 The @code{operating-system} declaration above specifies that, in
4439 addition to the basic services, we want the @command{lshd} secure shell
4440 daemon listening on port 2222, and allowing remote @code{root} logins
4441 (@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
4442 @code{lsh-service} arranges so that @code{lshd} is started with the
4443 right command-line options, possibly with supporting configuration files
4444 generated as needed (@pxref{Defining Services}). @xref{operating-system
4445 Reference}, for details about the available @code{operating-system}
4448 The configuration for a typical ``desktop'' usage, with the X11 display
4449 server, a desktop environment, network management, an SSH server, and
4450 more, would look like this:
4453 @include os-config-desktop.texi
4456 @xref{Desktop Services}, for the exact list of services provided by
4457 @var{%desktop-services}. @xref{X.509 Certificates}, for background
4458 information about the @code{nss-certs} package that is used here.
4460 Assuming the above snippet is stored in the @file{my-system-config.scm}
4461 file, the @command{guix system reconfigure my-system-config.scm} command
4462 instantiates that configuration, and makes it the default GRUB boot
4463 entry (@pxref{Invoking guix system}). The normal way to change the
4464 system's configuration is by updating this file and re-running the
4465 @command{guix system} command.
4467 At the Scheme level, the bulk of an @code{operating-system} declaration
4468 is instantiated with the following monadic procedure (@pxref{The Store
4471 @deffn {Monadic Procedure} operating-system-derivation os
4472 Return a derivation that builds @var{os}, an @code{operating-system}
4473 object (@pxref{Derivations}).
4475 The output of the derivation is a single directory that refers to all
4476 the packages, configuration files, and other supporting files needed to
4477 instantiate @var{os}.
4480 @node operating-system Reference
4481 @subsection @code{operating-system} Reference
4483 This section summarizes all the options available in
4484 @code{operating-system} declarations (@pxref{Using the Configuration
4487 @deftp {Data Type} operating-system
4488 This is the data type representing an operating system configuration.
4489 By that, we mean all the global system configuration, not per-user
4490 configuration (@pxref{Using the Configuration System}).
4493 @item @code{kernel} (default: @var{linux-libre})
4494 The package object of the operating system kernel to use@footnote{Currently
4495 only the Linux-libre kernel is supported. In the future, it will be
4496 possible to use the GNU@tie{}Hurd.}.
4498 @item @code{bootloader}
4499 The system bootloader configuration object. @xref{GRUB Configuration}.
4501 @item @code{initrd} (default: @code{base-initrd})
4502 A two-argument monadic procedure that returns an initial RAM disk for
4503 the Linux kernel. @xref{Initial RAM Disk}.
4505 @item @code{firmware} (default: @var{%base-firmware})
4507 List of firmware packages loadable by the operating system kernel.
4509 The default includes firmware needed for Atheros-based WiFi devices
4510 (Linux-libre module @code{ath9k}.)
4512 @item @code{host-name}
4515 @item @code{hosts-file}
4517 A file-like object (@pxref{G-Expressions, file-like objects}) for use as
4518 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
4519 Reference Manual}). The default is a file with entries for
4520 @code{localhost} and @var{host-name}.
4522 @item @code{mapped-devices} (default: @code{'()})
4523 A list of mapped devices. @xref{Mapped Devices}.
4525 @item @code{file-systems}
4526 A list of file systems. @xref{File Systems}.
4528 @item @code{swap-devices} (default: @code{'()})
4529 @cindex swap devices
4530 A list of strings identifying devices to be used for ``swap space''
4531 (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
4532 For example, @code{'("/dev/sda3")}.
4534 @item @code{users} (default: @code{%base-user-accounts})
4535 @itemx @code{groups} (default: @var{%base-groups})
4536 List of user accounts and groups. @xref{User Accounts}.
4538 @item @code{skeletons} (default: @code{(default-skeletons)})
4539 A monadic list of pairs of target file name and files. These are the
4540 files that will be used as skeletons as new accounts are created.
4542 For instance, a valid value may look like this:
4545 (mlet %store-monad ((bashrc (text-file "bashrc" "\
4546 export PATH=$HOME/.guix-profile/bin")))
4547 (return `((".bashrc" ,bashrc))))
4550 @item @code{issue} (default: @var{%default-issue})
4551 A string denoting the contents of the @file{/etc/issue} file, which is
4552 what displayed when users log in on a text console.
4554 @item @code{packages} (default: @var{%base-packages})
4555 The set of packages installed in the global profile, which is accessible
4556 at @file{/run/current-system/profile}.
4558 The default set includes core utilities, but it is good practice to
4559 install non-core utilities in user profiles (@pxref{Invoking guix
4562 @item @code{timezone}
4563 A timezone identifying string---e.g., @code{"Europe/Paris"}.
4565 @item @code{locale} (default: @code{"en_US.utf8"})
4566 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
4567 Library Reference Manual}). @xref{Locales}, for more information.
4569 @item @code{locale-definitions} (default: @var{%default-locale-definitions})
4570 The list of locale definitions to be compiled and that may be used at
4571 run time. @xref{Locales}.
4573 @item @code{name-service-switch} (default: @var{%default-nss})
4574 Configuration of libc's name service switch (NSS)---a
4575 @code{<name-service-switch>} object. @xref{Name Service Switch}, for
4578 @item @code{services} (default: @var{%base-services})
4579 A list of monadic values denoting system services. @xref{Services}.
4581 @item @code{pam-services} (default: @code{(base-pam-services)})
4583 @cindex pluggable authentication modules
4584 Linux @dfn{pluggable authentication module} (PAM) services.
4585 @c FIXME: Add xref to PAM services section.
4587 @item @code{setuid-programs} (default: @var{%setuid-programs})
4588 List of string-valued G-expressions denoting setuid programs.
4589 @xref{Setuid Programs}.
4591 @item @code{sudoers} (default: @var{%sudoers-specification})
4593 The contents of the @file{/etc/sudoers} file as a file-like object
4594 (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
4596 This file specifies which users can use the @command{sudo} command, what
4597 they are allowed to do, and what privileges they may gain. The default
4598 is that only @code{root} and members of the @code{wheel} group may use
4605 @subsection File Systems
4607 The list of file systems to be mounted is specified in the
4608 @code{file-systems} field of the operating system's declaration
4609 (@pxref{Using the Configuration System}). Each file system is declared
4610 using the @code{file-system} form, like this:
4614 (mount-point "/home")
4615 (device "/dev/sda3")
4619 As usual, some of the fields are mandatory---those shown in the example
4620 above---while others can be omitted. These are described below.
4622 @deftp {Data Type} file-system
4623 Objects of this type represent file systems to be mounted. They
4624 contain the following members:
4628 This is a string specifying the type of the file system---e.g.,
4631 @item @code{mount-point}
4632 This designates the place where the file system is to be mounted.
4635 This names the ``source'' of the file system. By default it is the name
4636 of a node under @file{/dev}, but its meaning depends on the @code{title}
4637 field described below.
4639 @item @code{title} (default: @code{'device})
4640 This is a symbol that specifies how the @code{device} field is to be
4643 When it is the symbol @code{device}, then the @code{device} field is
4644 interpreted as a file name; when it is @code{label}, then @code{device}
4645 is interpreted as a partition label name; when it is @code{uuid},
4646 @code{device} is interpreted as a partition unique identifier (UUID).
4648 The @code{label} and @code{uuid} options offer a way to refer to disk
4649 partitions without having to hard-code their actual device name.
4651 However, when a file system's source is a mapped device (@pxref{Mapped
4652 Devices}), its @code{device} field @emph{must} refer to the mapped
4653 device name---e.g., @file{/dev/mapper/root-partition}---and consequently
4654 @code{title} must be set to @code{'device}. This is required so that
4655 the system knows that mounting the file system depends on having the
4656 corresponding device mapping established.
4658 @item @code{flags} (default: @code{'()})
4659 This is a list of symbols denoting mount flags. Recognized flags
4660 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
4661 access to special files), @code{no-suid} (ignore setuid and setgid
4662 bits), and @code{no-exec} (disallow program execution.)
4664 @item @code{options} (default: @code{#f})
4665 This is either @code{#f}, or a string denoting mount options.
4667 @item @code{needed-for-boot?} (default: @code{#f})
4668 This Boolean value indicates whether the file system is needed when
4669 booting. If that is true, then the file system is mounted when the
4670 initial RAM disk (initrd) is loaded. This is always the case, for
4671 instance, for the root file system.
4673 @item @code{check?} (default: @code{#t})
4674 This Boolean indicates whether the file system needs to be checked for
4675 errors before being mounted.
4677 @item @code{create-mount-point?} (default: @code{#f})
4678 When true, the mount point is created if it does not exist yet.
4683 The @code{(gnu system file-systems)} exports the following useful
4686 @defvr {Scheme Variable} %base-file-systems
4687 These are essential file systems that are required on normal systems,
4688 such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
4689 below.) Operating system declarations should always contain at least
4693 @defvr {Scheme Variable} %devtmpfs-file-system
4694 The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
4695 requirement for udev (@pxref{Base Services, @code{udev-service}}).
4698 @defvr {Scheme Variable} %pseudo-terminal-file-system
4699 This is the file system to be mounted as @file{/dev/pts}. It supports
4700 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
4701 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
4702 Manual}). Pseudo-terminals are used by terminal emulators such as
4706 @defvr {Scheme Variable} %shared-memory-file-system
4707 This file system is mounted as @file{/dev/shm} and is used to support
4708 memory sharing across processes (@pxref{Memory-mapped I/O,
4709 @code{shm_open},, libc, The GNU C Library Reference Manual}).
4712 @defvr {Scheme Variable} %immutable-store
4713 This file system performs a read-only ``bind mount'' of
4714 @file{/gnu/store}, making it read-only for all the users including
4715 @code{root}. This prevents against accidental modification by software
4716 running as @code{root} or by system administrators.
4718 The daemon itself is still able to write to the store: it remounts it
4719 read-write in its own ``name space.''
4722 @defvr {Scheme Variable} %binary-format-file-system
4723 The @code{binfmt_misc} file system, which allows handling of arbitrary
4724 executable file types to be delegated to user space. This requires the
4725 @code{binfmt.ko} kernel module to be loaded.
4728 @defvr {Scheme Variable} %fuse-control-file-system
4729 The @code{fusectl} file system, which allows unprivileged users to mount
4730 and unmount user-space FUSE file systems. This requires the
4731 @code{fuse.ko} kernel module to be loaded.
4734 @node Mapped Devices
4735 @subsection Mapped Devices
4737 @cindex device mapping
4738 @cindex mapped devices
4739 The Linux kernel has a notion of @dfn{device mapping}: a block device,
4740 such as a hard disk partition, can be @dfn{mapped} into another device,
4741 with additional processing over the data that flows through
4742 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
4743 concept of a ``mapped device'' and that of a file system: both boil down
4744 to @emph{translating} input/output operations made on a file to
4745 operations on its backing store. Thus, the Hurd implements mapped
4746 devices, like file systems, using the generic @dfn{translator} mechanism
4747 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
4748 typical example is encryption device mapping: all writes to the mapped
4749 device are encrypted, and all reads are deciphered, transparently.
4751 Mapped devices are declared using the @code{mapped-device} form:
4755 (source "/dev/sda3")
4757 (type luks-device-mapping))
4761 @cindex disk encryption
4763 This example specifies a mapping from @file{/dev/sda3} to
4764 @file{/dev/mapper/home} using LUKS---the
4765 @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
4766 standard mechanism for disk encryption. The @file{/dev/mapper/home}
4767 device can then be used as the @code{device} of a @code{file-system}
4768 declaration (@pxref{File Systems}). The @code{mapped-device} form is
4771 @deftp {Data Type} mapped-device
4772 Objects of this type represent device mappings that will be made when
4773 the system boots up.
4777 This string specifies the name of the block device to be mapped, such as
4781 This string specifies the name of the mapping to be established. For
4782 example, specifying @code{"my-partition"} will lead to the creation of
4783 the @code{"/dev/mapper/my-partition"} device.
4786 This must be a @code{mapped-device-kind} object, which specifies how
4787 @var{source} is mapped to @var{target}.
4791 @defvr {Scheme Variable} luks-device-mapping
4792 This defines LUKS block device encryption using the @command{cryptsetup}
4793 command, from the same-named package. This relies on the
4794 @code{dm-crypt} Linux kernel module.
4798 @subsection User Accounts
4800 User accounts and groups are entirely managed through the
4801 @code{operating-system} declaration. They are specified with the
4802 @code{user-account} and @code{user-group} forms:
4808 (supplementary-groups '("wheel" ;allow use of sudo, etc.
4810 "video" ;video devices such as webcams
4811 "cdrom")) ;the good ol' CD-ROM
4812 (comment "Bob's sister")
4813 (home-directory "/home/alice"))
4816 When booting or upon completion of @command{guix system reconfigure},
4817 the system ensures that only the user accounts and groups specified in
4818 the @code{operating-system} declaration exist, and with the specified
4819 properties. Thus, account or group creations or modifications made by
4820 directly invoking commands such as @command{useradd} are lost upon
4821 reconfiguration or reboot. This ensures that the system remains exactly
4824 @deftp {Data Type} user-account
4825 Objects of this type represent user accounts. The following members may
4830 The name of the user account.
4833 This is the name (a string) or identifier (a number) of the user group
4834 this account belongs to.
4836 @item @code{supplementary-groups} (default: @code{'()})
4837 Optionally, this can be defined as a list of group names that this
4840 @item @code{uid} (default: @code{#f})
4841 This is the user ID for this account (a number), or @code{#f}. In the
4842 latter case, a number is automatically chosen by the system when the
4845 @item @code{comment} (default: @code{""})
4846 A comment about the account, such as the account's owner full name.
4848 @item @code{home-directory}
4849 This is the name of the home directory for the account.
4851 @item @code{shell} (default: Bash)
4852 This is a G-expression denoting the file name of a program to be used as
4853 the shell (@pxref{G-Expressions}).
4855 @item @code{system?} (default: @code{#f})
4856 This Boolean value indicates whether the account is a ``system''
4857 account. System accounts are sometimes treated specially; for instance,
4858 graphical login managers do not list them.
4860 @item @code{password} (default: @code{#f})
4861 You would normally leave this field to @code{#f}, initialize user
4862 passwords as @code{root} with the @command{passwd} command, and then let
4863 users change it with @command{passwd}. Passwords set with
4864 @command{passwd} are of course preserved across reboot and
4867 If you @emph{do} want to have a preset password for an account, then
4868 this field must contain the encrypted password, as a string.
4869 @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
4870 on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
4871 Manual}, for information on Guile's @code{crypt} procedure.
4876 User group declarations are even simpler:
4879 (user-group (name "students"))
4882 @deftp {Data Type} user-group
4883 This type is for, well, user groups. There are just a few fields:
4889 @item @code{id} (default: @code{#f})
4890 The group identifier (a number). If @code{#f}, a new number is
4891 automatically allocated when the group is created.
4893 @item @code{system?} (default: @code{#f})
4894 This Boolean value indicates whether the group is a ``system'' group.
4895 System groups have low numerical IDs.
4897 @item @code{password} (default: @code{#f})
4898 What, user groups can have a password? Well, apparently yes. Unless
4899 @code{#f}, this field specifies the group's password.
4904 For convenience, a variable lists all the basic user groups one may
4907 @defvr {Scheme Variable} %base-groups
4908 This is the list of basic user groups that users and/or packages expect
4909 to be present on the system. This includes groups such as ``root'',
4910 ``wheel'', and ``users'', as well as groups used to control access to
4911 specific devices such as ``audio'', ``disk'', and ``cdrom''.
4914 @defvr {Scheme Variable} %base-user-accounts
4915 This is the list of basic system accounts that programs may expect to
4916 find on a GNU/Linux system, such as the ``nobody'' account.
4918 Note that the ``root'' account is not included here. It is a
4919 special-case and is automatically added whether or not it is specified.
4926 A @dfn{locale} defines cultural conventions for a particular language
4927 and region of the world (@pxref{Locales,,, libc, The GNU C Library
4928 Reference Manual}). Each locale has a name that typically has the form
4929 @code{@var{language}_@var{territory}.@var{charset}}---e.g.,
4930 @code{fr_LU.utf8} designates the locale for the French language, with
4931 cultural conventions from Luxembourg, and using the UTF-8 encoding.
4933 @cindex locale definition
4934 Usually, you will want to specify the default locale for the machine
4935 using the @code{locale} field of the @code{operating-system} declaration
4936 (@pxref{operating-system Reference, @code{locale}}).
4938 That locale must be among the @dfn{locale definitions} that are known to
4939 the system---and these are specified in the @code{locale-definitions}
4940 slot of @code{operating-system}. The default value includes locale
4941 definition for some widely used locales, but not for all the available
4942 locales, in order to save space.
4944 If the locale specified in the @code{locale} field is not among the
4945 definitions listed in @code{locale-definitions}, @command{guix system}
4946 raises an error. In that case, you should add the locale definition to
4947 the @code{locale-definitions} field. For instance, to add the North
4948 Frisian locale for Germany, the value of that field may be:
4951 (cons (locale-definition
4952 (name "fy_DE.utf8") (source "fy_DE"))
4953 %default-locale-definitions)
4956 Likewise, to save space, one might want @code{locale-definitions} to
4957 list only the locales that are actually used, as in:
4960 (list (locale-definition
4961 (name "ja_JP.eucjp") (source "ja_JP")
4962 (charset "EUC-JP")))
4965 The @code{locale-definition} form is provided by the @code{(gnu system
4966 locale)} module. Details are given below.
4968 @deftp {Data Type} locale-definition
4969 This is the data type of a locale definition.
4974 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
4975 Reference Manual}, for more information on locale names.
4978 The name of the source for that locale. This is typically the
4979 @code{@var{language}_@var{territory}} part of the locale name.
4981 @item @code{charset} (default: @code{"UTF-8"})
4982 The ``character set'' or ``code set'' for that locale,
4983 @uref{http://www.iana.org/assignments/character-sets, as defined by
4989 @defvr {Scheme Variable} %default-locale-definitions
4990 An arbitrary list of commonly used locales, used as the default value of
4991 the @code{locale-definitions} field of @code{operating-system}
4996 @subsection Services
4998 @cindex system services
4999 An important part of preparing an @code{operating-system} declaration is
5000 listing @dfn{system services} and their configuration (@pxref{Using the
5001 Configuration System}). System services are typically daemons launched
5002 when the system boots, or other actions needed at that time---e.g.,
5003 configuring network access.
5005 Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
5006 dmd Manual}). On a running system, the @command{deco} command allows
5007 you to list the available services, show their status, start and stop
5008 them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
5009 Manual}). For example:
5015 The above command, run as @code{root}, lists the currently defined
5016 services. The @command{deco doc} command shows a synopsis of the given
5021 Run libc's name service cache daemon (nscd).
5024 The @command{start}, @command{stop}, and @command{restart} sub-commands
5025 have the effect you would expect. For instance, the commands below stop
5026 the nscd service and restart the Xorg display server:
5030 Service nscd has been stopped.
5031 # deco restart xorg-server
5032 Service xorg-server has been stopped.
5033 Service xorg-server has been started.
5036 The following sections document the available services, starting with
5037 the core services, that may be used in an @code{operating-system}
5041 * Base Services:: Essential system services.
5042 * Networking Services:: Network setup, SSH daemon, etc.
5043 * X Window:: Graphical display.
5044 * Desktop Services:: D-Bus and desktop services.
5045 * Database Services:: SQL databases.
5046 * Various Services:: Other services.
5050 @subsubsection Base Services
5052 The @code{(gnu services base)} module provides definitions for the basic
5053 services that one expects from the system. The services exported by
5054 this module are listed below.
5056 @defvr {Scheme Variable} %base-services
5057 This variable contains a list of basic services@footnote{Technically,
5058 this is a list of monadic services. @xref{The Store Monad}.} one would
5059 expect from the system: a login service (mingetty) on each tty, syslogd,
5060 libc's name service cache daemon (nscd), the udev device manager, and
5063 This is the default value of the @code{services} field of
5064 @code{operating-system} declarations. Usually, when customizing a
5065 system, you will want to append services to @var{%base-services}, like
5069 (cons* (avahi-service) (lsh-service) %base-services)
5073 @deffn {Monadic Procedure} host-name-service @var{name}
5074 Return a service that sets the host name to @var{name}.
5077 @deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
5078 [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
5079 [#:allow-empty-passwords? #f]
5080 Return a service to run mingetty on @var{tty}.
5082 When @var{allow-empty-passwords?} is true, allow empty log-in password. When
5083 @var{auto-login} is true, it must be a user name under which to log-in
5084 automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
5085 @var{auto-login}, in which case the user will have to press a key before the
5086 login shell is launched.
5088 When true, @var{login-program} is a gexp or a monadic gexp denoting the name
5089 of the log-in program (the default is the @code{login} program from the Shadow
5092 @var{motd} is a monadic value containing a text file to use as
5093 the ``message of the day''.
5096 @cindex name service cache daemon
5098 @deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
5099 [#:name-services '()]
5100 Return a service that runs libc's name service cache daemon (nscd) with
5101 the given @var{config}---an @code{<nscd-configuration>} object.
5102 Optionally, @code{#:name-services} is a list of packages that provide
5103 name service switch (NSS) modules needed by nscd. @xref{Name Service
5104 Switch}, for an example.
5107 @defvr {Scheme Variable} %nscd-default-configuration
5108 This is the default @code{<nscd-configuration>} value (see below) used
5109 by @code{nscd-service}. This uses the caches defined by
5110 @var{%nscd-default-caches}; see below.
5113 @deftp {Data Type} nscd-configuration
5114 This is the type representing the name service cache daemon (nscd)
5119 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
5120 Name of nscd's log file. This is where debugging output goes when
5121 @code{debug-level} is strictly positive.
5123 @item @code{debug-level} (default: @code{0})
5124 Integer denoting the debugging levels. Higher numbers mean more
5125 debugging output is logged.
5127 @item @code{caches} (default: @var{%nscd-default-caches})
5128 List of @code{<nscd-cache>} objects denoting things to be cached; see
5134 @deftp {Data Type} nscd-cache
5135 Data type representing a cache database of nscd and its parameters.
5139 @item @code{database}
5140 This is a symbol representing the name of the database to be cached.
5141 Valid values are @code{passwd}, @code{group}, @code{hosts}, and
5142 @code{services}, which designate the corresponding NSS database
5143 (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
5145 @item @code{positive-time-to-live}
5146 @itemx @code{negative-time-to-live} (default: @code{20})
5147 A number representing the number of seconds during which a positive or
5148 negative lookup result remains in cache.
5150 @item @code{check-files?} (default: @code{#t})
5151 Whether to check for updates of the files corresponding to
5154 For instance, when @var{database} is @code{hosts}, setting this flag
5155 instructs nscd to check for updates in @file{/etc/hosts} and to take
5158 @item @code{persistent?} (default: @code{#t})
5159 Whether the cache should be stored persistently on disk.
5161 @item @code{shared?} (default: @code{#t})
5162 Whether the cache should be shared among users.
5164 @item @code{max-database-size} (default: 32@tie{}MiB)
5165 Maximum size in bytes of the database cache.
5167 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
5168 @c settings, so leave them out.
5173 @defvr {Scheme Variable} %nscd-default-caches
5174 List of @code{<nscd-cache>} objects used by default by
5175 @code{nscd-configuration} (see above.)
5177 It enables persistent and aggressive caching of service and host name
5178 lookups. The latter provides better host name lookup performance,
5179 resilience in the face of unreliable name servers, and also better
5180 privacy---often the result of host name lookups is in local cache, so
5181 external name servers do not even need to be queried.
5185 @deffn {Monadic Procedure} syslog-service [#:config-file #f]
5186 Return a service that runs @code{syslogd}. If configuration file name
5187 @var{config-file} is not specified, use some reasonable default
5191 @deffn {Monadic Procedure} guix-service [#:guix guix] @
5192 [#:builder-group "guixbuild"] [#:build-accounts 10] @
5193 [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
5194 [#:extra-options '()]
5195 Return a service that runs the build daemon from @var{guix}, and has
5196 @var{build-accounts} user accounts available under @var{builder-group}.
5198 When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
5199 provided by @var{guix} is authorized upon activation, meaning that substitutes
5200 from @code{hydra.gnu.org} are used by default.
5202 If @var{use-substitutes?} is false, the daemon is run with
5203 @option{--no-substitutes} (@pxref{Invoking guix-daemon,
5204 @option{--no-substitutes}}).
5206 Finally, @var{extra-options} is a list of additional command-line options
5207 passed to @command{guix-daemon}.
5210 @deffn {Monadic Procedure} udev-service [#:udev udev]
5211 Run @var{udev}, which populates the @file{/dev} directory dynamically.
5214 @deffn {Monadic Procedure} console-keymap-service @var{file}
5215 Return a service to load console keymap from @var{file} using
5216 @command{loadkeys} command.
5220 @node Networking Services
5221 @subsubsection Networking Services
5223 The @code{(gnu services networking)} module provides services to configure
5224 the network interface.
5226 @cindex DHCP, networking service
5227 @deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
5228 Return a service that runs @var{dhcp}, a Dynamic Host Configuration
5229 Protocol (DHCP) client, on all the non-loopback network interfaces.
5232 @deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
5233 [#:gateway #f] [#:name-services @code{'()}]
5234 Return a service that starts @var{interface} with address @var{ip}. If
5235 @var{gateway} is true, it must be a string specifying the default network
5240 @deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
5241 Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
5242 network manager that aims to simplify wired and wireless networking.
5245 @deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
5246 [#:name-service @var{%ntp-servers}]
5247 Return a service that runs the daemon from @var{ntp}, the
5248 @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
5249 keep the system clock synchronized with that of @var{servers}.
5252 @defvr {Scheme Variable} %ntp-servers
5253 List of host names used as the default NTP servers.
5256 @deffn {Monadic Procedure} tor-service [#:tor tor]
5257 Return a service to run the @uref{https://torproject.org,Tor} daemon.
5259 The daemon runs with the default settings (in particular the default exit
5260 policy) as the @code{tor} unprivileged user.
5263 @deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
5264 [#:interface "127.0.0.1"] [#:port 6667] @
5265 [#:extra-settings ""]
5266 Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
5267 acts as a gateway between IRC and chat networks.
5269 The daemon will listen to the interface corresponding to the IP address
5270 specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
5271 local clients can connect, whereas @code{0.0.0.0} means that connections can
5272 come from any networking interface.
5274 In addition, @var{extra-settings} specifies a string to append to the
5278 Furthermore, @code{(gnu services ssh)} provides the following service.
5280 @deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
5281 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
5282 [#:allow-empty-passwords? #f] [#:root-login? #f] @
5283 [#:syslog-output? #t] [#:x11-forwarding? #t] @
5284 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
5285 [#:public-key-authentication? #t] [#:initialize? #t]
5286 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
5287 @var{host-key} must designate a file containing the host key, and readable
5290 When @var{daemonic?} is true, @command{lshd} will detach from the
5291 controlling terminal and log its output to syslogd, unless one sets
5292 @var{syslog-output?} to false. Obviously, it also makes lsh-service
5293 depend on existence of syslogd service. When @var{pid-file?} is true,
5294 @command{lshd} writes its PID to the file called @var{pid-file}.
5296 When @var{initialize?} is true, automatically create the seed and host key
5297 upon service activation if they do not exist yet. This may take long and
5298 require interaction.
5300 When @var{initialize?} is false, it is up to the user to initialize the
5301 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
5302 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
5303 basics,,, lsh, LSH Manual}).
5305 When @var{interfaces} is empty, lshd listens for connections on all the
5306 network interfaces; otherwise, @var{interfaces} must be a list of host names
5309 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
5310 passwords, and @var{root-login?} specifies whether to accept log-ins as
5313 The other options should be self-descriptive.
5316 @defvr {Scheme Variable} %facebook-host-aliases
5317 This variable contains a string for use in @file{/etc/hosts}
5318 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
5319 line contains a entry that maps a known server name of the Facebook
5320 on-line service---e.g., @code{www.facebook.com}---to the local
5321 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
5323 This variable is typically used in the @code{hosts-file} field of an
5324 @code{operating-system} declaration (@pxref{operating-system Reference,
5325 @file{/etc/hosts}}):
5328 (use-modules (gnu) (guix))
5331 (host-name "mymachine")
5334 ;; Create a /etc/hosts file with aliases for "localhost"
5335 ;; and "mymachine", as well as for Facebook servers.
5337 (string-append (local-host-aliases host-name)
5338 %facebook-host-aliases))))
5341 This mechanism can prevent programs running locally, such as Web
5342 browsers, from accessing Facebook.
5345 The @code{(gnu services avahi)} provides the following definition.
5347 @deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
5348 [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
5349 [#:ipv6? #t] [#:wide-area? #f] @
5350 [#:domains-to-browse '()]
5351 Return a service that runs @command{avahi-daemon}, a system-wide
5352 mDNS/DNS-SD responder that allows for service discovery and
5353 "zero-configuration" host name lookups (see @uref{http://avahi.org/}).
5355 If @var{host-name} is different from @code{#f}, use that as the host name to
5356 publish for this machine; otherwise, use the machine's actual host name.
5358 When @var{publish?} is true, publishing of host names and services is allowed;
5359 in particular, avahi-daemon will publish the machine's host name and IP
5360 address via mDNS on the local network.
5362 When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
5364 Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
5370 @subsubsection X Window
5372 Support for the X Window graphical display system---specifically
5373 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
5374 there is no @code{xorg-service} procedure. Instead, the X server is
5375 started by the @dfn{login manager}, currently SLiM.
5377 @deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
5378 [#:auto-login? #f] [#:default-user ""] [#:startx] @
5379 [#:theme @var{%default-slim-theme}] @
5380 [#:theme-name @var{%default-slim-theme-name}]
5381 Return a service that spawns the SLiM graphical login manager, which in
5382 turn starts the X display server with @var{startx}, a command as returned by
5383 @code{xorg-start-command}.
5387 SLiM automatically looks for session types described by the @file{.desktop}
5388 files in @file{/run/current-system/profile/share/xsessions} and allows users
5389 to choose a session from the log-in screen using @kbd{F1}. Packages such as
5390 @var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
5391 adding them to the system-wide set of packages automatically makes them
5392 available at the log-in screen.
5394 In addition, @file{~/.xsession} files are honored. When available,
5395 @file{~/.xsession} must be an executable that starts a window manager
5396 and/or other X clients.
5398 When @var{allow-empty-passwords?} is true, allow logins with an empty
5399 password. When @var{auto-login?} is true, log in automatically as
5402 If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
5403 @var{theme} must be a gexp denoting the name of a directory containing the
5404 theme to use. In that case, @var{theme-name} specifies the name of the
5408 @defvr {Scheme Variable} %default-theme
5409 @defvrx {Scheme Variable} %default-theme-name
5410 The G-Expression denoting the default SLiM theme and its name.
5413 @deffn {Monadic Procedure} xorg-start-command [#:guile] @
5414 [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
5415 Return a derivation that builds a @var{guile} script to start the X server
5416 from @var{xorg-server}. @var{configuration-file} is the server configuration
5417 file or a derivation that builds it; when omitted, the result of
5418 @code{xorg-configuration-file} is used.
5420 Usually the X server is started by a login manager.
5423 @deffn {Monadic Procedure} xorg-configuration-file @
5424 [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
5425 Return a configuration file for the Xorg server containing search paths for
5426 all the common drivers.
5428 @var{drivers} must be either the empty list, in which case Xorg chooses a
5429 graphics driver automatically, or a list of driver names that will be tried in
5430 this order---e.g., @code{(\"modesetting\" \"vesa\")}.
5432 Likewise, when @var{resolutions} is the empty list, Xorg chooses an
5433 appropriate screen resolution; otherwise, it must be a list of
5434 resolutions---e.g., @code{((1024 768) (640 480))}.
5436 Last, @var{extra-config} is a list of strings or objects appended to the
5437 @code{text-file*} argument list. It is used to pass extra text to be added
5438 verbatim to the configuration file.
5441 @node Desktop Services
5442 @subsubsection Desktop Services
5444 The @code{(gnu services desktop)} module provides services that are
5445 usually useful in the context of a ``desktop'' setup---that is, on a
5446 machine running a graphical display server, possibly with graphical user
5449 To simplify things, the module defines a variable containing the set of
5450 services that users typically expect on a machine with a graphical
5451 environment and networking:
5453 @defvr {Scheme Variable} %desktop-services
5454 This is a list of services that builds upon @var{%base-services} and
5455 adds or adjust services for a typical ``desktop'' setup.
5457 In particular, it adds a graphical login manager (@pxref{X Window,
5458 @code{slim-service}}), a network management tool (@pxref{Networking
5459 Services, @code{wicd-service}}), energy and color management services,
5460 an NTP client and an SSH server (@pxref{Networking Services}), the Avahi
5461 daemon, and has the name service switch service configured to be able to
5462 use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
5465 The @var{%desktop-services} variable can be used as the @code{services}
5466 field of an @code{operating-system} declaration (@pxref{operating-system
5467 Reference, @code{services}}).
5469 The actual service definitions provided by @code{(gnu services desktop)}
5470 are described below.
5472 @deffn {Monadic Procedure} dbus-service @var{services} @
5474 Return a service that runs the ``system bus'', using @var{dbus}, with
5475 support for @var{services}.
5477 @uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
5478 facility. Its system bus is used to allow system services to communicate
5479 and be notified of system-wide events.
5481 @var{services} must be a list of packages that provide an
5482 @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
5483 and policy files. For example, to allow avahi-daemon to use the system bus,
5484 @var{services} must be equal to @code{(list avahi)}.
5487 @deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
5488 [#:watts-up-pro? #f] @
5489 [#:poll-batteries? #t] @
5490 [#:ignore-lid? #f] @
5491 [#:use-percentage-for-policy? #f] @
5492 [#:percentage-low 10] @
5493 [#:percentage-critical 3] @
5494 [#:percentage-action 2] @
5496 [#:time-critical 300] @
5497 [#:time-action 120] @
5498 [#:critical-power-action 'hybrid-sleep]
5499 Return a service that runs @uref{http://upower.freedesktop.org/,
5500 @command{upowerd}}, a system-wide monitor for power consumption and battery
5501 levels, with the given configuration settings. It implements the
5502 @code{org.freedesktop.UPower} D-Bus interface, and is notably used by
5506 @deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
5507 Return a service that runs @command{colord}, a system service with a D-Bus
5508 interface to manage the color profiles of input and output devices such as
5509 screens and scanners. It is notably used by the GNOME Color Manager graphical
5510 tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
5511 site} for more information.
5514 @node Database Services
5515 @subsubsection Database Services
5517 The @code{(gnu services databases)} module provides the following service.
5519 @deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
5520 [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
5521 Return a service that runs @var{postgresql}, the PostgreSQL database
5524 The PostgreSQL daemon loads its runtime configuration from
5525 @var{config-file} and stores the database cluster in
5526 @var{data-directory}.
5529 @node Various Services
5530 @subsubsection Various Services
5532 The @code{(gnu services lirc)} module provides the following service.
5534 @deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
5535 [#:device #f] [#:driver #f] [#:config-file #f] @
5536 [#:extra-options '()]
5537 Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
5538 decodes infrared signals from remote controls.
5540 Optionally, @var{device}, @var{driver} and @var{config-file}
5541 (configuration file name) may be specified. See @command{lircd} manual
5544 Finally, @var{extra-options} is a list of additional command-line options
5545 passed to @command{lircd}.
5549 @node Setuid Programs
5550 @subsection Setuid Programs
5552 @cindex setuid programs
5553 Some programs need to run with ``root'' privileges, even when they are
5554 launched by unprivileged users. A notorious example is the
5555 @command{passwd} programs, which can users can run to change their
5556 password, and which requires write access to the @file{/etc/passwd} and
5557 @file{/etc/shadow} files---something normally restricted to root, for
5558 obvious security reasons. To address that, these executables are
5559 @dfn{setuid-root}, meaning that they always run with root privileges
5560 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
5561 for more info about the setuid mechanisms.)
5563 The store itself @emph{cannot} contain setuid programs: that would be a
5564 security issue since any user on the system can write derivations that
5565 populate the store (@pxref{The Store}). Thus, a different mechanism is
5566 used: instead of changing the setuid bit directly on files that are in
5567 the store, we let the system administrator @emph{declare} which programs
5568 should be setuid root.
5570 The @code{setuid-programs} field of an @code{operating-system}
5571 declaration contains a list of G-expressions denoting the names of
5572 programs to be setuid-root (@pxref{Using the Configuration System}).
5573 For instance, the @command{passwd} program, which is part of the Shadow
5574 package, can be designated by this G-expression (@pxref{G-Expressions}):
5577 #~(string-append #$shadow "/bin/passwd")
5580 A default set of setuid programs is defined by the
5581 @code{%setuid-programs} variable of the @code{(gnu system)} module.
5583 @defvr {Scheme Variable} %setuid-programs
5584 A list of G-expressions denoting common programs that are setuid-root.
5586 The list includes commands such as @command{passwd}, @command{ping},
5587 @command{su}, and @command{sudo}.
5590 Under the hood, the actual setuid programs are created in the
5591 @file{/run/setuid-programs} directory at system activation time. The
5592 files in this directory refer to the ``real'' binaries, which are in the
5595 @node X.509 Certificates
5596 @subsection X.509 Certificates
5598 @cindex HTTPS, certificates
5599 @cindex X.509 certificates
5601 Web servers available over HTTPS (that is, HTTP over the transport-layer
5602 security mechanism, TLS) send client programs an @dfn{X.509 certificate}
5603 that the client can then use to @emph{authenticate} the server. To do
5604 that, clients verify that the server's certificate is signed by a
5605 so-called @dfn{certificate authority} (CA). But to verify the CA's
5606 signature, clients must have first acquired the CA's certificate.
5608 Web browsers such as GNU@tie{}IceCat include their own set of CA
5609 certificates, such that they are able to verify CA signatures
5612 However, most other programs that can talk HTTPS---@command{wget},
5613 @command{git}, @command{w3m}, etc.---need to be told where CA
5614 certificates can be found.
5616 @cindex @code{nss-certs}
5617 In GuixSD, this is done by adding a package that provides certificates
5618 to the @code{packages} field of the @code{operating-system} declaration
5619 (@pxref{operating-system Reference}). GuixSD includes one such package,
5620 @code{nss-certs}, which is a set of CA certificates provided as part of
5621 Mozilla's Network Security Services.
5623 Note that it is @emph{not} part of @var{%base-packages}, so you need to
5624 explicitly add it. The @file{/etc/ssl/certs} directory, which is where
5625 most applications and libraries look for certificates by default, points
5626 to the certificates installed globally.
5628 Unprivileged users can also install their own certificate package in
5629 their profile. A number of environment variables need to be defined so
5630 that applications and libraries know where to find them. Namely, the
5631 OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
5632 variables. Some applications add their own environment variables; for
5633 instance, the Git version control system honors the certificate bundle
5634 pointed to by the @code{GIT_SSL_CAINFO} environment variable.
5637 @node Name Service Switch
5638 @subsection Name Service Switch
5640 @cindex name service switch
5642 The @code{(gnu system nss)} module provides bindings to the
5643 configuration file of libc's @dfn{name service switch} or @dfn{NSS}
5644 (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
5645 Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
5646 extended with new ``name'' lookup methods for system databases, which
5647 includes host names, service names, user accounts, and more (@pxref{Name
5648 Service Switch, System Databases and Name Service Switch,, libc, The GNU
5649 C Library Reference Manual}).
5651 The NSS configuration specifies, for each system database, which lookup
5652 method is to be used, and how the various methods are chained
5653 together---for instance, under which circumstances NSS should try the
5654 next method in the list. The NSS configuration is given in the
5655 @code{name-service-switch} field of @code{operating-system} declarations
5656 (@pxref{operating-system Reference, @code{name-service-switch}}).
5659 @cindex .local, host name lookup
5660 As an example, the declaration below configures the NSS to use the
5661 @uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
5662 back-end}, which supports host name lookups over multicast DNS (mDNS)
5663 for host names ending in @code{.local}:
5666 (name-service-switch
5667 (hosts (list %files ;first, check /etc/hosts
5669 ;; If the above did not succeed, try
5670 ;; with 'mdns_minimal'.
5672 (name "mdns_minimal")
5674 ;; 'mdns_minimal' is authoritative for
5675 ;; '.local'. When it returns "not found",
5676 ;; no need to try the next methods.
5677 (reaction (lookup-specification
5678 (not-found => return))))
5680 ;; Then fall back to DNS.
5684 ;; Finally, try with the "full" 'mdns'.
5689 Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
5690 contains this configuration, so you won't have to type it if all you
5691 want is to have @code{.local} host lookup working.
5693 Note that, in this case, in addition to setting the
5694 @code{name-service-switch} of the @code{operating-system} declaration,
5695 @code{nscd-service} must be told where to find the @code{nss-mdns}
5696 shared library (@pxref{Base Services, @code{nscd-service}}). Since the
5697 @code{nscd} service is part of @var{%base-services}, you may want to
5698 customize it by adding this snippet in the operating system
5702 (use-modules (guix) (gnu))
5704 (define %my-base-services
5705 ;; Replace the default nscd service with one that knows
5707 (map (lambda (mservice)
5708 ;; "Bind" the MSERVICE monadic value to inspect it.
5709 (mlet %store-monad ((service mservice))
5710 (if (member 'nscd (service-provision service))
5711 (nscd-service (nscd-configuration)
5712 #:name-services (list nss-mdns))
5718 @dots{} and then refer to @var{%my-base-services} instead of
5719 @var{%base-services} in the @code{operating-system} declaration.
5720 Lastly, this relies on the availability of the Avahi service
5721 (@pxref{Networking Services, @code{avahi-service}}).
5723 For convenience, the following variables provide typical NSS
5726 @defvr {Scheme Variable} %default-nss
5727 This is the default name service switch configuration, a
5728 @code{name-service-switch} object.
5731 @defvr {Scheme Variable} %mdns-host-lookup-nss
5732 This is the name service switch configuration with support for host name
5733 lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
5736 The reference for name service switch configuration is given below. It
5737 is a direct mapping of the C library's configuration file format, so
5738 please refer to the C library manual for more information (@pxref{NSS
5739 Configuration File,,, libc, The GNU C Library Reference Manual}).
5740 Compared to libc's NSS configuration file format, it has the advantage
5741 not only of adding this warm parenthetic feel that we like, but also
5742 static checks: you'll know about syntax errors and typos as soon as you
5743 run @command{guix system}.
5745 @deftp {Data Type} name-service-switch
5747 This is the data type representation the configuration of libc's name
5748 service switch (NSS). Each field below represents one of the supported
5765 The system databases handled by the NSS. Each of these fields must be a
5766 list of @code{<name-service>} objects (see below.)
5770 @deftp {Data Type} name-service
5772 This is the data type representing an actual name service and the
5773 associated lookup action.
5777 A string denoting the name service (@pxref{Services in the NSS
5778 configuration,,, libc, The GNU C Library Reference Manual}).
5780 Note that name services listed here must be visible to nscd. This is
5781 achieved by passing the @code{#:name-services} argument to
5782 @code{nscd-service} the list of packages providing the needed name
5783 services (@pxref{Base Services, @code{nscd-service}}).
5786 An action specified using the @code{lookup-specification} macro
5787 (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
5788 Reference Manual}). For example:
5791 (lookup-specification (unavailable => continue)
5792 (success => return))
5797 @node Initial RAM Disk
5798 @subsection Initial RAM Disk
5800 @cindex initial RAM disk (initrd)
5801 @cindex initrd (initial RAM disk)
5802 For bootstrapping purposes, the Linux-Libre kernel is passed an
5803 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
5804 root file system, as well as an initialization script. The latter is
5805 responsible for mounting the real root file system, and for loading any
5806 kernel modules that may be needed to achieve that.
5808 The @code{initrd} field of an @code{operating-system} declaration allows
5809 you to specify which initrd you would like to use. The @code{(gnu
5810 system linux-initrd)} module provides two ways to build an initrd: the
5811 high-level @code{base-initrd} procedure, and the low-level
5812 @code{expression->initrd} procedure.
5814 The @code{base-initrd} procedure is intended to cover most common uses.
5815 For example, if you want to add a bunch of kernel modules to be loaded
5816 at boot time, you can define the @code{initrd} field of the operating
5817 system declaration like this:
5820 (initrd (lambda (file-systems . rest)
5821 ;; Create a standard initrd that has modules "foo.ko"
5822 ;; and "bar.ko", as well as their dependencies, in
5823 ;; addition to the modules available by default.
5824 (apply base-initrd file-systems
5825 #:extra-modules '("foo" "bar")
5829 The @code{base-initrd} procedure also handles common use cases that
5830 involves using the system as a QEMU guest, or as a ``live'' system whose
5831 root file system is volatile.
5833 @deffn {Monadic Procedure} base-initrd @var{file-systems} @
5834 [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
5835 [#:extra-modules '()] [#:mapped-devices '()]
5836 Return a monadic derivation that builds a generic initrd. @var{file-systems} is
5837 a list of file-systems to be mounted by the initrd, possibly in addition to
5838 the root file system specified on the kernel command line via @code{--root}.
5839 @var{mapped-devices} is a list of device mappings to realize before
5840 @var{file-systems} are mounted (@pxref{Mapped Devices}).
5842 When @var{qemu-networking?} is true, set up networking with the standard QEMU
5843 parameters. When @var{virtio?} is true, load additional modules so the initrd can
5844 be used as a QEMU guest with para-virtualized I/O drivers.
5846 When @var{volatile-root?} is true, the root file system is writable but any changes
5849 The initrd is automatically populated with all the kernel modules necessary
5850 for @var{file-systems} and for the given options. However, additional kernel
5851 modules can be listed in @var{extra-modules}. They will be added to the initrd, and
5852 loaded at boot time in the order in which they appear.
5855 Needless to say, the initrds we produce and use embed a
5856 statically-linked Guile, and the initialization program is a Guile
5857 program. That gives a lot of flexibility. The
5858 @code{expression->initrd} procedure builds such an initrd, given the
5859 program to run in that initrd.
5861 @deffn {Monadic Procedure} expression->initrd @var{exp} @
5862 [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
5864 Return a derivation that builds a Linux initrd (a gzipped cpio archive)
5865 containing @var{guile} and that evaluates @var{exp}, a G-expression,
5866 upon booting. All the derivations referenced by @var{exp} are
5867 automatically copied to the initrd.
5869 @var{modules} is a list of Guile module names to be embedded in the
5873 @node GRUB Configuration
5874 @subsection GRUB Configuration
5879 The operating system uses GNU@tie{}GRUB as its boot loader
5880 (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
5881 configured using @code{grub-configuration} declarations. This data type
5882 is exported by the @code{(gnu system grub)} module, and described below.
5884 @deftp {Data Type} grub-configuration
5885 The type of a GRUB configuration declaration.
5890 This is a string denoting the boot device. It must be a device name
5891 understood by the @command{grub-install} command, such as
5892 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
5895 @item @code{menu-entries} (default: @code{()})
5896 A possibly empty list of @code{menu-entry} objects (see below), denoting
5897 entries to appear in the GRUB boot menu, in addition to the current
5898 system entry and the entry pointing to previous system generations.
5900 @item @code{default-entry} (default: @code{0})
5901 The index of the default boot menu entry. Index 0 is for the current
5904 @item @code{timeout} (default: @code{5})
5905 The number of seconds to wait for keyboard input before booting. Set to
5906 0 to boot immediately, and to -1 to wait indefinitely.
5908 @item @code{theme} (default: @var{%default-theme})
5909 The @code{grub-theme} object describing the theme to use.
5914 Should you want to list additional boot menu entries @i{via} the
5915 @code{menu-entries} field above, you will need to create them with the
5916 @code{menu-entry} form:
5918 @deftp {Data Type} menu-entry
5919 The type of an entry in the GRUB boot menu.
5924 The label to show in the menu---e.g., @code{"GNU"}.
5927 The Linux kernel to boot.
5929 @item @code{linux-arguments} (default: @code{()})
5930 The list of extra Linux kernel command-line arguments---e.g.,
5931 @code{("console=ttyS0")}.
5934 A G-Expression or string denoting the file name of the initial RAM disk
5935 to use (@pxref{G-Expressions}).
5940 @c FIXME: Write documentation once it's stable.
5941 Themes are created using the @code{grub-theme} form, which is not
5944 @defvr {Scheme Variable} %default-theme
5945 This is the default GRUB theme used by the operating system, with a
5946 fancy background image displaying the GNU and Guix logos.
5950 @node Invoking guix system
5951 @subsection Invoking @code{guix system}
5953 Once you have written an operating system declaration, as seen in the
5954 previous section, it can be @dfn{instantiated} using the @command{guix
5955 system} command. The synopsis is:
5958 guix system @var{options}@dots{} @var{action} @var{file}
5961 @var{file} must be the name of a file containing an
5962 @code{operating-system} declaration. @var{action} specifies how the
5963 operating system is instantiate. Currently the following values are
5968 Build the operating system described in @var{file}, activate it, and
5969 switch to it@footnote{This action is usable only on systems already
5972 This effects all the configuration specified in @var{file}: user
5973 accounts, system services, global package list, setuid programs, etc.
5975 It also adds a GRUB menu entry for the new OS configuration, and moves
5976 entries for older configurations to a submenu---unless
5977 @option{--no-grub} is passed.
5979 @c The paragraph below refers to the problem discussed at
5980 @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
5981 It is highly recommended to run @command{guix pull} once before you run
5982 @command{guix system reconfigure} for the first time (@pxref{Invoking
5983 guix pull}). Failing to do that you would see an older version of Guix
5984 once @command{reconfigure} has completed.
5987 Build the operating system's derivation, which includes all the
5988 configuration files and programs needed to boot and run the system.
5989 This action does not actually install anything.
5992 Populate the given directory with all the files necessary to run the
5993 operating system specified in @var{file}. This is useful for first-time
5994 installations of GuixSD. For instance:
5997 guix system init my-os-config.scm /mnt
6000 copies to @file{/mnt} all the store items required by the configuration
6001 specified in @file{my-os-config.scm}. This includes configuration
6002 files, packages, and so on. It also creates other essential files
6003 needed for the system to operate correctly---e.g., the @file{/etc},
6004 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
6006 This command also installs GRUB on the device specified in
6007 @file{my-os-config}, unless the @option{--no-grub} option was passed.
6010 @cindex virtual machine
6012 Build a virtual machine that contain the operating system declared in
6013 @var{file}, and return a script to run that virtual machine (VM).
6014 Arguments given to the script are passed as is to QEMU.
6016 The VM shares its store with the host system.
6018 Additional file systems can be shared between the host and the VM using
6019 the @code{--share} and @code{--expose} command-line options: the former
6020 specifies a directory to be shared with write access, while the latter
6021 provides read-only access to the shared directory.
6023 The example below creates a VM in which the user's home directory is
6024 accessible read-only, and where the @file{/exchange} directory is a
6025 read-write mapping of the host's @file{$HOME/tmp}:
6028 guix system vm my-config.scm \
6029 --expose=$HOME --share=$HOME/tmp=/exchange
6032 On GNU/Linux, the default is to boot directly to the kernel; this has
6033 the advantage of requiring only a very tiny root disk image since the
6034 host's store can then be mounted.
6036 The @code{--full-boot} option forces a complete boot sequence, starting
6037 with the bootloader. This requires more disk space since a root image
6038 containing at least the kernel, initrd, and bootloader data files must
6039 be created. The @code{--image-size} option can be used to specify the
6044 Return a virtual machine or disk image of the operating system declared
6045 in @var{file} that stands alone. Use the @option{--image-size} option
6046 to specify the size of the image.
6048 When using @code{vm-image}, the returned image is in qcow2 format, which
6049 the QEMU emulator can efficiently use.
6051 When using @code{disk-image}, a raw disk image is produced; it can be
6052 copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
6053 the device corresponding to a USB stick, one can copy the image on it
6054 using the following command:
6057 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
6062 @var{options} can contain any of the common build options provided by
6063 @command{guix build} (@pxref{Invoking guix build}). In addition,
6064 @var{options} can contain one of the following:
6067 @item --system=@var{system}
6068 @itemx -s @var{system}
6069 Attempt to build for @var{system} instead of the host's system type.
6070 This works as per @command{guix build} (@pxref{Invoking guix build}).
6072 @item --image-size=@var{size}
6073 For the @code{vm-image} and @code{disk-image} actions, create an image
6074 of the given @var{size}. @var{size} may be a number of bytes, or it may
6075 include a unit as a suffix (@pxref{Block size, size specifications,,
6076 coreutils, GNU Coreutils}).
6078 @item --on-error=@var{strategy}
6079 Apply @var{strategy} when an error occurs when reading @var{file}.
6080 @var{strategy} may be one of the following:
6083 @item nothing-special
6084 Report the error concisely and exit. This is the default strategy.
6087 Likewise, but also display a backtrace.
6090 Report the error and enter Guile's debugger. From there, you can run
6091 commands such as @code{,bt} to get a backtrace, @code{,locals} to
6092 display local variable values, and more generally inspect the program's
6093 state. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
6094 a list of available debugging commands.
6098 Note that all the actions above, except @code{build} and @code{init},
6099 rely on KVM support in the Linux-Libre kernel. Specifically, the
6100 machine should have hardware virtualization support, the corresponding
6101 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
6102 must exist and be readable and writable by the user and by the daemon's
6105 @node Defining Services
6106 @subsection Defining Services
6108 The @code{(gnu services @dots{})} modules define several procedures that allow
6109 users to declare the operating system's services (@pxref{Using the
6110 Configuration System}). These procedures are @emph{monadic
6111 procedures}---i.e., procedures that return a monadic value in the store
6112 monad (@pxref{The Store Monad}). For examples of such procedures,
6115 @cindex service definition
6116 The monadic value returned by those procedures is a @dfn{service
6117 definition}---a structure as returned by the @code{service} form.
6118 Service definitions specifies the inputs the service depends on, and an
6119 expression to start and stop the service. Behind the scenes, service
6120 definitions are ``translated'' into the form suitable for the
6121 configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
6124 As an example, here is what the @code{nscd-service} procedure looks
6128 (define (nscd-service)
6129 (with-monad %store-monad
6131 (documentation "Run libc's name service cache daemon.")
6134 (use-modules (guix build utils))
6135 (mkdir-p "/var/run/nscd")))
6136 (start #~(make-forkexec-constructor
6137 (string-append #$glibc "/sbin/nscd")
6138 "-f" "/dev/null" "--foreground"))
6139 (stop #~(make-kill-destructor))
6144 The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
6145 (@pxref{G-Expressions}). The @code{activate} field contains a script to
6146 run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
6147 directory exists before @command{nscd} is started.
6149 The @code{start} and @code{stop} fields refer to dmd's facilities to
6150 start and stop processes (@pxref{Service De- and Constructors,,, dmd,
6151 GNU dmd Manual}). The @code{provision} field specifies the name under
6152 which this service is known to dmd, and @code{documentation} specifies
6153 on-line documentation. Thus, the commands @command{deco start ncsd},
6154 @command{deco stop nscd}, and @command{deco doc nscd} will do what you
6155 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
6158 @node Installing Debugging Files
6159 @section Installing Debugging Files
6161 @cindex debugging files
6162 Program binaries, as produced by the GCC compilers for instance, are
6163 typically written in the ELF format, with a section containing
6164 @dfn{debugging information}. Debugging information is what allows the
6165 debugger, GDB, to map binary code to source code; it is required to
6166 debug a compiled program in good conditions.
6168 The problem with debugging information is that is takes up a fair amount
6169 of disk space. For example, debugging information for the GNU C Library
6170 weighs in at more than 60 MiB. Thus, as a user, keeping all the
6171 debugging info of all the installed programs is usually not an option.
6172 Yet, space savings should not come at the cost of an impediment to
6173 debugging---especially in the GNU system, which should make it easier
6174 for users to exert their computing freedom (@pxref{GNU Distribution}).
6176 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
6177 mechanism that allows users to get the best of both worlds: debugging
6178 information can be stripped from the binaries and stored in separate
6179 files. GDB is then able to load debugging information from those files,
6180 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
6183 The GNU distribution takes advantage of this by storing debugging
6184 information in the @code{lib/debug} sub-directory of a separate package
6185 output unimaginatively called @code{debug} (@pxref{Packages with
6186 Multiple Outputs}). Users can choose to install the @code{debug} output
6187 of a package when they need it. For instance, the following command
6188 installs the debugging information for the GNU C Library and for GNU
6192 guix package -i glibc:debug guile:debug
6195 GDB must then be told to look for debug files in the user's profile, by
6196 setting the @code{debug-file-directory} variable (consider setting it
6197 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
6201 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
6204 From there on, GDB will pick up debugging information from the
6205 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
6207 In addition, you will most likely want GDB to be able to show the source
6208 code being debugged. To do that, you will have to unpack the source
6209 code of the package of interest (obtained with @code{guix build
6210 --source}, @pxref{Invoking guix build}), and to point GDB to that source
6211 directory using the @code{directory} command (@pxref{Source Path,
6212 @code{directory},, gdb, Debugging with GDB}).
6214 @c XXX: keep me up-to-date
6215 The @code{debug} output mechanism in Guix is implemented by the
6216 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
6217 opt-in---debugging information is available only for those packages
6218 whose definition explicitly declares a @code{debug} output. This may be
6219 changed to opt-out in the future, if our build farm servers can handle
6220 the load. To check whether a package has a @code{debug} output, use
6221 @command{guix package --list-available} (@pxref{Invoking guix package}).
6224 @node Security Updates
6225 @section Security Updates
6228 As of version @value{VERSION}, the feature described in this section is
6232 @cindex security updates
6233 Occasionally, important security vulnerabilities are discovered in core
6234 software packages and must be patched. Guix follows a functional
6235 package management discipline (@pxref{Introduction}), which implies
6236 that, when a package is changed, @emph{every package that depends on it}
6237 must be rebuilt. This can significantly slow down the deployment of
6238 fixes in core packages such as libc or Bash, since basically the whole
6239 distribution would need to be rebuilt. Using pre-built binaries helps
6240 (@pxref{Substitutes}), but deployment may still take more time than
6244 To address that, Guix implements @dfn{grafts}, a mechanism that allows
6245 for fast deployment of critical updates without the costs associated
6246 with a whole-distribution rebuild. The idea is to rebuild only the
6247 package that needs to be patched, and then to ``graft'' it onto packages
6248 explicitly installed by the user and that were previously referring to
6249 the original package. The cost of grafting is typically very low, and
6250 order of magnitudes lower than a full rebuild of the dependency chain.
6252 @cindex replacements of packages, for grafts
6253 For instance, suppose a security update needs to be applied to Bash.
6254 Guix developers will provide a package definition for the ``fixed''
6255 Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
6256 Packages}). Then, the original package definition is augmented with a
6257 @code{replacement} field pointing to the package containing the bug fix:
6264 (replacement bash-fixed)))
6267 From there on, any package depending directly or indirectly on Bash that
6268 is installed will automatically be ``rewritten'' to refer to
6269 @var{bash-fixed} instead of @var{bash}. This grafting process takes
6270 time proportional to the size of the package, but expect less than a
6271 minute for an ``average'' package on a recent machine.
6273 Currently, the graft and the package it replaces (@var{bash-fixed} and
6274 @var{bash} in the example above) must have the exact same @code{name}
6275 and @code{version} fields. This restriction mostly comes from the fact
6276 that grafting works by patching files, including binary files, directly.
6277 Other restrictions may apply: for instance, when adding a graft to a
6278 package providing a shared library, the original shared library and its
6279 replacement must have the same @code{SONAME} and be binary-compatible.
6282 @node Package Modules
6283 @section Package Modules
6285 From a programming viewpoint, the package definitions of the
6286 GNU distribution are provided by Guile modules in the @code{(gnu packages
6287 @dots{})} name space@footnote{Note that packages under the @code{(gnu
6288 packages @dots{})} module name space are not necessarily ``GNU
6289 packages''. This module naming scheme follows the usual Guile module
6290 naming convention: @code{gnu} means that these modules are distributed
6291 as part of the GNU system, and @code{packages} identifies modules that
6292 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
6293 Reference Manual}). For instance, the @code{(gnu packages emacs)}
6294 module exports a variable named @code{emacs}, which is bound to a
6295 @code{<package>} object (@pxref{Defining Packages}).
6297 The @code{(gnu packages @dots{})} module name space is
6298 automatically scanned for packages by the command-line tools. For
6299 instance, when running @code{guix package -i emacs}, all the @code{(gnu
6300 packages @dots{})} modules are scanned until one that exports a package
6301 object whose name is @code{emacs} is found. This package search
6302 facility is implemented in the @code{(gnu packages)} module.
6304 @cindex customization, of packages
6305 @cindex package module search path
6306 Users can store package definitions in modules with different
6307 names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
6308 name and module name must match. For instance, the @code{(my-packages
6309 emacs)} module must be stored in a @file{my-packages/emacs.scm} file
6310 relative to the load path specified with @option{--load-path} or
6311 @code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
6312 guile, GNU Guile Reference Manual}, for details.}. These package definitions
6313 will not be visible by default. Thus, users can invoke commands such as
6314 @command{guix package} and @command{guix build} have to be used with the
6315 @code{-e} option so that they know where to find the package. Better
6316 yet, they can use the
6317 @code{-L} option of these commands to make those modules visible
6318 (@pxref{Invoking guix build, @code{--load-path}}), or define the
6319 @code{GUIX_PACKAGE_PATH} environment variable. This environment
6320 variable makes it easy to extend or customize the distribution and is
6321 honored by all the user interfaces.
6323 @defvr {Environment Variable} GUIX_PACKAGE_PATH
6324 This is a colon-separated list of directories to search for package
6325 modules. Directories listed in this variable take precedence over the
6326 distribution's own modules.
6329 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
6330 each package is built based solely on other packages in the
6331 distribution. The root of this dependency graph is a small set of
6332 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
6333 bootstrap)} module. For more information on bootstrapping,
6334 @pxref{Bootstrapping}.
6336 @node Packaging Guidelines
6337 @section Packaging Guidelines
6339 The GNU distribution is nascent and may well lack some of your favorite
6340 packages. This section describes how you can help make the distribution
6341 grow. @xref{Contributing}, for additional information on how you can
6344 Free software packages are usually distributed in the form of
6345 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
6346 all the source files. Adding a package to the distribution means
6347 essentially two things: adding a @dfn{recipe} that describes how to
6348 build the package, including a list of other packages required to build
6349 it, and adding @dfn{package meta-data} along with that recipe, such as a
6350 description and licensing information.
6352 In Guix all this information is embodied in @dfn{package definitions}.
6353 Package definitions provide a high-level view of the package. They are
6354 written using the syntax of the Scheme programming language; in fact,
6355 for each package we define a variable bound to the package definition,
6356 and export that variable from a module (@pxref{Package Modules}).
6357 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
6358 creating packages. For more information on package definitions,
6359 @pxref{Defining Packages}.
6361 Once a package definition is in place, stored in a file in the Guix
6362 source tree, it can be tested using the @command{guix build} command
6363 (@pxref{Invoking guix build}). For example, assuming the new package is
6364 called @code{gnew}, you may run this command from the Guix build tree
6365 (@pxref{Running Guix Before It Is Installed}):
6368 ./pre-inst-env guix build gnew --keep-failed
6371 Using @code{--keep-failed} makes it easier to debug build failures since
6372 it provides access to the failed build tree. Another useful
6373 command-line option when debugging is @code{--log-file}, to access the
6376 If the package is unknown to the @command{guix} command, it may be that
6377 the source file contains a syntax error, or lacks a @code{define-public}
6378 clause to export the package variable. To figure it out, you may load
6379 the module from Guile to get more information about the actual error:
6382 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
6385 Once your package builds correctly, please send us a patch
6386 (@pxref{Contributing}). Well, if you need help, we will be happy to
6387 help you too. Once the patch is committed in the Guix repository, the
6388 new package automatically gets built on the supported platforms by
6389 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
6393 Users can obtain the new package definition simply by running
6394 @command{guix pull} (@pxref{Invoking guix pull}). When
6395 @code{hydra.gnu.org} is done building the package, installing the
6396 package automatically downloads binaries from there
6397 (@pxref{Substitutes}). The only place where human intervention is
6398 needed is to review and apply the patch.
6402 * Software Freedom:: What may go into the distribution.
6403 * Package Naming:: What's in a name?
6404 * Version Numbers:: When the name is not enough.
6405 * Python Modules:: Taming the snake.
6406 * Perl Modules:: Little pearls.
6407 * Fonts:: Fond of fonts.
6410 @node Software Freedom
6411 @subsection Software Freedom
6413 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
6415 The GNU operating system has been developed so that users can have
6416 freedom in their computing. GNU is @dfn{free software}, meaning that
6417 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
6418 essential freedoms}: to run the program, to study and change the program
6419 in source code form, to redistribute exact copies, and to distribute
6420 modified versions. Packages found in the GNU distribution provide only
6421 software that conveys these four freedoms.
6423 In addition, the GNU distribution follow the
6424 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
6425 software distribution guidelines}. Among other things, these guidelines
6426 reject non-free firmware, recommendations of non-free software, and
6427 discuss ways to deal with trademarks and patents.
6429 Some packages contain a small and optional subset that violates the
6430 above guidelines, for instance because this subset is itself non-free
6431 code. When that happens, the offending items are removed with
6432 appropriate patches or code snippets in the package definition's
6433 @code{origin} form (@pxref{Defining Packages}). That way, @code{guix
6434 build --source} returns the ``freed'' source rather than the unmodified
6438 @node Package Naming
6439 @subsection Package Naming
6441 A package has actually two names associated with it:
6442 First, there is the name of the @emph{Scheme variable}, the one following
6443 @code{define-public}. By this name, the package can be made known in the
6444 Scheme code, for instance as input to another package. Second, there is
6445 the string in the @code{name} field of a package definition. This name
6446 is used by package management commands such as
6447 @command{guix package} and @command{guix build}.
6449 Both are usually the same and correspond to the lowercase conversion of
6450 the project name chosen upstream, with underscores replaced with
6451 hyphens. For instance, GNUnet is available as @code{gnunet}, and
6452 SDL_net as @code{sdl-net}.
6454 We do not add @code{lib} prefixes for library packages, unless these are
6455 already part of the official project name. But @pxref{Python
6456 Modules} and @ref{Perl Modules} for special rules concerning modules for
6457 the Python and Perl languages.
6459 Font package names are handled differently, @pxref{Fonts}.
6462 @node Version Numbers
6463 @subsection Version Numbers
6465 We usually package only the latest version of a given free software
6466 project. But sometimes, for instance for incompatible library versions,
6467 two (or more) versions of the same package are needed. These require
6468 different Scheme variable names. We use the name as defined
6469 in @ref{Package Naming}
6470 for the most recent version; previous versions use the same name, suffixed
6471 by @code{-} and the smallest prefix of the version number that may
6472 distinguish the two versions.
6474 The name inside the package definition is the same for all versions of a
6475 package and does not contain any version number.
6477 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
6485 (define-public gtk+-2
6491 If we also wanted GTK+ 3.8.2, this would be packaged as
6493 (define-public gtk+-3.8
6501 @node Python Modules
6502 @subsection Python Modules
6504 We currently package Python 2 and Python 3, under the Scheme variable names
6505 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
6506 To avoid confusion and naming clashes with other programming languages, it
6507 seems desirable that the name of a package for a Python module contains
6508 the word @code{python}.
6510 Some modules are compatible with only one version of Python, others with both.
6511 If the package Foo compiles only with Python 3, we name it
6512 @code{python-foo}; if it compiles only with Python 2, we name it
6513 @code{python2-foo}. If it is compatible with both versions, we create two
6514 packages with the corresponding names.
6516 If a project already contains the word @code{python}, we drop this;
6517 for instance, the module python-dateutil is packaged under the names
6518 @code{python-dateutil} and @code{python2-dateutil}.
6522 @subsection Perl Modules
6524 Perl programs standing for themselves are named as any other package,
6525 using the lowercase upstream name.
6526 For Perl packages containing a single class, we use the lowercase class name,
6527 replace all occurrences of @code{::} by dashes and prepend the prefix
6529 So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
6530 Modules containing several classes keep their lowercase upstream name and
6531 are also prepended by @code{perl-}. Such modules tend to have the word
6532 @code{perl} somewhere in their name, which gets dropped in favor of the
6533 prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
6539 For fonts that are in general not installed by a user for typesetting
6540 purposes, or that are distributed as part of a larger software package,
6541 we rely on the general packaging rules for software; for instance, this
6542 applies to the fonts delivered as part of the X.Org system or fonts that
6543 are part of TeX Live.
6545 To make it easier for a user to search for fonts, names for other packages
6546 containing only fonts are constructed as follows, independently of the
6547 upstream package name.
6549 The name of a package containing only one font family starts with
6550 @code{font-}; it is followed by the foundry name and a dash @code{-}
6551 if the foundry is known, and the font family name, in which spaces are
6552 replaced by dashes (and as usual, all upper case letters are transformed
6554 For example, the Gentium font family by SIL is packaged under the name
6555 @code{font-sil-gentium}.
6557 For a package containing several font families, the name of the collection
6558 is used in the place of the font family name.
6559 For instance, the Liberation fonts consist of three families,
6560 Liberation Sans, Liberation Serif and Liberation Mono.
6561 These could be packaged separately under the names
6562 @code{font-liberation-sans} and so on; but as they are distributed together
6563 under a common name, we prefer to package them together as
6564 @code{font-liberation}.
6566 In the case where several formats of the same font family or font collection
6567 are packaged separately, a short form of the format, prepended by a dash,
6568 is added to the package name. We use @code{-ttf} for TrueType fonts,
6569 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
6575 @section Bootstrapping
6577 @c Adapted from the ELS 2013 paper.
6579 @cindex bootstrapping
6581 Bootstrapping in our context refers to how the distribution gets built
6582 ``from nothing''. Remember that the build environment of a derivation
6583 contains nothing but its declared inputs (@pxref{Introduction}). So
6584 there's an obvious chicken-and-egg problem: how does the first package
6585 get built? How does the first compiler get compiled? Note that this is
6586 a question of interest only to the curious hacker, not to the regular
6587 user, so you can shamelessly skip this section if you consider yourself
6590 @cindex bootstrap binaries
6591 The GNU system is primarily made of C code, with libc at its core. The
6592 GNU build system itself assumes the availability of a Bourne shell and
6593 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
6594 `grep'. Furthermore, build programs---programs that run
6595 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
6596 (@pxref{Derivations}). Consequently, to be able to build anything at
6597 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
6598 Binutils, libc, and the other packages mentioned above---the
6599 @dfn{bootstrap binaries}.
6601 These bootstrap binaries are ``taken for granted'', though we can also
6602 re-create them if needed (more on that later).
6604 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
6606 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
6607 @c large image, it's hard to scroll. Oh well.
6608 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
6610 The figure above shows the very beginning of the dependency graph of the
6611 distribution, corresponding to the package definitions of the @code{(gnu
6612 packages bootstrap)} module. At this level of detail, things are
6613 slightly complex. First, Guile itself consists of an ELF executable,
6614 along with many source and compiled Scheme files that are dynamically
6615 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
6616 tarball shown in this graph. This tarball is part of Guix's ``source''
6617 distribution, and gets inserted into the store with @code{add-to-store}
6618 (@pxref{The Store}).
6620 But how do we write a derivation that unpacks this tarball and adds it
6621 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
6622 derivation---the first one that gets built---uses @code{bash} as its
6623 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
6624 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
6625 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
6626 the Guix source distribution, whose sole purpose is to allow the Guile
6627 tarball to be unpacked.
6629 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
6630 Guile that can be used to run subsequent build programs. Its first task
6631 is to download tarballs containing the other pre-built binaries---this
6632 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
6633 @code{ftp-client.scm} are used for this purpose. The
6634 @code{module-import.drv} derivations import those modules in a directory
6635 in the store, using the original layout. The
6636 @code{module-import-compiled.drv} derivations compile those modules, and
6637 write them in an output directory with the right layout. This
6638 corresponds to the @code{#:modules} argument of
6639 @code{build-expression->derivation} (@pxref{Derivations}).
6641 Finally, the various tarballs are unpacked by the
6642 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
6643 etc., at which point we have a working C tool chain.
6646 @unnumberedsubsec Building the Build Tools
6648 @c TODO: Add a package-level dependency graph generated from (gnu
6651 Bootstrapping is complete when we have a full tool chain that does not
6652 depend on the pre-built bootstrap tools discussed above. This
6653 no-dependency requirement is verified by checking whether the files of
6654 the final tool chain contain references to the @file{/gnu/store}
6655 directories of the bootstrap inputs. The process that leads to this
6656 ``final'' tool chain is described by the package definitions found in
6657 the @code{(gnu packages commencement)} module.
6659 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
6660 The first tool that gets built with the bootstrap binaries is
6661 GNU Make, which is a prerequisite for all the following packages.
6662 From there Findutils and Diffutils get built.
6664 Then come the first-stage Binutils and GCC, built as pseudo cross
6665 tools---i.e., with @code{--target} equal to @code{--host}. They are
6666 used to build libc. Thanks to this cross-build trick, this libc is
6667 guaranteed not to hold any reference to the initial tool chain.
6669 From there the final Binutils and GCC are built. GCC uses @code{ld}
6670 from the final Binutils, and links programs against the just-built libc.
6671 This tool chain is used to build the other packages used by Guix and by
6672 the GNU Build System: Guile, Bash, Coreutils, etc.
6674 And voilà! At this point we have the complete set of build tools that
6675 the GNU Build System expects. These are in the @code{%final-inputs}
6676 variable of the @code{(gnu packages commencement)} module, and are
6677 implicitly used by any package that uses @code{gnu-build-system}
6678 (@pxref{Build Systems, @code{gnu-build-system}}).
6681 @unnumberedsubsec Building the Bootstrap Binaries
6683 Because the final tool chain does not depend on the bootstrap binaries,
6684 those rarely need to be updated. Nevertheless, it is useful to have an
6685 automated way to produce them, should an update occur, and this is what
6686 the @code{(gnu packages make-bootstrap)} module provides.
6688 The following command builds the tarballs containing the bootstrap
6689 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
6690 of Coreutils and other basic command-line tools):
6693 guix build bootstrap-tarballs
6696 The generated tarballs are those that should be referred to in the
6697 @code{(gnu packages bootstrap)} module mentioned at the beginning of
6700 Still here? Then perhaps by now you've started to wonder: when do we
6701 reach a fixed point? That is an interesting question! The answer is
6702 unknown, but if you would like to investigate further (and have
6703 significant computational and storage resources to do so), then let us
6707 @section Porting to a New Platform
6709 As discussed above, the GNU distribution is self-contained, and
6710 self-containment is achieved by relying on pre-built ``bootstrap
6711 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
6712 operating system kernel, CPU architecture, and application binary
6713 interface (ABI). Thus, to port the distribution to a platform that is
6714 not yet supported, one must build those bootstrap binaries, and update
6715 the @code{(gnu packages bootstrap)} module to use them on that platform.
6717 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
6718 When everything goes well, and assuming the GNU tool chain supports the
6719 target platform, this can be as simple as running a command like this
6723 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
6726 For this to work, the @code{glibc-dynamic-linker} procedure in
6727 @code{(gnu packages bootstrap)} must be augmented to return the right
6728 file name for libc's dynamic linker on that platform; likewise,
6729 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
6730 taught about the new platform.
6732 Once these are built, the @code{(gnu packages bootstrap)} module needs
6733 to be updated to refer to these binaries on the target platform. That
6734 is, the hashes and URLs of the bootstrap tarballs for the new platform
6735 must be added alongside those of the currently supported platforms. The
6736 bootstrap Guile tarball is treated specially: it is expected to be
6737 available locally, and @file{gnu-system.am} has rules do download it for
6738 the supported architectures; a rule for the new platform must be added
6741 In practice, there may be some complications. First, it may be that the
6742 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
6743 above) is not recognized by all the GNU tools. Typically, glibc
6744 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
6745 configure flag (see @code{gcc.scm} for examples of how to handle this).
6746 Second, some of the required packages could fail to build for that
6747 platform. Lastly, the generated binaries could be broken for some
6751 @c *********************************************************************
6753 @chapter Contributing
6755 This project is a cooperative effort, and we need your help to make it
6756 grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6757 @code{#guix} on the Freenode IRC network. We welcome ideas, bug
6758 reports, patches, and anything that may be helpful to the project. We
6759 particularly welcome help on packaging (@pxref{Packaging Guidelines}).
6762 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
6763 @file{HACKING} file} that comes with the Guix source code for practical
6764 details about contributions.
6767 @c *********************************************************************
6768 @node Acknowledgments
6769 @chapter Acknowledgments
6771 Guix is based on the Nix package manager, which was designed and
6772 implemented by Eelco Dolstra, with contributions from other people (see
6773 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
6774 management, and promoted unprecedented features, such as transactional
6775 package upgrades and rollbacks, per-user profiles, and referentially
6776 transparent build processes. Without this work, Guix would not exist.
6778 The Nix-based software distributions, Nixpkgs and NixOS, have also been
6779 an inspiration for Guix.
6781 GNU@tie{}Guix itself is a collective work with contributions from a
6782 number of people. See the @file{AUTHORS} file in Guix for more
6783 information on these fine people. The @file{THANKS} file lists people
6784 who have helped by reporting bugs, taking care of the infrastructure,
6785 providing artwork and themes, making suggestions, and more---thank you!
6788 @c *********************************************************************
6789 @node GNU Free Documentation License
6790 @appendix GNU Free Documentation License
6792 @include fdl-1.3.texi
6794 @c *********************************************************************
6796 @unnumbered Concept Index
6799 @node Programming Index
6800 @unnumbered Programming Index
6808 @c ispell-local-dictionary: "american";