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
27 @author Nikita Karetnikov
30 @vskip 0pt plus 1filll
31 Edition @value{EDITION} @*
34 Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.3 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
42 copy of the license is included in the section entitled ``GNU Free
43 Documentation License''.
50 This manual documents GNU Guix version @value{VERSION}.
52 Copyright @copyright{} @value{YEARS} Ludovic Courtès
54 Permission is granted to copy, distribute and/or modify this document
55 under the terms of the GNU Free Documentation License, Version 1.3 or
56 any later version published by the Free Software Foundation; with no
57 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
58 copy of the license is included in the section entitled ``GNU Free
59 Documentation License.''
64 @c *********************************************************************
68 This document describes GNU Guix version @value{VERSION}, a functional
69 package management tool written for the GNU system.
73 Copyright @copyright{} @value{YEARS} Ludovic Courtès, Andreas Enge, Nikita Karetnikov
75 Permission is granted to copy, distribute and/or modify this document
76 under the terms of the GNU Free Documentation License, Version 1.3 or
77 any later version published by the Free Software Foundation; with no
78 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
79 copy of the license is included in the section entitled ``GNU Free
80 Documentation License.''
84 * Introduction:: What is Guix about?
85 * Installation:: Installing Guix.
86 * Package Management:: Package installation, upgrade, etc.
87 * Programming Interface:: Using Guix in Scheme.
88 * Utilities:: Package management commands.
89 * GNU Distribution:: Software for your friendly GNU system.
90 * Contributing:: Your help needed!
92 * Acknowledgments:: Thanks!
93 * GNU Free Documentation License:: The license of this manual.
94 * Concept Index:: Concepts.
95 * Function Index:: Functions.
98 @c *********************************************************************
100 @chapter Introduction
102 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
103 using the international phonetic alphabet (IPA).} is a functional
104 package management tool for the GNU system. Package management consists
105 of all activities that relate to building packages from sources,
106 honoring their build-time and run-time dependencies,
107 installing packages in user environments, upgrading installed packages
108 to new versions or rolling back to a previous set, removing unused
109 software packages, etc.
111 @cindex functional package management
112 The term @dfn{functional} refers to a specific package management
113 discipline. In Guix, the package build and installation process is seen
114 as a function, in the mathematical sense. That function takes inputs,
115 such as build scripts, a compiler, and libraries, and
116 returns an installed package. As a pure function, its result depends
117 solely on its inputs---for instance, it cannot refer to software or
118 scripts that were not explicitly passed as inputs. A build function
119 always produces the same result when passed a given set of inputs. It
120 cannot alter the system's environment in
121 any way; for instance, it cannot create, modify, or delete files outside
122 of its build and installation directories. This is achieved by running
123 build processes in isolated environments (or @dfn{chroots}), where only their
124 explicit inputs are visible.
127 The result of package build functions is @dfn{cached} in the file
128 system, in a special directory called @dfn{the store} (@pxref{The
129 Store}). Each package is installed in a directory of its own, in the
130 store---by default under @file{/nix/store}. The directory name contains
131 a hash of all the inputs used to build that package; thus, changing an
132 input yields a different directory name.
134 This approach is the foundation of Guix's salient features: support for
135 transactional package upgrade and rollback, per-user installation, and
136 garbage collection of packages (@pxref{Features}).
138 Guix has a command-line interface, which allows users to build, install,
139 upgrade, and remove packages, as well as a Scheme programming interface.
141 Last but not least, Guix is used to build a distribution of the GNU
142 system, with many GNU and non-GNU free software packages. @xref{GNU
145 @c *********************************************************************
147 @chapter Installation
149 GNU Guix is available for download from its website at
150 @url{http://www.gnu.org/software/guix/}. This section describes the
151 software requirements of Guix, as well as how to install it and get
154 The build procedure for Guix is the same as for other GNU software, and
155 is not covered here. Please see the files @file{README} and
156 @file{INSTALL} in the Guix source tree for additional details.
159 * Requirements:: Software needed to build and run Guix.
160 * Setting Up the Daemon:: Preparing the build daemon's environment.
161 * Invoking guix-daemon:: Running the build daemon.
165 @section Requirements
167 GNU Guix depends on the following packages:
170 @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.5 or later;
171 @item @url{http://gnupg.org/, GNU libgcrypt}
174 Unless @code{--disable-daemon} was passed to @command{configure}, the
175 following packages are also needed:
178 @item @url{http://sqlite.org, SQLite 3}
179 @item @url{http://www.bzip.org, libbz2}
180 @item @url{http://gcc.gnu.org, GCC's g++}
183 When a working installation of @url{http://nixos.org/nix/, the Nix package
184 manager} is available, you
185 can instead configure Guix with @code{--disable-daemon}. In that case,
186 Nix replaces the three dependencies above.
188 Guix is compatible with Nix, so it is possible to share the same store
189 between both. To do so, you must pass @command{configure} not only the
190 same @code{--with-store-dir} value, but also the same
191 @code{--localstatedir} value. The latter is essential because it
192 specifies where the database that stores metadata about the store is
193 located, among other things. The default values are
194 @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
195 Note that @code{--disable-daemon} is not required if
196 your goal is to share the store with Nix.
198 @node Setting Up the Daemon
199 @section Setting Up the Daemon
202 Operations such as building a package or running the garbage collector
203 are all performed by a specialized process, the @dfn{Guix daemon}, on
204 behalf of clients. Only the daemon may access the store and its
205 associated database. Thus, any operation that manipulates the store
206 goes through the daemon. For instance, command-line tools such as
207 @command{guix package} and @command{guix build} communicate with the
208 daemon (@i{via} remote procedure calls) to instruct it what to do.
210 In a standard multi-user setup, Guix and its daemon---the
211 @command{guix-daemon} program---are installed by the system
212 administrator; @file{/nix/store} is owned by @code{root} and
213 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
214 Guix tools to build packages or otherwise access the store, and the
215 daemon will do it on their behalf, ensuring that the store is kept in a
216 consistent state, and allowing built packages to be shared among users.
219 When @command{guix-daemon} runs as @code{root}, you may not want package
220 build processes themselves to run as @code{root} too, for obvious
221 security reasons. To avoid that, a special pool of @dfn{build users}
222 should be created for use by build processes started by the daemon.
223 These build users need not have a shell and a home directory: they will
224 just be used when the daemon drops @code{root} privileges in build
225 processes. Having several such users allows the daemon to launch
226 distinct build processes under separate UIDs, which guarantees that they
227 do not interfere with each other---an essential feature since builds are
228 regarded as pure functions (@pxref{Introduction}).
230 On a GNU/Linux system, a build user pool may be created like this (using
231 Bash syntax and the @code{shadow} commands):
233 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
234 @c for why `-G' is needed.
236 # groupadd guix-builder
237 # for i in `seq 1 10`;
239 useradd -g guix-builder -G guix-builder \
240 -d /var/empty -s `which nologin` \
241 -c "Guix build user $i" guix-builder$i;
246 The @code{guix-daemon} program may then be run as @code{root} with:
249 # guix-daemon --build-users-group=guix-builder
253 This way, the daemon starts build processes in a chroot, under one of
254 the @code{guix-builder} users. On GNU/Linux, by default, the chroot
255 environment contains nothing but the @code{/dev} and @code{/proc}
256 directories@footnote{On some systems @code{/dev/shm}, which supports
257 shared memory, is a symlink to another directory such as
258 @code{/run/shm}, that is @emph{not} is the chroot. When that is the
259 case, shared memory support is unavailable in the chroot environment.
260 The workaround is to make sure that @file{/dev/shm} is directly a
261 @code{tmpfs} mount point.}.
263 Guix may also be used in a single-user setup, with @command{guix-daemon}
264 running as an unprivileged user. However, to maximize non-interference
265 of build processes, the daemon still needs to perform certain operations
266 that are restricted to @code{root} on GNU/Linux: it should be able to
267 run build processes in a chroot, and to run them under different UIDs.
268 To that end, the @command{nix-setuid-helper} program is provided; it is
269 a small C program (less than 300 lines) that, if it is made setuid
270 @code{root}, can be executed by the daemon to perform these operations
271 on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file
272 is read by @command{nix-setuid-helper}; it should contain exactly two
273 words: the user name under which the authorized @command{guix-daemon}
274 runs, and the name of the build users group.
276 If you are installing Guix as an unprivileged user and do not have the
277 ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still
278 possible to run @command{guix-daemon}. However, build processes will
279 not be isolated from one another, and not from the rest of the system.
280 Thus, build processes may interfere with each other, and may access
281 programs, libraries, and other files available on the system---making it
282 much harder to view them as @emph{pure} functions.
284 @node Invoking guix-daemon
285 @section Invoking @command{guix-daemon}
287 The @command{guix-daemon} program implements all the functionality to
288 access the store. This includes launching build processes, running the
289 garbage collector, querying the availability of a build result, etc. It
290 is normally run as @code{root} like this:
293 # guix-daemon --build-users-group=guix-builder
297 For details on how to set it up, @ref{Setting Up the Daemon}.
299 By default, @command{guix-daemon} launches build processes under
300 different UIDs, taken from the build group specified with
301 @code{--build-users-group}. In addition, each build process is run in a
302 chroot environment that only contains the subset of the store that the
303 build process depends on, as specified by its derivation
304 (@pxref{Programming Interface, derivation}), plus a set of specific
305 system directories. By default, the latter contains @file{/dev} and
308 The following command-line options are supported:
311 @item --build-users-group=@var{group}
312 Take users from @var{group} to run build processes (@pxref{Setting Up
313 the Daemon, build users}).
315 @item --no-substitutes
316 Do not use substitutes for build products. That is, always build things
317 locally instead of allowing downloads of pre-built binaries.
319 @item --cache-failures
320 Cache build failures. By default, only successful builds are cached.
322 @item --cores=@var{n}
324 Use @var{n} CPU cores to build each derivation; @code{0} means as many
327 The default value is @code{1}, but it may be overridden by clients, such
328 as the @code{--cores} option of @command{guix build} (@pxref{Invoking
331 The effect is to define the @code{NIX_BUILD_CORES} environment variable
332 in the build process, which can then use it to exploit internal
333 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
335 @item --max-jobs=@var{n}
337 Allow at most @var{n} build jobs in parallel. The default value is
341 Produce debugging output.
343 This is useful to debug daemon start-up issues, but then it may be
344 overridden by clients, for example the @code{--verbosity} option of
345 @command{guix build} (@pxref{Invoking guix build}).
347 @item --chroot-directory=@var{dir}
348 Add @var{dir} to the build chroot.
350 Doing this may change the result of build processes---for instance if
351 they use optional dependencies found in @var{dir} when it is available,
352 and not otherwise. For that reason, it is not recommended to do so.
353 Instead, make sure that each derivation declares all the inputs that it
356 @item --disable-chroot
357 Disable chroot builds.
359 Using this option is not recommended since, again, it would allow build
360 processes to gain access to undeclared dependencies.
362 @item --disable-log-compression
363 Disable compression of the build logs.
365 Unless @code{--lose-logs} is used, all the build logs are kept in the
366 @var{localstatedir}. To save space, the daemon automatically compresses
367 them with bzip2 by default. This option disables that.
369 @item --disable-store-optimization
370 Disable automatic file ``deduplication'' in the store.
372 By default, files added to the store are automatically ``deduplicated'':
373 if a newly added file is identical as another one found in the store,
374 the daemon makes the new file a hard link to the other file. This
375 slightly increases the input/output load at the end of a build process.
376 This option disables this.
378 @item --impersonate-linux-2.6
379 On Linux-based systems, impersonate Linux 2.6. This means that the
380 kernel's @code{uname} system call will report 2.6 as the release number.
382 This might be helpful to build programs that (usually wrongfully) depend
383 on the kernel version number.
386 Do not keep build logs. By default they are kept under
387 @code{@var{localstatedir}/nix/log}.
389 @item --system=@var{system}
390 Assume @var{system} as the current system type. By default it is the
391 architecture/kernel pair found at configure time, such as
394 @item --listen=@var{socket}
395 Listen for connections on @var{socket}, the file name of a Unix-domain
396 socket. The default socket is
397 @file{@var{localstatedir}/daemon-socket/socket}. This option is only
398 useful in exceptional circumstances, such as if you need to run several
399 daemons on the same machine.
403 @c *********************************************************************
404 @node Package Management
405 @chapter Package Management
407 The purpose of GNU Guix is to allow users to easily install, upgrade, and
408 remove software packages, without having to know about their build
409 procedure or dependencies. Guix also goes beyond this obvious set of
412 This chapter describes the main features of Guix, as well as the package
413 management tools it provides.
416 * Features:: How Guix will make your life brighter.
417 * Invoking guix package:: Package installation, removal, etc.
418 * Packages with Multiple Outputs:: Single source package, multiple outputs.
419 * Invoking guix gc:: Running the garbage collector.
420 * Invoking guix pull:: Fetching the latest Guix and distribution.
426 When using Guix, each package ends up in the @dfn{package store}, in its
427 own directory---something that resembles
428 @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
430 Instead of referring to these directories, users have their own
431 @dfn{profile}, which points to the packages that they actually want to
432 use. These profiles are stored within each user's home directory, at
433 @code{$HOME/.guix-profile}.
435 For example, @code{alice} installs GCC 4.7.2. As a result,
436 @file{/home/alice/.guix-profile/bin/gcc} points to
437 @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
438 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
439 simply continues to point to
440 @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
441 coexist on the same system without any interference.
443 The @command{guix package} command is the central tool to manage
444 packages (@pxref{Invoking guix package}). It operates on those per-user
445 profiles, and can be used @emph{with normal user privileges}.
447 The command provides the obvious install, remove, and upgrade
448 operations. Each invocation is actually a @emph{transaction}: either
449 the specified operation succeeds, or nothing happens. Thus, if the
450 @command{guix package} process is terminated during the transaction,
451 or if a power outage occurs during the transaction, then the user's
452 profile remains in its previous state, and remains usable.
454 In addition, any package transaction may be @emph{rolled back}. So, if,
455 for example, an upgrade installs a new version of a package that turns
456 out to have a serious bug, users may roll back to the previous instance
457 of their profile, which was known to work well.
459 All those packages in the package store may be @emph{garbage-collected}.
460 Guix can determine which packages are still referenced by the user
461 profiles, and remove those that are provably no longer referenced
462 (@pxref{Invoking guix gc}). Users may also explicitly remove old
463 generations of their profile so that the packages they refer to can be
466 Finally, Guix takes a @dfn{purely functional} approach to package
467 management, as described in the introduction (@pxref{Introduction}).
468 Each @file{/nix/store} package directory name contains a hash of all the
469 inputs that were used to build that package---compiler, libraries, build
470 scripts, etc. This direct correspondence allows users to make sure a
471 given package installation matches the current state of their
472 distribution, and helps maximize @dfn{reproducibility}.
474 This foundation allows Guix to support @dfn{transparent binary/source
475 deployment}. When a pre-built binary for a @file{/nix/store} path is
476 available from an external source, Guix just downloads it; otherwise, it
477 builds the package from source, locally.
479 @node Invoking guix package
480 @section Invoking @command{guix package}
482 The @command{guix package} command is the tool that allows users to
483 install, upgrade, and remove packages, as well as rolling back to
484 previous configurations. It operates only on the user's own profile,
485 and works with normal user privileges (@pxref{Features}). Its syntax
489 guix package @var{options}
492 Primarily, @var{options} specifies the operations to be performed during
493 the transaction. Upon completion, a new profile is created, but
494 previous generations of the profile remain available, should the user
497 For each user, a symlink to the user's default profile is automatically
498 created in @file{$HOME/.guix-profile}. This symlink always points to the
499 current generation of the user's default profile. Thus, users can add
500 @file{$HOME/.guix-profile/bin} to their @code{PATH} environment
503 In a multi-user setup, user profiles must be stored in a place
504 registered as a @dfn{garbage-collector root}, which
505 @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That
506 directory is normally
507 @code{@var{localstatedir}/profiles/per-user/@var{user}}, where
508 @var{localstatedir} is the value passed to @code{configure} as
509 @code{--localstatedir}, and @var{user} is the user name. It must be
510 created by @code{root}, with @var{user} as the owner. When it does not
511 exist, or is not owned by @var{user}, @command{guix package} emits an
514 The @var{options} can be among the following:
518 @item --install=@var{package}
519 @itemx -i @var{package}
520 Install @var{package}.
522 @var{package} may specify either a simple package name, such as
523 @code{guile}, or a package name followed by a hyphen and version number,
524 such as @code{guile-1.8.8}. If no version number is specified, the
525 newest available version will be selected. In addition, @var{package}
526 may contain a colon, followed by the name of one of the outputs of the
527 package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
528 (@pxref{Packages with Multiple Outputs}).
530 @cindex propagated inputs
531 Sometimes packages have @dfn{propagated inputs}: these are dependencies
532 that automatically get installed along with the required package.
534 An example is the GNU MPC library: its C header files refer to those of
535 the GNU MPFR library, which in turn refer to those of the GMP library.
536 Thus, when installing MPC, the MPFR and GMP libraries also get installed
537 in the profile; removing MPC also removes MPFR and GMP---unless they had
538 also been explicitly installed independently.
540 Besides, packages sometimes rely on the definition of environment
541 variables for their search paths (see explanation of
542 @code{--search-paths} below). Any missing or possibly incorrect
543 environment variable definitions are reported here.
545 @c XXX: keep me up-to-date
546 Finally, when installing a GNU package, the tool reports the
547 availability of a newer upstream version. In the future, it may provide
548 the option of installing directly from the upstream version, even if
549 that version is not yet in the distribution.
551 @item --install-from-expression=@var{exp}
553 Install the package @var{exp} evaluates to.
555 @var{exp} must be a Scheme expression that evaluates to a
556 @code{<package>} object. This option is notably useful to disambiguate
557 between same-named variants of a package, with expressions such as
558 @code{(@@ (gnu packages base) guile-final)}.
560 Note that this option installs the first output of the specified
561 package, which may be insufficient when needing a specific output of a
562 multiple-output package.
564 @item --remove=@var{package}
565 @itemx -r @var{package}
566 Remove @var{package}.
568 @item --upgrade[=@var{regexp}]
569 @itemx -u [@var{regexp}]
570 Upgrade all the installed packages. When @var{regexp} is specified, upgrade
571 only installed packages whose name matches @var{regexp}.
573 Note that this upgrades package to the latest version of packages found
574 in the distribution currently installed. To update your distribution,
575 you should regularly run @command{guix pull} (@pxref{Invoking guix
579 Roll back to the previous @dfn{generation} of the profile---i.e., undo
580 the last transaction.
582 When combined with options such as @code{--install}, roll back occurs
583 before any other actions.
585 When rolling back from the first generation that actually contains
586 installed packages, the profile is made to point to the @dfn{zeroth
587 generation}, which contains no files apart from its own meta-data.
589 Installing, removing, or upgrading packages from a generation that has
590 been rolled back to overwrites previous future generations. Thus, the
591 history of a profile's generations is always linear.
595 Report environment variable definitions, in Bash syntax, that may be
596 needed in order to use the set of installed packages. These environment
597 variables are used to specify @dfn{search paths} for files used by some
598 of the installed packages.
600 For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
601 environment variables to be defined so it can look for headers and
602 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
603 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
604 library are installed in the profile, then @code{--search-paths} will
605 suggest setting these variables to @code{@var{profile}/include} and
606 @code{@var{profile}/lib}, respectively.
608 @item --profile=@var{profile}
609 @itemx -p @var{profile}
610 Use @var{profile} instead of the user's default profile.
614 Show what would be done without actually doing it.
617 When substituting a pre-built binary fails, fall back to building
620 @item --no-substitutes
621 @itemx --max-silent-time=@var{seconds}
622 Same as for @command{guix build} (@pxref{Invoking guix build}).
625 Produce verbose output. In particular, emit the environment's build log
626 on the standard error port.
629 Use the bootstrap Guile to build the profile. This option is only
630 useful to distribution developers.
634 In addition to these actions @command{guix package} supports the
635 following options to query the current state of a profile, or the
636 availability of packages:
640 @item --search=@var{regexp}
641 @itemx -s @var{regexp}
642 List the available packages whose synopsis or description matches
643 @var{regexp}. Print all the meta-data of matching packages in
644 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
645 GNU recutils manual}).
647 This allows specific fields to be extracted using the @command{recsel}
648 command, for instance:
651 $ guix package -s malloc | recsel -p name,version
659 @item --list-installed[=@var{regexp}]
660 @itemx -I [@var{regexp}]
661 List the currently installed packages in the specified profile, with the
662 most recently installed packages shown last. When @var{regexp} is
663 specified, list only installed packages whose name matches @var{regexp}.
665 For each installed package, print the following items, separated by
666 tabs: the package name, its version string, the part of the package that
667 is installed (for instance, @code{out} for the default output,
668 @code{include} for its headers, etc.), and the path of this package in
671 @item --list-available[=@var{regexp}]
672 @itemx -A [@var{regexp}]
673 List packages currently available in the software distribution
674 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
675 installed packages whose name matches @var{regexp}.
677 For each package, print the following items separated by tabs: its name,
678 its version string, the parts of the package (@pxref{Packages with
679 Multiple Outputs}), and the source location of its definition.
681 @item --list-generations[=@var{pattern}]
682 @itemx -l [@var{pattern}]
683 Return a list of generations along with their creation dates; for each
684 generation, show the installed packages, with the most recently
685 installed packages shown last. Note that the zeroth generation is never
688 For each installed package, print the following items, separated by
689 tabs: the name of a package, its version string, the part of the package
690 that is installed (@pxref{Packages with Multiple Outputs}), and the
691 location of this package in the store.
693 When @var{pattern} is used, the command returns only matching
694 generations. Valid patterns include:
697 @item @emph{Integers and comma-separated integers}. Both patterns denote
698 generation numbers. For instance, @code{--list-generations=1} returns
701 And @code{--list-generations=1,8,2} outputs three generations in the
702 specified order. Neither spaces nor trailing commas are allowed.
704 @item @emph{Ranges}. @code{--list-generations=2..9} prints the
705 specified generations and everything in between. Note that the start of
706 a range must be lesser than its end.
708 It is also possible to omit the endpoint. For example,
709 @code{--list-generations=2..}, returns all generations starting from the
712 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
713 or months by passing an integer along with the first letter of the
714 duration. For example, @code{--list-generations=20d} lists generations
715 that are up to 20 days old.
718 @item --delete-generations[=@var{pattern}]
719 @itemx -d [@var{pattern}]
720 When @var{pattern} is omitted, delete all generations except the current
723 This command accepts the same patterns as @option{--list-generations}.
724 When @var{pattern} is specified, delete the matching generations. When
725 @var{pattern} specifies a duration, generations @emph{older} than the
726 specified duration match. For instance, @code{--delete-generations=1m}
727 deletes generations that are more than one month old.
729 If the current generation matches, it is deleted atomically---i.e., by
730 switching to the previous available generation. Note that the zeroth
731 generation is never deleted.
733 Note that deleting generations prevents roll-back to them.
734 Consequently, this command must be used with care.
738 @node Packages with Multiple Outputs
739 @section Packages with Multiple Outputs
741 @cindex multiple-output packages
742 @cindex package outputs
744 Often, packages defined in Guix have a single @dfn{output}---i.e., the
745 source package leads exactly one directory in the store. When running
746 @command{guix package -i glibc}, one installs the default output of the
747 GNU libc package; the default output is called @code{out}, but its name
748 can be omitted as shown in this command. In this particular case, the
749 default output of @code{glibc} contains all the C header files, shared
750 libraries, static libraries, Info documentation, and other supporting
753 Sometimes it is more appropriate to separate the various types of files
754 produced from a single source package into separate outputs. For
755 instance, the GLib C library (used by GTK+ and related packages)
756 installs more than 20 MiB of reference documentation as HTML pages.
757 To save space for users who do not need it, the documentation goes to a
758 separate output, called @code{doc}. To install the main GLib output,
759 which contains everything but the documentation, one would run:
765 The command to install its documentation is:
768 guix package -i glib:doc
771 Some packages install programs with different ``dependency footprints''.
772 For instance, the WordNet package install both command-line tools and
773 graphical user interfaces (GUIs). The former depend solely on the C
774 library, whereas the latter depend on Tcl/Tk and the underlying X
775 libraries. In this case, we leave the command-line tools in the default
776 output, whereas the GUIs are in a separate output. This allows users
777 who do not need the GUIs to save space.
779 There are several such multiple-output packages in the GNU distribution.
780 Other conventional output names include @code{lib} for libraries and
781 possibly header files, @code{bin} for stand-alone programs, and
782 @code{debug} for debugging information (@pxref{Installing Debugging
783 Files}). The outputs of a packages are listed in the third column of
784 the output of @command{guix package --list-available} (@pxref{Invoking
788 @node Invoking guix gc
789 @section Invoking @command{guix gc}
791 @cindex garbage collector
792 Packages that are installed but not used may be @dfn{garbage-collected}.
793 The @command{guix gc} command allows users to explicitly run the garbage
794 collector to reclaim space from the @file{/nix/store} directory.
796 The garbage collector has a set of known @dfn{roots}: any file under
797 @file{/nix/store} reachable from a root is considered @dfn{live} and
798 cannot be deleted; any other file is considered @dfn{dead} and may be
799 deleted. The set of garbage collector roots includes default user
800 profiles, and may be augmented with @command{guix build --root}, for
801 example (@pxref{Invoking guix build}).
803 Prior to running @code{guix gc --collect-garbage} to make space, it is
804 often useful to remove old generations from user profiles; that way, old
805 package builds referenced by those generations can be reclaimed. This
806 is achieved by running @code{guix package --delete-generations}
807 (@pxref{Invoking guix package}).
809 The @command{guix gc} command has three modes of operation: it can be
810 used to garbage-collect any dead files (the default), to delete specific
811 files (the @code{--delete} option), or to print garbage-collector
812 information. The available options are listed below:
815 @item --collect-garbage[=@var{min}]
816 @itemx -C [@var{min}]
817 Collect garbage---i.e., unreachable @file{/nix/store} files and
818 sub-directories. This is the default operation when no option is
821 When @var{min} is given, stop once @var{min} bytes have been collected.
822 @var{min} may be a number of bytes, or it may include a unit as a
823 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes.
825 When @var{min} is omitted, collect all the garbage.
829 Attempt to delete all the store files and directories specified as
830 arguments. This fails if some of the files are not in the store, or if
834 Show the list of dead files and directories still present in the
835 store---i.e., files and directories no longer reachable from any root.
838 Show the list of live store files and directories.
842 In addition, the references among existing store files can be queried:
848 List the references (respectively, the referrers) of store files given
853 List the requisites of the store files passed as arguments. Requisites
854 include the store files themselves, their references, and the references
855 of these, recursively. In other words, the returned list is the
856 @dfn{transitive closure} of the store files.
861 @node Invoking guix pull
862 @section Invoking @command{guix pull}
864 Packages are installed or upgraded to the latest version available in
865 the distribution currently available on your local machine. To update
866 that distribution, along with the Guix tools, you must run @command{guix
867 pull}: the command downloads the latest Guix source code and package
868 descriptions, and deploys it.
870 On completion, @command{guix package} will use packages and package
871 versions from this just-retrieved copy of Guix. Not only that, but all
872 the Guix commands and Scheme modules will also be taken from that latest
873 version. New @command{guix} sub-commands added by the update also
876 The @command{guix pull} command is usually invoked with no arguments,
877 but it supports the following options:
881 Produce verbose output, writing build logs to the standard error output.
883 @item --url=@var{url}
884 Download the source tarball of Guix from @var{url}.
886 By default, the tarball is taken from its canonical address at
887 @code{gnu.org}, for the stable branch of Guix.
890 Use the bootstrap Guile to build the latest Guix. This option is only
891 useful to Guix developers.
894 @c *********************************************************************
895 @node Programming Interface
896 @chapter Programming Interface
898 GNU Guix provides several Scheme programming interfaces (APIs) to
899 define, build, and query packages. The first interface allows users to
900 write high-level package definitions. These definitions refer to
901 familiar packaging concepts, such as the name and version of a package,
902 its build system, and its dependencies. These definitions can then be
903 turned into concrete build actions.
905 Build actions are performed by the Guix daemon, on behalf of users. In a
906 standard setup, the daemon has write access to the store---the
907 @file{/nix/store} directory---whereas users do not. The recommended
908 setup also has the daemon perform builds in chroots, under a specific
909 build users, to minimize interference with the rest of the system.
912 Lower-level APIs are available to interact with the daemon and the
913 store. To instruct the daemon to perform a build action, users actually
914 provide it with a @dfn{derivation}. A derivation is a low-level
915 representation of the build actions to be taken, and the environment in
916 which they should occur---derivations are to package definitions what
917 assembly is to C programs.
919 This chapter describes all these APIs in turn, starting from high-level
923 * Defining Packages:: Defining new packages.
924 * The Store:: Manipulating the package store.
925 * Derivations:: Low-level interface to package derivations.
926 * The Store Monad:: Purely functional interface to the store.
929 @node Defining Packages
930 @section Defining Packages
932 The high-level interface to package definitions is implemented in the
933 @code{(guix packages)} and @code{(guix build-system)} modules. As an
934 example, the package definition, or @dfn{recipe}, for the GNU Hello
935 package looks like this:
938 (use-modules (guix packages)
940 (guix build-system gnu)
949 (uri (string-append "mirror://gnu/hello/hello-" version
952 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
953 (build-system gnu-build-system)
954 (inputs `(("gawk" ,gawk)))
955 (synopsis "GNU Hello")
956 (description "Yeah...")
957 (home-page "http://www.gnu.org/software/hello/")
962 Without being a Scheme expert, the reader may have guessed the meaning
963 of the various fields here. This expression binds variable @var{hello}
964 to a @code{<package>} object, which is essentially a record
965 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
966 This package object can be inspected using procedures found in the
967 @code{(guix packages)} module; for instance, @code{(package-name hello)}
968 returns---surprise!---@code{"hello"}.
970 There are a few points worth noting in the above package definition:
974 The @code{source} field of the package is an @code{<origin>} object.
975 Here, the @code{url-fetch} method from @code{(guix download)} is used,
976 meaning that the source is a file to be downloaded over FTP or HTTP.
978 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
979 the GNU mirrors defined in @code{(guix download)}.
981 The @code{sha256} field specifies the expected SHA256 hash of the file
982 being downloaded. It is mandatory, and allows Guix to check the
983 integrity of the file. The @code{(base32 @dots{})} form introduces the
984 base32 representation of the hash. You can obtain this information with
985 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
986 hash} (@pxref{Invoking guix hash}).
989 @cindex GNU Build System
990 The @code{build-system} field is set to @var{gnu-build-system}. The
991 @var{gnu-build-system} variable is defined in the @code{(guix
992 build-system gnu)} module, and is bound to a @code{<build-system>}
995 Naturally, @var{gnu-build-system} represents the familiar GNU Build
996 System, and variants thereof (@pxref{Configuration, configuration and
997 makefile conventions,, standards, GNU Coding Standards}). In a
998 nutshell, packages using the GNU Build System may be configured, built,
999 and installed with the usual @code{./configure && make && make check &&
1000 make install} command sequence. This is what @var{gnu-build-system}
1003 In addition, @var{gnu-build-system} ensures that the ``standard''
1004 environment for GNU packages is available. This includes tools such as
1005 GCC, Coreutils, Bash, Make, Diffutils, and Patch.
1008 The @code{inputs} field specifies inputs to the build process---i.e.,
1009 build-time or run-time dependencies of the package. Here, we define an
1010 input called @code{"gawk"} whose value is that of the @var{gawk}
1011 variable; @var{gawk} is itself bound to a @code{<package>} object.
1013 Note that GCC, Coreutils, Bash, and other essential tools do not need to
1014 be specified as inputs here. Instead, @var{gnu-build-system} takes care
1015 of ensuring that they are present.
1017 However, any other dependencies need to be specified in the
1018 @code{inputs} field. Any dependency not specified here will simply be
1019 unavailable to the build process, possibly leading to a build failure.
1022 There are other fields that package definitions may provide. Of
1023 particular interest is the @code{arguments} field. When specified, it
1024 must be bound to a list of additional arguments to be passed to the
1025 build system. For instance, the above definition could be augmented
1026 with the following field initializer:
1029 (arguments `(#:tests? #f
1030 #:configure-flags '("--enable-silent-rules")))
1034 These are keyword arguments (@pxref{Optional Arguments, keyword
1035 arguments in Guile,, guile, GNU Guile Reference Manual}). They are
1036 passed to @var{gnu-build-system}, which interprets them as meaning ``do
1037 not run @code{make check}'', and ``run @file{configure} with the
1038 @code{--enable-silent-rules} flag''. The value of these keyword
1039 parameters is actually evaluated in the @dfn{build stratum}---i.e., by a
1040 Guile process launched by the daemon (@pxref{Derivations}).
1042 Once a package definition is in place@footnote{Simple package
1043 definitions like the one above may be automatically converted from the
1044 Nixpkgs distribution using the @command{guix import} command.}, the
1045 package may actually be built using the @code{guix build} command-line
1046 tool (@pxref{Invoking guix build}). Eventually, updating the package
1047 definition to a new upstream version can be partly automated by the
1048 @command{guix refresh} command (@pxref{Invoking guix refresh}).
1050 Behind the scenes, a derivation corresponding to the @code{<package>}
1051 object is first computed by the @code{package-derivation} procedure.
1052 That derivation is stored in a @code{.drv} file under @file{/nix/store}.
1053 The build actions it prescribes may then be realized by using the
1054 @code{build-derivations} procedure (@pxref{The Store}).
1056 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
1057 Return the @code{<derivation>} object of @var{package} for @var{system}
1058 (@pxref{Derivations}).
1060 @var{package} must be a valid @code{<package>} object, and @var{system}
1061 must be a string denoting the target system type---e.g.,
1062 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1063 must be a connection to the daemon, which operates on the store
1064 (@pxref{The Store}).
1068 @cindex cross-compilation
1069 Similarly, it is possible to compute a derivation that cross-builds a
1070 package for some other system:
1072 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
1073 @var{package} @var{target} [@var{system}]
1074 Return the @code{<derivation>} object of @var{package} cross-built from
1075 @var{system} to @var{target}.
1077 @var{target} must be a valid GNU triplet denoting the target hardware
1078 and operating system, such as @code{"mips64el-linux-gnu"}
1079 (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1080 Configure and Build System}).
1090 Conceptually, the @dfn{store} is where derivations that have been
1091 successfully built are stored---by default, under @file{/nix/store}.
1092 Sub-directories in the store are referred to as @dfn{store paths}. The
1093 store has an associated database that contains information such has the
1094 store paths referred to by each store path, and the list of @emph{valid}
1095 store paths---paths that result from a successful build.
1097 The store is always accessed by the daemon on behalf of its clients
1098 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
1099 connect to the daemon over a Unix-domain socket, send it requests, and
1100 read the result---these are remote procedure calls, or RPCs.
1102 The @code{(guix store)} module provides procedures to connect to the
1103 daemon, and to perform RPCs. These are described below.
1105 @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
1106 Connect to the daemon over the Unix-domain socket at @var{file}. When
1107 @var{reserve-space?} is true, instruct it to reserve a little bit of
1108 extra space on the file system so that the garbage collector can still
1109 operate, should the disk become full. Return a server object.
1111 @var{file} defaults to @var{%default-socket-path}, which is the normal
1112 location given the options that were passed to @command{configure}.
1115 @deffn {Scheme Procedure} close-connection @var{server}
1116 Close the connection to @var{server}.
1119 @defvr {Scheme Variable} current-build-output-port
1120 This variable is bound to a SRFI-39 parameter, which refers to the port
1121 where build and error logs sent by the daemon should be written.
1124 Procedures that make RPCs all take a server object as their first
1127 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
1128 Return @code{#t} when @var{path} is a valid store path.
1131 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
1132 Add @var{text} under file @var{name} in the store, and return its store
1133 path. @var{references} is the list of store paths referred to by the
1134 resulting store path.
1137 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
1138 Build @var{derivations} (a list of @code{<derivation>} objects or
1139 derivation paths), and return when the worker is done building them.
1140 Return @code{#t} on success.
1143 Note that the @code{(guix monads)} module provides a monad as well as
1144 monadic versions of the above procedures, with the goal of making it
1145 more convenient to work with code that accesses the store (@pxref{The
1149 @i{This section is currently incomplete.}
1152 @section Derivations
1155 Low-level build actions and the environment in which they are performed
1156 are represented by @dfn{derivations}. A derivation contain the
1157 following pieces of information:
1161 The outputs of the derivation---derivations produce at least one file or
1162 directory in the store, but may produce more.
1165 The inputs of the derivations, which may be other derivations or plain
1166 files in the store (patches, build scripts, etc.)
1169 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
1172 The file name of a build script in the store, along with the arguments
1176 A list of environment variables to be defined.
1180 @cindex derivation path
1181 Derivations allow clients of the daemon to communicate build actions to
1182 the store. They exist in two forms: as an in-memory representation,
1183 both on the client- and daemon-side, and as files in the store whose
1184 name end in @code{.drv}---these files are referred to as @dfn{derivation
1185 paths}. Derivations paths can be passed to the @code{build-derivations}
1186 procedure to perform the build actions they prescribe (@pxref{The
1189 The @code{(guix derivations)} module provides a representation of
1190 derivations as Scheme objects, along with procedures to create and
1191 otherwise manipulate derivations. The lowest-level primitive to create
1192 a derivation is the @code{derivation} procedure:
1194 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f]
1195 Build a derivation with the given arguments, and return the resulting
1196 @code{<derivation>} object.
1198 When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a
1199 @dfn{fixed-output derivation} is created---i.e., one whose result is
1200 known in advance, such as a file download.
1202 When @var{references-graphs} is true, it must be a list of file
1203 name/store path pairs. In that case, the reference graph of each store
1204 path is exported in the build environment in the corresponding file, in
1205 a simple text format.
1209 Here's an example with a shell script as its builder, assuming
1210 @var{store} is an open connection to the daemon, and @var{bash} points
1211 to a Bash executable in the store:
1214 (use-modules (guix utils)
1218 (let ((builder ; add the Bash script to the store
1219 (add-text-to-store store "my-builder.sh"
1220 "echo hello world > $out\n" '())))
1221 (derivation store "foo"
1222 bash `("-e" ,builder)
1223 #:env-vars '(("HOME" . "/homeless"))))
1224 @result{} #<derivation /nix/store/@dots{}-foo.drv => /nix/store/@dots{}-foo>
1227 As can be guessed, this primitive is cumbersome to use directly. An
1228 improved variant is @code{build-expression->derivation}, which allows
1229 the caller to directly pass a Guile expression as the build script:
1231 @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 '()] [#:references-graphs #f] [#:guile-for-build #f]
1232 Return a derivation that executes Scheme expression @var{exp} as a
1233 builder for derivation @var{name}. @var{inputs} must be a list of
1234 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
1235 @code{"out"} is assumed. @var{modules} is a list of names of Guile
1236 modules from the current search path to be copied in the store,
1237 compiled, and made available in the load path during the execution of
1238 @var{exp}---e.g., @code{((guix build utils) (guix build
1239 gnu-build-system))}.
1241 @var{exp} is evaluated in an environment where @code{%outputs} is bound
1242 to a list of output/path pairs, and where @code{%build-inputs} is bound
1243 to a list of string/output-path pairs made from @var{inputs}.
1244 Optionally, @var{env-vars} is a list of string pairs specifying the name
1245 and value of environment variables visible to the builder. The builder
1246 terminates by passing the result of @var{exp} to @code{exit}; thus, when
1247 @var{exp} returns @code{#f}, the build is considered to have failed.
1249 @var{exp} is built using @var{guile-for-build} (a derivation). When
1250 @var{guile-for-build} is omitted or is @code{#f}, the value of the
1251 @code{%guile-for-build} fluid is used instead.
1253 See the @code{derivation} procedure for the meaning of @var{references-graphs}.
1257 Here's an example of a single-output derivation that creates a directory
1258 containing one file:
1261 (let ((builder '(let ((out (assoc-ref %outputs "out")))
1262 (mkdir out) ; create /nix/store/@dots{}-goo
1263 (call-with-output-file (string-append out "/test")
1265 (display '(hello guix) p))))))
1266 (build-expression->derivation store "goo" (%current-system)
1269 @result{} #<derivation /nix/store/@dots{}-goo.drv => @dots{}>
1272 @cindex strata of code
1273 Remember that the build expression passed to
1274 @code{build-expression->derivation} is run by a separate Guile process
1275 than the one that calls @code{build-expression->derivation}: it is run
1276 by a Guile process launched by the daemon, typically in a chroot. So,
1277 while there is a single language for both the @dfn{host} and the build
1278 side, there are really two @dfn{strata} of code: the host-side, and the
1279 build-side code@footnote{The term @dfn{stratum} in this context was
1280 coined by Manuel Serrano et al. in the context of their work on Hop.}.
1281 This distinction is important to keep in mind, notably when using
1282 higher-level constructs such as @var{gnu-build-system} (@pxref{Defining
1283 Packages}). For this reason, Guix modules that are meant to be used in
1284 the build stratum are kept in the @code{(guix build @dots{})} name
1287 @node The Store Monad
1288 @section The Store Monad
1292 The procedures that operate on the store described in the previous
1293 sections all take an open connection to the build daemon as their first
1294 argument. Although the underlying model is functional, they either have
1295 side effects or depend on the current state of the store.
1297 The former is inconvenient: the connection to the build daemon has to be
1298 carried around in all those functions, making it impossible to compose
1299 functions that do not take that parameter with functions that do. The
1300 latter can be problematic: since store operations have side effects
1301 and/or depend on external state, they have to be properly sequenced.
1303 @cindex monadic values
1304 @cindex monadic functions
1305 This is where the @code{(guix monads)} module comes in. This module
1306 provides a framework for working with @dfn{monads}, and a particularly
1307 useful monad for our uses, the @dfn{store monad}. Monads are a
1308 construct that allows two things: associating ``context'' with values
1309 (in our case, the context is the store), and building sequences of
1310 computations (here computations includes accesses to the store.) Values
1311 in a monad---values that carry this additional context---are called
1312 @dfn{monadic values}; procedures that return such values are called
1313 @dfn{monadic procedures}.
1315 Consider this ``normal'' procedure:
1318 (define (profile.sh store)
1319 ;; Return the name of a shell script in the store that
1320 ;; initializes the 'PATH' environment variable.
1321 (let* ((drv (package-derivation store coreutils))
1322 (out (derivation->output-path drv)))
1323 (add-text-to-store store "profile.sh"
1324 (format #f "export PATH=~a/bin" out))))
1327 Using @code{(guix monads)}, it may be rewritten as a monadic function:
1330 (define (profile.sh)
1331 ;; Same, but return a monadic value.
1332 (mlet %store-monad ((bin (package-file coreutils "bin")))
1333 (text-file "profile.sh"
1334 (string-append "export PATH=" bin))))
1337 There are two things to note in the second version: the @code{store}
1338 parameter is now implicit, and the monadic value returned by
1339 @code{package-file}---a wrapper around @code{package-derivation} and
1340 @code{derivation->output-path}---is @dfn{bound} using @code{mlet}
1341 instead of plain @code{let}.
1343 Calling the monadic @code{profile.sh} has no effect. To get the desired
1344 effect, one must use @code{run-with-store}:
1347 (run-with-store (open-connection) (profile.sh))
1348 @result{} /nix/store/...-profile.sh
1351 The main syntactic forms to deal with monads in general are described
1354 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
1355 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
1359 @deffn {Scheme Syntax} return @var{val}
1360 Return a monadic value that encapsulates @var{val}.
1363 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
1364 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
1365 procedure @var{mproc}@footnote{This operation is commonly referred to as
1366 ``bind'', but that name denotes an unrelated procedure in Guile. Thus
1367 we use this somewhat cryptic symbol inherited from the Haskell
1371 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
1373 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
1375 Bind the variables @var{var} to the monadic values @var{mval} in
1376 @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
1377 ``normal'' value @var{val}, as per @code{let}.
1379 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
1380 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
1383 The interface to the store monad provided by @code{(guix monads)} is as
1386 @defvr {Scheme Variable} %store-monad
1387 The store monad. Values in the store monad encapsulate accesses to the
1388 store. When its effect is needed, a value of the store monad must be
1389 ``evaluated'' by passing it to the @code{run-with-store} procedure (see
1393 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
1394 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
1395 open store connection.
1398 @deffn {Monadic Procedure} text-file @var{name} @var{text}
1399 Return as a monadic value the absolute file name in the store of the file
1400 containing @var{text}.
1403 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
1404 [#:system (%current-system)] [#:output "out"] Return as a monadic
1405 value in the absolute file name of @var{file} within the @var{output}
1406 directory of @var{package}. When @var{file} is omitted, return the name
1407 of the @var{output} directory of @var{package}.
1410 @deffn {Monadic Procedure} derivation-expression @var{name} @var{system} @
1411 @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] @
1412 [#:hash-algo #f] [#:env-vars '()] [#:modules '()] @
1413 [#:references-graphs #f] [#:guile-for-build #f]
1414 Monadic version of @code{build-expression->derivation}
1415 (@pxref{Derivations}).
1418 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
1419 Monadic version of @code{package-derivation} (@pxref{Defining
1424 @c *********************************************************************
1428 This section describes tools primarily targeted at developers and users
1429 who write new package definitions. They complement the Scheme
1430 programming interface of Guix in a convenient way.
1433 * Invoking guix build:: Building packages from the command line.
1434 * Invoking guix download:: Downloading a file and printing its hash.
1435 * Invoking guix hash:: Computing the cryptographic hash of a file.
1436 * Invoking guix refresh:: Updating package definitions.
1439 @node Invoking guix build
1440 @section Invoking @command{guix build}
1442 The @command{guix build} command builds packages or derivations and
1443 their dependencies, and prints the resulting store paths. Note that it
1444 does not modify the user's profile---this is the job of the
1445 @command{guix package} command (@pxref{Invoking guix package}). Thus,
1446 it is mainly useful for distribution developers.
1448 The general syntax is:
1451 guix build @var{options} @var{package-or-derivation}@dots{}
1454 @var{package-or-derivation} may be either the name of a package found in
1455 the software distribution such as @code{coreutils} or
1456 @code{coreutils-8.20}, or a derivation such as
1457 @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the
1458 @code{--expression} option may be used to specify a Scheme expression
1459 that evaluates to a package; this is useful when disambiguation among
1460 several same-named packages or package variants is needed.
1462 The @var{options} may be zero or more of the following:
1466 @item --expression=@var{expr}
1467 @itemx -e @var{expr}
1468 Build the package @var{expr} evaluates to.
1470 For example, @var{expr} may be @code{(@@ (gnu packages guile)
1471 guile-1.8)}, which unambiguously designates this specific variant of
1472 version 1.8 of Guile.
1476 Build the packages' source derivations, rather than the packages
1479 For instance, @code{guix build -S gcc} returns something like
1480 @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
1482 @item --system=@var{system}
1483 @itemx -s @var{system}
1484 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
1485 the host's system type.
1487 An example use of this is on Linux-based systems, which can emulate
1488 different personalities. For instance, passing
1489 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
1490 to build packages in a complete 32-bit environment.
1492 @item --target=@var{triplet}
1493 @cindex cross-compilation
1494 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
1495 as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
1496 configuration triplets,, configure, GNU Configure and Build System}).
1500 Return the derivation paths, not the output paths, of the given
1505 Keep the build tree of failed builds. Thus, if a build fail, its build
1506 tree is kept under @file{/tmp}, in a directory whose name is shown at
1507 the end of the build log. This is useful when debugging build issues.
1511 Do not build the derivations.
1514 When substituting a pre-built binary fails, fall back to building
1517 @item --no-substitutes
1518 Build instead of resorting to pre-built substitutes.
1520 @item --max-silent-time=@var{seconds}
1521 When the build or substitution process remains silent for more than
1522 @var{seconds}, terminate it and report a build failure.
1524 @item --cores=@var{n}
1526 Allow the use of up to @var{n} CPU cores for the build. The special
1527 value @code{0} means to use as many CPU cores as available.
1529 @item --root=@var{file}
1530 @itemx -r @var{file}
1531 Make @var{file} a symlink to the result, and register it as a garbage
1534 @item --verbosity=@var{level}
1535 Use the given verbosity level. @var{level} must be an integer between 0
1536 and 5; higher means more verbose output. Setting a level of 4 or more
1537 may be helpful when debugging setup issues with the build daemon.
1541 Behind the scenes, @command{guix build} is essentially an interface to
1542 the @code{package-derivation} procedure of the @code{(guix packages)}
1543 module, and to the @code{build-derivations} procedure of the @code{(guix
1546 @node Invoking guix download
1547 @section Invoking @command{guix download}
1549 When writing a package definition, developers typically need to download
1550 the package's source tarball, compute its SHA256 hash, and write that
1551 hash in the package definition (@pxref{Defining Packages}). The
1552 @command{guix download} tool helps with this task: it downloads a file
1553 from the given URI, adds it to the store, and prints both its file name
1554 in the store and its SHA256 hash.
1556 The fact that the downloaded file is added to the store saves bandwidth:
1557 when the developer eventually tries to build the newly defined package
1558 with @command{guix build}, the source tarball will not have to be
1559 downloaded again because it is already in the store. It is also a
1560 convenient way to temporarily stash files, which may be deleted
1561 eventually (@pxref{Invoking guix gc}).
1563 The @command{guix download} command supports the same URIs as used in
1564 package definitions. In particular, it supports @code{mirror://} URIs.
1565 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
1566 Guile bindings for GnuTLS are available in the user's environment; when
1567 they are not available, an error is raised.
1569 The following option is available:
1572 @item --format=@var{fmt}
1574 Write the hash in the format specified by @var{fmt}. For more
1575 information on the valid values for @var{fmt}, @ref{Invoking guix hash}.
1578 @node Invoking guix hash
1579 @section Invoking @command{guix hash}
1581 The @command{guix hash} command computes the SHA256 hash of a file.
1582 It is primarily a convenience tool for anyone contributing to the
1583 distribution: it computes the cryptographic hash of a file, which can be
1584 used in the definition of a package (@pxref{Defining Packages}).
1586 The general syntax is:
1589 guix hash @var{option} @var{file}
1592 @command{guix hash} has the following option:
1596 @item --format=@var{fmt}
1598 Write the hash in the format specified by @var{fmt}.
1600 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
1601 (@code{hex} and @code{hexadecimal} can be used as well).
1603 If the @option{--format} option is not specified, @command{guix hash}
1604 will output the hash in @code{nix-base32}. This representation is used
1605 in the definitions of packages.
1609 @node Invoking guix refresh
1610 @section Invoking @command{guix refresh}
1612 The primary audience of the @command{guix refresh} command is developers
1613 of the GNU software distribution. By default, it reports any packages
1614 provided by the distribution that are outdated compared to the latest
1615 upstream version, like this:
1619 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
1620 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
1623 It does so by browsing each package's FTP directory and determining the
1624 highest version number of the source tarballs
1625 therein@footnote{Currently, this only works for GNU packages.}.
1627 When passed @code{--update}, it modifies distribution source files to
1628 update the version numbers and source tarball hashes of those packages'
1629 recipes (@pxref{Defining Packages}). This is achieved by downloading
1630 each package's latest source tarball and its associated OpenPGP
1631 signature, authenticating the downloaded tarball against its signature
1632 using @command{gpg}, and finally computing its hash. When the public
1633 key used to sign the tarball is missing from the user's keyring, an
1634 attempt is made to automatically retrieve it from a public key server;
1635 when it's successful, the key is added to the user's keyring; otherwise,
1636 @command{guix refresh} reports an error.
1638 The following options are supported:
1644 Update distribution source files (package recipes) in place.
1645 @ref{Defining Packages}, for more information on package definitions.
1647 @item --select=[@var{subset}]
1648 @itemx -s @var{subset}
1649 Select all the packages in @var{subset}, one of @code{core} or
1652 The @code{core} subset refers to all the packages at the core of the
1653 distribution---i.e., packages that are used to build ``everything
1654 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
1655 changing one of these packages in the distribution entails a rebuild of
1656 all the others. Thus, such updates are an inconvenience to users in
1657 terms of build time or bandwidth used to achieve the upgrade.
1659 The @code{non-core} subset refers to the remaining packages. It is
1660 typically useful in cases where an update of the core packages would be
1665 In addition, @command{guix refresh} can be passed one or more package
1666 names, as in this example:
1669 guix refresh -u emacs idutils
1673 The command above specifically updates the @code{emacs} and
1674 @code{idutils} packages. The @code{--select} option would have no
1675 effect in this case.
1677 The following options can be used to customize GnuPG operation:
1681 @item --key-server=@var{host}
1682 Use @var{host} as the OpenPGP key server when importing a public key.
1684 @item --gpg=@var{command}
1685 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
1686 for in @code{$PATH}.
1691 @c *********************************************************************
1692 @node GNU Distribution
1693 @chapter GNU Distribution
1695 Guix comes with a distribution of free software@footnote{The term
1696 ``free'' here refers to the
1697 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
1698 users of that software}.} that form the basis of the GNU system. This
1699 includes core GNU packages such as GNU libc, GCC, and Binutils, as well
1700 as many GNU and non-GNU applications. The complete list of available
1701 packages can be seen by running @command{guix package} (@pxref{Invoking
1705 guix package --list-available
1708 Our goal is to build a practical 100% free software distribution of
1709 Linux-based and other variants of GNU, with a focus on the promotion and
1710 tight integration of GNU components, and an emphasis on programs and
1711 tools that help users exert that freedom.
1714 * Installing Debugging Files:: Feeding the debugger.
1715 * Package Modules:: Packages from the programmer's viewpoint.
1716 * Packaging Guidelines:: Growing the distribution.
1717 * Bootstrapping:: GNU/Linux built from scratch.
1718 * Porting:: Targeting another platform or kernel.
1721 Building this distribution is a cooperative effort, and you are invited
1722 to join! @ref{Contributing}, for information about how you can help.
1725 @node Installing Debugging Files
1726 @section Installing Debugging Files
1728 Program binaries, as produced by the GCC compilers for instance, are
1729 typically written in the ELF format, with a section containing
1730 @dfn{debugging information}. Debugging information is what allows the
1731 debugger, GDB, to map binary code to source code; it is required to
1732 debug a compiled program in good conditions.
1734 The problem with debugging information is that is takes up a fair amount
1735 of disk space. For example, debugging information for the GNU C Library
1736 weighs in at more than 60 MiB. Thus, as a user, keeping all the
1737 debugging info of all the installed programs is usually not an option.
1738 Yet, space savings should not come at the cost of an impediment to
1739 debugging---especially in the GNU system, which should make it easier
1740 for users to exert their computing freedom (@pxref{GNU Distribution}).
1742 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
1743 mechanism that allows users to get the best of both worlds: debugging
1744 information can be stripped from the binaries and stored in separate
1745 files. GDB is then able to load debugging information from those files,
1746 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
1749 The GNU distribution takes advantage of this by storing debugging
1750 information in the @code{lib/debug} sub-directory of a separate package
1751 output unimaginatively called @code{debug} (@pxref{Packages with
1752 Multiple Outputs}). Users can choose to install the @code{debug} output
1753 of a package when they need it. For instance, the following command
1754 installs the debugging information for the GNU C Library and for GNU
1758 guix package -i glibc:debug -i guile:debug
1761 GDB must then be told to look for debug files in the user's profile, by
1762 setting the @code{debug-file-directory} variable (consider setting it
1763 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
1767 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
1770 From there on, GDB will pick up debugging information from the
1771 @code{.debug} files under @file{~/.guix-profile/lib/debug}.
1773 @c XXX: keep me up-to-date
1774 The @code{debug} output mechanism in Guix is implemented by the
1775 @code{gnu-build-system} (@pxref{Defining Packages}). Currently, it is
1776 opt-in---debugging information is available only for those packages
1777 whose definition explicitly declares a @code{debug} output. This may be
1778 changed to opt-out in the future, if our build farm servers can handle
1779 the load. To check whether a package has a @code{debug} output, use
1780 @command{guix package --list-available} (@pxref{Invoking guix package}).
1783 @node Package Modules
1784 @section Package Modules
1786 From a programming viewpoint, the package definitions of the
1787 distribution are provided by Guile modules in the @code{(gnu packages
1788 ...)} name space (@pxref{Modules, Guile modules,, guile, GNU Guile
1789 Reference Manual}). For instance, the @code{(gnu packages emacs)}
1790 module exports a variable named @code{emacs}, which is bound to a
1791 @code{<package>} object (@pxref{Defining Packages}). The @code{(gnu
1792 packages)} module provides facilities for searching for packages.
1794 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
1795 each package is built based solely on other packages in the
1796 distribution. The root of this dependency graph is a small set of
1797 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
1798 bootstrap)} module. For more information on bootstrapping,
1799 @ref{Bootstrapping}.
1801 @node Packaging Guidelines
1802 @section Packaging Guidelines
1804 The GNU distribution is nascent and may well lack some of your favorite
1805 packages. This section describes how you can help make the distribution
1806 grow. @xref{Contributing}, for additional information on how you can
1809 Free software packages are usually distributed in the form of
1810 @dfn{source code tarballs}---typically @file{tar.gz} files that contain
1811 all the source files. Adding a package to the distribution means
1812 essentially two things: adding a @dfn{recipe} that describes how to
1813 build the package, including a list of other packages required to build
1814 it, and adding @dfn{package meta-data} along with that recipe, such as a
1815 description and licensing information.
1817 In Guix all this information is embodied in @dfn{package definitions}.
1818 Package definitions provide a high-level view of the package. They are
1819 written using the syntax of the Scheme programming language; in fact,
1820 for each package we define a variable bound to the package definition,
1821 and export that variable from a module (@pxref{Package Modules}).
1822 However, in-depth Scheme knowledge is @emph{not} a prerequisite for
1823 creating packages. For more information on package definitions,
1824 @ref{Defining Packages}.
1826 Once a package definition is in place, stored in a file in the Guix
1827 source tree, it can be tested using the @command{guix build} command
1828 (@pxref{Invoking guix build}). For example, assuming the new package is
1829 called @code{gnew}, you may run this command from the Guix build tree:
1832 ./pre-inst-env guix build gnew --keep-failed
1835 Using @code{--keep-failed} makes it easier to debug build failures since
1836 it provides access to the failed build tree.
1838 Once your package builds correctly, please send us a patch
1839 (@pxref{Contributing}). Well, if you need help, we will be happy to
1840 help you too. Once the patch is committed in the Guix repository, the
1841 new package automatically gets built on the supported platforms by
1842 @url{http://hydra.gnu.org/gnu/master, our continuous integration
1846 Users can obtain the new package definition simply by running
1847 @command{guix pull} (@pxref{Invoking guix pull}). When
1848 @code{hydra.gnu.org} is done building the package, installing the
1849 package automatically downloads binaries from there (except when using
1850 @code{--no-substitutes}). The only place where human intervention is
1851 needed is to review and apply the patch.
1855 * Software Freedom:: What may go into the distribution.
1856 * Package Naming:: What's in a name?
1857 * Version Numbers:: When the name is not enough.
1858 * Python Modules:: Taming the snake.
1861 @node Software Freedom
1862 @subsection Software Freedom
1864 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
1866 The GNU operating system has been developed so that users can have
1867 freedom in their computing. GNU is @dfn{free software}, meaning that
1868 users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
1869 essential freedoms}: to run the program, to study and change the program
1870 in source code form, to redistribute exact copies, and to distribute
1871 modified versions. Packages found in the GNU distribution provide only
1872 software that conveys these four freedoms.
1874 In addition, the GNU distribution follow the
1875 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
1876 software distribution guidelines}. Among other things, these guidelines
1877 reject non-free firmware, recommendations of non-free software, and
1878 discuss ways to deal with trademarks and patents.
1881 @node Package Naming
1882 @subsection Package Naming
1884 A package has actually two names associated with it:
1885 First, there is the name of the @emph{Scheme variable}, the one following
1886 @code{define-public}. By this name, the package can be made known in the
1887 Scheme code, for instance as input to another package. Second, there is
1888 the string in the @code{name} field of a package definition. This name
1889 is used by package management commands such as
1890 @command{guix package} and @command{guix build}.
1892 Both are usually the same and correspond to the lowercase conversion of the
1893 project name chosen upstream. For instance, the GNUnet project is packaged
1894 as @code{gnunet}. We do not add @code{lib} prefixes for library packages,
1895 unless these are already part of the official project name. But see
1896 @ref{Python Modules} for special rules concerning modules for
1897 the Python language.
1900 @node Version Numbers
1901 @subsection Version Numbers
1903 We usually package only the latest version of a given free software
1904 project. But sometimes, for instance for incompatible library versions,
1905 two (or more) versions of the same package are needed. These require
1906 different Scheme variable names. We use the name as defined
1907 in @ref{Package Naming}
1908 for the most recent version; previous versions use the same name, suffixed
1909 by @code{-} and the smallest prefix of the version number that may
1910 distinguish the two versions.
1912 The name inside the package definition is the same for all versions of a
1913 package and does not contain any version number.
1915 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
1923 (define-public gtk+-2
1929 If we also wanted GTK+ 3.8.2, this would be packaged as
1931 (define-public gtk+-3.8
1939 @node Python Modules
1940 @subsection Python Modules
1942 We currently package Python 2 and Python 3, under the Scheme variable names
1943 @code{python-2} and @code{python} as explained in @ref{Version Numbers}.
1944 To avoid confusion and naming clashes with other programming languages, it
1945 seems desirable that the name of a package for a Python module contains
1946 the word @code{python}.
1948 Some modules are compatible with only one version of Python, others with both.
1949 If the package Foo compiles only with Python 3, we name it
1950 @code{python-foo}; if it compiles only with Python 2, we name it
1951 @code{python2-foo}. If it is compatible with both versions, we create two
1952 packages with the corresponding names.
1954 If a project already contains the word @code{python}, we drop this;
1955 for instance, the module python-dateutil is packaged under the names
1956 @code{python-dateutil} and @code{python2-dateutil}.
1963 @section Bootstrapping
1965 @c Adapted from the ELS 2013 paper.
1967 @cindex bootstrapping
1969 Bootstrapping in our context refers to how the distribution gets built
1970 ``from nothing''. Remember that the build environment of a derivation
1971 contains nothing but its declared inputs (@pxref{Introduction}). So
1972 there's an obvious chicken-and-egg problem: how does the first package
1973 get built? How does the first compiler get compiled? Note that this is
1974 a question of interest only to the curious hacker, not to the regular
1975 user, so you can shamelessly skip this section if you consider yourself
1978 @cindex bootstrap binaries
1979 The GNU system is primarily made of C code, with libc at its core. The
1980 GNU build system itself assumes the availability of a Bourne shell and
1981 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
1982 `grep'. Furthermore, build programs---programs that run
1983 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
1984 (@pxref{Derivations}). Consequently, to be able to build anything at
1985 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
1986 Binutils, libc, and the other packages mentioned above---the
1987 @dfn{bootstrap binaries}.
1989 These bootstrap binaries are ``taken for granted'', though we can also
1990 re-create them if needed (more on that later).
1992 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
1994 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
1995 @c large image, it's hard to scroll. Oh well.
1996 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
1998 The figure above shows the very beginning of the dependency graph of the
1999 distribution, corresponding to the package definitions of the @code{(gnu
2000 packages bootstrap)} module. At this level of detail, things are
2001 slightly complex. First, Guile itself consists of an ELF executable,
2002 along with many source and compiled Scheme files that are dynamically
2003 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
2004 tarball shown in this graph. This tarball is part of Guix's ``source''
2005 distribution, and gets inserted into the store with @code{add-to-store}
2006 (@pxref{The Store}).
2008 But how do we write a derivation that unpacks this tarball and adds it
2009 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
2010 derivation---the first one that gets built---uses @code{bash} as its
2011 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
2012 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
2013 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
2014 the Guix source distribution, whose sole purpose is to allow the Guile
2015 tarball to be unpacked.
2017 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
2018 Guile that can be used to run subsequent build programs. Its first task
2019 is to download tarballs containing the other pre-built binaries---this
2020 is what the @code{.tar.xz.drv} derivations do. Guix modules such as
2021 @code{ftp-client.scm} are used for this purpose. The
2022 @code{module-import.drv} derivations import those modules in a directory
2023 in the store, using the original layout. The
2024 @code{module-import-compiled.drv} derivations compile those modules, and
2025 write them in an output directory with the right layout. This
2026 corresponds to the @code{#:modules} argument of
2027 @code{build-expression->derivation} (@pxref{Derivations}).
2029 Finally, the various tarballs are unpacked by the
2030 derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
2031 etc., at which point we have a working C tool chain.
2034 @unnumberedsubsec Building the Build Tools
2036 @c TODO: Add a package-level dependency graph generated from (gnu
2039 Bootstrapping is complete when we have a full tool chain that does not
2040 depend on the pre-built bootstrap tools discussed above. This
2041 no-dependency requirement is verified by checking whether the files of
2042 the final tool chain contain references to the @file{/nix/store}
2043 directories of the bootstrap inputs. The process that leads to this
2044 ``final'' tool chain is described by the package definitions found in
2045 the @code{(gnu packages base)} module.
2047 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
2048 The first tool that gets built with the bootstrap binaries is
2049 GNU Make, which is a prerequisite for all the following packages.
2050 From there Findutils and Diffutils get built.
2052 Then come the first-stage Binutils and GCC, built as pseudo cross
2053 tools---i.e., with @code{--target} equal to @code{--host}. They are
2054 used to build libc. Thanks to this cross-build trick, this libc is
2055 guaranteed not to hold any reference to the initial tool chain.
2057 From there the final Binutils and GCC are built. GCC uses @code{ld}
2058 from the final Binutils, and links programs against the just-built libc.
2059 This tool chain is used to build the other packages used by Guix and by
2060 the GNU Build System: Guile, Bash, Coreutils, etc.
2062 And voilà! At this point we have the complete set of build tools that
2063 the GNU Build System expects. These are in the @code{%final-inputs}
2064 variables of the @code{(gnu packages base)} module, and are implicitly
2065 used by any package that uses @code{gnu-build-system} (@pxref{Defining
2069 @unnumberedsubsec Building the Bootstrap Binaries
2071 Because the final tool chain does not depend on the bootstrap binaries,
2072 those rarely need to be updated. Nevertheless, it is useful to have an
2073 automated way to produce them, should an update occur, and this is what
2074 the @code{(gnu packages make-bootstrap)} module provides.
2076 The following command builds the tarballs containing the bootstrap
2077 binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
2078 of Coreutils and other basic command-line tools):
2081 guix build bootstrap-tarballs
2084 The generated tarballs are those that should be referred to in the
2085 @code{(gnu packages bootstrap)} module mentioned at the beginning of
2088 Still here? Then perhaps by now you've started to wonder: when do we
2089 reach a fixed point? That is an interesting question! The answer is
2090 unknown, but if you would like to investigate further (and have
2091 significant computational and storage resources to do so), then let us
2095 @section Porting to a New Platform
2097 As discussed above, the GNU distribution is self-contained, and
2098 self-containment is achieved by relying on pre-built ``bootstrap
2099 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
2100 operating system kernel, CPU architecture, and application binary
2101 interface (ABI). Thus, to port the distribution to a platform that is
2102 not yet supported, one must build those bootstrap binaries, and update
2103 the @code{(gnu packages bootstrap)} module to use them on that platform.
2105 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
2106 When everything goes well, and assuming the GNU tool chain supports the
2107 target platform, this can be as simple as running a command like this
2111 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
2114 In practice, there may be some complications. First, it may be that the
2115 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
2116 above) is not recognized by all the GNU tools. Typically, glibc
2117 recognizes some of these, whereas GCC uses an extra @code{--with-abi}
2118 configure flag (see @code{gcc.scm} for examples of how to handle this).
2119 Second, some of the required packages could fail to build for that
2120 platform. Lastly, the generated binaries could be broken for some
2124 @c *********************************************************************
2126 @chapter Contributing
2128 This project is a cooperative effort, and we need your help to make it
2129 grow! Please get in touch with us on @email{guix-devel@@gnu.org}. We
2130 welcome ideas, bug reports, patches, and anything that may be helpful to
2131 the project. We particularly welcome help on packaging
2132 (@pxref{Packaging Guidelines}).
2135 @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
2136 @file{HACKING} file} that comes with the Guix source code for practical
2137 details about contributions.
2140 @c *********************************************************************
2141 @node Acknowledgments
2142 @chapter Acknowledgments
2144 Guix is based on the Nix package manager, which was designed and
2145 implemented by Eelco Dolstra. Nix pioneered functional package
2146 management, and promoted unprecedented features, such as transactional
2147 package upgrades and rollbacks, per-user profiles, and referentially
2148 transparent build processes. Without this work, Guix would not exist.
2150 The Nix-based software distributions, Nixpkgs and NixOS, have also been
2151 an inspiration for Guix.
2153 @c *********************************************************************
2154 @node GNU Free Documentation License
2155 @appendix GNU Free Documentation License
2157 @include fdl-1.3.texi
2159 @c *********************************************************************
2161 @unnumbered Concept Index
2164 @node Function Index
2165 @unnumbered Function Index
2171 @c ispell-local-dictionary: "american";