6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
13 @dircategory Package management
15 * guix: (guix). Guix, the functional package manager.
16 * guix package: (guix)Invoking guix package
17 Managing packages with Guix.
18 * guix build: (guix)Invoking guix build
19 Building packages with Guix.
23 @title{GNU Guix Reference Manual}
24 @subtitle{Using the GNU Guix Functional Package Manager}
25 @author Ludovic Courtès
26 @author Nikita Karetnikov
29 @vskip 0pt plus 1filll
30 Edition @value{EDITION} @*
33 Copyright @copyright{} @value{YEARS} Ludovic Court@`es
36 Permission is granted to copy, distribute and/or modify this document
37 under the terms of the GNU Free Documentation License, Version 1.3 or
38 any later version published by the Free Software Foundation; with no
39 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
40 copy of the license is included in the section entitled ``GNU Free
41 Documentation License''.
46 This manual documents GNU Guix version @value{VERSION}.
48 Copyright @copyright{} @value{YEARS} Ludovic Courtès
50 Permission is granted to copy, distribute and/or modify this document
51 under the terms of the GNU Free Documentation License, Version 1.3 or
52 any later version published by the Free Software Foundation; with no
53 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
54 copy of the license is included in the section entitled ``GNU Free
55 Documentation License.''
60 @c *********************************************************************
64 This document describes GNU Guix version @value{VERSION}, a functional
65 package management tool written for the GNU system.
68 Copyright @copyright{} @value{YEARS} Ludovic Courtès
70 Permission is granted to copy, distribute and/or modify this document
71 under the terms of the GNU Free Documentation License, Version 1.3 or
72 any later version published by the Free Software Foundation; with no
73 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
74 copy of the license is included in the section entitled ``GNU Free
75 Documentation License.''
79 * Introduction:: What is Guix about?
80 * Installation:: Installing Guix.
81 * Package Management:: Package installation, upgrade, etc.
82 * Programming Interface:: Using Guix in Scheme.
83 * Utilities:: Package management commands.
84 * GNU Distribution:: Software for your friendly GNU system.
86 * Acknowledgments:: Thanks!
87 * GNU Free Documentation License:: The license of this manual.
88 * Concept Index:: Concepts.
89 * Function Index:: Functions.
92 @c *********************************************************************
96 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
97 using the international phonetic alphabet (IPA).} is a functional
98 package management tool for the GNU system. Package management consists
99 in all the activities that relate to building packages from source,
100 honoring the build-time and run-time dependencies on packages,
101 installing packages in user environments, upgrading installed packages
102 to new versions or rolling back to a previous set, removing unused
103 software packages, etc.
105 @cindex functional package management
106 The term @dfn{functional} refers to a specific package management
107 discipline. In Guix, the package build and installation process is seen
108 as a function, in the mathematical sense: that function takes inputs,
109 such as build scripts, a compiler, and libraries depended on, and
110 returns the installed package. As a pure function, its result depends
111 solely on its inputs---for instance, it cannot refer to software or
112 scripts that were not explicitly passed as inputs. A build function
113 always produces the same result when passed a given set of inputs. Last
114 but not least, a build function cannot alter the system's environment in
115 any way; for instance, it cannot create, modify, or delete files outside
116 of its build and installation directories. This is achieved by running
117 build processes in dedicated ``chroots'', where only their explicit
121 The result of package build functions is @dfn{cached} in the file
122 system, in a special directory called @dfn{the store} (@pxref{The
123 Store}). Each package is installed in a directory of its own, in the
124 store---by default under @file{/nix/store}. The directory name contains
125 a hash of all the inputs used to build that package; thus, changing an
126 input yields a different directory name.
128 This approach is the foundation of Guix's salient features: support for
129 transactional package upgrades and rollback, per-user installation, and
130 garbage collection of packages (@pxref{Features}).
132 Guix has a command-line interface allowing users to build, install,
133 upgrade, and remove packages, as well as a Scheme programming interface.
134 The remainder of this manual describes them.
136 Last but not least, Guix is used to build a distribution of the GNU
137 system, with many GNU and non-GNU free software packages. @xref{GNU
140 @c *********************************************************************
142 @chapter Installation
144 This section describes the software requirements of Guix, as well as how
145 to install it and get ready to use it.
147 The build procedure for Guix is the same as for other GNU software, and
148 is not covered here. Please see the files @file{README} and
149 @file{INSTALL} in the Guix source tree for additional details.
152 * Requirements:: Software needed to build and run Guix.
153 * Setting Up the Daemon:: Preparing the build daemon's environment.
154 * Invoking guix-daemon:: Running the build daemon.
158 @section Requirements
160 GNU Guix depends on the following packages:
163 @item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x};
164 @item @url{http://gnupg.org/, GNU libgcrypt}
167 Unless @code{--disable-daemon} was passed to @command{configure}, the
168 following packages are also needed:
171 @item @url{http://sqlite.org, SQLite 3}
172 @item @url{http://www.bzip.org, libbz2}
173 @item @url{http://gcc.gnu.org, GCC's g++}
176 When a working installation of the Nix package manager is available, you
177 can instead configure Guix with @code{--disable-daemon}. In that case,
178 @url{http://nixos.org/nix/, Nix} replaces the three dependencies above.
180 Guix is compatible with Nix, so it is possible to share the same store
181 between both. To do so, you must pass @command{configure} not only the
182 same @code{--with-store-dir} value, but also the same
183 @code{--localstatedir} value (the latter is essential because it
184 specifies where the database that store meta-data about the store is
185 located, among other things.) The default values are
186 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
187 Note that @code{--disable-daemon} is orthogonal and is not required if
188 your goal is to share the same store as Nix.
190 @node Setting Up the Daemon
191 @section Setting Up the Daemon
194 Operations such as building a package or running the garbage collector
195 are all performed by a specialized process, the @dfn{Guix daemon}, on
196 behalf of clients. Only the daemon may access the store and its
197 associated database. Thus, any operation that manipulates the store
198 goes through the daemon. For instance, command-line tools such as
199 @command{guix package} and @command{guix build} communicate with the
200 daemon (@i{via} remote procedure calls) to instruct it what to do.
202 In a standard multi-user setup, Guix and its daemon---the
203 @command{guix-daemon} program---are installed by the system
204 administrator; @file{/nix/store} is owned by @code{root} and
205 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
206 Guix tools to build packages or otherwise access the store, and the
207 daemon will do it on their behalf, ensuring that the store is kept in a
208 consistent state, and allowing built packages to be shared among users.
211 When @command{guix-daemon} runs as @code{root}, you may not want package
212 build processes themselves to run as @code{root} too, for obvious
213 security reasons. To avoid that, a special pool of @dfn{build users}
214 should be created for use by build processes started by the daemon.
215 These build users need not have a shell and a home directory: they will
216 just be used when the daemon drops @code{root} privileges in build
217 processes. Having several such users allows the daemon to launch
218 distinct build processes under separate UIDs, which guarantees that they
219 do not interfere with each other---an essential feature since builds are
220 regarded as pure functions (@pxref{Introduction}).
222 On a GNU/Linux system, a build user pool may be created like this (using
223 Bash syntax and the @code{shadow} commands):
225 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
226 @c for why `-G' is needed.
228 # groupadd guix-builder
229 # for i in `seq 1 10`;
231 useradd -g guix-builder -G guix-builder \
232 -d /var/empty -s `which nologin` \
233 -c "Guix build user $i" guix-builder$i;
238 The @code{guix-daemon} program may then be run as @code{root} with:
241 # guix-daemon --build-users-group=guix-builder
244 Guix may also be used in a single-user setup, with @command{guix-daemon}
245 running as an unprivileged user. However, to maximize non-interference
246 of build processes, the daemon still needs to perform certain operations
247 that are restricted to @code{root} on GNU/Linux: it should be able to
248 run build processes in a chroot, and to run them under different UIDs.
249 To that end, the @command{nix-setuid-helper} program is provided; it is
250 a small C program (less than 300 lines) that, if it is made setuid
251 @code{root}, can be executed by the daemon to perform these operations
252 on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
253 is read by @command{nix-setuid-helper}; it should contain exactly two
254 words: the user name under which the authorized @command{guix-daemon}
255 runs, and the name of the build users group.
257 If you are installing Guix as an unprivileged user and do not have the
258 ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
259 possible to run @command{guix-daemon}. However, build processes will
260 not be isolated from one another, and not from the rest of the system.
261 Thus, build processes may interfere with each other, and may access
262 programs, libraries, and other files available on the system---making it
263 much harder to view them as @emph{pure} functions.
265 @node Invoking guix-daemon
266 @section Invoking @command{guix-daemon}
268 The @command{guix-daemon} program implements all the functionality to
269 access the store. This includes launching build processes, running the
270 garbage collector, querying the availability of a build result, etc. It
271 is normally run as @code{root} like this:
274 # guix-daemon --build-users-group=guix-builder
278 For details on how to set it up, @ref{Setting Up the Daemon}.
280 By default, @command{guix-daemon} launches build processes under
281 different UIDs, taken from the build group specified with
282 @code{--build-users-group}. In addition, each build process is run in a
283 chroot environment that only contains the subset of the store that the
284 build process depends on, as specified by its derivation
285 (@pxref{Programming Interface, derivation}), plus a set of specific
286 system directories. By default, the latter contains @file{/dev} and
289 The following command-line options are supported:
292 @item --build-users-group=@var{group}
293 Take users from @var{group} to run build processes (@pxref{Setting Up
294 the Daemon, build users}).
296 @item --cache-failures
297 Cache build failures. By default, only successful builds are cached.
299 @item --cores=@var{n}
301 Use @var{n} CPU cores to build each derivation; @code{0} means as many
304 The default value is @code{1}, but it may be overridden by clients, such
305 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
308 The effect is to define the @code{NIX_BUILD_CORES} environment variable
309 in the build process, which can then use it to exploit internal
310 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
312 @item --max-jobs=@var{n}
314 Allow at most @var{n} build jobs in parallel. The default value is
318 Produce debugging output.
320 This is useful to debug daemon start-up issues, but then it may be
321 overridden by clients, for example the @code{--verbosity} option of
322 @command{guix build} (@pxref{Invoking guix build}).
324 @item --chroot-directory=@var{dir}
325 Add @var{dir} to the build chroot.
327 Doing this may change the result of build processes---for instance if
328 they use optional dependencies found in @var{dir} when it is available,
329 and not otherwise. For that reason, it is not recommended to do so.
330 Instead, make sure that each derivation declares all the inputs that it
333 @item --disable-chroot
334 Disable chroot builds.
336 Using this option is not recommended since, again, it would allow build
337 processes to gain access to undeclared dependencies.
339 @item --disable-log-compression
340 Disable compression of the build logs.
342 Unless @code{--lose-logs} is used, all the build logs are kept in the
343 @var{localstatedir}. To save space, the daemon automatically compresses
344 them with bzip2 by default. This option disables that.
346 @item --disable-store-optimization
347 Disable automatic file ``deduplication'' in the store.
349 By default, files added to the store are automatically ``deduplicated'':
350 if a newly added file is identical as another one found in the store,
351 the daemon makes the new file a hard link to the other file. This
352 slightly increases the input/output load at the end of a build process.
353 This option disables this.
355 @item --impersonate-linux-2.6
356 On Linux-based systems, impersonate Linux 2.6. This means that the
357 kernel's @code{uname} system call will report 2.6 as the release number.
359 This might be helpful to build programs that (usually wrongfully) depend
360 on the kernel version number.
363 Do not keep build logs. By default they are kept under
364 @code{@var{localstatedir}/nix/log}.
366 @item --system=@var{system}
367 Assume @var{system} as the current system type. By default it is the
368 architecture/kernel pair found at configure time, such as
373 @c *********************************************************************
374 @node Package Management
375 @chapter Package Management
377 The purpose of GNU Guix is to allow users to easily install, upgrade, and
378 remove software packages, without having to know about their build
379 procedure or dependencies. Guix also goes beyond this obvious set of
382 This chapter describes the main features of Guix, as well as the package
383 management tools it provides.
386 * Features:: How Guix will make your life brighter.
387 * Invoking guix package:: Package installation, removal, etc.
388 * Invoking guix gc:: Running the garbage collector.
394 When using Guix, each package ends up in the @dfn{package store}, in its
395 own directory---something that resembles
396 @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
398 Instead of referring to these directories, users have their own
399 @dfn{profile}, which points to the packages that they actually want to
400 use. These profiles are stored within each user's home directory, at
401 @code{$HOME/.guix-profile}.
403 For example, @code{alice} installs GCC 4.7.2. As a result,
404 @file{/home/alice/.guix-profile/bin/gcc} points to
405 @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
406 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
407 simply continues to point to
408 @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
409 coexist on the same system without any interference.
411 The @command{guix package} command is the central tool to manage
412 packages (@pxref{Invoking guix package}). It operates on those per-user
413 profiles, and can be used @emph{with normal user privileges}.
415 The command provides the obvious install, remove, and upgrade
416 operations. Each invocation is actually a @emph{transaction}: either
417 the specified operation succeeds, or nothing happens. Thus, if the
418 @command{guix package} process is terminated during the transaction,
419 or if a power outage occurs during the transaction, then the user's
420 profile remains in its previous state, and remains usable.
422 In addition, any package transaction may be @emph{rolled back}. So, if,
423 for example, an upgrade installs a new version of a package that turns
424 out to have a serious bug, users may roll back to the previous instance
425 of their profile, which was known to work well.
427 All those packages in the package store may be @emph{garbage-collected}.
428 Guix can determine which packages are still referenced by the user
429 profiles, and remove those that are provably no longer referenced
430 (@pxref{Invoking guix gc}). Users may also explicitly remove old
431 generations of their profile so that the packages they refer to can be
434 Finally, Guix takes a @dfn{purely functional} approach to package
435 management, as described in the introduction (@pxref{Introduction}).
436 Each @file{/nix/store} package directory name contains a hash of all the
437 inputs that were used to build that package---compiler, libraries, build
438 scripts, etc. This direct correspondence allows users to make sure a
439 given package installation matches the current state of their
440 distribution, and helps maximize @dfn{reproducibility}.
442 @c FIXME: Remove footnote when it's implemented.
443 This foundation allows Guix to support @dfn{transparent binary/source
444 deployment}@footnote{This feature is not implemented as of version
445 @value{VERSION}. Please contact @email{bug-guix@@gnu.org} for more
446 details.}. When a pre-built binary for a @file{/nix/store} path is
447 available from an external source, Guix just downloads it; otherwise, it
448 builds the package from source, locally.
450 @node Invoking guix package
451 @section Invoking @command{guix package}
453 The @command{guix package} command is the tool that allows users to
454 install, upgrade, and remove packages, as well as rolling back to
455 previous configurations. It operates only on the user's own profile,
456 and works with normal user privileges (@pxref{Features}). Its syntax
460 guix package @var{options}
463 Primarily, @var{options} specifies the operations to be performed during
464 the transaction. Upon completion, a new profile is created, but
465 previous generations of the profile remain available, should the user
468 For each user, a symlink to the user's default profile is automatically
469 created in @file{$HOME/.guix-profile}. This symlink always points to the
470 current generation of the user's default profile. Thus, users can add
471 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
474 In a multi-user setup, user profiles must be stored in a place
475 registered as a @dfn{garbage-collector root}, which
476 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
477 directory is normally
478 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
479 @var{localstatedir} is the value passed to @code{configure} as
480 @code{--localstatedir}, and @var{user} is the user name. It must be
481 created by @code{root}, with @var{user} as the owner. When it does not
482 exist, @command{guix package} emits an error about it.
484 The @var{options} can be among the following:
488 @item --install=@var{package}
489 @itemx -i @var{package}
490 Install @var{package}.
492 @var{package} may specify either a simple package name, such as
493 @code{guile}, or a package name followed by a hyphen and version number,
494 such as @code{guile-1.8.8}. If no version number is specified, the
495 newest available version will be selected. In addition, @var{package}
496 may contain a colon, followed by the name of one of the outputs of the
497 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}.
499 @cindex propagated inputs
500 Sometimes packages have @dfn{propagated inputs}: these are dependencies
501 that automatically get installed along with the required package.
503 An example is the GNU MPC library: its C header files refer to those of
504 the GNU MPFR library, which in turn refer to those of the GMP library.
505 Thus, when installing MPC, the MPFR and GMP libraries also get installed
506 in the profile; removing MPC also removes MPFR and GMP---unless they had
507 also been explicitly installed independently.
509 @item --remove=@var{package}
510 @itemx -r @var{package}
511 Remove @var{package}.
513 @item --upgrade=@var{regexp}
514 @itemx -u @var{regexp}
515 Upgrade all the installed packages matching @var{regexp}.
518 Roll back to the previous @dfn{generation} of the profile---i.e., undo
519 the last transaction.
521 When combined with options such as @code{--install}, roll back occurs
522 before any other actions.
524 When rolling back from the first generation that actually contains
525 installed packages, the profile is made to point to the @dfn{empty
526 profile}, also known as @dfn{profile zero}---i.e., it contains no files
527 apart from its own meta-data.
529 Installing, removing, or upgrading packages from a generation that has
530 been rolled back to overwrites previous future generations. Thus, the
531 history of a profile's generations is always linear.
533 @item --profile=@var{profile}
534 @itemx -p @var{profile}
535 Use @var{profile} instead of the user's default profile.
539 Show what would be done without actually doing it.
542 Produce verbose output. In particular, emit the environment's build log
543 on the standard error port.
546 Use the bootstrap Guile to build the profile. This option is only
547 useful to distribution developers.
551 In addition to these actions @command{guix package} supports the
552 following options to query the current state of a profile, or the
553 availability of packages:
557 @item --search=@var{regexp}
558 @itemx -s @var{regexp}
559 List the available packages whose synopsis or description matches
560 @var{regexp}. Print all the meta-data of matching packages in
561 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
562 GNU recutils manual}).
564 This allows specific fields to be extracted using the @command{recsel}
565 command, for instance:
568 $ guix package -s malloc | recsel -p name,version
576 @item --list-installed[=@var{regexp}]
577 @itemx -I [@var{regexp}]
578 List currently installed packages in the specified profile. When
579 @var{regexp} is specified, list only installed packages whose name
580 matches @var{regexp}.
582 For each installed package, print the following items, separated by
583 tabs: the package name, its version string, the part of the package that
584 is installed (for instance, @code{out} for the default output,
585 @code{include} for its headers, etc.), and the path of this package in
588 @item --list-available[=@var{regexp}]
589 @itemx -A [@var{regexp}]
590 List packages currently available in the software distribution
591 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
592 installed packages whose name matches @var{regexp}.
594 For each package, print the following items separated by tabs: its name,
595 its version string, the parts of the package (@code{out} for the main
596 files, @code{lib} for libraries and possibly headers, etc.), and the
597 source location of its definition.
602 @node Invoking guix gc
603 @section Invoking @command{guix gc}
605 @cindex garbage collector
606 Packages that are installed but not used may be @dfn{garbage-collected}.
607 The @command{guix gc} command allows users to explicitly run the garbage
608 collector to reclaim space from the @file{/nix/store} directory.
610 The garbage collector has a set of known @dfn{roots}: any file under
611 @file{/nix/store} reachable from a root is considered @dfn{live} and
612 cannot be deleted; any other file is considered @dfn{dead} and may be
613 deleted. The set of garbage collector roots includes default user
614 profiles, and may be augmented with @command{guix build --root}, for
615 example (@pxref{Invoking guix build}).
617 The @command{guix gc} command has three modes of operation: it can be
618 used to garbage-collect any dead files (the default), to delete specific
619 files (the @code{--delete} option), or to print garbage-collector
620 information. The available options are listed below:
623 @item --collect-garbage[=@var{min}]
624 @itemx -C [@var{min}]
625 Collect garbage---i.e., unreachable @file{/nix/store} files and
626 sub-directories. This is the default operation when no option is
629 When @var{min} is given, stop once @var{min} bytes have been collected.
630 @var{min} may be a number of bytes, or it may include a unit as a
631 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
633 When @var{min} is omitted, collect all the garbage.
637 Attempt to delete all the store files and directories specified as
638 arguments. This fails if some of the files are not in the store, or if
642 Show the list of dead files and directories still present in the
643 store---i.e., files and directories no longer reachable from any root.
646 Show the list of live store files and directories.
650 @c *********************************************************************
651 @node Programming Interface
652 @chapter Programming Interface
654 GNU Guix provides several Scheme programming interfaces (APIs) to
655 define, build, and query packages. The first interface allows users to
656 write high-level package definitions. These definitions refer to
657 familiar packaging concepts, such as the name and version of a package,
658 its build system, and its dependencies. These definitions can then be
659 turned into concrete build actions.
661 Build actions are performed by the Guix daemon, on behalf of users. In a
662 standard setup, the daemon has write access to the store---the
663 @file{/nix/store} directory---whereas users do not. The recommended
664 setup also has the daemon perform builds in chroots, under a specific
665 build users, to minimize interference with the rest of the system.
668 Lower-level APIs are available to interact with the daemon and the
669 store. To instruct the daemon to perform a build action, users actually
670 provide it with a @dfn{derivation}. A derivation is a low-level
671 representation of the build actions to be taken, and the environment in
672 which they should occur---derivations are to package definitions what
673 assembly is to C programs.
675 This chapter describes all these APIs in turn, starting from high-level
679 * Defining Packages:: Defining new packages.
680 * The Store:: Manipulating the package store.
681 * Derivations:: Low-level interface to package derivations.
684 @node Defining Packages
685 @section Defining Packages
687 The high-level interface to package definitions is implemented in the
688 @code{(guix packages)} and @code{(guix build-system)} modules. As an
689 example, the package definition, or @dfn{recipe}, for the GNU Hello
690 package looks like this:
693 (use-modules (guix packages)
695 (guix build-system gnu)
704 (uri (string-append "mirror://gnu/hello/hello-" version
707 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
708 (build-system gnu-build-system)
709 (inputs `(("gawk" ,gawk)))
710 (synopsis "GNU Hello")
711 (description "Yeah...")
712 (home-page "http://www.gnu.org/software/hello/")
717 Without being a Scheme expert, the reader may have guessed the meaning
718 of the various fields here. This expression binds variable @var{hello}
719 to a @code{<package>} object, which is essentially a record
720 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
721 This package object can be inspected using procedures found in the
722 @code{(guix packages)} module; for instance, @code{(package-name hello)}
723 returns---surprise!---@code{"hello"}.
725 There are a few points worth noting in the above package definition:
729 The @code{source} field of the package is an @code{<origin>} object.
730 Here, the @code{url-fetch} method from @code{(guix download)} is used,
731 meaning that the source is a file to be downloaded over FTP or HTTP.
733 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
734 the GNU mirrors defined in @code{(guix download)}.
736 The @code{sha256} field specifies the expected SHA256 hash of the file
737 being downloaded. It is mandatory, and allows Guix to check the
738 integrity of the file. The @code{(base32 @dots{})} form introduces the
739 base32 representation of the hash. A convenient way to obtain this
740 information is with the @code{guix download} tool.
743 @cindex GNU Build System
744 The @code{build-system} field is set to @var{gnu-build-system}. The
745 @var{gnu-build-system} variable is defined in the @code{(guix
746 build-system gnu)} module, and is bound to a @code{<build-system>}
749 Naturally, @var{gnu-build-system} represents the familiar GNU Build
750 System, and variants thereof (@pxref{Configuration, configuration and
751 makefile conventions,, standards, GNU Coding Standards}). In a
752 nutshell, packages using the GNU Build System may be configured, built,
753 and installed with the usual @code{./configure && make && make check &&
754 make install} command sequence. This is what @var{gnu-build-system}
757 In addition, @var{gnu-build-system} ensures that the ``standard''
758 environment for GNU packages is available. This includes tools such as
759 GCC, Coreutils, Bash, Make, Diffutils, and Patch.
762 The @code{inputs} field specifies inputs to the build process---i.e.,
763 build-time or run-time dependencies of the package. Here, we define an
764 input called @code{"gawk"} whose value is that of the @var{gawk}
765 variable; @var{gawk} is itself bound to a @code{<package>} object.
767 Note that GCC, Coreutils, Bash, and other essential tools do not need to
768 be specified as inputs here. Instead, @var{gnu-build-system} takes care
769 of ensuring that they are present.
771 However, any other dependencies need to be specified in the
772 @code{inputs} field. Any dependency not specified here will simply be
773 unavailable to the build process, possibly leading to a build failure.
776 There are other fields that package definitions may provide. Of
777 particular interest is the @code{arguments} field. When specified, it
778 must be bound to a list of additional arguments to be passed to the
779 build system. For instance, the above definition could be augmented
780 with the following field initializer:
783 (arguments `(#:tests? #f
784 #:configure-flags '("--enable-silent-rules")))
788 These are keyword arguments (@pxref{Optional Arguments, keyword
789 arguments in Guile,, guile, GNU Guile Reference Manual}). They are
790 passed to @var{gnu-build-system}, which interprets them as meaning ``do
791 not run @code{make check}'', and ``run @file{configure} with the
792 @code{--enable-silent-rules} flag''. The value of these keyword
793 parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
794 Guile process launched by the daemon (@pxref{Derivations}).
796 Once a package definition is in place@footnote{Simple package
797 definitions like the one above may be automatically converted from the
798 Nixpkgs distribution using the @command{guix import} command.}, the
799 package may actually be built using the @code{guix build} command-line
800 tool (@pxref{Invoking guix build}).
802 Behind the scenes, a derivation corresponding to the @code{<package>}
803 object is first computed by the @code{package-derivation} procedure.
804 That derivation is stored in a @code{.drv} file under @file{/nix/store}.
805 The build actions it prescribes may then be realized by using the
806 @code{build-derivations} procedure (@pxref{The Store}).
808 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
809 Return the derivation path and corresponding @code{<derivation>} object
810 of @var{package} for @var{system} (@pxref{Derivations}).
812 @var{package} must be a valid @code{<package>} object, and @var{system}
813 must be a string denoting the target system type---e.g.,
814 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
815 must be a connection to the daemon, which operates on the store
825 Conceptually, the @dfn{store} is where derivations that have been
826 successfully built are stored---by default, under @file{/nix/store}.
827 Sub-directories in the store are referred to as @dfn{store paths}. The
828 store has an associated database that contains information such has the
829 store paths referred to by each store path, and the list of @emph{valid}
830 store paths---paths that result from a successful build.
832 The store is always accessed by the daemon on behalf of its clients
833 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
834 connect to the daemon over a Unix-domain socket, send it requests, and
835 read the result---these are remote procedure calls, or RPCs.
837 The @code{(guix store)} module provides procedures to connect to the
838 daemon, and to perform RPCs. These are described below.
840 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
841 Connect to the daemon over the Unix-domain socket at @var{file}. When
842 @var{reserve-space?} is true, instruct it to reserve a little bit of
843 extra space on the file system so that the garbage collector can still
844 operate, should the disk become full. Return a server object.
846 @var{file} defaults to @var{%default-socket-path}, which is the normal
847 location given the options that were passed to @command{configure}.
850 @deffn {Scheme Procedure} close-connection @var{server}
851 Close the connection to @var{server}.
854 @defvr {Scheme Variable} current-build-output-port
855 This variable is bound to a SRFI-39 parameter, which refers to the port
856 where build and error logs sent by the daemon should be written.
859 Procedures that make RPCs all take a server object as their first
862 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
863 Return @code{#t} when @var{path} is a valid store path.
866 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
867 Add @var{text} under file @var{name} in the store, and return its store
868 path. @var{references} is the list of store paths referred to by the
869 resulting store path.
872 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
873 Build @var{derivations} (a list of derivation paths), and return when
874 the worker is done building them. Return @code{#t} on success.
878 @i{This section is currently incomplete.}
884 Low-level build actions and the environment in which they are performed
885 are represented by @dfn{derivations}. A derivation contain the
886 following pieces of information:
890 The outputs of the derivation---derivations produce at least one file or
891 directory in the store, but may produce more.
894 The inputs of the derivations, which may be other derivations or plain
895 files in the store (patches, build scripts, etc.)
898 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
901 The file name of a build script in the store, along with the arguments
905 A list of environment variables to be defined.
909 @cindex derivation path
910 Derivations allow clients of the daemon to communicate build actions to
911 the store. They exist in two forms: as an in-memory representation,
912 both on the client- and daemon-side, and as files in the store whose
913 name end in @code{.drv}---these files are referred to as @dfn{derivation
914 paths}. Derivations paths can be passed to the @code{build-derivations}
915 procedure to perform the build actions they prescribe (@pxref{The
918 The @code{(guix derivations)} module provides a representation of
919 derivations as Scheme objects, along with procedures to create and
920 otherwise manipulate derivations. The lowest-level primitive to create
921 a derivation is the @code{derivation} procedure:
923 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f]
924 Build a derivation with the given arguments. Return the resulting store
925 path and @code{<derivation>} object.
927 When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
928 @dfn{fixed-output derivation} is created---i.e., one whose result is
929 known in advance, such as a file download.
933 Here's an example with a shell script as its builder, assuming
934 @var{store} is an open connection to the daemon, and @var{bash} points
935 to a Bash executable in the store:
938 (use-modules (guix utils)
944 (let ((builder ; add the Bash script to the store
945 (add-text-to-store store "my-builder.sh"
946 "echo hello world > $out\n" '())))
947 (derivation store "foo" (%current-system)
948 bash `("-e" ,builder)
949 '(("HOME" . "/homeless")) '())))
951 @result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
954 As can be guessed, this primitive is cumbersome to use directly. An
955 improved variant is @code{build-expression->derivation}, which allows
956 the caller to directly pass a Guile expression as the build script:
958 @deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f]
959 Return a derivation that executes Scheme expression @var{exp} as a
960 builder for derivation @var{name}. @var{inputs} must be a list of
961 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
962 @code{"out"} is assumed. @var{modules} is a list of names of Guile
963 modules from the current search path to be copied in the store,
964 compiled, and made available in the load path during the execution of
965 @var{exp}---e.g., @code{((guix build utils) (guix build
968 @var{exp} is evaluated in an environment where @code{%outputs} is bound
969 to a list of output/path pairs, and where @code{%build-inputs} is bound
970 to a list of string/output-path pairs made from @var{inputs}.
971 Optionally, @var{env-vars} is a list of string pairs specifying the name
972 and value of environment variables visible to the builder. The builder
973 terminates by passing the result of @var{exp} to @code{exit}; thus, when
974 @var{exp} returns @code{#f}, the build is considered to have failed.
976 @var{exp} is built using @var{guile-for-build} (a derivation). When
977 @var{guile-for-build} is omitted or is @code{#f}, the value of the
978 @code{%guile-for-build} fluid is used instead.
982 Here's an example of a single-output derivation that creates a directory
986 (let ((builder '(let ((out (assoc-ref %outputs "out")))
987 (mkdir out) ; create /nix/store/@dots{}-goo
988 (call-with-output-file (string-append out "/test")
990 (display '(hello guix) p))))))
991 (build-expression->derivation store "goo" (%current-system)
994 @result{} "/nix/store/@dots{}-goo.drv"
995 @result{} #<<derivation> @dots{}>
998 @cindex strata of code
999 Remember that the build expression passed to
1000 @code{build-expression->derivation} is run by a separate Guile process
1001 than the one that calls @code{build-expression->derivation}: it is run
1002 by a Guile process launched by the daemon, typically in a chroot. So,
1003 while there is a single language for both the @dfn{host} and the build
1004 side, there are really two @dfn{strata} of code: the host-side, and the
1005 build-side code@footnote{The term @dfn{stratum} in this context was
1006 coined by Manuel Serrano et al. in the context of their work on Hop.}.
1007 This distinction is important to keep in mind, notably when using
1008 higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
1009 Packages}). For this reason, Guix modules that are meant to be used in
1010 the build stratum are kept in the @code{(guix build @dots{})} name
1013 @c *********************************************************************
1018 * Invoking guix build:: Building packages from the command line.
1021 @node Invoking guix build
1022 @section Invoking @command{guix build}
1024 The @command{guix build} command builds packages or derivations and
1025 their dependencies, and prints the resulting store paths. Note that it
1026 does not modify the user's profile---this is the job of the
1027 @command{guix package} command (@pxref{Invoking guix package}). Thus,
1028 it is mainly useful for distribution developers.
1030 The general syntax is:
1033 guix build @var{options} @var{package-or-derivation}@dots{}
1036 @var{package-or-derivation} may be either the name of a package found in
1037 the software distribution such as @code{coreutils} or
1038 @code{coreutils-8.20}, or a derivation such as
1039 @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
1040 @code{--expression} option may be used to specify a Scheme expression
1041 that evaluates to a package; this is useful when disambiguation among
1042 several same-named packages or package variants is needed.
1044 The @var{options} may be zero or more of the following:
1048 @item --expression=@var{expr}
1049 @itemx -e @var{expr}
1050 Build the package @var{expr} evaluates to.
1052 For example, @var{expr} may be @code{(@@ (gnu packages guile)
1053 guile-1.8)}, which unambiguously designates this specific variant of
1054 version 1.8 of Guile.
1058 Build the packages' source derivations, rather than the packages
1061 For instance, @code{guix build -S gcc} returns something like
1062 @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
1064 @item --system=@var{system}
1065 @itemx -s @var{system}
1066 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
1067 the host's system type.
1069 An example use of this is on Linux-based systems, which can emulate
1070 different personalities. For instance, passing
1071 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
1072 to build packages in a complete 32-bit environment.
1076 Return the derivation paths, not the output paths, of the given
1081 Keep the build tree of failed builds. Thus, if a build fail, its build
1082 tree is kept under @file{/tmp}, in a directory whose name is shown at
1083 the end of the build log. This is useful when debugging build issues.
1087 Do not build the derivations.
1089 @item --no-substitutes
1090 Build instead of resorting to pre-built substitutes.
1092 @item --cores=@var{n}
1094 Allow the use of up to @var{n} CPU cores for the build. The special
1095 value @code{0} means to use as many CPU cores as available.
1097 @item --root=@var{file}
1098 @itemx -r @var{file}
1099 Make @var{file} a symlink to the result, and register it as a garbage
1102 @item --verbosity=@var{level}
1103 Use the given verbosity level. @var{level} must be an integer between 0
1104 and 5; higher means more verbose output. Setting a level of 4 or more
1105 may be helpful when debugging setup issues with the build daemon.
1109 Behind the scenes, @command{guix build} is essentially an interface to
1110 the @code{package-derivation} procedure of the @code{(guix packages)}
1111 module, and to the @code{build-derivations} procedure of the @code{(guix
1114 @c *********************************************************************
1115 @node GNU Distribution
1116 @chapter GNU Distribution
1118 Guix comes with a distribution of free software@footnote{The term
1119 ``free'' here refers to the
1120 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
1121 users of that software}.} that form the basis of the GNU system. This
1122 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
1123 as many GNU and non-GNU applications. The complete list of available
1124 packages can be seen by running @command{guix package} (@pxref{Invoking
1128 guix package --list-available
1131 The package definitions of the distribution may are provided by Guile
1132 modules in the @code{(gnu packages ...)} name space---for instance, the
1133 @code{(gnu packages emacs)} module exports a variable named
1134 @code{emacs}, which is bound to a @code{<package>} object
1135 (@pxref{Defining Packages}). The @code{(gnu packages)} module provides
1136 facilities for searching for packages.
1138 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
1139 each package is built based solely on other packages in the
1140 distribution. The root of this dependency graph is a small set of
1141 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
1142 bootstrap)} module. These are statically-linked binaries of the core
1143 tools without which building anything at all would be impossible.
1146 Our goal is to build a practical 100% free software distribution of
1147 Linux-based and other variants of GNU, with a focus on the promotion and
1148 tight integration of GNU components, and an emphasis on programs and
1149 tools that help users exert that freedom.
1151 Building this distribution is a cooperative effort, and you are invited
1152 to join! Please get in touch with us on @email{bug-guix@@gnu.org}. We
1153 welcome ideas, bug reports, patches, and anything that may be helpful to
1157 @c *********************************************************************
1158 @node Acknowledgments
1159 @chapter Acknowledgments
1161 Guix is based on the Nix package manager, which was designed and
1162 implemented by Eelco Dolstra. Nix pioneered functional package
1163 management, and promoted unprecedented features, such as transactional
1164 package upgrades and rollbacks, per-user profiles, and referentially
1165 transparent build processes. Without this work, Guix would not exist.
1167 The Nix-based software distributions, Nixpkgs and NixOS, have also been
1168 an inspiration for Guix.
1170 @c *********************************************************************
1171 @node GNU Free Documentation License
1172 @appendix GNU Free Documentation License
1174 @include fdl-1.3.texi
1176 @c *********************************************************************
1178 @unnumbered Concept Index
1181 @node Function Index
1182 @unnumbered Function Index
1188 @c ispell-local-dictionary: "american";