Commit | Line | Data |
---|---|---|
568717fd LC |
1 | \input texinfo |
2 | @c -*-texinfo-*- | |
3 | ||
4 | @c %**start of header | |
5 | @setfilename guix.info | |
6 | @documentencoding UTF-8 | |
f8348b91 | 7 | @settitle GNU Guix Reference Manual |
568717fd LC |
8 | @c %**end of header |
9 | ||
10 | @include version.texi | |
11 | ||
eeaf4427 | 12 | @dircategory Package management |
568717fd LC |
13 | @direntry |
14 | * guix: (guix). Guix, the functional package manager. | |
eeaf4427 LC |
15 | * guix-package: (guix)Invoking guix-package |
16 | Managing packages with Guix. | |
568717fd LC |
17 | * guix-build: (guix)Invoking guix-build |
18 | Building packages with Guix. | |
19 | @end direntry | |
568717fd LC |
20 | |
21 | @titlepage | |
f8348b91 LC |
22 | @title{GNU Guix Reference Manual} |
23 | @subtitle{Using the GNU Guix Functional Package Manager} | |
568717fd LC |
24 | @author Ludovic Courtès |
25 | ||
26 | @page | |
27 | @vskip 0pt plus 1filll | |
28 | Edition @value{EDITION} @* | |
29 | @value{UPDATED} @* | |
30 | ||
31 | Copyright @copyright{} 2012 Ludovic Court@`es | |
32 | ||
33 | @quotation | |
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''. | |
40 | @end quotation | |
41 | @end titlepage | |
42 | ||
43 | @copying | |
f8348b91 | 44 | This manual documents GNU Guix version @value{VERSION}. |
568717fd LC |
45 | |
46 | Copyright (C) 2012 Ludovic Courtès | |
47 | ||
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.'' | |
54 | @end copying | |
55 | ||
56 | @contents | |
57 | ||
58 | @c ********************************************************************* | |
59 | @node Top | |
f8348b91 | 60 | @top GNU Guix |
568717fd | 61 | |
f8348b91 LC |
62 | This document describes GNU Guix version @value{VERSION}, a functional |
63 | package management tool written for the GNU system. | |
568717fd LC |
64 | |
65 | @menu | |
66 | * Introduction:: What is Guix about? | |
eeaf4427 | 67 | * Package Management:: Package installation, upgrade, etc. |
568717fd LC |
68 | * Programming Interface:: Using Guix in Scheme. |
69 | * Utilities:: Package management commands. | |
70 | ||
71 | * Acknowledgments:: Thanks! | |
72 | * GNU Free Documentation License:: The license of this manual. | |
73 | * Concept Index:: Concepts. | |
74 | * Function Index:: Functions. | |
75 | @end menu | |
76 | ||
77 | @c ********************************************************************* | |
78 | @node Introduction | |
79 | @chapter Introduction | |
80 | ||
f8348b91 LC |
81 | GNU Guix is a functional package management tool for the GNU system. |
82 | Package management consists in all the activities that relate to | |
83 | building packages from source, honoring the build-time and run-time | |
84 | dependencies on packages, installing packages in user environments, | |
85 | upgrading installed packages to new versions or rolling back to a | |
86 | previous set, removing unused software packages, etc. | |
568717fd LC |
87 | |
88 | @cindex functional package management | |
89 | The term @dfn{functional} refers to a specific package management | |
90 | discipline. In Guix, the package build and installation process is seen | |
91 | as a function, in the mathematical sense: that function takes inputs, | |
92 | such as build scripts, a compiler, and libraries depended on, and | |
93 | returns the installed package. As a pure function, its result depends | |
94 | solely on its inputs---for instance, it cannot refer to software or | |
95 | scripts that were not explicitly passed as inputs. A build function | |
96 | always produces the same result when passed a given set of inputs. Last | |
97 | but not least, a build function cannot alter the system's environment in | |
98 | any way; for instance, it cannot create, modify, or delete files outside | |
99 | of its build and installation directories. This is achieved by running | |
100 | build processes in dedicated ``chroots'', where only their explicit | |
101 | inputs are visible. | |
102 | ||
103 | @cindex package store | |
104 | The result of package build functions is @dfn{cached} in the file | |
105 | system, in a special directory called the @dfn{package store}. In | |
106 | practice, each package is installed in a directory of its own, in the | |
107 | store---by default under @file{/nix/store}. The directory name contains | |
108 | a hash of all the inputs used to build that package; thus, changing an | |
109 | input yields a different directory name. | |
110 | ||
111 | This approach is the foundation of Guix's salient features: support for | |
112 | transactional package upgrades and rollback, per-user installation, and | |
eeaf4427 | 113 | garbage collection of packages (@pxref{Features}). |
568717fd LC |
114 | |
115 | Guix has a command-line interface allowing users to build, install, | |
116 | upgrade, and remove packages, as well as a Scheme programming interface. | |
117 | The remainder of this manual describes them. | |
118 | ||
eeaf4427 LC |
119 | @c ********************************************************************* |
120 | @node Package Management | |
121 | @chapter Package Management | |
122 | ||
f8348b91 | 123 | The purpose of GNU Guix is to allow users to easily install, upgrade, and |
eeaf4427 LC |
124 | remove software packages, without having to know about their build |
125 | procedure or dependencies. Guix also goes beyond this obvious set of | |
126 | features. | |
127 | ||
128 | This chapter describes the main features of Guix, as well as the package | |
129 | management tools it provides. | |
130 | ||
131 | @menu | |
132 | * Features:: How Guix will make your life brighter. | |
133 | * Invoking guix-package:: Package installation, removal, etc. | |
134 | @end menu | |
135 | ||
136 | @node Features | |
137 | @section Features | |
138 | ||
139 | When using Guix, each package ends up in the @dfn{package store}, in its | |
140 | own directory---something that resembles | |
141 | @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string. | |
142 | ||
143 | Instead of referring to these directories, users have their own | |
144 | @dfn{profile}, which points to the packages that they actually want to | |
145 | use. That profile is normally stored in @code{$HOME/.guix-profile}, and | |
146 | each user has its own profile. | |
147 | ||
148 | For example, if @code{alice} installed GCC 4.7.2, then | |
149 | @file{/home/alice/.guix-profile/bin/gcc} points to | |
150 | @file{/nix/store/xxx-gcc-4.7.2/bin/gcc}; on the same machine, @code{bob} | |
151 | may have installed GCC 4.8.0, in which case its profile refers to these | |
152 | particular package installation. Both coexist, without any | |
153 | interference. | |
154 | ||
155 | The @command{guix-package} command is the central tool to manage | |
156 | packages. It operates on those per-user profiles, and can be used | |
157 | @emph{with normal user privileges}. | |
158 | ||
159 | The command provides the obvious install, remove, and upgrade | |
160 | operations. Each invocation is actually a @emph{transaction}: either | |
161 | the specified operations succeed, or nothing happens. Thus, if the | |
162 | @command{guix-package} processed is terminated during the transaction, | |
163 | or if a power outage occurs during the transaction, then the user's | |
164 | profile remains in its previous state, and remains usable. | |
165 | ||
166 | In addition, any package transaction may be @emph{rolled back}. So, if, | |
167 | for example, an upgrade installs a new version of a package that turns | |
168 | out to have a serious bug, users may roll back to the previous instance | |
169 | of their profile, which was known to work well. | |
170 | ||
171 | All those packages in the package store may be @emph{garbage-collected}. | |
172 | Guix can determine which packages are still referenced by the user | |
173 | profiles, and remove those that are provably no longer referenced. | |
174 | Users may also explicitly remove old generations of their profile so | |
175 | that the packages they refer to can be collected. | |
176 | ||
177 | Finally, Guix takes a @dfn{purely functional} approach to package | |
178 | management, as described in the introduction (@pxref{Introduction}). | |
179 | Each @file{/nix/store} package directory name contains a hash of all the | |
180 | inputs that were used to build that package---compiler, libraries, build | |
181 | scripts, etc. This direct correspondence allows users to make sure a | |
182 | given package installation matches the current state of their | |
183 | distribution. | |
184 | ||
185 | This foundation allows Guix to support @dfn{transparent binary/source | |
186 | deployment}. When a pre-built binary for a @file{/nix/store} path is | |
187 | available from an external source, Guix just downloads it; otherwise, it | |
188 | builds the package from source, locally. | |
189 | ||
190 | @node Invoking guix-package | |
191 | @section Invoking @command{guix-package} | |
192 | ||
193 | The @command{guix-package} command it the tool that allows users to | |
194 | install, upgrade, and remove packages, as well as rolling back to | |
195 | previous configurations. It operates only on the user's own profile, | |
196 | and works with normal user privileges (@pxref{Features}). Its syntax | |
197 | is: | |
198 | ||
199 | @example | |
200 | guix-package @var{options} | |
201 | @end example | |
202 | ||
203 | Primarily, @var{options} specify the operations to be performed during | |
204 | the transaction. Upon completion, a new profile is created, but | |
205 | previous generations of the profile remain available, should the user | |
206 | want to roll back. | |
207 | ||
208 | @table @code | |
209 | ||
210 | @item --install=@var{package} | |
211 | @itemx -x @var{package} | |
212 | Install @var{package}. | |
213 | ||
214 | @var{package} may specify either a simple package name, such as | |
215 | @code{guile}, or a package name followed by a hyphen and version number, | |
216 | such as @code{guile-1.8}. In addition, @var{package} may contain a | |
217 | colon, followed by the name of one of the outputs of the package, as in | |
218 | @code{gcc:doc} or @code{libsigsegv-2.10:lib}. | |
219 | ||
220 | @item --remove=@var{package} | |
221 | @itemx -r @var{package} | |
222 | Remove @var{package}. | |
223 | ||
224 | @item --upgrade=@var{REGEXP} | |
225 | @itemx -u @var{REGEXP} | |
226 | Upgrade all the installed packages matching @var{regexp}. | |
227 | ||
228 | @item --profile=@var{profile} | |
229 | @itemx -p @var{profile} | |
230 | Use @var{profile} instead of the user's default profile. | |
231 | ||
232 | @item --dry-run | |
233 | @itemx -n | |
234 | Show what would be done without actually doing it. | |
235 | ||
236 | @item --bootstrap | |
237 | Use the bootstrap Guile to build the profile. This option is only | |
238 | useful to distribution developers. | |
239 | ||
240 | @end table | |
241 | ||
242 | ||
243 | ||
244 | ||
245 | ||
568717fd LC |
246 | @c ********************************************************************* |
247 | @node Programming Interface | |
248 | @chapter Programming Interface | |
249 | ||
250 | @menu | |
251 | * Defining Packages:: Defining new packages. | |
252 | * The Store:: Manipulating the package store. | |
253 | * Derivations:: Low-level interface to package derivations. | |
254 | @end menu | |
255 | ||
256 | @node Defining Packages | |
257 | @section Defining Packages | |
258 | ||
259 | @code{(guix packages)} and @code{(guix build-system)} | |
260 | ||
261 | @node The Store | |
262 | @section The Store | |
263 | ||
264 | @code{(guix store)} | |
265 | ||
266 | @node Derivations | |
267 | @section Derivations | |
268 | ||
269 | @code{(guix derivations)} | |
270 | ||
271 | @c ********************************************************************* | |
272 | @node Utilities | |
273 | @chapter Utilities | |
274 | ||
275 | @menu | |
276 | * Invoking guix-build:: Building packages from the command line. | |
277 | @end menu | |
278 | ||
279 | @node Invoking guix-build | |
280 | @section Invoking @command{guix-build} | |
281 | ||
c78bd12b LC |
282 | The @command{guix-build} command builds packages or derivations and |
283 | their dependencies, and prints the resulting store paths. It is mainly | |
284 | useful for distribution developers. The general syntax is: | |
285 | ||
286 | @example | |
287 | guix-build @var{options} @var{package-or-derivation}@dots{} | |
288 | @end example | |
289 | ||
290 | @var{package-or-derivation} may be either the name of a package found in | |
291 | the software distribution such as @code{coreutils}, or a derivation such | |
292 | as @file{/nix/store/xxx-coreutils-8.19.drv}. Alternatively, the | |
293 | @code{--expression} option may be used to specify a Scheme expression | |
294 | that evaluates to a package; this is useful when disambiguation among | |
295 | several same-named packages or package variants is needed. | |
296 | ||
297 | The @var{options} may be zero or more of the following: | |
298 | ||
299 | @table @code | |
300 | ||
301 | @item --expression=@var{expr} | |
302 | @itemx -e @var{expr} | |
303 | Build the package @var{expr} evaluates to. | |
304 | ||
305 | For example, @var{expr} may be @code{(@@ (distro packages guile) | |
306 | guile-1.8)}, which unambiguously designates this specific variant of | |
307 | version 1.8 of Guile. | |
308 | ||
309 | @item --source | |
310 | @itemx -S | |
311 | Build the packages' source derivations, rather than the packages | |
312 | themselves. | |
313 | ||
314 | For instance, @code{guix-build -S gcc} returns something like | |
315 | @file{/nix/store/xxx-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. | |
316 | ||
317 | @item --system=@var{system} | |
318 | @itemx -s @var{system} | |
319 | Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of | |
320 | the host's system type. | |
321 | ||
322 | An example use of this is on Linux-based systems, which can emulate | |
323 | different personalities. For instance, passing | |
324 | @code{--system=i686-linux} on an @code{x86_64-linux} system allows users | |
325 | to build packages in a complete 32-bit environment. | |
326 | ||
327 | @item --derivations | |
328 | @itemx -d | |
329 | Return the derivation paths, not the output paths, of the given | |
330 | packages. | |
331 | ||
332 | @item --keep-failed | |
333 | @itemx -K | |
334 | Keep the build tree of failed builds. Thus, if a build fail, its build | |
335 | tree is kept under @file{/tmp}, in a directory whose name is shown at | |
336 | the end of the build log. This is useful when debugging build issues. | |
337 | ||
338 | @item --dry-run | |
339 | @itemx -n | |
340 | Do not build the derivations. | |
341 | ||
342 | @item --no-substitutes | |
343 | Build instead of resorting to pre-built substitutes. | |
344 | ||
345 | @item --cores=@var{n} | |
346 | @itemx -c @var{n} | |
347 | Allow the use of up to @var{n} CPU cores for the build. The special | |
348 | value @code{0} means to use as many CPU cores as available. | |
349 | ||
350 | @item --root=@var{file} | |
351 | @itemx -r @var{file} | |
352 | Make @var{file} a symlink to the result, and register it as a garbage | |
353 | collector root. | |
354 | @end table | |
355 | ||
356 | Behind the scenes, @command{guix-build} is essentially an interface to | |
357 | the @code{package-derivation} procedure of the @code{(guix packages)} | |
358 | module, and to the @code{build-derivations} procedure of the @code{(guix | |
359 | store)} module. | |
360 | ||
361 | ||
568717fd LC |
362 | @c ********************************************************************* |
363 | @node Acknowledgments | |
364 | @chapter Acknowledgments | |
365 | ||
366 | Guix is based on the Nix package manager, which was designed and | |
367 | implemented by Eelco Dolstra. Nix pioneered functional package | |
368 | management, and promoted unprecedented features, such as transactional | |
369 | package upgrades and rollbacks, per-user profiles, and referentially | |
370 | transparent build processes. Without this work, Guix would not exist. | |
371 | ||
372 | The Nix-based software distributions, Nixpkgs and NixOS, have also been | |
373 | an inspiration for Guix. | |
374 | ||
375 | @c ********************************************************************* | |
376 | @node GNU Free Documentation License | |
377 | @appendix GNU Free Documentation License | |
378 | ||
379 | @include fdl-1.3.texi | |
380 | ||
381 | @c ********************************************************************* | |
382 | @node Concept Index | |
383 | @unnumbered Concept Index | |
384 | @printindex cp | |
385 | ||
386 | @node Function Index | |
387 | @unnumbered Function Index | |
388 | @printindex fn | |
389 | ||
390 | @bye | |
391 | ||
392 | @c Local Variables: | |
393 | @c ispell-local-dictionary: "american"; | |
394 | @c End: |