| 1 | \input texinfo |
| 2 | @c -*-texinfo-*- |
| 3 | |
| 4 | @c %**start of header |
| 5 | @setfilename guix.info |
| 6 | @documentencoding UTF-8 |
| 7 | @settitle GNU Guix Reference Manual |
| 8 | @c %**end of header |
| 9 | |
| 10 | @include version.texi |
| 11 | @set YEARS 2012, 2013 |
| 12 | |
| 13 | @dircategory Package management |
| 14 | @direntry |
| 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. |
| 20 | @end direntry |
| 21 | |
| 22 | @titlepage |
| 23 | @title GNU Guix Reference Manual |
| 24 | @subtitle Using the GNU Guix Functional Package Manager |
| 25 | @author Ludovic Courtès |
| 26 | @author Nikita Karetnikov |
| 27 | |
| 28 | @page |
| 29 | @vskip 0pt plus 1filll |
| 30 | Edition @value{EDITION} @* |
| 31 | @value{UPDATED} @* |
| 32 | |
| 33 | Copyright @copyright{} @value{YEARS} Ludovic Court@`es |
| 34 | |
| 35 | @quotation |
| 36 | Permission is granted to copy, distribute and/or modify this document |
| 37 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 38 | any later version published by the Free Software Foundation; with no |
| 39 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 40 | copy of the license is included in the section entitled ``GNU Free |
| 41 | Documentation License''. |
| 42 | @end quotation |
| 43 | @end titlepage |
| 44 | |
| 45 | @copying |
| 46 | This manual documents GNU Guix version @value{VERSION}. |
| 47 | |
| 48 | Copyright @copyright{} @value{YEARS} Ludovic Courtès |
| 49 | |
| 50 | Permission is granted to copy, distribute and/or modify this document |
| 51 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 52 | any later version published by the Free Software Foundation; with no |
| 53 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 54 | copy of the license is included in the section entitled ``GNU Free |
| 55 | Documentation License.'' |
| 56 | @end copying |
| 57 | |
| 58 | @contents |
| 59 | |
| 60 | @c ********************************************************************* |
| 61 | @node Top |
| 62 | @top GNU Guix |
| 63 | |
| 64 | This document describes GNU Guix version @value{VERSION}, a functional |
| 65 | package management tool written for the GNU system. |
| 66 | |
| 67 | @quotation |
| 68 | Copyright @copyright{} @value{YEARS} Ludovic Courtès |
| 69 | |
| 70 | Permission is granted to copy, distribute and/or modify this document |
| 71 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 72 | any later version published by the Free Software Foundation; with no |
| 73 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 74 | copy of the license is included in the section entitled ``GNU Free |
| 75 | Documentation License.'' |
| 76 | @end quotation |
| 77 | |
| 78 | @menu |
| 79 | * Introduction:: What is Guix about? |
| 80 | * Installation:: Installing Guix. |
| 81 | * Package Management:: Package installation, upgrade, etc. |
| 82 | * Programming Interface:: Using Guix in Scheme. |
| 83 | * Utilities:: Package management commands. |
| 84 | * GNU Distribution:: Software for your friendly GNU system. |
| 85 | |
| 86 | * Acknowledgments:: Thanks! |
| 87 | * GNU Free Documentation License:: The license of this manual. |
| 88 | * Concept Index:: Concepts. |
| 89 | * Function Index:: Functions. |
| 90 | @end menu |
| 91 | |
| 92 | @c ********************************************************************* |
| 93 | @node Introduction |
| 94 | @chapter Introduction |
| 95 | |
| 96 | GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' |
| 97 | using the international phonetic alphabet (IPA).} is a functional |
| 98 | package management tool for the GNU system. Package management consists |
| 99 | in all the activities that relate to building packages from source, |
| 100 | honoring the build-time and run-time dependencies on packages, |
| 101 | installing packages in user environments, upgrading installed packages |
| 102 | to new versions or rolling back to a previous set, removing unused |
| 103 | software packages, etc. |
| 104 | |
| 105 | @cindex functional package management |
| 106 | The term @dfn{functional} refers to a specific package management |
| 107 | discipline. In Guix, the package build and installation process is seen |
| 108 | as a function, in the mathematical sense: that function takes inputs, |
| 109 | such as build scripts, a compiler, and libraries depended on, and |
| 110 | returns the installed package. As a pure function, its result depends |
| 111 | solely on its inputs---for instance, it cannot refer to software or |
| 112 | scripts that were not explicitly passed as inputs. A build function |
| 113 | always produces the same result when passed a given set of inputs. Last |
| 114 | but not least, a build function cannot alter the system's environment in |
| 115 | any way; for instance, it cannot create, modify, or delete files outside |
| 116 | of its build and installation directories. This is achieved by running |
| 117 | build processes in dedicated ``chroots'', where only their explicit |
| 118 | inputs are visible. |
| 119 | |
| 120 | @cindex store |
| 121 | The result of package build functions is @dfn{cached} in the file |
| 122 | system, in a special directory called @dfn{the store} (@pxref{The |
| 123 | Store}). Each package is installed in a directory of its own, in the |
| 124 | store---by default under @file{/nix/store}. The directory name contains |
| 125 | a hash of all the inputs used to build that package; thus, changing an |
| 126 | input yields a different directory name. |
| 127 | |
| 128 | This approach is the foundation of Guix's salient features: support for |
| 129 | transactional package upgrades and rollback, per-user installation, and |
| 130 | garbage collection of packages (@pxref{Features}). |
| 131 | |
| 132 | Guix has a command-line interface allowing users to build, install, |
| 133 | upgrade, and remove packages, as well as a Scheme programming interface. |
| 134 | The remainder of this manual describes them. |
| 135 | |
| 136 | Last but not least, Guix is used to build a distribution of the GNU |
| 137 | system, with many GNU and non-GNU free software packages. @xref{GNU |
| 138 | Distribution}. |
| 139 | |
| 140 | @c ********************************************************************* |
| 141 | @node Installation |
| 142 | @chapter Installation |
| 143 | |
| 144 | This section describes the software requirements of Guix, as well as how |
| 145 | to install it and get ready to use it. |
| 146 | |
| 147 | The build procedure for Guix is the same as for other GNU software, and |
| 148 | is not covered here. Please see the files @file{README} and |
| 149 | @file{INSTALL} in the Guix source tree for additional details. |
| 150 | |
| 151 | @menu |
| 152 | * Requirements:: Software needed to build and run Guix. |
| 153 | * Setting Up the Daemon:: Preparing the build daemon's environment. |
| 154 | * Invoking guix-daemon:: Running the build daemon. |
| 155 | @end menu |
| 156 | |
| 157 | @node Requirements |
| 158 | @section Requirements |
| 159 | |
| 160 | GNU Guix depends on the following packages: |
| 161 | |
| 162 | @itemize |
| 163 | @item @url{http://gnu.org/software/guile/, GNU Guile 2.0.x}; |
| 164 | @item @url{http://gnupg.org/, GNU libgcrypt} |
| 165 | @end itemize |
| 166 | |
| 167 | Unless @code{--disable-daemon} was passed to @command{configure}, the |
| 168 | following packages are also needed: |
| 169 | |
| 170 | @itemize |
| 171 | @item @url{http://sqlite.org, SQLite 3} |
| 172 | @item @url{http://www.bzip.org, libbz2} |
| 173 | @item @url{http://gcc.gnu.org, GCC's g++} |
| 174 | @end itemize |
| 175 | |
| 176 | When a working installation of the Nix package manager is available, you |
| 177 | can instead configure Guix with @code{--disable-daemon}. In that case, |
| 178 | @url{http://nixos.org/nix/, Nix} replaces the three dependencies above. |
| 179 | |
| 180 | Guix is compatible with Nix, so it is possible to share the same store |
| 181 | between both. To do so, you must pass @command{configure} not only the |
| 182 | same @code{--with-store-dir} value, but also the same |
| 183 | @code{--localstatedir} value (the latter is essential because it |
| 184 | specifies where the database that store meta-data about the store is |
| 185 | located, among other things.) The default values are |
| 186 | @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}. |
| 187 | Note that @code{--disable-daemon} is orthogonal and is not required if |
| 188 | your goal is to share the same store as Nix. |
| 189 | |
| 190 | @node Setting Up the Daemon |
| 191 | @section Setting Up the Daemon |
| 192 | |
| 193 | @cindex daemon |
| 194 | Operations such as building a package or running the garbage collector |
| 195 | are all performed by a specialized process, the @dfn{Guix daemon}, on |
| 196 | behalf of clients. Only the daemon may access the store and its |
| 197 | associated database. Thus, any operation that manipulates the store |
| 198 | goes through the daemon. For instance, command-line tools such as |
| 199 | @command{guix package} and @command{guix build} communicate with the |
| 200 | daemon (@i{via} remote procedure calls) to instruct it what to do. |
| 201 | |
| 202 | In a standard multi-user setup, Guix and its daemon---the |
| 203 | @command{guix-daemon} program---are installed by the system |
| 204 | administrator; @file{/nix/store} is owned by @code{root} and |
| 205 | @command{guix-daemon} runs as @code{root}. Unprivileged users may use |
| 206 | Guix tools to build packages or otherwise access the store, and the |
| 207 | daemon will do it on their behalf, ensuring that the store is kept in a |
| 208 | consistent state, and allowing built packages to be shared among users. |
| 209 | |
| 210 | @cindex build users |
| 211 | When @command{guix-daemon} runs as @code{root}, you may not want package |
| 212 | build processes themselves to run as @code{root} too, for obvious |
| 213 | security reasons. To avoid that, a special pool of @dfn{build users} |
| 214 | should be created for use by build processes started by the daemon. |
| 215 | These build users need not have a shell and a home directory: they will |
| 216 | just be used when the daemon drops @code{root} privileges in build |
| 217 | processes. Having several such users allows the daemon to launch |
| 218 | distinct build processes under separate UIDs, which guarantees that they |
| 219 | do not interfere with each other---an essential feature since builds are |
| 220 | regarded as pure functions (@pxref{Introduction}). |
| 221 | |
| 222 | On a GNU/Linux system, a build user pool may be created like this (using |
| 223 | Bash syntax and the @code{shadow} commands): |
| 224 | |
| 225 | @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html |
| 226 | @c for why `-G' is needed. |
| 227 | @example |
| 228 | # groupadd guix-builder |
| 229 | # for i in `seq 1 10`; |
| 230 | do |
| 231 | useradd -g guix-builder -G guix-builder \ |
| 232 | -d /var/empty -s `which nologin` \ |
| 233 | -c "Guix build user $i" guix-builder$i; |
| 234 | done |
| 235 | @end example |
| 236 | |
| 237 | @noindent |
| 238 | The @code{guix-daemon} program may then be run as @code{root} with: |
| 239 | |
| 240 | @example |
| 241 | # guix-daemon --build-users-group=guix-builder |
| 242 | @end example |
| 243 | |
| 244 | Guix may also be used in a single-user setup, with @command{guix-daemon} |
| 245 | running as an unprivileged user. However, to maximize non-interference |
| 246 | of build processes, the daemon still needs to perform certain operations |
| 247 | that are restricted to @code{root} on GNU/Linux: it should be able to |
| 248 | run build processes in a chroot, and to run them under different UIDs. |
| 249 | To that end, the @command{nix-setuid-helper} program is provided; it is |
| 250 | a small C program (less than 300 lines) that, if it is made setuid |
| 251 | @code{root}, can be executed by the daemon to perform these operations |
| 252 | on its behalf. The @code{root}-owned @file{/etc/nix-setuid.conf} file |
| 253 | is read by @command{nix-setuid-helper}; it should contain exactly two |
| 254 | words: the user name under which the authorized @command{guix-daemon} |
| 255 | runs, and the name of the build users group. |
| 256 | |
| 257 | If you are installing Guix as an unprivileged user and do not have the |
| 258 | ability to make @file{nix-setuid-helper} setuid-@code{root}, it is still |
| 259 | possible to run @command{guix-daemon}. However, build processes will |
| 260 | not be isolated from one another, and not from the rest of the system. |
| 261 | Thus, build processes may interfere with each other, and may access |
| 262 | programs, libraries, and other files available on the system---making it |
| 263 | much harder to view them as @emph{pure} functions. |
| 264 | |
| 265 | @node Invoking guix-daemon |
| 266 | @section Invoking @command{guix-daemon} |
| 267 | |
| 268 | The @command{guix-daemon} program implements all the functionality to |
| 269 | access the store. This includes launching build processes, running the |
| 270 | garbage collector, querying the availability of a build result, etc. It |
| 271 | is normally run as @code{root} like this: |
| 272 | |
| 273 | @example |
| 274 | # guix-daemon --build-users-group=guix-builder |
| 275 | @end example |
| 276 | |
| 277 | @noindent |
| 278 | For details on how to set it up, @ref{Setting Up the Daemon}. |
| 279 | |
| 280 | By default, @command{guix-daemon} launches build processes under |
| 281 | different UIDs, taken from the build group specified with |
| 282 | @code{--build-users-group}. In addition, each build process is run in a |
| 283 | chroot environment that only contains the subset of the store that the |
| 284 | build process depends on, as specified by its derivation |
| 285 | (@pxref{Programming Interface, derivation}), plus a set of specific |
| 286 | system directories. By default, the latter contains @file{/dev} and |
| 287 | @file{/dev/pts}. |
| 288 | |
| 289 | The following command-line options are supported: |
| 290 | |
| 291 | @table @code |
| 292 | @item --build-users-group=@var{group} |
| 293 | Take users from @var{group} to run build processes (@pxref{Setting Up |
| 294 | the Daemon, build users}). |
| 295 | |
| 296 | @item --cache-failures |
| 297 | Cache build failures. By default, only successful builds are cached. |
| 298 | |
| 299 | @item --cores=@var{n} |
| 300 | @itemx -c @var{n} |
| 301 | Use @var{n} CPU cores to build each derivation; @code{0} means as many |
| 302 | as available. |
| 303 | |
| 304 | The default value is @code{1}, but it may be overridden by clients, such |
| 305 | as the @code{--cores} option of @command{guix build} (@pxref{Invoking |
| 306 | guix build}). |
| 307 | |
| 308 | The effect is to define the @code{NIX_BUILD_CORES} environment variable |
| 309 | in the build process, which can then use it to exploit internal |
| 310 | parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}. |
| 311 | |
| 312 | @item --max-jobs=@var{n} |
| 313 | @itemx -M @var{n} |
| 314 | Allow at most @var{n} build jobs in parallel. The default value is |
| 315 | @code{1}. |
| 316 | |
| 317 | @item --debug |
| 318 | Produce debugging output. |
| 319 | |
| 320 | This is useful to debug daemon start-up issues, but then it may be |
| 321 | overridden by clients, for example the @code{--verbosity} option of |
| 322 | @command{guix build} (@pxref{Invoking guix build}). |
| 323 | |
| 324 | @item --chroot-directory=@var{dir} |
| 325 | Add @var{dir} to the build chroot. |
| 326 | |
| 327 | Doing this may change the result of build processes---for instance if |
| 328 | they use optional dependencies found in @var{dir} when it is available, |
| 329 | and not otherwise. For that reason, it is not recommended to do so. |
| 330 | Instead, make sure that each derivation declares all the inputs that it |
| 331 | needs. |
| 332 | |
| 333 | @item --disable-chroot |
| 334 | Disable chroot builds. |
| 335 | |
| 336 | Using this option is not recommended since, again, it would allow build |
| 337 | processes to gain access to undeclared dependencies. |
| 338 | |
| 339 | @item --disable-log-compression |
| 340 | Disable compression of the build logs. |
| 341 | |
| 342 | Unless @code{--lose-logs} is used, all the build logs are kept in the |
| 343 | @var{localstatedir}. To save space, the daemon automatically compresses |
| 344 | them with bzip2 by default. This option disables that. |
| 345 | |
| 346 | @item --disable-store-optimization |
| 347 | Disable automatic file ``deduplication'' in the store. |
| 348 | |
| 349 | By default, files added to the store are automatically ``deduplicated'': |
| 350 | if a newly added file is identical as another one found in the store, |
| 351 | the daemon makes the new file a hard link to the other file. This |
| 352 | slightly increases the input/output load at the end of a build process. |
| 353 | This option disables this. |
| 354 | |
| 355 | @item --impersonate-linux-2.6 |
| 356 | On Linux-based systems, impersonate Linux 2.6. This means that the |
| 357 | kernel's @code{uname} system call will report 2.6 as the release number. |
| 358 | |
| 359 | This might be helpful to build programs that (usually wrongfully) depend |
| 360 | on the kernel version number. |
| 361 | |
| 362 | @item --lose-logs |
| 363 | Do not keep build logs. By default they are kept under |
| 364 | @code{@var{localstatedir}/nix/log}. |
| 365 | |
| 366 | @item --system=@var{system} |
| 367 | Assume @var{system} as the current system type. By default it is the |
| 368 | architecture/kernel pair found at configure time, such as |
| 369 | @code{x86_64-linux}. |
| 370 | |
| 371 | @item --listen=@var{socket} |
| 372 | Listen for connections on @var{socket}, the file name of a Unix-domain |
| 373 | socket. The default socket is |
| 374 | @file{@var{localstatedir}/daemon-socket/socket}. This option is only |
| 375 | useful in exceptional circumstances, such as if you need to run several |
| 376 | daemons on the same machine. |
| 377 | @end table |
| 378 | |
| 379 | |
| 380 | @c ********************************************************************* |
| 381 | @node Package Management |
| 382 | @chapter Package Management |
| 383 | |
| 384 | The purpose of GNU Guix is to allow users to easily install, upgrade, and |
| 385 | remove software packages, without having to know about their build |
| 386 | procedure or dependencies. Guix also goes beyond this obvious set of |
| 387 | features. |
| 388 | |
| 389 | This chapter describes the main features of Guix, as well as the package |
| 390 | management tools it provides. |
| 391 | |
| 392 | @menu |
| 393 | * Features:: How Guix will make your life brighter. |
| 394 | * Invoking guix package:: Package installation, removal, etc. |
| 395 | * Invoking guix gc:: Running the garbage collector. |
| 396 | * Invoking guix pull:: Fetching the latest Guix and distribution. |
| 397 | @end menu |
| 398 | |
| 399 | @node Features |
| 400 | @section Features |
| 401 | |
| 402 | When using Guix, each package ends up in the @dfn{package store}, in its |
| 403 | own directory---something that resembles |
| 404 | @file{/nix/store/xxx-package-1.2}, where @code{xxx} is a base32 string. |
| 405 | |
| 406 | Instead of referring to these directories, users have their own |
| 407 | @dfn{profile}, which points to the packages that they actually want to |
| 408 | use. These profiles are stored within each user's home directory, at |
| 409 | @code{$HOME/.guix-profile}. |
| 410 | |
| 411 | For example, @code{alice} installs GCC 4.7.2. As a result, |
| 412 | @file{/home/alice/.guix-profile/bin/gcc} points to |
| 413 | @file{/nix/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, |
| 414 | @code{bob} had already installed GCC 4.8.0. The profile of @code{bob} |
| 415 | simply continues to point to |
| 416 | @file{/nix/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC |
| 417 | coexist on the same system without any interference. |
| 418 | |
| 419 | The @command{guix package} command is the central tool to manage |
| 420 | packages (@pxref{Invoking guix package}). It operates on those per-user |
| 421 | profiles, and can be used @emph{with normal user privileges}. |
| 422 | |
| 423 | The command provides the obvious install, remove, and upgrade |
| 424 | operations. Each invocation is actually a @emph{transaction}: either |
| 425 | the specified operation succeeds, or nothing happens. Thus, if the |
| 426 | @command{guix package} process is terminated during the transaction, |
| 427 | or if a power outage occurs during the transaction, then the user's |
| 428 | profile remains in its previous state, and remains usable. |
| 429 | |
| 430 | In addition, any package transaction may be @emph{rolled back}. So, if, |
| 431 | for example, an upgrade installs a new version of a package that turns |
| 432 | out to have a serious bug, users may roll back to the previous instance |
| 433 | of their profile, which was known to work well. |
| 434 | |
| 435 | All those packages in the package store may be @emph{garbage-collected}. |
| 436 | Guix can determine which packages are still referenced by the user |
| 437 | profiles, and remove those that are provably no longer referenced |
| 438 | (@pxref{Invoking guix gc}). Users may also explicitly remove old |
| 439 | generations of their profile so that the packages they refer to can be |
| 440 | collected. |
| 441 | |
| 442 | Finally, Guix takes a @dfn{purely functional} approach to package |
| 443 | management, as described in the introduction (@pxref{Introduction}). |
| 444 | Each @file{/nix/store} package directory name contains a hash of all the |
| 445 | inputs that were used to build that package---compiler, libraries, build |
| 446 | scripts, etc. This direct correspondence allows users to make sure a |
| 447 | given package installation matches the current state of their |
| 448 | distribution, and helps maximize @dfn{reproducibility}. |
| 449 | |
| 450 | @c FIXME: Remove footnote when it's implemented. |
| 451 | This foundation allows Guix to support @dfn{transparent binary/source |
| 452 | deployment}@footnote{This feature is not implemented as of version |
| 453 | @value{VERSION}. Please contact @email{bug-guix@@gnu.org} for more |
| 454 | details.}. When a pre-built binary for a @file{/nix/store} path is |
| 455 | available from an external source, Guix just downloads it; otherwise, it |
| 456 | builds the package from source, locally. |
| 457 | |
| 458 | @node Invoking guix package |
| 459 | @section Invoking @command{guix package} |
| 460 | |
| 461 | The @command{guix package} command is the tool that allows users to |
| 462 | install, upgrade, and remove packages, as well as rolling back to |
| 463 | previous configurations. It operates only on the user's own profile, |
| 464 | and works with normal user privileges (@pxref{Features}). Its syntax |
| 465 | is: |
| 466 | |
| 467 | @example |
| 468 | guix package @var{options} |
| 469 | @end example |
| 470 | |
| 471 | Primarily, @var{options} specifies the operations to be performed during |
| 472 | the transaction. Upon completion, a new profile is created, but |
| 473 | previous generations of the profile remain available, should the user |
| 474 | want to roll back. |
| 475 | |
| 476 | For each user, a symlink to the user's default profile is automatically |
| 477 | created in @file{$HOME/.guix-profile}. This symlink always points to the |
| 478 | current generation of the user's default profile. Thus, users can add |
| 479 | @file{$HOME/.guix-profile/bin} to their @code{PATH} environment |
| 480 | variable, and so on. |
| 481 | |
| 482 | In a multi-user setup, user profiles must be stored in a place |
| 483 | registered as a @dfn{garbage-collector root}, which |
| 484 | @file{$HOME/.guix-profile} points to (@pxref{Invoking guix gc}). That |
| 485 | directory is normally |
| 486 | @code{@var{localstatedir}/profiles/per-user/@var{user}}, where |
| 487 | @var{localstatedir} is the value passed to @code{configure} as |
| 488 | @code{--localstatedir}, and @var{user} is the user name. It must be |
| 489 | created by @code{root}, with @var{user} as the owner. When it does not |
| 490 | exist, @command{guix package} emits an error about it. |
| 491 | |
| 492 | The @var{options} can be among the following: |
| 493 | |
| 494 | @table @code |
| 495 | |
| 496 | @item --install=@var{package} |
| 497 | @itemx -i @var{package} |
| 498 | Install @var{package}. |
| 499 | |
| 500 | @var{package} may specify either a simple package name, such as |
| 501 | @code{guile}, or a package name followed by a hyphen and version number, |
| 502 | such as @code{guile-1.8.8}. If no version number is specified, the |
| 503 | newest available version will be selected. In addition, @var{package} |
| 504 | may contain a colon, followed by the name of one of the outputs of the |
| 505 | package, as in @code{gcc:doc} or @code{binutils-2.22:lib}. |
| 506 | |
| 507 | @cindex propagated inputs |
| 508 | Sometimes packages have @dfn{propagated inputs}: these are dependencies |
| 509 | that automatically get installed along with the required package. |
| 510 | |
| 511 | An example is the GNU MPC library: its C header files refer to those of |
| 512 | the GNU MPFR library, which in turn refer to those of the GMP library. |
| 513 | Thus, when installing MPC, the MPFR and GMP libraries also get installed |
| 514 | in the profile; removing MPC also removes MPFR and GMP---unless they had |
| 515 | also been explicitly installed independently. |
| 516 | |
| 517 | @c XXX: keep me up-to-date |
| 518 | Besides, when installing a GNU package, the tool reports the |
| 519 | availability of a newer upstream version. In the future, it may provide |
| 520 | the option of installing directly from the upstream version, even if |
| 521 | that version is not yet in the distribution. |
| 522 | |
| 523 | @item --install-from-expression=@var{exp} |
| 524 | @itemx -e @var{exp} |
| 525 | Install the package @var{exp} evaluates to. |
| 526 | |
| 527 | @var{exp} must be a Scheme expression that evaluates to a |
| 528 | @code{<package>} object. This option is notably useful to disambiguate |
| 529 | between same-named variants of a package, with expressions such as |
| 530 | @code{(@@ (gnu packages base) guile-final)}. |
| 531 | |
| 532 | Note that this option installs the first output of the specified |
| 533 | package, which may be insufficient when needing a specific output of a |
| 534 | multiple-output package. |
| 535 | |
| 536 | @item --remove=@var{package} |
| 537 | @itemx -r @var{package} |
| 538 | Remove @var{package}. |
| 539 | |
| 540 | @item --upgrade[=@var{regexp}] |
| 541 | @itemx -u [@var{regexp}] |
| 542 | Upgrade all the installed packages. When @var{regexp} is specified, upgrade |
| 543 | only installed packages whose name matches @var{regexp}. |
| 544 | |
| 545 | Note that this upgrades package to the latest version of packages found |
| 546 | in the distribution currently installed. To update your distribution, |
| 547 | you should regularly run @command{guix pull} (@pxref{Invoking guix |
| 548 | pull}). |
| 549 | |
| 550 | @item --roll-back |
| 551 | Roll back to the previous @dfn{generation} of the profile---i.e., undo |
| 552 | the last transaction. |
| 553 | |
| 554 | When combined with options such as @code{--install}, roll back occurs |
| 555 | before any other actions. |
| 556 | |
| 557 | When rolling back from the first generation that actually contains |
| 558 | installed packages, the profile is made to point to the @dfn{empty |
| 559 | profile}, also known as @dfn{profile zero}---i.e., it contains no files |
| 560 | apart from its own meta-data. |
| 561 | |
| 562 | Installing, removing, or upgrading packages from a generation that has |
| 563 | been rolled back to overwrites previous future generations. Thus, the |
| 564 | history of a profile's generations is always linear. |
| 565 | |
| 566 | @item --profile=@var{profile} |
| 567 | @itemx -p @var{profile} |
| 568 | Use @var{profile} instead of the user's default profile. |
| 569 | |
| 570 | @item --dry-run |
| 571 | @itemx -n |
| 572 | Show what would be done without actually doing it. |
| 573 | |
| 574 | @item --no-substitutes |
| 575 | Build instead of resorting to pre-built substitutes. |
| 576 | |
| 577 | @item --verbose |
| 578 | Produce verbose output. In particular, emit the environment's build log |
| 579 | on the standard error port. |
| 580 | |
| 581 | @item --bootstrap |
| 582 | Use the bootstrap Guile to build the profile. This option is only |
| 583 | useful to distribution developers. |
| 584 | |
| 585 | @end table |
| 586 | |
| 587 | In addition to these actions @command{guix package} supports the |
| 588 | following options to query the current state of a profile, or the |
| 589 | availability of packages: |
| 590 | |
| 591 | @table @option |
| 592 | |
| 593 | @item --search=@var{regexp} |
| 594 | @itemx -s @var{regexp} |
| 595 | List the available packages whose synopsis or description matches |
| 596 | @var{regexp}. Print all the meta-data of matching packages in |
| 597 | @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, |
| 598 | GNU recutils manual}). |
| 599 | |
| 600 | This allows specific fields to be extracted using the @command{recsel} |
| 601 | command, for instance: |
| 602 | |
| 603 | @example |
| 604 | $ guix package -s malloc | recsel -p name,version |
| 605 | name: glibc |
| 606 | version: 2.17 |
| 607 | |
| 608 | name: libgc |
| 609 | version: 7.2alpha6 |
| 610 | @end example |
| 611 | |
| 612 | @item --list-installed[=@var{regexp}] |
| 613 | @itemx -I [@var{regexp}] |
| 614 | List currently installed packages in the specified profile. When |
| 615 | @var{regexp} is specified, list only installed packages whose name |
| 616 | matches @var{regexp}. |
| 617 | |
| 618 | For each installed package, print the following items, separated by |
| 619 | tabs: the package name, its version string, the part of the package that |
| 620 | is installed (for instance, @code{out} for the default output, |
| 621 | @code{include} for its headers, etc.), and the path of this package in |
| 622 | the store. |
| 623 | |
| 624 | @item --list-available[=@var{regexp}] |
| 625 | @itemx -A [@var{regexp}] |
| 626 | List packages currently available in the software distribution |
| 627 | (@pxref{GNU Distribution}). When @var{regexp} is specified, list only |
| 628 | installed packages whose name matches @var{regexp}. |
| 629 | |
| 630 | For each package, print the following items separated by tabs: its name, |
| 631 | its version string, the parts of the package (@code{out} for the main |
| 632 | files, @code{lib} for libraries and possibly headers, etc.), and the |
| 633 | source location of its definition. |
| 634 | |
| 635 | @end table |
| 636 | |
| 637 | |
| 638 | @node Invoking guix gc |
| 639 | @section Invoking @command{guix gc} |
| 640 | |
| 641 | @cindex garbage collector |
| 642 | Packages that are installed but not used may be @dfn{garbage-collected}. |
| 643 | The @command{guix gc} command allows users to explicitly run the garbage |
| 644 | collector to reclaim space from the @file{/nix/store} directory. |
| 645 | |
| 646 | The garbage collector has a set of known @dfn{roots}: any file under |
| 647 | @file{/nix/store} reachable from a root is considered @dfn{live} and |
| 648 | cannot be deleted; any other file is considered @dfn{dead} and may be |
| 649 | deleted. The set of garbage collector roots includes default user |
| 650 | profiles, and may be augmented with @command{guix build --root}, for |
| 651 | example (@pxref{Invoking guix build}). |
| 652 | |
| 653 | The @command{guix gc} command has three modes of operation: it can be |
| 654 | used to garbage-collect any dead files (the default), to delete specific |
| 655 | files (the @code{--delete} option), or to print garbage-collector |
| 656 | information. The available options are listed below: |
| 657 | |
| 658 | @table @code |
| 659 | @item --collect-garbage[=@var{min}] |
| 660 | @itemx -C [@var{min}] |
| 661 | Collect garbage---i.e., unreachable @file{/nix/store} files and |
| 662 | sub-directories. This is the default operation when no option is |
| 663 | specified. |
| 664 | |
| 665 | When @var{min} is given, stop once @var{min} bytes have been collected. |
| 666 | @var{min} may be a number of bytes, or it may include a unit as a |
| 667 | suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes. |
| 668 | |
| 669 | When @var{min} is omitted, collect all the garbage. |
| 670 | |
| 671 | @item --delete |
| 672 | @itemx -d |
| 673 | Attempt to delete all the store files and directories specified as |
| 674 | arguments. This fails if some of the files are not in the store, or if |
| 675 | they are still live. |
| 676 | |
| 677 | @item --list-dead |
| 678 | Show the list of dead files and directories still present in the |
| 679 | store---i.e., files and directories no longer reachable from any root. |
| 680 | |
| 681 | @item --list-live |
| 682 | Show the list of live store files and directories. |
| 683 | |
| 684 | @end table |
| 685 | |
| 686 | In addition, the references among existing store files can be queried: |
| 687 | |
| 688 | @table @code |
| 689 | |
| 690 | @item --references |
| 691 | @itemx --referrers |
| 692 | List the references (respectively, the referrers) of store files given |
| 693 | as arguments. |
| 694 | |
| 695 | @end table |
| 696 | |
| 697 | |
| 698 | @node Invoking guix pull |
| 699 | @section Invoking @command{guix pull} |
| 700 | |
| 701 | Packages are installed or upgraded to the latest version available in |
| 702 | the distribution currently available on your local machine. To update |
| 703 | that distribution, along with the Guix tools, you must run @command{guix |
| 704 | pull}: the command downloads the latest Guix source code and package |
| 705 | descriptions, and deploys it. |
| 706 | |
| 707 | On completion, @command{guix package} will use packages and package |
| 708 | versions from this just-retrieved copy of Guix. Not only that, but all |
| 709 | the Guix commands and Scheme modules will also be taken from that latest |
| 710 | version. New @command{guix} sub-commands added by the update also |
| 711 | become available. |
| 712 | |
| 713 | The @command{guix pull} command is usually invoked with no arguments, |
| 714 | but it supports the following options: |
| 715 | |
| 716 | @table @code |
| 717 | @item --verbose |
| 718 | Produce verbose output, writing build logs to the standard error output. |
| 719 | |
| 720 | @item --bootstrap |
| 721 | Use the bootstrap Guile to build the latest Guix. This option is only |
| 722 | useful to Guix developers. |
| 723 | @end table |
| 724 | |
| 725 | @c ********************************************************************* |
| 726 | @node Programming Interface |
| 727 | @chapter Programming Interface |
| 728 | |
| 729 | GNU Guix provides several Scheme programming interfaces (APIs) to |
| 730 | define, build, and query packages. The first interface allows users to |
| 731 | write high-level package definitions. These definitions refer to |
| 732 | familiar packaging concepts, such as the name and version of a package, |
| 733 | its build system, and its dependencies. These definitions can then be |
| 734 | turned into concrete build actions. |
| 735 | |
| 736 | Build actions are performed by the Guix daemon, on behalf of users. In a |
| 737 | standard setup, the daemon has write access to the store---the |
| 738 | @file{/nix/store} directory---whereas users do not. The recommended |
| 739 | setup also has the daemon perform builds in chroots, under a specific |
| 740 | build users, to minimize interference with the rest of the system. |
| 741 | |
| 742 | @cindex derivation |
| 743 | Lower-level APIs are available to interact with the daemon and the |
| 744 | store. To instruct the daemon to perform a build action, users actually |
| 745 | provide it with a @dfn{derivation}. A derivation is a low-level |
| 746 | representation of the build actions to be taken, and the environment in |
| 747 | which they should occur---derivations are to package definitions what |
| 748 | assembly is to C programs. |
| 749 | |
| 750 | This chapter describes all these APIs in turn, starting from high-level |
| 751 | package definitions. |
| 752 | |
| 753 | @menu |
| 754 | * Defining Packages:: Defining new packages. |
| 755 | * The Store:: Manipulating the package store. |
| 756 | * Derivations:: Low-level interface to package derivations. |
| 757 | @end menu |
| 758 | |
| 759 | @node Defining Packages |
| 760 | @section Defining Packages |
| 761 | |
| 762 | The high-level interface to package definitions is implemented in the |
| 763 | @code{(guix packages)} and @code{(guix build-system)} modules. As an |
| 764 | example, the package definition, or @dfn{recipe}, for the GNU Hello |
| 765 | package looks like this: |
| 766 | |
| 767 | @example |
| 768 | (use-modules (guix packages) |
| 769 | (guix download) |
| 770 | (guix build-system gnu) |
| 771 | (guix licenses)) |
| 772 | |
| 773 | (define hello |
| 774 | (package |
| 775 | (name "hello") |
| 776 | (version "2.8") |
| 777 | (source (origin |
| 778 | (method url-fetch) |
| 779 | (uri (string-append "mirror://gnu/hello/hello-" version |
| 780 | ".tar.gz")) |
| 781 | (sha256 |
| 782 | (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6")))) |
| 783 | (build-system gnu-build-system) |
| 784 | (inputs `(("gawk" ,gawk))) |
| 785 | (synopsis "GNU Hello") |
| 786 | (description "Yeah...") |
| 787 | (home-page "http://www.gnu.org/software/hello/") |
| 788 | (license gpl3+))) |
| 789 | @end example |
| 790 | |
| 791 | @noindent |
| 792 | Without being a Scheme expert, the reader may have guessed the meaning |
| 793 | of the various fields here. This expression binds variable @var{hello} |
| 794 | to a @code{<package>} object, which is essentially a record |
| 795 | (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). |
| 796 | This package object can be inspected using procedures found in the |
| 797 | @code{(guix packages)} module; for instance, @code{(package-name hello)} |
| 798 | returns---surprise!---@code{"hello"}. |
| 799 | |
| 800 | There are a few points worth noting in the above package definition: |
| 801 | |
| 802 | @itemize |
| 803 | @item |
| 804 | The @code{source} field of the package is an @code{<origin>} object. |
| 805 | Here, the @code{url-fetch} method from @code{(guix download)} is used, |
| 806 | meaning that the source is a file to be downloaded over FTP or HTTP. |
| 807 | |
| 808 | The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of |
| 809 | the GNU mirrors defined in @code{(guix download)}. |
| 810 | |
| 811 | The @code{sha256} field specifies the expected SHA256 hash of the file |
| 812 | being downloaded. It is mandatory, and allows Guix to check the |
| 813 | integrity of the file. The @code{(base32 @dots{})} form introduces the |
| 814 | base32 representation of the hash. A convenient way to obtain this |
| 815 | information is with the @code{guix download} tool. |
| 816 | |
| 817 | @item |
| 818 | @cindex GNU Build System |
| 819 | The @code{build-system} field is set to @var{gnu-build-system}. The |
| 820 | @var{gnu-build-system} variable is defined in the @code{(guix |
| 821 | build-system gnu)} module, and is bound to a @code{<build-system>} |
| 822 | object. |
| 823 | |
| 824 | Naturally, @var{gnu-build-system} represents the familiar GNU Build |
| 825 | System, and variants thereof (@pxref{Configuration, configuration and |
| 826 | makefile conventions,, standards, GNU Coding Standards}). In a |
| 827 | nutshell, packages using the GNU Build System may be configured, built, |
| 828 | and installed with the usual @code{./configure && make && make check && |
| 829 | make install} command sequence. This is what @var{gnu-build-system} |
| 830 | does. |
| 831 | |
| 832 | In addition, @var{gnu-build-system} ensures that the ``standard'' |
| 833 | environment for GNU packages is available. This includes tools such as |
| 834 | GCC, Coreutils, Bash, Make, Diffutils, and Patch. |
| 835 | |
| 836 | @item |
| 837 | The @code{inputs} field specifies inputs to the build process---i.e., |
| 838 | build-time or run-time dependencies of the package. Here, we define an |
| 839 | input called @code{"gawk"} whose value is that of the @var{gawk} |
| 840 | variable; @var{gawk} is itself bound to a @code{<package>} object. |
| 841 | |
| 842 | Note that GCC, Coreutils, Bash, and other essential tools do not need to |
| 843 | be specified as inputs here. Instead, @var{gnu-build-system} takes care |
| 844 | of ensuring that they are present. |
| 845 | |
| 846 | However, any other dependencies need to be specified in the |
| 847 | @code{inputs} field. Any dependency not specified here will simply be |
| 848 | unavailable to the build process, possibly leading to a build failure. |
| 849 | @end itemize |
| 850 | |
| 851 | There are other fields that package definitions may provide. Of |
| 852 | particular interest is the @code{arguments} field. When specified, it |
| 853 | must be bound to a list of additional arguments to be passed to the |
| 854 | build system. For instance, the above definition could be augmented |
| 855 | with the following field initializer: |
| 856 | |
| 857 | @example |
| 858 | (arguments `(#:tests? #f |
| 859 | #:configure-flags '("--enable-silent-rules"))) |
| 860 | @end example |
| 861 | |
| 862 | @noindent |
| 863 | These are keyword arguments (@pxref{Optional Arguments, keyword |
| 864 | arguments in Guile,, guile, GNU Guile Reference Manual}). They are |
| 865 | passed to @var{gnu-build-system}, which interprets them as meaning ``do |
| 866 | not run @code{make check}'', and ``run @file{configure} with the |
| 867 | @code{--enable-silent-rules} flag''. The value of these keyword |
| 868 | parameters is actually evaluated in the @dfn{build stratum}---i.e., by a |
| 869 | Guile process launched by the daemon (@pxref{Derivations}). |
| 870 | |
| 871 | Once a package definition is in place@footnote{Simple package |
| 872 | definitions like the one above may be automatically converted from the |
| 873 | Nixpkgs distribution using the @command{guix import} command.}, the |
| 874 | package may actually be built using the @code{guix build} command-line |
| 875 | tool (@pxref{Invoking guix build}). |
| 876 | |
| 877 | Behind the scenes, a derivation corresponding to the @code{<package>} |
| 878 | object is first computed by the @code{package-derivation} procedure. |
| 879 | That derivation is stored in a @code{.drv} file under @file{/nix/store}. |
| 880 | The build actions it prescribes may then be realized by using the |
| 881 | @code{build-derivations} procedure (@pxref{The Store}). |
| 882 | |
| 883 | @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] |
| 884 | Return the derivation path and corresponding @code{<derivation>} object |
| 885 | of @var{package} for @var{system} (@pxref{Derivations}). |
| 886 | |
| 887 | @var{package} must be a valid @code{<package>} object, and @var{system} |
| 888 | must be a string denoting the target system type---e.g., |
| 889 | @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store} |
| 890 | must be a connection to the daemon, which operates on the store |
| 891 | (@pxref{The Store}). |
| 892 | @end deffn |
| 893 | |
| 894 | @node The Store |
| 895 | @section The Store |
| 896 | |
| 897 | @cindex store |
| 898 | @cindex store paths |
| 899 | |
| 900 | Conceptually, the @dfn{store} is where derivations that have been |
| 901 | successfully built are stored---by default, under @file{/nix/store}. |
| 902 | Sub-directories in the store are referred to as @dfn{store paths}. The |
| 903 | store has an associated database that contains information such has the |
| 904 | store paths referred to by each store path, and the list of @emph{valid} |
| 905 | store paths---paths that result from a successful build. |
| 906 | |
| 907 | The store is always accessed by the daemon on behalf of its clients |
| 908 | (@pxref{Invoking guix-daemon}). To manipulate the store, clients |
| 909 | connect to the daemon over a Unix-domain socket, send it requests, and |
| 910 | read the result---these are remote procedure calls, or RPCs. |
| 911 | |
| 912 | The @code{(guix store)} module provides procedures to connect to the |
| 913 | daemon, and to perform RPCs. These are described below. |
| 914 | |
| 915 | @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t] |
| 916 | Connect to the daemon over the Unix-domain socket at @var{file}. When |
| 917 | @var{reserve-space?} is true, instruct it to reserve a little bit of |
| 918 | extra space on the file system so that the garbage collector can still |
| 919 | operate, should the disk become full. Return a server object. |
| 920 | |
| 921 | @var{file} defaults to @var{%default-socket-path}, which is the normal |
| 922 | location given the options that were passed to @command{configure}. |
| 923 | @end deffn |
| 924 | |
| 925 | @deffn {Scheme Procedure} close-connection @var{server} |
| 926 | Close the connection to @var{server}. |
| 927 | @end deffn |
| 928 | |
| 929 | @defvr {Scheme Variable} current-build-output-port |
| 930 | This variable is bound to a SRFI-39 parameter, which refers to the port |
| 931 | where build and error logs sent by the daemon should be written. |
| 932 | @end defvr |
| 933 | |
| 934 | Procedures that make RPCs all take a server object as their first |
| 935 | argument. |
| 936 | |
| 937 | @deffn {Scheme Procedure} valid-path? @var{server} @var{path} |
| 938 | Return @code{#t} when @var{path} is a valid store path. |
| 939 | @end deffn |
| 940 | |
| 941 | @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} @var{references} |
| 942 | Add @var{text} under file @var{name} in the store, and return its store |
| 943 | path. @var{references} is the list of store paths referred to by the |
| 944 | resulting store path. |
| 945 | @end deffn |
| 946 | |
| 947 | @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations} |
| 948 | Build @var{derivations} (a list of derivation paths), and return when |
| 949 | the worker is done building them. Return @code{#t} on success. |
| 950 | @end deffn |
| 951 | |
| 952 | @c FIXME |
| 953 | @i{This section is currently incomplete.} |
| 954 | |
| 955 | @node Derivations |
| 956 | @section Derivations |
| 957 | |
| 958 | @cindex derivations |
| 959 | Low-level build actions and the environment in which they are performed |
| 960 | are represented by @dfn{derivations}. A derivation contain the |
| 961 | following pieces of information: |
| 962 | |
| 963 | @itemize |
| 964 | @item |
| 965 | The outputs of the derivation---derivations produce at least one file or |
| 966 | directory in the store, but may produce more. |
| 967 | |
| 968 | @item |
| 969 | The inputs of the derivations, which may be other derivations or plain |
| 970 | files in the store (patches, build scripts, etc.) |
| 971 | |
| 972 | @item |
| 973 | The system type targeted by the derivation---e.g., @code{x86_64-linux}. |
| 974 | |
| 975 | @item |
| 976 | The file name of a build script in the store, along with the arguments |
| 977 | to be passed. |
| 978 | |
| 979 | @item |
| 980 | A list of environment variables to be defined. |
| 981 | |
| 982 | @end itemize |
| 983 | |
| 984 | @cindex derivation path |
| 985 | Derivations allow clients of the daemon to communicate build actions to |
| 986 | the store. They exist in two forms: as an in-memory representation, |
| 987 | both on the client- and daemon-side, and as files in the store whose |
| 988 | name end in @code{.drv}---these files are referred to as @dfn{derivation |
| 989 | paths}. Derivations paths can be passed to the @code{build-derivations} |
| 990 | procedure to perform the build actions they prescribe (@pxref{The |
| 991 | Store}). |
| 992 | |
| 993 | The @code{(guix derivations)} module provides a representation of |
| 994 | derivations as Scheme objects, along with procedures to create and |
| 995 | otherwise manipulate derivations. The lowest-level primitive to create |
| 996 | a derivation is the @code{derivation} procedure: |
| 997 | |
| 998 | @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] |
| 999 | Build a derivation with the given arguments. Return the resulting store |
| 1000 | path and @code{<derivation>} object. |
| 1001 | |
| 1002 | When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a |
| 1003 | @dfn{fixed-output derivation} is created---i.e., one whose result is |
| 1004 | known in advance, such as a file download. |
| 1005 | @end deffn |
| 1006 | |
| 1007 | @noindent |
| 1008 | Here's an example with a shell script as its builder, assuming |
| 1009 | @var{store} is an open connection to the daemon, and @var{bash} points |
| 1010 | to a Bash executable in the store: |
| 1011 | |
| 1012 | @lisp |
| 1013 | (use-modules (guix utils) |
| 1014 | (guix store) |
| 1015 | (guix derivations)) |
| 1016 | |
| 1017 | (call-with-values |
| 1018 | (lambda () |
| 1019 | (let ((builder ; add the Bash script to the store |
| 1020 | (add-text-to-store store "my-builder.sh" |
| 1021 | "echo hello world > $out\n" '()))) |
| 1022 | (derivation store "foo" (%current-system) |
| 1023 | bash `("-e" ,builder) |
| 1024 | '(("HOME" . "/homeless")) '()))) |
| 1025 | list) |
| 1026 | @result{} ("/nix/store/@dots{}-foo.drv" #<<derivation> @dots{}>) |
| 1027 | @end lisp |
| 1028 | |
| 1029 | As can be guessed, this primitive is cumbersome to use directly. An |
| 1030 | improved variant is @code{build-expression->derivation}, which allows |
| 1031 | the caller to directly pass a Guile expression as the build script: |
| 1032 | |
| 1033 | @deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f] |
| 1034 | Return a derivation that executes Scheme expression @var{exp} as a |
| 1035 | builder for derivation @var{name}. @var{inputs} must be a list of |
| 1036 | @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted, |
| 1037 | @code{"out"} is assumed. @var{modules} is a list of names of Guile |
| 1038 | modules from the current search path to be copied in the store, |
| 1039 | compiled, and made available in the load path during the execution of |
| 1040 | @var{exp}---e.g., @code{((guix build utils) (guix build |
| 1041 | gnu-build-system))}. |
| 1042 | |
| 1043 | @var{exp} is evaluated in an environment where @code{%outputs} is bound |
| 1044 | to a list of output/path pairs, and where @code{%build-inputs} is bound |
| 1045 | to a list of string/output-path pairs made from @var{inputs}. |
| 1046 | Optionally, @var{env-vars} is a list of string pairs specifying the name |
| 1047 | and value of environment variables visible to the builder. The builder |
| 1048 | terminates by passing the result of @var{exp} to @code{exit}; thus, when |
| 1049 | @var{exp} returns @code{#f}, the build is considered to have failed. |
| 1050 | |
| 1051 | @var{exp} is built using @var{guile-for-build} (a derivation). When |
| 1052 | @var{guile-for-build} is omitted or is @code{#f}, the value of the |
| 1053 | @code{%guile-for-build} fluid is used instead. |
| 1054 | @end deffn |
| 1055 | |
| 1056 | @noindent |
| 1057 | Here's an example of a single-output derivation that creates a directory |
| 1058 | containing one file: |
| 1059 | |
| 1060 | @lisp |
| 1061 | (let ((builder '(let ((out (assoc-ref %outputs "out"))) |
| 1062 | (mkdir out) ; create /nix/store/@dots{}-goo |
| 1063 | (call-with-output-file (string-append out "/test") |
| 1064 | (lambda (p) |
| 1065 | (display '(hello guix) p)))))) |
| 1066 | (build-expression->derivation store "goo" (%current-system) |
| 1067 | builder '())) |
| 1068 | |
| 1069 | @result{} "/nix/store/@dots{}-goo.drv" |
| 1070 | @result{} #<<derivation> @dots{}> |
| 1071 | @end lisp |
| 1072 | |
| 1073 | @cindex strata of code |
| 1074 | Remember that the build expression passed to |
| 1075 | @code{build-expression->derivation} is run by a separate Guile process |
| 1076 | than the one that calls @code{build-expression->derivation}: it is run |
| 1077 | by a Guile process launched by the daemon, typically in a chroot. So, |
| 1078 | while there is a single language for both the @dfn{host} and the build |
| 1079 | side, there are really two @dfn{strata} of code: the host-side, and the |
| 1080 | build-side code@footnote{The term @dfn{stratum} in this context was |
| 1081 | coined by Manuel Serrano et al. in the context of their work on Hop.}. |
| 1082 | This distinction is important to keep in mind, notably when using |
| 1083 | higher-level constructs such as @var{gnu-build-system} (@pxref{Defining |
| 1084 | Packages}). For this reason, Guix modules that are meant to be used in |
| 1085 | the build stratum are kept in the @code{(guix build @dots{})} name |
| 1086 | space. |
| 1087 | |
| 1088 | @c ********************************************************************* |
| 1089 | @node Utilities |
| 1090 | @chapter Utilities |
| 1091 | |
| 1092 | @menu |
| 1093 | * Invoking guix build:: Building packages from the command line. |
| 1094 | @end menu |
| 1095 | |
| 1096 | @node Invoking guix build |
| 1097 | @section Invoking @command{guix build} |
| 1098 | |
| 1099 | The @command{guix build} command builds packages or derivations and |
| 1100 | their dependencies, and prints the resulting store paths. Note that it |
| 1101 | does not modify the user's profile---this is the job of the |
| 1102 | @command{guix package} command (@pxref{Invoking guix package}). Thus, |
| 1103 | it is mainly useful for distribution developers. |
| 1104 | |
| 1105 | The general syntax is: |
| 1106 | |
| 1107 | @example |
| 1108 | guix build @var{options} @var{package-or-derivation}@dots{} |
| 1109 | @end example |
| 1110 | |
| 1111 | @var{package-or-derivation} may be either the name of a package found in |
| 1112 | the software distribution such as @code{coreutils} or |
| 1113 | @code{coreutils-8.20}, or a derivation such as |
| 1114 | @file{/nix/store/@dots{}-coreutils-8.19.drv}. Alternatively, the |
| 1115 | @code{--expression} option may be used to specify a Scheme expression |
| 1116 | that evaluates to a package; this is useful when disambiguation among |
| 1117 | several same-named packages or package variants is needed. |
| 1118 | |
| 1119 | The @var{options} may be zero or more of the following: |
| 1120 | |
| 1121 | @table @code |
| 1122 | |
| 1123 | @item --expression=@var{expr} |
| 1124 | @itemx -e @var{expr} |
| 1125 | Build the package @var{expr} evaluates to. |
| 1126 | |
| 1127 | For example, @var{expr} may be @code{(@@ (gnu packages guile) |
| 1128 | guile-1.8)}, which unambiguously designates this specific variant of |
| 1129 | version 1.8 of Guile. |
| 1130 | |
| 1131 | @item --source |
| 1132 | @itemx -S |
| 1133 | Build the packages' source derivations, rather than the packages |
| 1134 | themselves. |
| 1135 | |
| 1136 | For instance, @code{guix build -S gcc} returns something like |
| 1137 | @file{/nix/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. |
| 1138 | |
| 1139 | @item --system=@var{system} |
| 1140 | @itemx -s @var{system} |
| 1141 | Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of |
| 1142 | the host's system type. |
| 1143 | |
| 1144 | An example use of this is on Linux-based systems, which can emulate |
| 1145 | different personalities. For instance, passing |
| 1146 | @code{--system=i686-linux} on an @code{x86_64-linux} system allows users |
| 1147 | to build packages in a complete 32-bit environment. |
| 1148 | |
| 1149 | @item --derivations |
| 1150 | @itemx -d |
| 1151 | Return the derivation paths, not the output paths, of the given |
| 1152 | packages. |
| 1153 | |
| 1154 | @item --keep-failed |
| 1155 | @itemx -K |
| 1156 | Keep the build tree of failed builds. Thus, if a build fail, its build |
| 1157 | tree is kept under @file{/tmp}, in a directory whose name is shown at |
| 1158 | the end of the build log. This is useful when debugging build issues. |
| 1159 | |
| 1160 | @item --dry-run |
| 1161 | @itemx -n |
| 1162 | Do not build the derivations. |
| 1163 | |
| 1164 | @item --no-substitutes |
| 1165 | Build instead of resorting to pre-built substitutes. |
| 1166 | |
| 1167 | @item --cores=@var{n} |
| 1168 | @itemx -c @var{n} |
| 1169 | Allow the use of up to @var{n} CPU cores for the build. The special |
| 1170 | value @code{0} means to use as many CPU cores as available. |
| 1171 | |
| 1172 | @item --root=@var{file} |
| 1173 | @itemx -r @var{file} |
| 1174 | Make @var{file} a symlink to the result, and register it as a garbage |
| 1175 | collector root. |
| 1176 | |
| 1177 | @item --verbosity=@var{level} |
| 1178 | Use the given verbosity level. @var{level} must be an integer between 0 |
| 1179 | and 5; higher means more verbose output. Setting a level of 4 or more |
| 1180 | may be helpful when debugging setup issues with the build daemon. |
| 1181 | |
| 1182 | @end table |
| 1183 | |
| 1184 | Behind the scenes, @command{guix build} is essentially an interface to |
| 1185 | the @code{package-derivation} procedure of the @code{(guix packages)} |
| 1186 | module, and to the @code{build-derivations} procedure of the @code{(guix |
| 1187 | store)} module. |
| 1188 | |
| 1189 | @c ********************************************************************* |
| 1190 | @node GNU Distribution |
| 1191 | @chapter GNU Distribution |
| 1192 | |
| 1193 | Guix comes with a distribution of free software@footnote{The term |
| 1194 | ``free'' here refers to the |
| 1195 | @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to |
| 1196 | users of that software}.} that form the basis of the GNU system. This |
| 1197 | includes core GNU packages such as GNU libc, GCC, and Binutils, as well |
| 1198 | as many GNU and non-GNU applications. The complete list of available |
| 1199 | packages can be seen by running @command{guix package} (@pxref{Invoking |
| 1200 | guix package}): |
| 1201 | |
| 1202 | @example |
| 1203 | guix package --list-available |
| 1204 | @end example |
| 1205 | |
| 1206 | The package definitions of the distribution may are provided by Guile |
| 1207 | modules in the @code{(gnu packages ...)} name space---for instance, the |
| 1208 | @code{(gnu packages emacs)} module exports a variable named |
| 1209 | @code{emacs}, which is bound to a @code{<package>} object |
| 1210 | (@pxref{Defining Packages}). The @code{(gnu packages)} module provides |
| 1211 | facilities for searching for packages. |
| 1212 | |
| 1213 | The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: |
| 1214 | each package is built based solely on other packages in the |
| 1215 | distribution. The root of this dependency graph is a small set of |
| 1216 | @dfn{bootstrap binaries}, provided by the @code{(gnu packages |
| 1217 | bootstrap)} module. These are statically-linked binaries of the core |
| 1218 | tools without which building anything at all would be impossible. |
| 1219 | |
| 1220 | |
| 1221 | Our goal is to build a practical 100% free software distribution of |
| 1222 | Linux-based and other variants of GNU, with a focus on the promotion and |
| 1223 | tight integration of GNU components, and an emphasis on programs and |
| 1224 | tools that help users exert that freedom. |
| 1225 | |
| 1226 | Building this distribution is a cooperative effort, and you are invited |
| 1227 | to join! Please get in touch with us on @email{bug-guix@@gnu.org}. We |
| 1228 | welcome ideas, bug reports, patches, and anything that may be helpful to |
| 1229 | the project. |
| 1230 | |
| 1231 | |
| 1232 | @c ********************************************************************* |
| 1233 | @node Acknowledgments |
| 1234 | @chapter Acknowledgments |
| 1235 | |
| 1236 | Guix is based on the Nix package manager, which was designed and |
| 1237 | implemented by Eelco Dolstra. Nix pioneered functional package |
| 1238 | management, and promoted unprecedented features, such as transactional |
| 1239 | package upgrades and rollbacks, per-user profiles, and referentially |
| 1240 | transparent build processes. Without this work, Guix would not exist. |
| 1241 | |
| 1242 | The Nix-based software distributions, Nixpkgs and NixOS, have also been |
| 1243 | an inspiration for Guix. |
| 1244 | |
| 1245 | @c ********************************************************************* |
| 1246 | @node GNU Free Documentation License |
| 1247 | @appendix GNU Free Documentation License |
| 1248 | |
| 1249 | @include fdl-1.3.texi |
| 1250 | |
| 1251 | @c ********************************************************************* |
| 1252 | @node Concept Index |
| 1253 | @unnumbered Concept Index |
| 1254 | @printindex cp |
| 1255 | |
| 1256 | @node Function Index |
| 1257 | @unnumbered Function Index |
| 1258 | @printindex fn |
| 1259 | |
| 1260 | @bye |
| 1261 | |
| 1262 | @c Local Variables: |
| 1263 | @c ispell-local-dictionary: "american"; |
| 1264 | @c End: |