6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
12 @dircategory Package management
14 * guix: (guix). Guix, the functional package manager.
15 * guix-package: (guix)Invoking guix-package
16 Managing packages with Guix.
17 * guix-build: (guix)Invoking guix-build
18 Building packages with Guix.
22 @title{GNU Guix Reference Manual}
23 @subtitle{Using the GNU Guix Functional Package Manager}
24 @author Ludovic Courtès
27 @vskip 0pt plus 1filll
28 Edition @value{EDITION} @*
31 Copyright @copyright{} 2012 Ludovic Court@`es
34 Permission is granted to copy, distribute and/or modify this document
35 under the terms of the GNU Free Documentation License, Version 1.3 or
36 any later version published by the Free Software Foundation; with no
37 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
38 copy of the license is included in the section entitled ``GNU Free
39 Documentation License''.
44 This manual documents GNU Guix version @value{VERSION}.
46 Copyright (C) 2012 Ludovic Courtès
48 Permission is granted to copy, distribute and/or modify this document
49 under the terms of the GNU Free Documentation License, Version 1.3 or
50 any later version published by the Free Software Foundation; with no
51 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
52 copy of the license is included in the section entitled ``GNU Free
53 Documentation License.''
58 @c *********************************************************************
62 This document describes GNU Guix version @value{VERSION}, a functional
63 package management tool written for the GNU system.
66 * Introduction:: What is Guix about?
67 * Package Management:: Package installation, upgrade, etc.
68 * Programming Interface:: Using Guix in Scheme.
69 * Utilities:: Package management commands.
71 * Acknowledgments:: Thanks!
72 * GNU Free Documentation License:: The license of this manual.
73 * Concept Index:: Concepts.
74 * Function Index:: Functions.
77 @c *********************************************************************
81 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
82 using the international phonetic alphabet (IPA).} is a functional
83 package management tool for the GNU system. Package management consists
84 in all the activities that relate to building packages from source,
85 honoring the build-time and run-time dependencies on packages,
86 installing packages in user environments, upgrading installed packages
87 to new versions or rolling back to a previous set, removing unused
88 software packages, etc.
90 @cindex functional package management
91 The term @dfn{functional} refers to a specific package management
92 discipline. In Guix, the package build and installation process is seen
93 as a function, in the mathematical sense: that function takes inputs,
94 such as build scripts, a compiler, and libraries depended on, and
95 returns the installed package. As a pure function, its result depends
96 solely on its inputs---for instance, it cannot refer to software or
97 scripts that were not explicitly passed as inputs. A build function
98 always produces the same result when passed a given set of inputs. Last
99 but not least, a build function cannot alter the system's environment in
100 any way; for instance, it cannot create, modify, or delete files outside
101 of its build and installation directories. This is achieved by running
102 build processes in dedicated ``chroots'', where only their explicit
105 @cindex package store
106 The result of package build functions is @dfn{cached} in the file
107 system, in a special directory called the @dfn{package store}. In
108 practice, each package is installed in a directory of its own, in the
109 store---by default under @file{/nix/store}. The directory name contains
110 a hash of all the inputs used to build that package; thus, changing an
111 input yields a different directory name.
113 This approach is the foundation of Guix's salient features: support for
114 transactional package upgrades and rollback, per-user installation, and
115 garbage collection of packages (@pxref{Features}).
117 Guix has a command-line interface allowing users to build, install,
118 upgrade, and remove packages, as well as a Scheme programming interface.
119 The remainder of this manual describes them.
121 @c *********************************************************************
122 @node Package Management
123 @chapter Package Management
125 The purpose of GNU Guix is to allow users to easily install, upgrade, and
126 remove software packages, without having to know about their build
127 procedure or dependencies. Guix also goes beyond this obvious set of
130 This chapter describes the main features of Guix, as well as the package
131 management tools it provides.
134 * Features:: How Guix will make your life brighter.
135 * Invoking guix-package:: Package installation, removal, etc.
141 When using Guix, each package ends up in the @dfn{package store}, in its
142 own directory---something that resembles
143 @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
145 Instead of referring to these directories, users have their own
146 @dfn{profile}, which points to the packages that they actually want to
147 use. That profile is normally stored in @code{$HOME/.guix-profile}, and
148 each user has its own profile.
150 For example, if @code{alice} installed GCC 4.7.2, then
151 @file{/home/alice/.guix-profile/bin/gcc} points to
152 @file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob}
153 may have installed GCC 4.8.0, in which case its profile refers to these
154 particular package installation. Both coexist, without any
157 The @command{guix-package} command is the central tool to manage
158 packages. It operates on those per-user profiles, and can be used
159 @emph{with normal user privileges}.
161 The command provides the obvious install, remove, and upgrade
162 operations. Each invocation is actually a @emph{transaction}: either
163 the specified operation succeeds, or nothing happens. Thus, if the
164 @command{guix-package} processed is terminated during the transaction,
165 or if a power outage occurs during the transaction, then the user's
166 profile remains in its previous state, and remains usable.
168 In addition, any package transaction may be @emph{rolled back}. So, if,
169 for example, an upgrade installs a new version of a package that turns
170 out to have a serious bug, users may roll back to the previous instance
171 of their profile, which was known to work well.
173 All those packages in the package store may be @emph{garbage-collected}.
174 Guix can determine which packages are still referenced by the user
175 profiles, and remove those that are provably no longer referenced.
176 Users may also explicitly remove old generations of their profile so
177 that the packages they refer to can be collected.
179 Finally, Guix takes a @dfn{purely functional} approach to package
180 management, as described in the introduction (@pxref{Introduction}).
181 Each @file{/nix/store} package directory name contains a hash of all the
182 inputs that were used to build that package---compiler, libraries, build
183 scripts, etc. This direct correspondence allows users to make sure a
184 given package installation matches the current state of their
187 This foundation allows Guix to support @dfn{transparent binary/source
188 deployment}. When a pre-built binary for a @file{/nix/store} path is
189 available from an external source, Guix just downloads it; otherwise, it
190 builds the package from source, locally.
192 @node Invoking guix-package
193 @section Invoking @command{guix-package}
195 The @command{guix-package} command is the tool that allows users to
196 install, upgrade, and remove packages, as well as rolling back to
197 previous configurations. It operates only on the user's own profile,
198 and works with normal user privileges (@pxref{Features}). Its syntax
202 guix-package @var{options}
205 Primarily, @var{options} specifies the operations to be performed during
206 the transaction. Upon completion, a new profile is created, but
207 previous generations of the profile remain available, should the user
212 @item --install=@var{package}
213 @itemx -i @var{package}
214 Install @var{package}.
216 @var{package} may specify either a simple package name, such as
217 @code{guile}, or a package name followed by a hyphen and version number,
218 such as @code{guile-1.8}. In addition, @var{package} may contain a
219 colon, followed by the name of one of the outputs of the package, as in
220 @code{gcc:doc} or @code{libsigsegv-2.10:lib}.
222 @item --remove=@var{package}
223 @itemx -r @var{package}
224 Remove @var{package}.
226 @item --upgrade=@var{regexp}
227 @itemx -u @var{regexp}
228 Upgrade all the installed packages matching @var{regexp}.
230 @item --profile=@var{profile}
231 @itemx -p @var{profile}
232 Use @var{profile} instead of the user's default profile.
236 Show what would be done without actually doing it.
239 Use the bootstrap Guile to build the profile. This option is only
240 useful to distribution developers.
244 In addition to these actions @command{guix-package} supports the
245 following options to query the current state of a profile, or the
246 availability of packages:
250 @item --list-installed[=@var{regexp}]
251 @itemx -I [@var{regexp}]
252 List currently installed packages in the specified profile. When
253 @var{regexp} is specified, list only installed packages whose name
254 matches @var{regexp}.
256 For each installed package, print the following items, separated by
257 tabs: the package name, its version string, the part of the package that
258 is installed (for instance, @code{out} for the default output,
259 @code{include} for its headers, etc.), and the path of this package in
262 @item --list-available[=@var{regexp}]
263 @itemx -A [@var{regexp}]
264 List packages currently available in the software distribution. When
265 @var{regexp} is specified, list only installed packages whose name
266 matches @var{regexp}.
268 For each package, print the following items separated by tabs: its name,
269 its version string, and the source location of its definition.
275 @c *********************************************************************
276 @node Programming Interface
277 @chapter Programming Interface
279 GNU Guix provides several Scheme programming interfaces (APIs) to
280 define, build, and query packages. The first interface allows users to
281 write high-level package definitions. These definitions refer to
282 familiar packaging concepts, such as the name and version of a package,
283 its build system, and its dependencies. These definitions can then be
284 turned into concrete build actions.
286 Build actions are performed by the Guix daemon, on behalf of users. In a
287 standard setup, the daemon has write access to the store---the
288 @file{/nix/store} directory---whereas users do not. The recommended
289 setup also has the daemon perform builds in chroots, under a specific
290 build users, to minimize interference with the rest of the system.
293 Lower-level APIs are available to interact with the daemon and the
294 store. To instruct the daemon to perform a build action, users actually
295 provide it with a @dfn{derivation}. A derivation is a low-level
296 representation of the build actions to be taken, and the environment in
297 which they should occur---derivations are to package definitions what
298 assembly is to C programs.
300 This chapter describes all these APIs in turn, starting from high-level
304 * Defining Packages:: Defining new packages.
305 * The Store:: Manipulating the package store.
306 * Derivations:: Low-level interface to package derivations.
309 @node Defining Packages
310 @section Defining Packages
312 The high-level interface to package definitions is implemented in the
313 @code{(guix packages)} and @code{(guix build-system)} modules. As an
314 example, the package definition, or @dfn{recipe}, for the GNU Hello
315 package looks like this:
324 (uri (string-append "mirror://gnu/hello/hello-" version
327 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
328 (build-system gnu-build-system)
329 (inputs `(("gawk" ,gawk)))
330 (synopsis "GNU Hello")
331 (description "Yeah...")
332 (home-page "http://www.gnu.org/software/hello/")
337 Without being a Scheme expert, the reader may have guessed the meaning
338 of the various fields here. This expression binds variable @var{hello}
339 to a @code{<package>} object, which is essentially a record
340 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
341 This package object can be inspected using procedures found in the
342 @code{(guix packages)} module; for instance, @code{(package-name hello)}
343 returns---surprise!---@code{"hello"}.
345 There are a few points worth noting in the above package definition:
349 The @code{source} field of the package is an @code{<origin>} object.
350 Here, the @code{url-fetch} method from @code{(guix download)} is used,
351 meaning that the source is a file to be downloaded over FTP or HTTP.
353 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
354 the GNU mirrors defined in @code{(guix download)}.
356 The @code{sha256} field specifies the expected SHA256 hash of the file
357 being downloaded. It is mandatory, and allows Guix to check the
358 integrity of the file. The @code{(base32 @dots{})} form introduces the
359 base32 representation of the hash. A convenient way to obtain this
360 information is with the @code{guix-download} tool.
363 @cindex GNU Build System
364 The @code{build-system} field is set to @var{gnu-build-system}. The
365 @var{gnu-build-system} variable is defined in the @code{(guix
366 build-system gnu)} module, and is bound to a @code{<build-system>}
369 Naturally, @var{gnu-build-system} represents the familiar GNU Build
370 System, and variants thereof (@pxref{Configuration, configuration and
371 makefile conventions,, standards, GNU Coding Standards}). In a
372 nutshell, packages using the GNU Build System may be configured, built,
373 and installed with the usual @code{./configure && make && make check &&
374 make install} command sequence. This is what @var{gnu-build-system}
377 In addition, @var{gnu-build-system} ensures that the ``standard''
378 environment for GNU packages is available. This includes tools such as
379 GCC, Coreutils, Bash, Make, Diffutils, and Patch.
382 The @code{inputs} field specifies inputs to the build process---i.e.,
383 build-time or run-time dependencies of the package. Here, we define an
384 input called @code{"gawk"} whose value is that of the @var{gawk}
385 variable; @var{gawk} is itself bound to a @code{<package>} object.
387 Note that GCC, Coreutils, Bash, and other essential tools do not need to
388 be specified as inputs here. Instead, @var{gnu-build-system} takes care
389 of ensuring that they are present.
391 However, any other dependencies need to be specified in the
392 @code{inputs} field. Any dependency not specified here will simply be
393 unavailable to the build process, possibly leading to a build failure.
396 There are other fields that package definitions may provide. Of
397 particular interest is the @code{arguments} field. When specified, it
398 must be bound to a list of additional arguments to be passed to the
399 build system. For instance, the above definition could be augmented
400 with the following field initializer:
403 (arguments `(#:tests? #f
404 #:configure-flags '("--enable-silent-rules")))
408 These are keyword arguments (@pxref{Optional Arguments, keyword
409 arguments in Guile,, guile, GNU Guile Reference Manual}). They are
410 passed to @var{gnu-build-system}, which interprets them as meaning ``do
411 not run @code{make check}'', and ``run @file{configure} with the
412 @code{--enable-silent-rules} flag''.
414 Once a package definition is in place@footnote{Simple package
415 definitions like the one above may be automatically converted from the
416 Nixpkgs distribution using the @command{guix-import} command.}, the
417 package may actually be built using the @code{guix-build} command-line
418 tool (@pxref{Invoking guix-build}).
420 Behind the scenes, a derivation corresponding to the @code{<package>}
421 object is first computed by the @code{package-derivation} procedure.
422 That derivation is stored in a @code{.drv} file under @file{/nix/store}.
423 The build actions it prescribes may then be realized by using the
424 @code{build-derivations} procedure (@pxref{The Store}).
426 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
427 Return the derivation of @var{package} for @var{system}. The result is
428 the file name of the derivation---i.e., a @code{.drv} file under
431 @var{package} must be a valid @code{<package>} object, and @var{system}
432 must be a string denoting the target system type---e.g.,
433 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
434 must be a connection to the daemon, which operates on the store
446 @code{(guix derivations)}
448 @c *********************************************************************
453 * Invoking guix-build:: Building packages from the command line.
456 @node Invoking guix-build
457 @section Invoking @command{guix-build}
459 The @command{guix-build} command builds packages or derivations and
460 their dependencies, and prints the resulting store paths. It is mainly
461 useful for distribution developers. The general syntax is:
464 guix-build @var{options} @var{package-or-derivation}@dots{}
467 @var{package-or-derivation} may be either the name of a package found in
468 the software distribution such as @code{coreutils}, or a derivation such
469 as @file{/nix/store/xxx-coreutils-8.19.drv}. Alternatively, the
470 @code{--expression} option may be used to specify a Scheme expression
471 that evaluates to a package; this is useful when disambiguation among
472 several same-named packages or package variants is needed.
474 The @var{options} may be zero or more of the following:
478 @item --expression=@var{expr}
480 Build the package @var{expr} evaluates to.
482 For example, @var{expr} may be @code{(@@ (distro packages guile)
483 guile-1.8)}, which unambiguously designates this specific variant of
484 version 1.8 of Guile.
488 Build the packages' source derivations, rather than the packages
491 For instance, @code{guix-build -S gcc} returns something like
492 @file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
494 @item --system=@var{system}
495 @itemx -s @var{system}
496 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
497 the host's system type.
499 An example use of this is on Linux-based systems, which can emulate
500 different personalities. For instance, passing
501 @code{--system=i686-linux} on an @code{x86_64-linux} system allows users
502 to build packages in a complete 32-bit environment.
506 Return the derivation paths, not the output paths, of the given
511 Keep the build tree of failed builds. Thus, if a build fail, its build
512 tree is kept under @file{/tmp}, in a directory whose name is shown at
513 the end of the build log. This is useful when debugging build issues.
517 Do not build the derivations.
519 @item --no-substitutes
520 Build instead of resorting to pre-built substitutes.
522 @item --cores=@var{n}
524 Allow the use of up to @var{n} CPU cores for the build. The special
525 value @code{0} means to use as many CPU cores as available.
527 @item --root=@var{file}
529 Make @var{file} a symlink to the result, and register it as a garbage
533 Behind the scenes, @command{guix-build} is essentially an interface to
534 the @code{package-derivation} procedure of the @code{(guix packages)}
535 module, and to the @code{build-derivations} procedure of the @code{(guix
539 @c *********************************************************************
540 @node Acknowledgments
541 @chapter Acknowledgments
543 Guix is based on the Nix package manager, which was designed and
544 implemented by Eelco Dolstra. Nix pioneered functional package
545 management, and promoted unprecedented features, such as transactional
546 package upgrades and rollbacks, per-user profiles, and referentially
547 transparent build processes. Without this work, Guix would not exist.
549 The Nix-based software distributions, Nixpkgs and NixOS, have also been
550 an inspiration for Guix.
552 @c *********************************************************************
553 @node GNU Free Documentation License
554 @appendix GNU Free Documentation License
556 @include fdl-1.3.texi
558 @c *********************************************************************
560 @unnumbered Concept Index
564 @unnumbered Function Index
570 @c ispell-local-dictionary: "american";