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