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 GNU Guix is available for download from its website at
145 @url{http://www.gnu.org/software/guix/}. This section describes the
146 software requirements of Guix, as well as how to install it and get
149 The build procedure for Guix is the same as for other GNU software, and
150 is not covered here. Please see the files @file{README} and
151 @file{INSTALL} in the Guix source tree for additional details.
154 * Requirements:: Software needed to build and run Guix.
155 * Setting Up the Daemon:: Preparing the build daemon's environment.
156 * Invoking guix-daemon:: Running the build daemon.
160 @section Requirements
162 GNU Guix depends on the following packages:
165 @item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x};
166 @item @url{http://gnupg.org/, GNU libgcrypt}
169 Unless @code{--disable-daemon} was passed to @command{configure}, the
170 following packages are also needed:
173 @item @url{http://sqlite.org, SQLite 3}
174 @item @url{http://www.bzip.org, libbz2}
175 @item @url{http://gcc.gnu.org, GCC's g++}
178 When a working installation of the Nix package manager is available, you
179 can instead configure Guix with @code{--disable-daemon}. In that case,
180 @url{http://nixos.org/nix/, Nix} replaces the three dependencies above.
182 Guix is compatible with Nix, so it is possible to share the same store
183 between both. To do so, you must pass @command{configure} not only the
184 same @code{--with-store-dir} value, but also the same
185 @code{--localstatedir} value (the latter is essential because it
186 specifies where the database that store meta-data about the store is
187 located, among other things.) The default values are
188 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
189 Note that @code{--disable-daemon} is orthogonal and is not required if
190 your goal is to share the same store as Nix.
192 @node Setting Up the Daemon
193 @section Setting Up the Daemon
196 Operations such as building a package or running the garbage collector
197 are all performed by a specialized process, the @dfn{Guix daemon}, on
198 behalf of clients. Only the daemon may access the store and its
199 associated database. Thus, any operation that manipulates the store
200 goes through the daemon. For instance, command-line tools such as
201 @command{guix package} and @command{guix build} communicate with the
202 daemon (@i{via} remote procedure calls) to instruct it what to do.
204 In a standard multi-user setup, Guix and its daemon---the
205 @command{guix-daemon} program---are installed by the system
206 administrator; @file{/nix/store} is owned by @code{root} and
207 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
208 Guix tools to build packages or otherwise access the store, and the
209 daemon will do it on their behalf, ensuring that the store is kept in a
210 consistent state, and allowing built packages to be shared among users.
213 When @command{guix-daemon} runs as @code{root}, you may not want package
214 build processes themselves to run as @code{root} too, for obvious
215 security reasons. To avoid that, a special pool of @dfn{build users}
216 should be created for use by build processes started by the daemon.
217 These build users need not have a shell and a home directory: they will
218 just be used when the daemon drops @code{root} privileges in build
219 processes. Having several such users allows the daemon to launch
220 distinct build processes under separate UIDs, which guarantees that they
221 do not interfere with each other---an essential feature since builds are
222 regarded as pure functions (@pxref{Introduction}).
224 On a GNU/Linux system, a build user pool may be created like this (using
225 Bash syntax and the @code{shadow} commands):
227 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
228 @c for why `-G' is needed.
230 # groupadd guix-builder
231 # for i in `seq 1 10`;
233 useradd -g guix-builder -G guix-builder \
234 -d /var/empty -s `which nologin` \
235 -c "Guix build user $i" guix-builder$i;
240 The @code{guix-daemon} program may then be run as @code{root} with:
243 # guix-daemon --build-users-group=guix-builder
246 Guix may also be used in a single-user setup, with @command{guix-daemon}
247 running as an unprivileged user. However, to maximize non-interference
248 of build processes, the daemon still needs to perform certain operations
249 that are restricted to @code{root} on GNU/Linux: it should be able to
250 run build processes in a chroot, and to run them under different UIDs.
251 To that end, the @command{nix-setuid-helper} program is provided; it is
252 a small C program (less than 300 lines) that, if it is made setuid
253 @code{root}, can be executed by the daemon to perform these operations
254 on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
255 is read by @command{nix-setuid-helper}; it should contain exactly two
256 words: the user name under which the authorized @command{guix-daemon}
257 runs, and the name of the build users group.
259 If you are installing Guix as an unprivileged user and do not have the
260 ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
261 possible to run @command{guix-daemon}. However, build processes will
262 not be isolated from one another, and not from the rest of the system.
263 Thus, build processes may interfere with each other, and may access
264 programs, libraries, and other files available on the system---making it
265 much harder to view them as @emph{pure} functions.
267 @node Invoking guix-daemon
268 @section Invoking @command{guix-daemon}
270 The @command{guix-daemon} program implements all the functionality to
271 access the store. This includes launching build processes, running the
272 garbage collector, querying the availability of a build result, etc. It
273 is normally run as @code{root} like this:
276 # guix-daemon --build-users-group=guix-builder
280 For details on how to set it up, @ref{Setting Up the Daemon}.
282 By default, @command{guix-daemon} launches build processes under
283 different UIDs, taken from the build group specified with
284 @code{--build-users-group}. In addition, each build process is run in a
285 chroot environment that only contains the subset of the store that the
286 build process depends on, as specified by its derivation
287 (@pxref{Programming Interface, derivation}), plus a set of specific
288 system directories. By default, the latter contains @file{/dev} and
291 The following command-line options are supported:
294 @item --build-users-group=@var{group}
295 Take users from @var{group} to run build processes (@pxref{Setting Up
296 the Daemon, build users}).
298 @item --no-substitutes
299 Do not use substitutes for build products. That is, always build things
300 locally instead of allowing downloads of pre-built binaries.
302 @item --cache-failures
303 Cache build failures. By default, only successful builds are cached.
305 @item --cores=@var{n}
307 Use @var{n} CPU cores to build each derivation; @code{0} means as many
310 The default value is @code{1}, but it may be overridden by clients, such
311 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
314 The effect is to define the @code{NIX_BUILD_CORES} environment variable
315 in the build process, which can then use it to exploit internal
316 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
318 @item --max-jobs=@var{n}
320 Allow at most @var{n} build jobs in parallel. The default value is
324 Produce debugging output.
326 This is useful to debug daemon start-up issues, but then it may be
327 overridden by clients, for example the @code{--verbosity} option of
328 @command{guix build} (@pxref{Invoking guix build}).
330 @item --chroot-directory=@var{dir}
331 Add @var{dir} to the build chroot.
333 Doing this may change the result of build processes---for instance if
334 they use optional dependencies found in @var{dir} when it is available,
335 and not otherwise. For that reason, it is not recommended to do so.
336 Instead, make sure that each derivation declares all the inputs that it
339 @item --disable-chroot
340 Disable chroot builds.
342 Using this option is not recommended since, again, it would allow build
343 processes to gain access to undeclared dependencies.
345 @item --disable-log-compression
346 Disable compression of the build logs.
348 Unless @code{--lose-logs} is used, all the build logs are kept in the
349 @var{localstatedir}. To save space, the daemon automatically compresses
350 them with bzip2 by default. This option disables that.
352 @item --disable-store-optimization
353 Disable automatic file ``deduplication'' in the store.
355 By default, files added to the store are automatically ``deduplicated'':
356 if a newly added file is identical as another one found in the store,
357 the daemon makes the new file a hard link to the other file. This
358 slightly increases the input/output load at the end of a build process.
359 This option disables this.
361 @item --impersonate-linux-2.6
362 On Linux-based systems, impersonate Linux 2.6. This means that the
363 kernel's @code{uname} system call will report 2.6 as the release number.
365 This might be helpful to build programs that (usually wrongfully) depend
366 on the kernel version number.
369 Do not keep build logs. By default they are kept under
370 @code{@var{localstatedir}/nix/log}.
372 @item --system=@var{system}
373 Assume @var{system} as the current system type. By default it is the
374 architecture/kernel pair found at configure time, such as
377 @item --listen=@var{socket}
378 Listen for connections on @var{socket}, the file name of a Unix-domain
379 socket. The default socket is
380 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
381 useful in exceptional circumstances, such as if you need to run several
382 daemons on the same machine.
386 @c *********************************************************************
387 @node Package Management
388 @chapter Package Management
390 The purpose of GNU Guix is to allow users to easily install, upgrade, and
391 remove software packages, without having to know about their build
392 procedure or dependencies. Guix also goes beyond this obvious set of
395 This chapter describes the main features of Guix, as well as the package
396 management tools it provides.
399 * Features:: How Guix will make your life brighter.
400 * Invoking guix package:: Package installation, removal, etc.
401 * Invoking guix gc:: Running the garbage collector.
402 * Invoking guix pull:: Fetching the latest Guix and distribution.
408 When using Guix, each package ends up in the @dfn{package store}, in its
409 own directory---something that resembles
410 @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
412 Instead of referring to these directories, users have their own
413 @dfn{profile}, which points to the packages that they actually want to
414 use. These profiles are stored within each user's home directory, at
415 @code{$HOME/.guix-profile}.
417 For example, @code{alice} installs GCC 4.7.2. As a result,
418 @file{/home/alice/.guix-profile/bin/gcc} points to
419 @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
420 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
421 simply continues to point to
422 @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
423 coexist on the same system without any interference.
425 The @command{guix package} command is the central tool to manage
426 packages (@pxref{Invoking guix package}). It operates on those per-user
427 profiles, and can be used @emph{with normal user privileges}.
429 The command provides the obvious install, remove, and upgrade
430 operations. Each invocation is actually a @emph{transaction}: either
431 the specified operation succeeds, or nothing happens. Thus, if the
432 @command{guix package} process is terminated during the transaction,
433 or if a power outage occurs during the transaction, then the user's
434 profile remains in its previous state, and remains usable.
436 In addition, any package transaction may be @emph{rolled back}. So, if,
437 for example, an upgrade installs a new version of a package that turns
438 out to have a serious bug, users may roll back to the previous instance
439 of their profile, which was known to work well.
441 All those packages in the package store may be @emph{garbage-collected}.
442 Guix can determine which packages are still referenced by the user
443 profiles, and remove those that are provably no longer referenced
444 (@pxref{Invoking guix gc}). Users may also explicitly remove old
445 generations of their profile so that the packages they refer to can be
448 Finally, Guix takes a @dfn{purely functional} approach to package
449 management, as described in the introduction (@pxref{Introduction}).
450 Each @file{/nix/store} package directory name contains a hash of all the
451 inputs that were used to build that package---compiler, libraries, build
452 scripts, etc. This direct correspondence allows users to make sure a
453 given package installation matches the current state of their
454 distribution, and helps maximize @dfn{reproducibility}.
456 This foundation allows Guix to support @dfn{transparent binary/source
457 deployment}. When a pre-built binary for a @file{/nix/store} path is
458 available from an external source, Guix just downloads it; otherwise, it
459 builds the package from source, locally.
461 @node Invoking guix package
462 @section Invoking @command{guix package}
464 The @command{guix package} command is the tool that allows users to
465 install, upgrade, and remove packages, as well as rolling back to
466 previous configurations. It operates only on the user's own profile,
467 and works with normal user privileges (@pxref{Features}). Its syntax
471 guix package @var{options}
474 Primarily, @var{options} specifies the operations to be performed during
475 the transaction. Upon completion, a new profile is created, but
476 previous generations of the profile remain available, should the user
479 For each user, a symlink to the user's default profile is automatically
480 created in @file{$HOME/.guix-profile}. This symlink always points to the
481 current generation of the user's default profile. Thus, users can add
482 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
485 In a multi-user setup, user profiles must be stored in a place
486 registered as a @dfn{garbage-collector root}, which
487 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
488 directory is normally
489 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
490 @var{localstatedir} is the value passed to @code{configure} as
491 @code{--localstatedir}, and @var{user} is the user name. It must be
492 created by @code{root}, with @var{user} as the owner. When it does not
493 exist, @command{guix package} emits an error about it.
495 The @var{options} can be among the following:
499 @item --install=@var{package}
500 @itemx -i @var{package}
501 Install @var{package}.
503 @var{package} may specify either a simple package name, such as
504 @code{guile}, or a package name followed by a hyphen and version number,
505 such as @code{guile-1.8.8}. If no version number is specified, the
506 newest available version will be selected. In addition, @var{package}
507 may contain a colon, followed by the name of one of the outputs of the
508 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}.
510 @cindex propagated inputs
511 Sometimes packages have @dfn{propagated inputs}: these are dependencies
512 that automatically get installed along with the required package.
514 An example is the GNU MPC library: its C header files refer to those of
515 the GNU MPFR library, which in turn refer to those of the GMP library.
516 Thus, when installing MPC, the MPFR and GMP libraries also get installed
517 in the profile; removing MPC also removes MPFR and GMP---unless they had
518 also been explicitly installed independently.
520 Besides, packages sometime rely on the definition of environment
521 variables for their search paths (see explanation of
522 @code{--search-paths} below.) Any missing or possibly incorrect
523 environment variable definitions are reported here.
525 @c XXX: keep me up-to-date
526 Finally, when installing a GNU package, the tool reports the
527 availability of a newer upstream version. In the future, it may provide
528 the option of installing directly from the upstream version, even if
529 that version is not yet in the distribution.
531 @item --install-from-expression=@var{exp}
533 Install the package @var{exp} evaluates to.
535 @var{exp} must be a Scheme expression that evaluates to a
536 @code{<package>} object. This option is notably useful to disambiguate
537 between same-named variants of a package, with expressions such as
538 @code{(@@ (gnu packages base) guile-final)}.
540 Note that this option installs the first output of the specified
541 package, which may be insufficient when needing a specific output of a
542 multiple-output package.
544 @item --remove=@var{package}
545 @itemx -r @var{package}
546 Remove @var{package}.
548 @item --upgrade[=@var{regexp}]
549 @itemx -u [@var{regexp}]
550 Upgrade all the installed packages. When @var{regexp} is specified, upgrade
551 only installed packages whose name matches @var{regexp}.
553 Note that this upgrades package to the latest version of packages found
554 in the distribution currently installed. To update your distribution,
555 you should regularly run @command{guix pull} (@pxref{Invoking guix
559 Roll back to the previous @dfn{generation} of the profile---i.e., undo
560 the last transaction.
562 When combined with options such as @code{--install}, roll back occurs
563 before any other actions.
565 When rolling back from the first generation that actually contains
566 installed packages, the profile is made to point to the @dfn{empty
567 profile}, also known as @dfn{profile zero}---i.e., it contains no files
568 apart from its own meta-data.
570 Installing, removing, or upgrading packages from a generation that has
571 been rolled back to overwrites previous future generations. Thus, the
572 history of a profile's generations is always linear.
576 Report environment variable definitions, in Bash syntax, that may be
577 needed in order to use the set of installed packages. These environment
578 variables are used to specify @dfn{search paths} for files used by some
579 of the installed packages.
581 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
582 environment variables to be defined so it can look for headers and
583 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
584 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
585 library are installed in the profile, then @code{--search-paths} will
586 suggest setting these variables to @code{@var{profile}/include} and
587 @code{@var{profile}/lib}, respectively.
589 @item --profile=@var{profile}
590 @itemx -p @var{profile}
591 Use @var{profile} instead of the user's default profile.
595 Show what would be done without actually doing it.
597 @item --no-substitutes
598 Build instead of resorting to pre-built substitutes.
601 Produce verbose output. In particular, emit the environment's build log
602 on the standard error port.
605 Use the bootstrap Guile to build the profile. This option is only
606 useful to distribution developers.
610 In addition to these actions @command{guix package} supports the
611 following options to query the current state of a profile, or the
612 availability of packages:
616 @item --search=@var{regexp}
617 @itemx -s @var{regexp}
618 List the available packages whose synopsis or description matches
619 @var{regexp}. Print all the meta-data of matching packages in
620 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
621 GNU recutils manual}).
623 This allows specific fields to be extracted using the @command{recsel}
624 command, for instance:
627 $ guix package -s malloc | recsel -p name,version
635 @item --list-installed[=@var{regexp}]
636 @itemx -I [@var{regexp}]
637 List currently installed packages in the specified profile. When
638 @var{regexp} is specified, list only installed packages whose name
639 matches @var{regexp}.
641 For each installed package, print the following items, separated by
642 tabs: the package name, its version string, the part of the package that
643 is installed (for instance, @code{out} for the default output,
644 @code{include} for its headers, etc.), and the path of this package in
647 @item --list-available[=@var{regexp}]
648 @itemx -A [@var{regexp}]
649 List packages currently available in the software distribution
650 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
651 installed packages whose name matches @var{regexp}.
653 For each package, print the following items separated by tabs: its name,
654 its version string, the parts of the package (@code{out} for the main
655 files, @code{lib} for libraries and possibly headers, etc.), and the
656 source location of its definition.
661 @node Invoking guix gc
662 @section Invoking @command{guix gc}
664 @cindex garbage collector
665 Packages that are installed but not used may be @dfn{garbage-collected}.
666 The @command{guix gc} command allows users to explicitly run the garbage
667 collector to reclaim space from the @file{/nix/store} directory.
669 The garbage collector has a set of known @dfn{roots}: any file under
670 @file{/nix/store} reachable from a root is considered @dfn{live} and
671 cannot be deleted; any other file is considered @dfn{dead} and may be
672 deleted. The set of garbage collector roots includes default user
673 profiles, and may be augmented with @command{guix build --root}, for
674 example (@pxref{Invoking guix build}).
676 The @command{guix gc} command has three modes of operation: it can be
677 used to garbage-collect any dead files (the default), to delete specific
678 files (the @code{--delete} option), or to print garbage-collector
679 information. The available options are listed below:
682 @item --collect-garbage[=@var{min}]
683 @itemx -C [@var{min}]
684 Collect garbage---i.e., unreachable @file{/nix/store} files and
685 sub-directories. This is the default operation when no option is
688 When @var{min} is given, stop once @var{min} bytes have been collected.
689 @var{min} may be a number of bytes, or it may include a unit as a
690 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
692 When @var{min} is omitted, collect all the garbage.
696 Attempt to delete all the store files and directories specified as
697 arguments. This fails if some of the files are not in the store, or if
701 Show the list of dead files and directories still present in the
702 store---i.e., files and directories no longer reachable from any root.
705 Show the list of live store files and directories.
709 In addition, the references among existing store files can be queried:
715 List the references (respectively, the referrers) of store files given
721 @node Invoking guix pull
722 @section Invoking @command{guix pull}
724 Packages are installed or upgraded to the latest version available in
725 the distribution currently available on your local machine. To update
726 that distribution, along with the Guix tools, you must run @command{guix
727 pull}: the command downloads the latest Guix source code and package
728 descriptions, and deploys it.
730 On completion, @command{guix package} will use packages and package
731 versions from this just-retrieved copy of Guix. Not only that, but all
732 the Guix commands and Scheme modules will also be taken from that latest
733 version. New @command{guix} sub-commands added by the update also
736 The @command{guix pull} command is usually invoked with no arguments,
737 but it supports the following options:
741 Produce verbose output, writing build logs to the standard error output.
744 Use the bootstrap Guile to build the latest Guix. This option is only
745 useful to Guix developers.
748 @c *********************************************************************
749 @node Programming Interface
750 @chapter Programming Interface
752 GNU Guix provides several Scheme programming interfaces (APIs) to
753 define, build, and query packages. The first interface allows users to
754 write high-level package definitions. These definitions refer to
755 familiar packaging concepts, such as the name and version of a package,
756 its build system, and its dependencies. These definitions can then be
757 turned into concrete build actions.
759 Build actions are performed by the Guix daemon, on behalf of users. In a
760 standard setup, the daemon has write access to the store---the
761 @file{/nix/store} directory---whereas users do not. The recommended
762 setup also has the daemon perform builds in chroots, under a specific
763 build users, to minimize interference with the rest of the system.
766 Lower-level APIs are available to interact with the daemon and the
767 store. To instruct the daemon to perform a build action, users actually
768 provide it with a @dfn{derivation}. A derivation is a low-level
769 representation of the build actions to be taken, and the environment in
770 which they should occur---derivations are to package definitions what
771 assembly is to C programs.
773 This chapter describes all these APIs in turn, starting from high-level
777 * Defining Packages:: Defining new packages.
778 * The Store:: Manipulating the package store.
779 * Derivations:: Low-level interface to package derivations.
782 @node Defining Packages
783 @section Defining Packages
785 The high-level interface to package definitions is implemented in the
786 @code{(guix packages)} and @code{(guix build-system)} modules. As an
787 example, the package definition, or @dfn{recipe}, for the GNU Hello
788 package looks like this:
791 (use-modules (guix packages)
793 (guix build-system gnu)
802 (uri (string-append "mirror://gnu/hello/hello-" version
805 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
806 (build-system gnu-build-system)
807 (inputs `(("gawk" ,gawk)))
808 (synopsis "GNU Hello")
809 (description "Yeah...")
810 (home-page "http://www.gnu.org/software/hello/")
815 Without being a Scheme expert, the reader may have guessed the meaning
816 of the various fields here. This expression binds variable @var{hello}
817 to a @code{<package>} object, which is essentially a record
818 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
819 This package object can be inspected using procedures found in the
820 @code{(guix packages)} module; for instance, @code{(package-name hello)}
821 returns---surprise!---@code{"hello"}.
823 There are a few points worth noting in the above package definition:
827 The @code{source} field of the package is an @code{<origin>} object.
828 Here, the @code{url-fetch} method from @code{(guix download)} is used,
829 meaning that the source is a file to be downloaded over FTP or HTTP.
831 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
832 the GNU mirrors defined in @code{(guix download)}.
834 The @code{sha256} field specifies the expected SHA256 hash of the file
835 being downloaded. It is mandatory, and allows Guix to check the
836 integrity of the file. The @code{(base32 @dots{})} form introduces the
837 base32 representation of the hash. You can obtain this information with
838 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
839 hash} (@pxref{Invoking guix hash}).
842 @cindex GNU Build System
843 The @code{build-system} field is set to @var{gnu-build-system}. The
844 @var{gnu-build-system} variable is defined in the @code{(guix
845 build-system gnu)} module, and is bound to a @code{<build-system>}
848 Naturally, @var{gnu-build-system} represents the familiar GNU Build
849 System, and variants thereof (@pxref{Configuration, configuration and
850 makefile conventions,, standards, GNU Coding Standards}). In a
851 nutshell, packages using the GNU Build System may be configured, built,
852 and installed with the usual @code{./configure && make && make check &&
853 make install} command sequence. This is what @var{gnu-build-system}
856 In addition, @var{gnu-build-system} ensures that the ``standard''
857 environment for GNU packages is available. This includes tools such as
858 GCC, Coreutils, Bash, Make, Diffutils, and Patch.
861 The @code{inputs} field specifies inputs to the build process---i.e.,
862 build-time or run-time dependencies of the package. Here, we define an
863 input called @code{"gawk"} whose value is that of the @var{gawk}
864 variable; @var{gawk} is itself bound to a @code{<package>} object.
866 Note that GCC, Coreutils, Bash, and other essential tools do not need to
867 be specified as inputs here. Instead, @var{gnu-build-system} takes care
868 of ensuring that they are present.
870 However, any other dependencies need to be specified in the
871 @code{inputs} field. Any dependency not specified here will simply be
872 unavailable to the build process, possibly leading to a build failure.
875 There are other fields that package definitions may provide. Of
876 particular interest is the @code{arguments} field. When specified, it
877 must be bound to a list of additional arguments to be passed to the
878 build system. For instance, the above definition could be augmented
879 with the following field initializer:
882 (arguments `(#:tests? #f
883 #:configure-flags '("--enable-silent-rules")))
887 These are keyword arguments (@pxref{Optional Arguments, keyword
888 arguments in Guile,, guile, GNU Guile Reference Manual}). They are
889 passed to @var{gnu-build-system}, which interprets them as meaning ``do
890 not run @code{make check}'', and ``run @file{configure} with the
891 @code{--enable-silent-rules} flag''. The value of these keyword
892 parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
893 Guile process launched by the daemon (@pxref{Derivations}).
895 Once a package definition is in place@footnote{Simple package
896 definitions like the one above may be automatically converted from the
897 Nixpkgs distribution using the @command{guix import} command.}, the
898 package may actually be built using the @code{guix build} command-line
899 tool (@pxref{Invoking guix build}). Eventually, updating the package
900 definition to a new upstream version can be partly automated by the
901 @command{guix refresh} command (@pxref{Invoking guix refresh}).
903 Behind the scenes, a derivation corresponding to the @code{<package>}
904 object is first computed by the @code{package-derivation} procedure.
905 That derivation is stored in a @code{.drv} file under @file{/nix/store}.
906 The build actions it prescribes may then be realized by using the
907 @code{build-derivations} procedure (@pxref{The Store}).
909 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
910 Return the derivation path and corresponding @code{<derivation>} object
911 of @var{package} for @var{system} (@pxref{Derivations}).
913 @var{package} must be a valid @code{<package>} object, and @var{system}
914 must be a string denoting the target system type---e.g.,
915 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
916 must be a connection to the daemon, which operates on the store
926 Conceptually, the @dfn{store} is where derivations that have been
927 successfully built are stored---by default, under @file{/nix/store}.
928 Sub-directories in the store are referred to as @dfn{store paths}. The
929 store has an associated database that contains information such has the
930 store paths referred to by each store path, and the list of @emph{valid}
931 store paths---paths that result from a successful build.
933 The store is always accessed by the daemon on behalf of its clients
934 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
935 connect to the daemon over a Unix-domain socket, send it requests, and
936 read the result---these are remote procedure calls, or RPCs.
938 The @code{(guix store)} module provides procedures to connect to the
939 daemon, and to perform RPCs. These are described below.
941 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
942 Connect to the daemon over the Unix-domain socket at @var{file}. When
943 @var{reserve-space?} is true, instruct it to reserve a little bit of
944 extra space on the file system so that the garbage collector can still
945 operate, should the disk become full. Return a server object.
947 @var{file} defaults to @var{%default-socket-path}, which is the normal
948 location given the options that were passed to @command{configure}.
951 @deffn {Scheme Procedure} close-connection @var{server}
952 Close the connection to @var{server}.
955 @defvr {Scheme Variable} current-build-output-port
956 This variable is bound to a SRFI-39 parameter, which refers to the port
957 where build and error logs sent by the daemon should be written.
960 Procedures that make RPCs all take a server object as their first
963 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
964 Return @code{#t} when @var{path} is a valid store path.
967 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references}
968 Add @var{text} under file @var{name} in the store, and return its store
969 path. @var{references} is the list of store paths referred to by the
970 resulting store path.
973 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
974 Build @var{derivations} (a list of derivation paths), and return when
975 the worker is done building them. Return @code{#t} on success.
979 @i{This section is currently incomplete.}
985 Low-level build actions and the environment in which they are performed
986 are represented by @dfn{derivations}. A derivation contain the
987 following pieces of information:
991 The outputs of the derivation---derivations produce at least one file or
992 directory in the store, but may produce more.
995 The inputs of the derivations, which may be other derivations or plain
996 files in the store (patches, build scripts, etc.)
999 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1002 The file name of a build script in the store, along with the arguments
1006 A list of environment variables to be defined.
1010 @cindex derivation path
1011 Derivations allow clients of the daemon to communicate build actions to
1012 the store. They exist in two forms: as an in-memory representation,
1013 both on the client- and daemon-side, and as files in the store whose
1014 name end in @code{.drv}---these files are referred to as @dfn{derivation
1015 paths}. Derivations paths can be passed to the @code{build-derivations}
1016 procedure to perform the build actions they prescribe (@pxref{The
1019 The @code{(guix derivations)} module provides a representation of
1020 derivations as Scheme objects, along with procedures to create and
1021 otherwise manipulate derivations. The lowest-level primitive to create
1022 a derivation is the @code{derivation} procedure:
1024 @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]
1025 Build a derivation with the given arguments. Return the resulting store
1026 path and @code{<derivation>} object.
1028 When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
1029 @dfn{fixed-output derivation} is created---i.e., one whose result is
1030 known in advance, such as a file download.
1034 Here's an example with a shell script as its builder, assuming
1035 @var{store} is an open connection to the daemon, and @var{bash} points
1036 to a Bash executable in the store:
1039 (use-modules (guix utils)
1045 (let ((builder ; add the Bash script to the store
1046 (add-text-to-store store "my-builder.sh"
1047 "echo hello world > $out\n" '())))
1048 (derivation store "foo" (%current-system)
1049 bash `("-e" ,builder)
1050 '(("HOME" . "/homeless")) '())))
1052 @result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>)
1055 As can be guessed, this primitive is cumbersome to use directly. An
1056 improved variant is @code{build-expression->derivation}, which allows
1057 the caller to directly pass a Guile expression as the build script:
1059 @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]
1060 Return a derivation that executes Scheme expression @var{exp} as a
1061 builder for derivation @var{name}. @var{inputs} must be a list of
1062 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1063 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1064 modules from the current search path to be copied in the store,
1065 compiled, and made available in the load path during the execution of
1066 @var{exp}---e.g., @code{((guix build utils) (guix build
1067 gnu-build-system))}.
1069 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1070 to a list of output/path pairs, and where @code{%build-inputs} is bound
1071 to a list of string/output-path pairs made from @var{inputs}.
1072 Optionally, @var{env-vars} is a list of string pairs specifying the name
1073 and value of environment variables visible to the builder. The builder
1074 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1075 @var{exp} returns @code{#f}, the build is considered to have failed.
1077 @var{exp} is built using @var{guile-for-build} (a derivation). When
1078 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1079 @code{%guile-for-build} fluid is used instead.
1083 Here's an example of a single-output derivation that creates a directory
1084 containing one file:
1087 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1088 (mkdir out) ; create /nix/store/@dots{}-goo
1089 (call-with-output-file (string-append out "/test")
1091 (display '(hello guix) p))))))
1092 (build-expression->derivation store "goo" (%current-system)
1095 @result{} "/nix/store/@dots{}-goo.drv"
1096 @result{} #<<derivation> @dots{}>
1099 @cindex strata of code
1100 Remember that the build expression passed to
1101 @code{build-expression->derivation} is run by a separate Guile process
1102 than the one that calls @code{build-expression->derivation}: it is run
1103 by a Guile process launched by the daemon, typically in a chroot. So,
1104 while there is a single language for both the @dfn{host} and the build
1105 side, there are really two @dfn{strata} of code: the host-side, and the
1106 build-side code@footnote{The term @dfn{stratum} in this context was
1107 coined by Manuel Serrano et al. in the context of their work on Hop.}.
1108 This distinction is important to keep in mind, notably when using
1109 higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
1110 Packages}). For this reason, Guix modules that are meant to be used in
1111 the build stratum are kept in the @code{(guix build @dots{})} name
1114 @c *********************************************************************
1118 This section describes tools primarily targeted at developers and users
1119 who write new package definitions. They complement the Scheme
1120 programming interface of Guix in a convenient way.
1123 * Invoking guix build:: Building packages from the command line.
1124 * Invoking guix download:: Downloading a file and printing its hash.
1125 * Invoking guix hash:: Computing the cryptographic hash of a file.
1126 * Invoking guix refresh:: Updating package definitions.
1129 @node Invoking guix build
1130 @section Invoking @command{guix build}
1132 The @command{guix build} command builds packages or derivations and
1133 their dependencies, and prints the resulting store paths. Note that it
1134 does not modify the user's profile---this is the job of the
1135 @command{guix package} command (@pxref{Invoking guix package}). Thus,
1136 it is mainly useful for distribution developers.
1138 The general syntax is:
1141 guix build @var{options} @var{package-or-derivation}@dots{}
1144 @var{package-or-derivation} may be either the name of a package found in
1145 the software distribution such as @code{coreutils} or
1146 @code{coreutils-8.20}, or a derivation such as
1147 @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
1148 @code{--expression} option may be used to specify a Scheme expression
1149 that evaluates to a package; this is useful when disambiguation among
1150 several same-named packages or package variants is needed.
1152 The @var{options} may be zero or more of the following:
1156 @item --expression=@var{expr}
1157 @itemx -e @var{expr}
1158 Build the package @var{expr} evaluates to.
1160 For example, @var{expr} may be @code{(@@ (gnu packages guile)
1161 guile-1.8)}, which unambiguously designates this specific variant of
1162 version 1.8 of Guile.
1166 Build the packages' source derivations, rather than the packages
1169 For instance, @code{guix build -S gcc} returns something like
1170 @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
1172 @item --system=@var{system}
1173 @itemx -s @var{system}
1174 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
1175 the host's system type.
1177 An example use of this is on Linux-based systems, which can emulate
1178 different personalities. For instance, passing
1179 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
1180 to build packages in a complete 32-bit environment.
1184 Return the derivation paths, not the output paths, of the given
1189 Keep the build tree of failed builds. Thus, if a build fail, its build
1190 tree is kept under @file{/tmp}, in a directory whose name is shown at
1191 the end of the build log. This is useful when debugging build issues.
1195 Do not build the derivations.
1197 @item --no-substitutes
1198 Build instead of resorting to pre-built substitutes.
1200 @item --cores=@var{n}
1202 Allow the use of up to @var{n} CPU cores for the build. The special
1203 value @code{0} means to use as many CPU cores as available.
1205 @item --root=@var{file}
1206 @itemx -r @var{file}
1207 Make @var{file} a symlink to the result, and register it as a garbage
1210 @item --verbosity=@var{level}
1211 Use the given verbosity level. @var{level} must be an integer between 0
1212 and 5; higher means more verbose output. Setting a level of 4 or more
1213 may be helpful when debugging setup issues with the build daemon.
1217 Behind the scenes, @command{guix build} is essentially an interface to
1218 the @code{package-derivation} procedure of the @code{(guix packages)}
1219 module, and to the @code{build-derivations} procedure of the @code{(guix
1222 @node Invoking guix download
1223 @section Invoking @command{guix download}
1225 When writing a package definition, developers typically need to download
1226 the package's source tarball, compute its SHA256 hash, and write that
1227 hash in the package definition (@pxref{Defining Packages}). The
1228 @command{guix download} tool helps with this task: it downloads a file
1229 from the given URI, adds it to the store, and prints both its file name
1230 in the store and its SHA256 hash.
1232 The fact that the downloaded file is added to the store saves bandwidth:
1233 when the developer eventually tries to build the newly defined package
1234 with @command{guix build}, the source tarball will not have to be
1235 downloaded again because it is already in the store. It is also a
1236 convenient way to temporarily stash files, which may be deleted
1237 eventually (@pxref{Invoking guix gc}).
1239 The @command{guix download} command supports the same URIs as used in
1240 package definitions. In particular, it supports @code{mirror://} URIs.
1241 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
1242 Guile bindings for GnuTLS are available in the user's environment; when
1243 they are not available, an error is raised.
1245 The following option is available:
1248 @item --format=@var{fmt}
1250 Write the hash in the format specified by @var{fmt}. For more
1251 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
1254 @node Invoking guix hash
1255 @section Invoking @command{guix hash}
1257 The @command{guix hash} command computes the SHA256 hash of a file.
1258 It is primarily a convenience tool for anyone contributing to the
1259 distribution: it computes the cryptographic hash of a file, which can be
1260 used in the definition of a package (@pxref{Defining Packages}).
1262 The general syntax is:
1265 guix hash @var{option} @var{file}
1268 @command{guix hash} has the following option:
1272 @item --format=@var{fmt}
1274 Write the hash in the format specified by @var{fmt}.
1276 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
1277 (@code{hex} and @code{hexadecimal} can be used as well).
1279 If the @option{--format} option is not specified, @command{guix hash}
1280 will output the hash in @code{nix-base32}. This representation is used
1281 in the definitions of packages.
1285 @node Invoking guix refresh
1286 @section Invoking @command{guix refresh}
1288 The primary audience of the @command{guix refresh} command is developers
1289 of the GNU software distribution. By default, it reports any packages
1290 provided by the distribution that are outdated compared to the latest
1291 upstream version, like this:
1295 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
1296 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
1299 It does so by browsing each package's FTP directory and determining the
1300 highest version number of the source tarballs
1301 therein@footnote{Currently, this only works for GNU packages.}.
1303 When passed @code{--update}, it modifies distribution source files to
1304 update the version numbers and source tarball hashes of those packages'
1305 recipes (@pxref{Defining Packages}). This is achieved by downloading
1306 each package's latest source tarball and its associated OpenPGP
1307 signature, authenticating the downloaded tarball against its signature
1308 using @command{gpg}, and finally computing its hash. When the public
1309 key used to sign the tarball is missing from the user's keyring, an
1310 attempt is made to automatically retrieve it from a public key server;
1311 when it's successful, the key is added to the user's keyring; otherwise,
1312 @command{guix refresh} reports an error.
1314 The following options are supported:
1320 Update distribution source files (package recipes) in place.
1321 @ref{Defining Packages}, for more information on package definitions.
1323 @item --select=[@var{subset}]
1324 @itemx -s @var{subset}
1325 Select all the packages in @var{subset}, one of @code{core} or
1328 The @code{core} subset refers to all the packages at the core of the
1329 distribution---i.e., packages that are used to build ``everything
1330 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
1331 changing one of these packages in the distribution entails a rebuild of
1332 all the others. Thus, such updates are an inconvenience to users in
1333 terms of build time or bandwidth used to achieve the upgrade.
1335 The @code{non-core} subset refers to the remaining packages. It is
1336 typically useful in cases where an update of the core packages would be
1341 In addition, @command{guix refresh} can be passed one or more package
1342 names, as in this example:
1345 guix refresh -u emacs idutils
1349 The command above specifically updates the @code{emacs} and
1350 @code{idutils} packages. The @code{--select} option would have no
1351 effect in this case.
1353 The following options can be used to customize GnuPG operation:
1357 @item --key-server=@var{host}
1358 Use @var{host} as the OpenPGP key server when importing a public key.
1360 @item --gpg=@var{command}
1361 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
1362 for in @code{$PATH}.
1367 @c *********************************************************************
1368 @node GNU Distribution
1369 @chapter GNU Distribution
1371 Guix comes with a distribution of free software@footnote{The term
1372 ``free'' here refers to the
1373 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
1374 users of that software}.} that form the basis of the GNU system. This
1375 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
1376 as many GNU and non-GNU applications. The complete list of available
1377 packages can be seen by running @command{guix package} (@pxref{Invoking
1381 guix package --list-available
1384 The package definitions of the distribution may are provided by Guile
1385 modules in the @code{(gnu packages ...)} name space---for instance, the
1386 @code{(gnu packages emacs)} module exports a variable named
1387 @code{emacs}, which is bound to a @code{<package>} object
1388 (@pxref{Defining Packages}). The @code{(gnu packages)} module provides
1389 facilities for searching for packages.
1391 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
1392 each package is built based solely on other packages in the
1393 distribution. The root of this dependency graph is a small set of
1394 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
1395 bootstrap)} module. These are statically-linked binaries of the core
1396 tools without which building anything at all would be impossible.
1399 Our goal is to build a practical 100% free software distribution of
1400 Linux-based and other variants of GNU, with a focus on the promotion and
1401 tight integration of GNU components, and an emphasis on programs and
1402 tools that help users exert that freedom.
1404 Building this distribution is a cooperative effort, and you are invited
1405 to join! Please get in touch with us on @email{bug-guix@@gnu.org}. We
1406 welcome ideas, bug reports, patches, and anything that may be helpful to
1410 @c *********************************************************************
1411 @node Acknowledgments
1412 @chapter Acknowledgments
1414 Guix is based on the Nix package manager, which was designed and
1415 implemented by Eelco Dolstra. Nix pioneered functional package
1416 management, and promoted unprecedented features, such as transactional
1417 package upgrades and rollbacks, per-user profiles, and referentially
1418 transparent build processes. Without this work, Guix would not exist.
1420 The Nix-based software distributions, Nixpkgs and NixOS, have also been
1421 an inspiration for Guix.
1423 @c *********************************************************************
1424 @node GNU Free Documentation License
1425 @appendix GNU Free Documentation License
1427 @include fdl-1.3.texi
1429 @c *********************************************************************
1431 @unnumbered Concept Index
1434 @node Function Index
1435 @unnumbered Function Index
1441 @c ispell-local-dictionary: "american";