| 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 | |
| 12 | @copying |
| 13 | Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@* |
| 14 | Copyright @copyright{} 2013, 2014 Andreas Enge@* |
| 15 | Copyright @copyright{} 2013 Nikita Karetnikov@* |
| 16 | Copyright @copyright{} 2015 Mathieu Lirzin@* |
| 17 | Copyright @copyright{} 2014 Pierre-Antoine Rault@* |
| 18 | Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer |
| 19 | |
| 20 | Permission is granted to copy, distribute and/or modify this document |
| 21 | under the terms of the GNU Free Documentation License, Version 1.3 or |
| 22 | any later version published by the Free Software Foundation; with no |
| 23 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A |
| 24 | copy of the license is included in the section entitled ``GNU Free |
| 25 | Documentation License''. |
| 26 | @end copying |
| 27 | |
| 28 | @dircategory Package management |
| 29 | @direntry |
| 30 | * guix: (guix). Guix, the functional package manager. |
| 31 | * guix package: (guix)Invoking guix package |
| 32 | Managing packages with Guix. |
| 33 | * guix build: (guix)Invoking guix build |
| 34 | Building packages with Guix. |
| 35 | * guix system: (guix)Invoking guix system |
| 36 | Managing the operating system configuration. |
| 37 | @end direntry |
| 38 | |
| 39 | @dircategory Software development |
| 40 | @direntry |
| 41 | * guix environment: (guix)Invoking guix environment |
| 42 | Building development environments with Guix. |
| 43 | @end direntry |
| 44 | |
| 45 | @titlepage |
| 46 | @title GNU Guix Reference Manual |
| 47 | @subtitle Using the GNU Guix Functional Package Manager |
| 48 | @author The GNU Guix Developers |
| 49 | |
| 50 | @page |
| 51 | @vskip 0pt plus 1filll |
| 52 | Edition @value{EDITION} @* |
| 53 | @value{UPDATED} @* |
| 54 | |
| 55 | @insertcopying |
| 56 | @end titlepage |
| 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 | @menu |
| 68 | * Introduction:: What is Guix about? |
| 69 | * Installation:: Installing Guix. |
| 70 | * Package Management:: Package installation, upgrade, etc. |
| 71 | * Emacs Interface:: Using Guix from Emacs. |
| 72 | * Programming Interface:: Using Guix in Scheme. |
| 73 | * Utilities:: Package management commands. |
| 74 | * GNU Distribution:: Software for your friendly GNU system. |
| 75 | * Contributing:: Your help needed! |
| 76 | |
| 77 | * Acknowledgments:: Thanks! |
| 78 | * GNU Free Documentation License:: The license of this manual. |
| 79 | * Concept Index:: Concepts. |
| 80 | * Programming Index:: Data types, functions, and variables. |
| 81 | |
| 82 | @detailmenu |
| 83 | --- The Detailed Node Listing --- |
| 84 | |
| 85 | Installation |
| 86 | |
| 87 | * Binary Installation:: Getting Guix running in no time! |
| 88 | * Requirements:: Software needed to build and run Guix. |
| 89 | * Running the Test Suite:: Testing Guix. |
| 90 | * Setting Up the Daemon:: Preparing the build daemon's environment. |
| 91 | * Invoking guix-daemon:: Running the build daemon. |
| 92 | * Application Setup:: Application-specific setup. |
| 93 | |
| 94 | Setting Up the Daemon |
| 95 | |
| 96 | * Build Environment Setup:: Preparing the isolated build environment. |
| 97 | * Daemon Offload Setup:: Offloading builds to remote machines. |
| 98 | |
| 99 | Package Management |
| 100 | |
| 101 | * Features:: How Guix will make your life brighter. |
| 102 | * Invoking guix package:: Package installation, removal, etc. |
| 103 | * Substitutes:: Downloading pre-built binaries. |
| 104 | * Packages with Multiple Outputs:: Single source package, multiple outputs. |
| 105 | * Invoking guix gc:: Running the garbage collector. |
| 106 | * Invoking guix pull:: Fetching the latest Guix and distribution. |
| 107 | * Invoking guix archive:: Exporting and importing store files. |
| 108 | |
| 109 | Emacs Interface |
| 110 | |
| 111 | * Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}. |
| 112 | * Package Management: Emacs Package Management. Managing packages and generations. |
| 113 | * Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands. |
| 114 | * Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names. |
| 115 | * Build Log Mode: Emacs Build Log. Highlighting Guix build logs. |
| 116 | * Completions: Emacs Completions. Completing @command{guix} shell command. |
| 117 | * Development: Emacs Development. Tools for Guix developers. |
| 118 | |
| 119 | Programming Interface |
| 120 | |
| 121 | * Defining Packages:: Defining new packages. |
| 122 | * Build Systems:: Specifying how packages are built. |
| 123 | * The Store:: Manipulating the package store. |
| 124 | * Derivations:: Low-level interface to package derivations. |
| 125 | * The Store Monad:: Purely functional interface to the store. |
| 126 | * G-Expressions:: Manipulating build expressions. |
| 127 | |
| 128 | Defining Packages |
| 129 | |
| 130 | * package Reference:: The package data type. |
| 131 | * origin Reference:: The origin data type. |
| 132 | |
| 133 | Utilities |
| 134 | |
| 135 | * Invoking guix build:: Building packages from the command line. |
| 136 | * Invoking guix edit:: Editing package definitions. |
| 137 | * Invoking guix download:: Downloading a file and printing its hash. |
| 138 | * Invoking guix hash:: Computing the cryptographic hash of a file. |
| 139 | * Invoking guix import:: Importing package definitions. |
| 140 | * Invoking guix refresh:: Updating package definitions. |
| 141 | * Invoking guix lint:: Finding errors in package definitions. |
| 142 | * Invoking guix size:: Profiling disk usage. |
| 143 | * Invoking guix graph:: Visualizing the graph of packages. |
| 144 | * Invoking guix environment:: Setting up development environments. |
| 145 | * Invoking guix publish:: Sharing substitutes. |
| 146 | * Invoking guix challenge:: Challenging substitute servers. |
| 147 | * Invoking guix container:: Process isolation. |
| 148 | |
| 149 | GNU Distribution |
| 150 | |
| 151 | * System Installation:: Installing the whole operating system. |
| 152 | * System Configuration:: Configuring the operating system. |
| 153 | * Installing Debugging Files:: Feeding the debugger. |
| 154 | * Security Updates:: Deploying security fixes quickly. |
| 155 | * Package Modules:: Packages from the programmer's viewpoint. |
| 156 | * Packaging Guidelines:: Growing the distribution. |
| 157 | * Bootstrapping:: GNU/Linux built from scratch. |
| 158 | * Porting:: Targeting another platform or kernel. |
| 159 | |
| 160 | System Configuration |
| 161 | |
| 162 | * Using the Configuration System:: Customizing your GNU system. |
| 163 | * operating-system Reference:: Detail of operating-system declarations. |
| 164 | * File Systems:: Configuring file system mounts. |
| 165 | * Mapped Devices:: Block device extra processing. |
| 166 | * User Accounts:: Specifying user accounts. |
| 167 | * Locales:: Language and cultural convention settings. |
| 168 | * Services:: Specifying system services. |
| 169 | * Setuid Programs:: Programs running with root privileges. |
| 170 | * X.509 Certificates:: Authenticating HTTPS servers. |
| 171 | * Name Service Switch:: Configuring libc's name service switch. |
| 172 | * Initial RAM Disk:: Linux-Libre bootstrapping. |
| 173 | * GRUB Configuration:: Configuring the boot loader. |
| 174 | * Invoking guix system:: Instantiating a system configuration. |
| 175 | * Defining Services:: Adding new service definitions. |
| 176 | |
| 177 | Services |
| 178 | |
| 179 | * Base Services:: Essential system services. |
| 180 | * Networking Services:: Network setup, SSH daemon, etc. |
| 181 | * X Window:: Graphical display. |
| 182 | * Desktop Services:: D-Bus and desktop services. |
| 183 | * Database Services:: SQL databases. |
| 184 | * Web Services:: Web servers. |
| 185 | * Various Services:: Other services. |
| 186 | |
| 187 | Defining Services |
| 188 | |
| 189 | * Service Composition:: The model for composing services. |
| 190 | * Service Types and Services:: Types and services. |
| 191 | * Service Reference:: API reference. |
| 192 | * dmd Services:: A particular type of service. |
| 193 | |
| 194 | Packaging Guidelines |
| 195 | |
| 196 | * Software Freedom:: What may go into the distribution. |
| 197 | * Package Naming:: What's in a name? |
| 198 | * Version Numbers:: When the name is not enough. |
| 199 | * Synopses and Descriptions:: Helping users find the right package. |
| 200 | * Python Modules:: Taming the snake. |
| 201 | * Perl Modules:: Little pearls. |
| 202 | * Fonts:: Fond of fonts. |
| 203 | |
| 204 | Contributing |
| 205 | |
| 206 | * Building from Git:: The latest and greatest. |
| 207 | * Running Guix Before It Is Installed:: Hacker tricks. |
| 208 | * The Perfect Setup:: The right tools. |
| 209 | * Coding Style:: Hygiene of the contributor. |
| 210 | * Submitting Patches:: Share your work. |
| 211 | |
| 212 | Coding Style |
| 213 | |
| 214 | * Programming Paradigm:: How to compose your elements. |
| 215 | * Modules:: Where to store your code? |
| 216 | * Data Types and Pattern Matching:: Implementing data structures. |
| 217 | * Formatting Code:: Writing conventions. |
| 218 | |
| 219 | @end detailmenu |
| 220 | @end menu |
| 221 | |
| 222 | @c ********************************************************************* |
| 223 | @node Introduction |
| 224 | @chapter Introduction |
| 225 | |
| 226 | GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' |
| 227 | using the international phonetic alphabet (IPA).} is a functional |
| 228 | package management tool for the GNU system. Package management consists |
| 229 | of all activities that relate to building packages from sources, |
| 230 | honoring their build-time and run-time dependencies, |
| 231 | installing packages in user environments, upgrading installed packages |
| 232 | to new versions or rolling back to a previous set, removing unused |
| 233 | software packages, etc. |
| 234 | |
| 235 | @cindex functional package management |
| 236 | The term @dfn{functional} refers to a specific package management |
| 237 | discipline pioneered by Nix (@pxref{Acknowledgments}). |
| 238 | In Guix, the package build and installation process is seen |
| 239 | as a function, in the mathematical sense. That function takes inputs, |
| 240 | such as build scripts, a compiler, and libraries, and |
| 241 | returns an installed package. As a pure function, its result depends |
| 242 | solely on its inputs---for instance, it cannot refer to software or |
| 243 | scripts that were not explicitly passed as inputs. A build function |
| 244 | always produces the same result when passed a given set of inputs. It |
| 245 | cannot alter the system's environment in |
| 246 | any way; for instance, it cannot create, modify, or delete files outside |
| 247 | of its build and installation directories. This is achieved by running |
| 248 | build processes in isolated environments (or @dfn{containers}), where only their |
| 249 | explicit inputs are visible. |
| 250 | |
| 251 | @cindex store |
| 252 | The result of package build functions is @dfn{cached} in the file |
| 253 | system, in a special directory called @dfn{the store} (@pxref{The |
| 254 | Store}). Each package is installed in a directory of its own, in the |
| 255 | store---by default under @file{/gnu/store}. The directory name contains |
| 256 | a hash of all the inputs used to build that package; thus, changing an |
| 257 | input yields a different directory name. |
| 258 | |
| 259 | This approach is the foundation of Guix's salient features: support for |
| 260 | transactional package upgrade and rollback, per-user installation, and |
| 261 | garbage collection of packages (@pxref{Features}). |
| 262 | |
| 263 | Guix has a command-line interface, which allows users to build, install, |
| 264 | upgrade, and remove packages, as well as a Scheme programming interface. |
| 265 | |
| 266 | @cindex Guix System Distribution |
| 267 | @cindex GuixSD |
| 268 | Last but not least, Guix is used to build a distribution of the GNU |
| 269 | system, with many GNU and non-GNU free software packages. The Guix |
| 270 | System Distribution, or GNU@tie{}GuixSD, takes advantage of the core |
| 271 | properties of Guix at the system level. With GuixSD, users |
| 272 | @emph{declare} all aspects of the operating system configuration, and |
| 273 | Guix takes care of instantiating that configuration in a reproducible, |
| 274 | stateless fashion. @xref{GNU Distribution}. |
| 275 | |
| 276 | @c ********************************************************************* |
| 277 | @node Installation |
| 278 | @chapter Installation |
| 279 | |
| 280 | GNU Guix is available for download from its website at |
| 281 | @url{http://www.gnu.org/software/guix/}. This section describes the |
| 282 | software requirements of Guix, as well as how to install it and get |
| 283 | ready to use it. |
| 284 | |
| 285 | Note that this section is concerned with the installation of the package |
| 286 | manager, which can be done on top of a running GNU/Linux system. If, |
| 287 | instead, you want to install the complete GNU operating system, |
| 288 | @pxref{System Installation}. |
| 289 | |
| 290 | @menu |
| 291 | * Binary Installation:: Getting Guix running in no time! |
| 292 | * Requirements:: Software needed to build and run Guix. |
| 293 | * Running the Test Suite:: Testing Guix. |
| 294 | * Setting Up the Daemon:: Preparing the build daemon's environment. |
| 295 | * Invoking guix-daemon:: Running the build daemon. |
| 296 | * Application Setup:: Application-specific setup. |
| 297 | @end menu |
| 298 | |
| 299 | @node Binary Installation |
| 300 | @section Binary Installation |
| 301 | |
| 302 | This section describes how to install Guix on an arbitrary system from a |
| 303 | self-contained tarball providing binaries for Guix and for all its |
| 304 | dependencies. This is often quicker than installing from source, which |
| 305 | is described in the next sections. The only requirement is to have |
| 306 | GNU@tie{}tar and Xz. |
| 307 | |
| 308 | Installing goes along these lines: |
| 309 | |
| 310 | @enumerate |
| 311 | @item |
| 312 | Download the binary tarball from |
| 313 | @indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As |
| 314 | usual, make sure to download the associated @file{.sig} file and to |
| 315 | verify the authenticity of the tarball against it!}, where @var{system} |
| 316 | is @code{x86_64-linux} for an @code{x86_64} machine already running the |
| 317 | kernel Linux, and so on. |
| 318 | |
| 319 | @item |
| 320 | As @code{root}, run: |
| 321 | |
| 322 | @example |
| 323 | # cd /tmp |
| 324 | # tar --warning=no-timestamp -xf \ |
| 325 | guix-binary-@value{VERSION}.@var{system}.tar.xz |
| 326 | # mv var/guix /var/ && mv gnu / |
| 327 | @end example |
| 328 | |
| 329 | This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}. |
| 330 | The latter contains a ready-to-use profile for @code{root} (see next |
| 331 | step.) |
| 332 | |
| 333 | Do @emph{not} unpack the tarball on a working Guix system since that |
| 334 | would overwrite its own essential files. |
| 335 | |
| 336 | The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does |
| 337 | not emit warnings about ``implausibly old time stamps'' (such |
| 338 | warnings were triggered by GNU@tie{}tar 1.26 and older; recent |
| 339 | versions are fine.) |
| 340 | They stem from the fact that all the |
| 341 | files in the archive have their modification time set to zero (which |
| 342 | means January 1st, 1970.) This is done on purpose to make sure the |
| 343 | archive content is independent of its creation time, thus making it |
| 344 | reproducible. |
| 345 | |
| 346 | @item |
| 347 | Make @code{root}'s profile available under @file{~/.guix-profile}: |
| 348 | |
| 349 | @example |
| 350 | # ln -sf /var/guix/profiles/per-user/root/guix-profile \ |
| 351 | ~root/.guix-profile |
| 352 | @end example |
| 353 | |
| 354 | @item |
| 355 | Create the group and user accounts for build users as explained below |
| 356 | (@pxref{Build Environment Setup}). |
| 357 | |
| 358 | @item |
| 359 | Run the daemon: |
| 360 | |
| 361 | @example |
| 362 | # ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild |
| 363 | @end example |
| 364 | |
| 365 | On hosts using the systemd init system, drop |
| 366 | @file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in |
| 367 | @file{/etc/systemd/system}. |
| 368 | |
| 369 | @item |
| 370 | Make the @command{guix} command available to other users on the machine, |
| 371 | for instance with: |
| 372 | |
| 373 | @example |
| 374 | # mkdir -p /usr/local/bin |
| 375 | # cd /usr/local/bin |
| 376 | # ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix |
| 377 | @end example |
| 378 | |
| 379 | @item |
| 380 | To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}), |
| 381 | authorize them: |
| 382 | |
| 383 | @example |
| 384 | # guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub |
| 385 | @end example |
| 386 | @end enumerate |
| 387 | |
| 388 | And that's it! For additional tips and tricks, @pxref{Application |
| 389 | Setup}. |
| 390 | |
| 391 | The @code{guix} package must remain available in @code{root}'s |
| 392 | profile, or it would become subject to garbage collection---in which |
| 393 | case you would find yourself badly handicapped by the lack of the |
| 394 | @command{guix} command. |
| 395 | |
| 396 | The tarball in question can be (re)produced and verified simply by |
| 397 | running the following command in the Guix source tree: |
| 398 | |
| 399 | @example |
| 400 | make guix-binary.@var{system}.tar.xz |
| 401 | @end example |
| 402 | |
| 403 | |
| 404 | @node Requirements |
| 405 | @section Requirements |
| 406 | |
| 407 | This section lists requirements when building Guix from source. The |
| 408 | build procedure for Guix is the same as for other GNU software, and is |
| 409 | not covered here. Please see the files @file{README} and @file{INSTALL} |
| 410 | in the Guix source tree for additional details. |
| 411 | |
| 412 | GNU Guix depends on the following packages: |
| 413 | |
| 414 | @itemize |
| 415 | @item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later; |
| 416 | @item @url{http://gnupg.org/, GNU libgcrypt}; |
| 417 | @item @url{http://www.gnu.org/software/make/, GNU Make}. |
| 418 | @end itemize |
| 419 | |
| 420 | The following dependencies are optional: |
| 421 | |
| 422 | @itemize |
| 423 | @item |
| 424 | Installing |
| 425 | @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will |
| 426 | allow you to use the @command{guix import pypi} command (@pxref{Invoking |
| 427 | guix import}). It is of |
| 428 | interest primarily for developers and not for casual users. |
| 429 | @item |
| 430 | Installing @uref{http://gnutls.org/, GnuTLS-Guile} will |
| 431 | allow you to access @code{https} URLs with the @command{guix download} |
| 432 | command (@pxref{Invoking guix download}), the @command{guix import pypi} |
| 433 | command, and the @command{guix import cpan} command. This is primarily |
| 434 | of interest to developers. @xref{Guile Preparations, how to install the |
| 435 | GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}. |
| 436 | @end itemize |
| 437 | |
| 438 | Unless @code{--disable-daemon} was passed to @command{configure}, the |
| 439 | following packages are also needed: |
| 440 | |
| 441 | @itemize |
| 442 | @item @url{http://sqlite.org, SQLite 3}; |
| 443 | @item @url{http://www.bzip.org, libbz2}; |
| 444 | @item @url{http://gcc.gnu.org, GCC's g++}, with support for the |
| 445 | C++11 standard. |
| 446 | @end itemize |
| 447 | |
| 448 | When a working installation of @url{http://nixos.org/nix/, the Nix package |
| 449 | manager} is available, you |
| 450 | can instead configure Guix with @code{--disable-daemon}. In that case, |
| 451 | Nix replaces the three dependencies above. |
| 452 | |
| 453 | Guix is compatible with Nix, so it is possible to share the same store |
| 454 | between both. To do so, you must pass @command{configure} not only the |
| 455 | same @code{--with-store-dir} value, but also the same |
| 456 | @code{--localstatedir} value. The latter is essential because it |
| 457 | specifies where the database that stores metadata about the store is |
| 458 | located, among other things. The default values for Nix are |
| 459 | @code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}. |
| 460 | Note that @code{--disable-daemon} is not required if |
| 461 | your goal is to share the store with Nix. |
| 462 | |
| 463 | @node Running the Test Suite |
| 464 | @section Running the Test Suite |
| 465 | |
| 466 | After a successful @command{configure} and @code{make} run, it is a good |
| 467 | idea to run the test suite. It can help catch issues with the setup or |
| 468 | environment, or bugs in Guix itself---and really, reporting test |
| 469 | failures is a good way to help improve the software. To run the test |
| 470 | suite, type: |
| 471 | |
| 472 | @example |
| 473 | make check |
| 474 | @end example |
| 475 | |
| 476 | Test cases can run in parallel: you can use the @code{-j} option of |
| 477 | GNU@tie{}make to speed things up. The first run may take a few minutes |
| 478 | on a recent machine; subsequent runs will be faster because the store |
| 479 | that is created for test purposes will already have various things in |
| 480 | cache. |
| 481 | |
| 482 | Upon failure, please email @email{bug-guix@@gnu.org} and attach the |
| 483 | @file{test-suite.log} file. When @file{tests/@var{something}.scm} |
| 484 | fails, please also attach the @file{@var{something}.log} file available |
| 485 | in the top-level build directory. Please specify the Guix version being |
| 486 | used as well as version numbers of the dependencies |
| 487 | (@pxref{Requirements}) in your message. |
| 488 | |
| 489 | @node Setting Up the Daemon |
| 490 | @section Setting Up the Daemon |
| 491 | |
| 492 | @cindex daemon |
| 493 | Operations such as building a package or running the garbage collector |
| 494 | are all performed by a specialized process, the @dfn{build daemon}, on |
| 495 | behalf of clients. Only the daemon may access the store and its |
| 496 | associated database. Thus, any operation that manipulates the store |
| 497 | goes through the daemon. For instance, command-line tools such as |
| 498 | @command{guix package} and @command{guix build} communicate with the |
| 499 | daemon (@i{via} remote procedure calls) to instruct it what to do. |
| 500 | |
| 501 | The following sections explain how to prepare the build daemon's |
| 502 | environment. Also @ref{Substitutes}, for information on how to allow |
| 503 | the daemon to download pre-built binaries. |
| 504 | |
| 505 | @menu |
| 506 | * Build Environment Setup:: Preparing the isolated build environment. |
| 507 | * Daemon Offload Setup:: Offloading builds to remote machines. |
| 508 | @end menu |
| 509 | |
| 510 | @node Build Environment Setup |
| 511 | @subsection Build Environment Setup |
| 512 | |
| 513 | In a standard multi-user setup, Guix and its daemon---the |
| 514 | @command{guix-daemon} program---are installed by the system |
| 515 | administrator; @file{/gnu/store} is owned by @code{root} and |
| 516 | @command{guix-daemon} runs as @code{root}. Unprivileged users may use |
| 517 | Guix tools to build packages or otherwise access the store, and the |
| 518 | daemon will do it on their behalf, ensuring that the store is kept in a |
| 519 | consistent state, and allowing built packages to be shared among users. |
| 520 | |
| 521 | @cindex build users |
| 522 | When @command{guix-daemon} runs as @code{root}, you may not want package |
| 523 | build processes themselves to run as @code{root} too, for obvious |
| 524 | security reasons. To avoid that, a special pool of @dfn{build users} |
| 525 | should be created for use by build processes started by the daemon. |
| 526 | These build users need not have a shell and a home directory: they will |
| 527 | just be used when the daemon drops @code{root} privileges in build |
| 528 | processes. Having several such users allows the daemon to launch |
| 529 | distinct build processes under separate UIDs, which guarantees that they |
| 530 | do not interfere with each other---an essential feature since builds are |
| 531 | regarded as pure functions (@pxref{Introduction}). |
| 532 | |
| 533 | On a GNU/Linux system, a build user pool may be created like this (using |
| 534 | Bash syntax and the @code{shadow} commands): |
| 535 | |
| 536 | @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html |
| 537 | @c for why `-G' is needed. |
| 538 | @example |
| 539 | # groupadd --system guixbuild |
| 540 | # for i in `seq -w 1 10`; |
| 541 | do |
| 542 | useradd -g guixbuild -G guixbuild \ |
| 543 | -d /var/empty -s `which nologin` \ |
| 544 | -c "Guix build user $i" --system \ |
| 545 | guixbuilder$i; |
| 546 | done |
| 547 | @end example |
| 548 | |
| 549 | @noindent |
| 550 | The number of build users determines how many build jobs may run in |
| 551 | parallel, as specified by the @option{--max-jobs} option |
| 552 | (@pxref{Invoking guix-daemon, @option{--max-jobs}}). The |
| 553 | @code{guix-daemon} program may then be run as @code{root} with the |
| 554 | following command@footnote{If your machine uses the systemd init system, |
| 555 | dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} |
| 556 | file in @file{/etc/systemd/system} will ensure that |
| 557 | @command{guix-daemon} is automatically started.}: |
| 558 | |
| 559 | @example |
| 560 | # guix-daemon --build-users-group=guixbuild |
| 561 | @end example |
| 562 | |
| 563 | @cindex chroot |
| 564 | @noindent |
| 565 | This way, the daemon starts build processes in a chroot, under one of |
| 566 | the @code{guixbuilder} users. On GNU/Linux, by default, the chroot |
| 567 | environment contains nothing but: |
| 568 | |
| 569 | @c Keep this list in sync with libstore/build.cc! ----------------------- |
| 570 | @itemize |
| 571 | @item |
| 572 | a minimal @code{/dev} directory, created mostly independently from the |
| 573 | host @code{/dev}@footnote{``Mostly'', because while the set of files |
| 574 | that appear in the chroot's @code{/dev} is fixed, most of these files |
| 575 | can only be created if the host has them.}; |
| 576 | |
| 577 | @item |
| 578 | the @code{/proc} directory; it only shows the container's processes |
| 579 | since a separate PID name space is used; |
| 580 | |
| 581 | @item |
| 582 | @file{/etc/passwd} with an entry for the current user and an entry for |
| 583 | user @file{nobody}; |
| 584 | |
| 585 | @item |
| 586 | @file{/etc/group} with an entry for the user's group; |
| 587 | |
| 588 | @item |
| 589 | @file{/etc/hosts} with an entry that maps @code{localhost} to |
| 590 | @code{127.0.0.1}; |
| 591 | |
| 592 | @item |
| 593 | a writable @file{/tmp} directory. |
| 594 | @end itemize |
| 595 | |
| 596 | If you are installing Guix as an unprivileged user, it is still possible |
| 597 | to run @command{guix-daemon} provided you pass @code{--disable-chroot}. |
| 598 | However, build processes will not be isolated from one another, and not |
| 599 | from the rest of the system. Thus, build processes may interfere with |
| 600 | each other, and may access programs, libraries, and other files |
| 601 | available on the system---making it much harder to view them as |
| 602 | @emph{pure} functions. |
| 603 | |
| 604 | |
| 605 | @node Daemon Offload Setup |
| 606 | @subsection Using the Offload Facility |
| 607 | |
| 608 | @cindex offloading |
| 609 | @cindex build hook |
| 610 | When desired, the build daemon can @dfn{offload} |
| 611 | derivation builds to other machines |
| 612 | running Guix, using the @code{offload} @dfn{build hook}. When that |
| 613 | feature is enabled, a list of user-specified build machines is read from |
| 614 | @file{/etc/guix/machines.scm}; anytime a build is requested, for |
| 615 | instance via @code{guix build}, the daemon attempts to offload it to one |
| 616 | of the machines that satisfies the derivation's constraints, in |
| 617 | particular its system type---e.g., @file{x86_64-linux}. Missing |
| 618 | prerequisites for the build are copied over SSH to the target machine, |
| 619 | which then proceeds with the build; upon success the output(s) of the |
| 620 | build are copied back to the initial machine. |
| 621 | |
| 622 | The @file{/etc/guix/machines.scm} file typically looks like this: |
| 623 | |
| 624 | @example |
| 625 | (list (build-machine |
| 626 | (name "eightysix.example.org") |
| 627 | (system "x86_64-linux") |
| 628 | (user "bob") |
| 629 | (speed 2.)) ; incredibly fast! |
| 630 | |
| 631 | (build-machine |
| 632 | (name "meeps.example.org") |
| 633 | (system "mips64el-linux") |
| 634 | (user "alice") |
| 635 | (private-key |
| 636 | (string-append (getenv "HOME") |
| 637 | "/.lsh/identity-for-guix")))) |
| 638 | @end example |
| 639 | |
| 640 | @noindent |
| 641 | In the example above we specify a list of two build machines, one for |
| 642 | the @code{x86_64} architecture and one for the @code{mips64el} |
| 643 | architecture. |
| 644 | |
| 645 | In fact, this file is---not surprisingly!---a Scheme file that is |
| 646 | evaluated when the @code{offload} hook is started. Its return value |
| 647 | must be a list of @code{build-machine} objects. While this example |
| 648 | shows a fixed list of build machines, one could imagine, say, using |
| 649 | DNS-SD to return a list of potential build machines discovered in the |
| 650 | local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using |
| 651 | Avahi in Guile Scheme Programs}). The @code{build-machine} data type is |
| 652 | detailed below. |
| 653 | |
| 654 | @deftp {Data Type} build-machine |
| 655 | This data type represents build machines the daemon may offload builds |
| 656 | to. The important fields are: |
| 657 | |
| 658 | @table @code |
| 659 | |
| 660 | @item name |
| 661 | The remote machine's host name. |
| 662 | |
| 663 | @item system |
| 664 | The remote machine's system type---e.g., @code{"x86_64-linux"}. |
| 665 | |
| 666 | @item user |
| 667 | The user account to use when connecting to the remote machine over SSH. |
| 668 | Note that the SSH key pair must @emph{not} be passphrase-protected, to |
| 669 | allow non-interactive logins. |
| 670 | |
| 671 | @end table |
| 672 | |
| 673 | A number of optional fields may be specified: |
| 674 | |
| 675 | @table @code |
| 676 | |
| 677 | @item port |
| 678 | Port number of the machine's SSH server (default: 22). |
| 679 | |
| 680 | @item private-key |
| 681 | The SSH private key file to use when connecting to the machine. |
| 682 | |
| 683 | Currently offloading uses GNU@tie{}lsh as its SSH client |
| 684 | (@pxref{Invoking lsh,,, GNU lsh Manual}). Thus, the key file here must |
| 685 | be an lsh key file. This may change in the future, though. |
| 686 | |
| 687 | @item parallel-builds |
| 688 | The number of builds that may run in parallel on the machine (1 by |
| 689 | default.) |
| 690 | |
| 691 | @item speed |
| 692 | A ``relative speed factor''. The offload scheduler will tend to prefer |
| 693 | machines with a higher speed factor. |
| 694 | |
| 695 | @item features |
| 696 | A list of strings denoting specific features supported by the machine. |
| 697 | An example is @code{"kvm"} for machines that have the KVM Linux modules |
| 698 | and corresponding hardware support. Derivations can request features by |
| 699 | name, and they will be scheduled on matching build machines. |
| 700 | |
| 701 | @end table |
| 702 | @end deftp |
| 703 | |
| 704 | The @code{guix} command must be in the search path on the build |
| 705 | machines, since offloading works by invoking the @code{guix archive} and |
| 706 | @code{guix build} commands. In addition, the Guix modules must be in |
| 707 | @code{$GUILE_LOAD_PATH} on the build machine---you can check whether |
| 708 | this is the case by running: |
| 709 | |
| 710 | @example |
| 711 | lsh build-machine guile -c '(use-modules (guix config))' |
| 712 | @end example |
| 713 | |
| 714 | There's one last thing to do once @file{machines.scm} is in place. As |
| 715 | explained above, when offloading, files are transferred back and forth |
| 716 | between the machine stores. For this to work, you first need to |
| 717 | generate a key pair on each machine to allow the daemon to export signed |
| 718 | archives of files from the store (@pxref{Invoking guix archive}): |
| 719 | |
| 720 | @example |
| 721 | # guix archive --generate-key |
| 722 | @end example |
| 723 | |
| 724 | @noindent |
| 725 | Each build machine must authorize the key of the master machine so that |
| 726 | it accepts store items it receives from the master: |
| 727 | |
| 728 | @example |
| 729 | # guix archive --authorize < master-public-key.txt |
| 730 | @end example |
| 731 | |
| 732 | @noindent |
| 733 | Likewise, the master machine must authorize the key of each build machine. |
| 734 | |
| 735 | All the fuss with keys is here to express pairwise mutual trust |
| 736 | relations between the master and the build machines. Concretely, when |
| 737 | the master receives files from a build machine (and @i{vice versa}), its |
| 738 | build daemon can make sure they are genuine, have not been tampered |
| 739 | with, and that they are signed by an authorized key. |
| 740 | |
| 741 | |
| 742 | @node Invoking guix-daemon |
| 743 | @section Invoking @command{guix-daemon} |
| 744 | |
| 745 | The @command{guix-daemon} program implements all the functionality to |
| 746 | access the store. This includes launching build processes, running the |
| 747 | garbage collector, querying the availability of a build result, etc. It |
| 748 | is normally run as @code{root} like this: |
| 749 | |
| 750 | @example |
| 751 | # guix-daemon --build-users-group=guixbuild |
| 752 | @end example |
| 753 | |
| 754 | @noindent |
| 755 | For details on how to set it up, @pxref{Setting Up the Daemon}. |
| 756 | |
| 757 | @cindex chroot |
| 758 | @cindex container, build environment |
| 759 | @cindex build environment |
| 760 | @cindex reproducible builds |
| 761 | By default, @command{guix-daemon} launches build processes under |
| 762 | different UIDs, taken from the build group specified with |
| 763 | @code{--build-users-group}. In addition, each build process is run in a |
| 764 | chroot environment that only contains the subset of the store that the |
| 765 | build process depends on, as specified by its derivation |
| 766 | (@pxref{Programming Interface, derivation}), plus a set of specific |
| 767 | system directories. By default, the latter contains @file{/dev} and |
| 768 | @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a |
| 769 | @dfn{container}: in addition to having its own file system tree, it has |
| 770 | a separate mount name space, its own PID name space, network name space, |
| 771 | etc. This helps achieve reproducible builds (@pxref{Features}). |
| 772 | |
| 773 | When the daemon performs a build on behalf of the user, it creates a |
| 774 | build directory under @file{/tmp} or under the directory specified by |
| 775 | its @code{TMPDIR} environment variable; this directory is shared with |
| 776 | the container for the duration of the build. Be aware that using a |
| 777 | directory other than @file{/tmp} can affect build results---for example, |
| 778 | with a longer directory name, a build process that uses Unix-domain |
| 779 | sockets might hit the name length limitation for @code{sun_path}, which |
| 780 | it would otherwise not hit. |
| 781 | |
| 782 | The build directory is automatically deleted upon completion, unless the |
| 783 | build failed and the client specified @option{--keep-failed} |
| 784 | (@pxref{Invoking guix build, @option{--keep-failed}}). |
| 785 | |
| 786 | The following command-line options are supported: |
| 787 | |
| 788 | @table @code |
| 789 | @item --build-users-group=@var{group} |
| 790 | Take users from @var{group} to run build processes (@pxref{Setting Up |
| 791 | the Daemon, build users}). |
| 792 | |
| 793 | @item --no-substitutes |
| 794 | @cindex substitutes |
| 795 | Do not use substitutes for build products. That is, always build things |
| 796 | locally instead of allowing downloads of pre-built binaries |
| 797 | (@pxref{Substitutes}). |
| 798 | |
| 799 | By default substitutes are used, unless the client---such as the |
| 800 | @command{guix package} command---is explicitly invoked with |
| 801 | @code{--no-substitutes}. |
| 802 | |
| 803 | When the daemon runs with @code{--no-substitutes}, clients can still |
| 804 | explicitly enable substitution @i{via} the @code{set-build-options} |
| 805 | remote procedure call (@pxref{The Store}). |
| 806 | |
| 807 | @item --substitute-urls=@var{urls} |
| 808 | @anchor{daemon-substitute-urls} |
| 809 | Consider @var{urls} the default whitespace-separated list of substitute |
| 810 | source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org} |
| 811 | is used. |
| 812 | |
| 813 | This means that substitutes may be downloaded from @var{urls}, as long |
| 814 | as they are signed by a trusted signature (@pxref{Substitutes}). |
| 815 | |
| 816 | @cindex build hook |
| 817 | @item --no-build-hook |
| 818 | Do not use the @dfn{build hook}. |
| 819 | |
| 820 | The build hook is a helper program that the daemon can start and to |
| 821 | which it submits build requests. This mechanism is used to offload |
| 822 | builds to other machines (@pxref{Daemon Offload Setup}). |
| 823 | |
| 824 | @item --cache-failures |
| 825 | Cache build failures. By default, only successful builds are cached. |
| 826 | |
| 827 | When this option is used, @command{guix gc --list-failures} can be used |
| 828 | to query the set of store items marked as failed; @command{guix gc |
| 829 | --clear-failures} removes store items from the set of cached failures. |
| 830 | @xref{Invoking guix gc}. |
| 831 | |
| 832 | @item --cores=@var{n} |
| 833 | @itemx -c @var{n} |
| 834 | Use @var{n} CPU cores to build each derivation; @code{0} means as many |
| 835 | as available. |
| 836 | |
| 837 | The default value is @code{0}, but it may be overridden by clients, such |
| 838 | as the @code{--cores} option of @command{guix build} (@pxref{Invoking |
| 839 | guix build}). |
| 840 | |
| 841 | The effect is to define the @code{NIX_BUILD_CORES} environment variable |
| 842 | in the build process, which can then use it to exploit internal |
| 843 | parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}. |
| 844 | |
| 845 | @item --max-jobs=@var{n} |
| 846 | @itemx -M @var{n} |
| 847 | Allow at most @var{n} build jobs in parallel. The default value is |
| 848 | @code{1}. Setting it to @code{0} means that no builds will be performed |
| 849 | locally; instead, the daemon will offload builds (@pxref{Daemon Offload |
| 850 | Setup}), or simply fail. |
| 851 | |
| 852 | @item --debug |
| 853 | Produce debugging output. |
| 854 | |
| 855 | This is useful to debug daemon start-up issues, but then it may be |
| 856 | overridden by clients, for example the @code{--verbosity} option of |
| 857 | @command{guix build} (@pxref{Invoking guix build}). |
| 858 | |
| 859 | @item --chroot-directory=@var{dir} |
| 860 | Add @var{dir} to the build chroot. |
| 861 | |
| 862 | Doing this may change the result of build processes---for instance if |
| 863 | they use optional dependencies found in @var{dir} when it is available, |
| 864 | and not otherwise. For that reason, it is not recommended to do so. |
| 865 | Instead, make sure that each derivation declares all the inputs that it |
| 866 | needs. |
| 867 | |
| 868 | @item --disable-chroot |
| 869 | Disable chroot builds. |
| 870 | |
| 871 | Using this option is not recommended since, again, it would allow build |
| 872 | processes to gain access to undeclared dependencies. It is necessary, |
| 873 | though, when @command{guix-daemon} is running under an unprivileged user |
| 874 | account. |
| 875 | |
| 876 | @item --disable-log-compression |
| 877 | Disable compression of the build logs. |
| 878 | |
| 879 | Unless @code{--lose-logs} is used, all the build logs are kept in the |
| 880 | @var{localstatedir}. To save space, the daemon automatically compresses |
| 881 | them with bzip2 by default. This option disables that. |
| 882 | |
| 883 | @item --disable-deduplication |
| 884 | @cindex deduplication |
| 885 | Disable automatic file ``deduplication'' in the store. |
| 886 | |
| 887 | By default, files added to the store are automatically ``deduplicated'': |
| 888 | if a newly added file is identical to another one found in the store, |
| 889 | the daemon makes the new file a hard link to the other file. This can |
| 890 | noticeably reduce disk usage, at the expense of slightly increased |
| 891 | input/output load at the end of a build process. This option disables |
| 892 | this optimization. |
| 893 | |
| 894 | @item --gc-keep-outputs[=yes|no] |
| 895 | Tell whether the garbage collector (GC) must keep outputs of live |
| 896 | derivations. |
| 897 | |
| 898 | When set to ``yes'', the GC will keep the outputs of any live derivation |
| 899 | available in the store---the @code{.drv} files. The default is ``no'', |
| 900 | meaning that derivation outputs are kept only if they are GC roots. |
| 901 | |
| 902 | @item --gc-keep-derivations[=yes|no] |
| 903 | Tell whether the garbage collector (GC) must keep derivations |
| 904 | corresponding to live outputs. |
| 905 | |
| 906 | When set to ``yes'', as is the case by default, the GC keeps |
| 907 | derivations---i.e., @code{.drv} files---as long as at least one of their |
| 908 | outputs is live. This allows users to keep track of the origins of |
| 909 | items in their store. Setting it to ``no'' saves a bit of disk space. |
| 910 | |
| 911 | Note that when both @code{--gc-keep-derivations} and |
| 912 | @code{--gc-keep-outputs} are used, the effect is to keep all the build |
| 913 | prerequisites (the sources, compiler, libraries, and other build-time |
| 914 | tools) of live objects in the store, regardless of whether these |
| 915 | prerequisites are live. This is convenient for developers since it |
| 916 | saves rebuilds or downloads. |
| 917 | |
| 918 | @item --impersonate-linux-2.6 |
| 919 | On Linux-based systems, impersonate Linux 2.6. This means that the |
| 920 | kernel's @code{uname} system call will report 2.6 as the release number. |
| 921 | |
| 922 | This might be helpful to build programs that (usually wrongfully) depend |
| 923 | on the kernel version number. |
| 924 | |
| 925 | @item --lose-logs |
| 926 | Do not keep build logs. By default they are kept under |
| 927 | @code{@var{localstatedir}/guix/log}. |
| 928 | |
| 929 | @item --system=@var{system} |
| 930 | Assume @var{system} as the current system type. By default it is the |
| 931 | architecture/kernel pair found at configure time, such as |
| 932 | @code{x86_64-linux}. |
| 933 | |
| 934 | @item --listen=@var{socket} |
| 935 | Listen for connections on @var{socket}, the file name of a Unix-domain |
| 936 | socket. The default socket is |
| 937 | @file{@var{localstatedir}/daemon-socket/socket}. This option is only |
| 938 | useful in exceptional circumstances, such as if you need to run several |
| 939 | daemons on the same machine. |
| 940 | @end table |
| 941 | |
| 942 | |
| 943 | @node Application Setup |
| 944 | @section Application Setup |
| 945 | |
| 946 | When using Guix on top of GNU/Linux distribution other than GuixSD---a |
| 947 | so-called @dfn{foreign distro}---a few additional steps are needed to |
| 948 | get everything in place. Here are some of them. |
| 949 | |
| 950 | @subsection Locales |
| 951 | |
| 952 | @anchor{locales-and-locpath} |
| 953 | @cindex locales, when not on GuixSD |
| 954 | @vindex LOCPATH |
| 955 | @vindex GUIX_LOCPATH |
| 956 | Packages installed @i{via} Guix will not use the host system's locale |
| 957 | data. Instead, you must first install one of the locale packages |
| 958 | available with Guix and then define the @code{GUIX_LOCPATH} environment |
| 959 | variable: |
| 960 | |
| 961 | @example |
| 962 | $ guix package -i glibc-locales |
| 963 | $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale |
| 964 | @end example |
| 965 | |
| 966 | Note that the @code{glibc-locales} package contains data for all the |
| 967 | locales supported by the GNU@tie{}libc and weighs in at around |
| 968 | 110@tie{}MiB. Alternately, the @code{glibc-utf8-locales} is smaller but |
| 969 | limited to a few UTF-8 locales. |
| 970 | |
| 971 | The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH} |
| 972 | (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference |
| 973 | Manual}). There are two important differences though: |
| 974 | |
| 975 | @enumerate |
| 976 | @item |
| 977 | @code{GUIX_LOCPATH} is honored only by Guix's libc, and not by the libc |
| 978 | provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you |
| 979 | to make sure the the foreign distro's programs will not end up loading |
| 980 | incompatible locale data. |
| 981 | |
| 982 | @item |
| 983 | libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where |
| 984 | @code{X.Y} is the libc version---e.g., @code{2.22}. This means that, |
| 985 | should your Guix profile contain a mixture of programs linked against |
| 986 | different libc version, each libc version will only try to load locale |
| 987 | data in the right format. |
| 988 | @end enumerate |
| 989 | |
| 990 | This is important because the locale data format used by different libc |
| 991 | versions may be incompatible. |
| 992 | |
| 993 | @subsection X11 Fonts |
| 994 | |
| 995 | The majority of graphical applications use Fontconfig to locate and |
| 996 | load fonts and perform X11-client-side rendering. Guix's |
| 997 | @code{fontconfig} package looks for fonts in @file{$HOME/.guix-profile} |
| 998 | by default. Thus, to allow graphical applications installed with Guix |
| 999 | to display fonts, you will have to install fonts with Guix as well. |
| 1000 | Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and |
| 1001 | @code{font-gnu-freefont-ttf}. |
| 1002 | |
| 1003 | @c TODO What else? |
| 1004 | |
| 1005 | @c ********************************************************************* |
| 1006 | @node Package Management |
| 1007 | @chapter Package Management |
| 1008 | |
| 1009 | The purpose of GNU Guix is to allow users to easily install, upgrade, and |
| 1010 | remove software packages, without having to know about their build |
| 1011 | procedure or dependencies. Guix also goes beyond this obvious set of |
| 1012 | features. |
| 1013 | |
| 1014 | This chapter describes the main features of Guix, as well as the package |
| 1015 | management tools it provides. Two user interfaces are provided for |
| 1016 | routine package management tasks: A command-line interface described below |
| 1017 | (@pxref{Invoking guix package, @code{guix package}}), as well as a visual user |
| 1018 | interface in Emacs described in a subsequent chapter (@pxref{Emacs Interface}). |
| 1019 | |
| 1020 | @menu |
| 1021 | * Features:: How Guix will make your life brighter. |
| 1022 | * Invoking guix package:: Package installation, removal, etc. |
| 1023 | * Substitutes:: Downloading pre-built binaries. |
| 1024 | * Packages with Multiple Outputs:: Single source package, multiple outputs. |
| 1025 | * Invoking guix gc:: Running the garbage collector. |
| 1026 | * Invoking guix pull:: Fetching the latest Guix and distribution. |
| 1027 | * Invoking guix archive:: Exporting and importing store files. |
| 1028 | @end menu |
| 1029 | |
| 1030 | @node Features |
| 1031 | @section Features |
| 1032 | |
| 1033 | When using Guix, each package ends up in the @dfn{package store}, in its |
| 1034 | own directory---something that resembles |
| 1035 | @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string |
| 1036 | (note that Guix comes with an Emacs extension to shorten those file |
| 1037 | names, @pxref{Emacs Prettify}.) |
| 1038 | |
| 1039 | Instead of referring to these directories, users have their own |
| 1040 | @dfn{profile}, which points to the packages that they actually want to |
| 1041 | use. These profiles are stored within each user's home directory, at |
| 1042 | @code{$HOME/.guix-profile}. |
| 1043 | |
| 1044 | For example, @code{alice} installs GCC 4.7.2. As a result, |
| 1045 | @file{/home/alice/.guix-profile/bin/gcc} points to |
| 1046 | @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, |
| 1047 | @code{bob} had already installed GCC 4.8.0. The profile of @code{bob} |
| 1048 | simply continues to point to |
| 1049 | @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC |
| 1050 | coexist on the same system without any interference. |
| 1051 | |
| 1052 | The @command{guix package} command is the central tool to manage |
| 1053 | packages (@pxref{Invoking guix package}). It operates on those per-user |
| 1054 | profiles, and can be used @emph{with normal user privileges}. |
| 1055 | |
| 1056 | The command provides the obvious install, remove, and upgrade |
| 1057 | operations. Each invocation is actually a @emph{transaction}: either |
| 1058 | the specified operation succeeds, or nothing happens. Thus, if the |
| 1059 | @command{guix package} process is terminated during the transaction, |
| 1060 | or if a power outage occurs during the transaction, then the user's |
| 1061 | profile remains in its previous state, and remains usable. |
| 1062 | |
| 1063 | In addition, any package transaction may be @emph{rolled back}. So, if, |
| 1064 | for example, an upgrade installs a new version of a package that turns |
| 1065 | out to have a serious bug, users may roll back to the previous instance |
| 1066 | of their profile, which was known to work well. Similarly, the global |
| 1067 | system configuration is subject to transactional upgrades and roll-back |
| 1068 | (@pxref{Using the Configuration System}). |
| 1069 | |
| 1070 | All those packages in the package store may be @emph{garbage-collected}. |
| 1071 | Guix can determine which packages are still referenced by the user |
| 1072 | profiles, and remove those that are provably no longer referenced |
| 1073 | (@pxref{Invoking guix gc}). Users may also explicitly remove old |
| 1074 | generations of their profile so that the packages they refer to can be |
| 1075 | collected. |
| 1076 | |
| 1077 | @cindex reproducibility |
| 1078 | @cindex reproducible builds |
| 1079 | Finally, Guix takes a @dfn{purely functional} approach to package |
| 1080 | management, as described in the introduction (@pxref{Introduction}). |
| 1081 | Each @file{/gnu/store} package directory name contains a hash of all the |
| 1082 | inputs that were used to build that package---compiler, libraries, build |
| 1083 | scripts, etc. This direct correspondence allows users to make sure a |
| 1084 | given package installation matches the current state of their |
| 1085 | distribution. It also helps maximize @dfn{build reproducibility}: |
| 1086 | thanks to the isolated build environments that are used, a given build |
| 1087 | is likely to yield bit-identical files when performed on different |
| 1088 | machines (@pxref{Invoking guix-daemon, container}). |
| 1089 | |
| 1090 | @cindex substitutes |
| 1091 | This foundation allows Guix to support @dfn{transparent binary/source |
| 1092 | deployment}. When a pre-built binary for a @file{/gnu/store} item is |
| 1093 | available from an external source---a @dfn{substitute}, Guix just |
| 1094 | downloads it and unpacks it; |
| 1095 | otherwise, it builds the package from source, locally |
| 1096 | (@pxref{Substitutes}). |
| 1097 | |
| 1098 | Control over the build environment is a feature that is also useful for |
| 1099 | developers. The @command{guix environment} command allows developers of |
| 1100 | a package to quickly set up the right development environment for their |
| 1101 | package, without having to manually install the package's dependencies |
| 1102 | in their profile (@pxref{Invoking guix environment}). |
| 1103 | |
| 1104 | @node Invoking guix package |
| 1105 | @section Invoking @command{guix package} |
| 1106 | |
| 1107 | The @command{guix package} command is the tool that allows users to |
| 1108 | install, upgrade, and remove packages, as well as rolling back to |
| 1109 | previous configurations. It operates only on the user's own profile, |
| 1110 | and works with normal user privileges (@pxref{Features}). Its syntax |
| 1111 | is: |
| 1112 | |
| 1113 | @example |
| 1114 | guix package @var{options} |
| 1115 | @end example |
| 1116 | |
| 1117 | Primarily, @var{options} specifies the operations to be performed during |
| 1118 | the transaction. Upon completion, a new profile is created, but |
| 1119 | previous @dfn{generations} of the profile remain available, should the user |
| 1120 | want to roll back. |
| 1121 | |
| 1122 | For example, to remove @code{lua} and install @code{guile} and |
| 1123 | @code{guile-cairo} in a single transaction: |
| 1124 | |
| 1125 | @example |
| 1126 | guix package -r lua -i guile guile-cairo |
| 1127 | @end example |
| 1128 | |
| 1129 | @command{guix package} also supports a @dfn{declarative approach} |
| 1130 | whereby the user specifies the exact set of packages to be available and |
| 1131 | passes it @i{via} the @option{--manifest} option |
| 1132 | (@pxref{profile-manifest, @option{--manifest}}). |
| 1133 | |
| 1134 | For each user, a symlink to the user's default profile is automatically |
| 1135 | created in @file{$HOME/.guix-profile}. This symlink always points to the |
| 1136 | current generation of the user's default profile. Thus, users can add |
| 1137 | @file{$HOME/.guix-profile/bin} to their @code{PATH} environment |
| 1138 | variable, and so on. |
| 1139 | @cindex search paths |
| 1140 | If you are not using the Guix System Distribution, consider adding the |
| 1141 | following lines to your @file{~/.bash_profile} (@pxref{Bash Startup |
| 1142 | Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned |
| 1143 | shells get all the right environment variable definitions: |
| 1144 | |
| 1145 | @example |
| 1146 | GUIX_PROFILE="$HOME/.guix-profile" \ |
| 1147 | source "$HOME/.guix-profile/etc/profile" |
| 1148 | @end example |
| 1149 | |
| 1150 | In a multi-user setup, user profiles are stored in a place registered as |
| 1151 | a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points |
| 1152 | to (@pxref{Invoking guix gc}). That directory is normally |
| 1153 | @code{@var{localstatedir}/profiles/per-user/@var{user}}, where |
| 1154 | @var{localstatedir} is the value passed to @code{configure} as |
| 1155 | @code{--localstatedir}, and @var{user} is the user name. The |
| 1156 | @file{per-user} directory is created when @command{guix-daemon} is |
| 1157 | started, and the @var{user} sub-directory is created by @command{guix |
| 1158 | package}. |
| 1159 | |
| 1160 | The @var{options} can be among the following: |
| 1161 | |
| 1162 | @table @code |
| 1163 | |
| 1164 | @item --install=@var{package} @dots{} |
| 1165 | @itemx -i @var{package} @dots{} |
| 1166 | Install the specified @var{package}s. |
| 1167 | |
| 1168 | Each @var{package} may specify either a simple package name, such as |
| 1169 | @code{guile}, or a package name followed by a hyphen and version number, |
| 1170 | such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter |
| 1171 | case, the newest version prefixed by @code{1.8} is selected.) |
| 1172 | |
| 1173 | If no version number is specified, the |
| 1174 | newest available version will be selected. In addition, @var{package} |
| 1175 | may contain a colon, followed by the name of one of the outputs of the |
| 1176 | package, as in @code{gcc:doc} or @code{binutils-2.22:lib} |
| 1177 | (@pxref{Packages with Multiple Outputs}). Packages with a corresponding |
| 1178 | name (and optionally version) are searched for among the GNU |
| 1179 | distribution modules (@pxref{Package Modules}). |
| 1180 | |
| 1181 | @cindex propagated inputs |
| 1182 | Sometimes packages have @dfn{propagated inputs}: these are dependencies |
| 1183 | that automatically get installed along with the required package |
| 1184 | (@pxref{package-propagated-inputs, @code{propagated-inputs} in |
| 1185 | @code{package} objects}, for information about propagated inputs in |
| 1186 | package definitions). |
| 1187 | |
| 1188 | @anchor{package-cmd-propagated-inputs} |
| 1189 | An example is the GNU MPC library: its C header files refer to those of |
| 1190 | the GNU MPFR library, which in turn refer to those of the GMP library. |
| 1191 | Thus, when installing MPC, the MPFR and GMP libraries also get installed |
| 1192 | in the profile; removing MPC also removes MPFR and GMP---unless they had |
| 1193 | also been explicitly installed independently. |
| 1194 | |
| 1195 | Besides, packages sometimes rely on the definition of environment |
| 1196 | variables for their search paths (see explanation of |
| 1197 | @code{--search-paths} below). Any missing or possibly incorrect |
| 1198 | environment variable definitions are reported here. |
| 1199 | |
| 1200 | @c XXX: keep me up-to-date |
| 1201 | Finally, when installing a GNU package, the tool reports the |
| 1202 | availability of a newer upstream version. In the future, it may provide |
| 1203 | the option of installing directly from the upstream version, even if |
| 1204 | that version is not yet in the distribution. |
| 1205 | |
| 1206 | @item --install-from-expression=@var{exp} |
| 1207 | @itemx -e @var{exp} |
| 1208 | Install the package @var{exp} evaluates to. |
| 1209 | |
| 1210 | @var{exp} must be a Scheme expression that evaluates to a |
| 1211 | @code{<package>} object. This option is notably useful to disambiguate |
| 1212 | between same-named variants of a package, with expressions such as |
| 1213 | @code{(@@ (gnu packages base) guile-final)}. |
| 1214 | |
| 1215 | Note that this option installs the first output of the specified |
| 1216 | package, which may be insufficient when needing a specific output of a |
| 1217 | multiple-output package. |
| 1218 | |
| 1219 | @item --install-from-file=@var{file} |
| 1220 | @itemx -f @var{file} |
| 1221 | Install the package that the code within @var{file} evaluates to. |
| 1222 | |
| 1223 | As an example, @var{file} might contain a definition like this |
| 1224 | (@pxref{Defining Packages}): |
| 1225 | |
| 1226 | @example |
| 1227 | @verbatiminclude package-hello.scm |
| 1228 | @end example |
| 1229 | |
| 1230 | Developers may find it useful to include such a @file{package.scm} file |
| 1231 | in the root of their project's source tree that can be used to test |
| 1232 | development snapshots and create reproducible development environments |
| 1233 | (@pxref{Invoking guix environment}). |
| 1234 | |
| 1235 | @item --remove=@var{package} @dots{} |
| 1236 | @itemx -r @var{package} @dots{} |
| 1237 | Remove the specified @var{package}s. |
| 1238 | |
| 1239 | As for @code{--install}, each @var{package} may specify a version number |
| 1240 | and/or output name in addition to the package name. For instance, |
| 1241 | @code{-r glibc:debug} would remove the @code{debug} output of |
| 1242 | @code{glibc}. |
| 1243 | |
| 1244 | @item --upgrade[=@var{regexp} @dots{}] |
| 1245 | @itemx -u [@var{regexp} @dots{}] |
| 1246 | Upgrade all the installed packages. If one or more @var{regexp}s are |
| 1247 | specified, upgrade only installed packages whose name matches a |
| 1248 | @var{regexp}. Also see the @code{--do-not-upgrade} option below. |
| 1249 | |
| 1250 | Note that this upgrades package to the latest version of packages found |
| 1251 | in the distribution currently installed. To update your distribution, |
| 1252 | you should regularly run @command{guix pull} (@pxref{Invoking guix |
| 1253 | pull}). |
| 1254 | |
| 1255 | @item --do-not-upgrade[=@var{regexp} @dots{}] |
| 1256 | When used together with the @code{--upgrade} option, do @emph{not} |
| 1257 | upgrade any packages whose name matches a @var{regexp}. For example, to |
| 1258 | upgrade all packages in the current profile except those containing the |
| 1259 | substring ``emacs'': |
| 1260 | |
| 1261 | @example |
| 1262 | $ guix package --upgrade . --do-not-upgrade emacs |
| 1263 | @end example |
| 1264 | |
| 1265 | @item @anchor{profile-manifest}--manifest=@var{file} |
| 1266 | @itemx -m @var{file} |
| 1267 | @cindex profile declaration |
| 1268 | @cindex profile manifest |
| 1269 | Create a new generation of the profile from the manifest object |
| 1270 | returned by the Scheme code in @var{file}. |
| 1271 | |
| 1272 | This allows you to @emph{declare} the profile's contents rather than |
| 1273 | constructing it through a sequence of @code{--install} and similar |
| 1274 | commands. The advantage is that @var{file} can be put under version |
| 1275 | control, copied to different machines to reproduce the same profile, and |
| 1276 | so on. |
| 1277 | |
| 1278 | @c FIXME: Add reference to (guix profile) documentation when available. |
| 1279 | @var{file} must return a @dfn{manifest} object, which is roughly a list |
| 1280 | of packages: |
| 1281 | |
| 1282 | @findex packages->manifest |
| 1283 | @example |
| 1284 | (use-package-modules guile emacs) |
| 1285 | |
| 1286 | (packages->manifest |
| 1287 | (list emacs |
| 1288 | guile-2.0 |
| 1289 | ;; Use a specific package output. |
| 1290 | (list guile-2.0 "debug"))) |
| 1291 | @end example |
| 1292 | |
| 1293 | @item --roll-back |
| 1294 | Roll back to the previous @dfn{generation} of the profile---i.e., undo |
| 1295 | the last transaction. |
| 1296 | |
| 1297 | When combined with options such as @code{--install}, roll back occurs |
| 1298 | before any other actions. |
| 1299 | |
| 1300 | When rolling back from the first generation that actually contains |
| 1301 | installed packages, the profile is made to point to the @dfn{zeroth |
| 1302 | generation}, which contains no files apart from its own meta-data. |
| 1303 | |
| 1304 | Installing, removing, or upgrading packages from a generation that has |
| 1305 | been rolled back to overwrites previous future generations. Thus, the |
| 1306 | history of a profile's generations is always linear. |
| 1307 | |
| 1308 | @item --switch-generation=@var{pattern} |
| 1309 | @itemx -S @var{pattern} |
| 1310 | Switch to a particular generation defined by @var{pattern}. |
| 1311 | |
| 1312 | @var{pattern} may be either a generation number or a number prefixed |
| 1313 | with ``+'' or ``-''. The latter means: move forward/backward by a |
| 1314 | specified number of generations. For example, if you want to return to |
| 1315 | the latest generation after @code{--roll-back}, use |
| 1316 | @code{--switch-generation=+1}. |
| 1317 | |
| 1318 | The difference between @code{--roll-back} and |
| 1319 | @code{--switch-generation=-1} is that @code{--switch-generation} will |
| 1320 | not make a zeroth generation, so if a specified generation does not |
| 1321 | exist, the current generation will not be changed. |
| 1322 | |
| 1323 | @item --search-paths[=@var{kind}] |
| 1324 | @cindex search paths |
| 1325 | Report environment variable definitions, in Bash syntax, that may be |
| 1326 | needed in order to use the set of installed packages. These environment |
| 1327 | variables are used to specify @dfn{search paths} for files used by some |
| 1328 | of the installed packages. |
| 1329 | |
| 1330 | For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH} |
| 1331 | environment variables to be defined so it can look for headers and |
| 1332 | libraries in the user's profile (@pxref{Environment Variables,,, gcc, |
| 1333 | Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C |
| 1334 | library are installed in the profile, then @code{--search-paths} will |
| 1335 | suggest setting these variables to @code{@var{profile}/include} and |
| 1336 | @code{@var{profile}/lib}, respectively. |
| 1337 | |
| 1338 | The typical use case is to define these environment variables in the |
| 1339 | shell: |
| 1340 | |
| 1341 | @example |
| 1342 | $ eval `guix package --search-paths` |
| 1343 | @end example |
| 1344 | |
| 1345 | @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix}, |
| 1346 | meaning that the returned environment variable definitions will either |
| 1347 | be exact settings, or prefixes or suffixes of the current value of these |
| 1348 | variables. When omitted, @var{kind} defaults to @code{exact}. |
| 1349 | |
| 1350 | @item --profile=@var{profile} |
| 1351 | @itemx -p @var{profile} |
| 1352 | Use @var{profile} instead of the user's default profile. |
| 1353 | |
| 1354 | @item --verbose |
| 1355 | Produce verbose output. In particular, emit the environment's build log |
| 1356 | on the standard error port. |
| 1357 | |
| 1358 | @item --bootstrap |
| 1359 | Use the bootstrap Guile to build the profile. This option is only |
| 1360 | useful to distribution developers. |
| 1361 | |
| 1362 | @end table |
| 1363 | |
| 1364 | In addition to these actions @command{guix package} supports the |
| 1365 | following options to query the current state of a profile, or the |
| 1366 | availability of packages: |
| 1367 | |
| 1368 | @table @option |
| 1369 | |
| 1370 | @item --search=@var{regexp} |
| 1371 | @itemx -s @var{regexp} |
| 1372 | List the available packages whose name, synopsis, or description matches |
| 1373 | @var{regexp}. Print all the meta-data of matching packages in |
| 1374 | @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, |
| 1375 | GNU recutils manual}). |
| 1376 | |
| 1377 | This allows specific fields to be extracted using the @command{recsel} |
| 1378 | command, for instance: |
| 1379 | |
| 1380 | @example |
| 1381 | $ guix package -s malloc | recsel -p name,version |
| 1382 | name: glibc |
| 1383 | version: 2.17 |
| 1384 | |
| 1385 | name: libgc |
| 1386 | version: 7.2alpha6 |
| 1387 | @end example |
| 1388 | |
| 1389 | Similarly, to show the name of all the packages available under the |
| 1390 | terms of the GNU@tie{}LGPL version 3: |
| 1391 | |
| 1392 | @example |
| 1393 | $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' |
| 1394 | name: elfutils |
| 1395 | |
| 1396 | name: gmp |
| 1397 | @dots{} |
| 1398 | @end example |
| 1399 | |
| 1400 | @item --show=@var{package} |
| 1401 | Show details about @var{package}, taken from the list of available packages, in |
| 1402 | @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU |
| 1403 | recutils manual}). |
| 1404 | |
| 1405 | @example |
| 1406 | $ guix package --show=python | recsel -p name,version |
| 1407 | name: python |
| 1408 | version: 2.7.6 |
| 1409 | |
| 1410 | name: python |
| 1411 | version: 3.3.5 |
| 1412 | @end example |
| 1413 | |
| 1414 | You may also specify the full name of a package to only get details about a |
| 1415 | specific version of it: |
| 1416 | @example |
| 1417 | $ guix package --show=python-3.3.5 | recsel -p name,version |
| 1418 | name: python |
| 1419 | version: 3.3.5 |
| 1420 | @end example |
| 1421 | |
| 1422 | |
| 1423 | |
| 1424 | @item --list-installed[=@var{regexp}] |
| 1425 | @itemx -I [@var{regexp}] |
| 1426 | List the currently installed packages in the specified profile, with the |
| 1427 | most recently installed packages shown last. When @var{regexp} is |
| 1428 | specified, list only installed packages whose name matches @var{regexp}. |
| 1429 | |
| 1430 | For each installed package, print the following items, separated by |
| 1431 | tabs: the package name, its version string, the part of the package that |
| 1432 | is installed (for instance, @code{out} for the default output, |
| 1433 | @code{include} for its headers, etc.), and the path of this package in |
| 1434 | the store. |
| 1435 | |
| 1436 | @item --list-available[=@var{regexp}] |
| 1437 | @itemx -A [@var{regexp}] |
| 1438 | List packages currently available in the distribution for this system |
| 1439 | (@pxref{GNU Distribution}). When @var{regexp} is specified, list only |
| 1440 | installed packages whose name matches @var{regexp}. |
| 1441 | |
| 1442 | For each package, print the following items separated by tabs: its name, |
| 1443 | its version string, the parts of the package (@pxref{Packages with |
| 1444 | Multiple Outputs}), and the source location of its definition. |
| 1445 | |
| 1446 | @item --list-generations[=@var{pattern}] |
| 1447 | @itemx -l [@var{pattern}] |
| 1448 | Return a list of generations along with their creation dates; for each |
| 1449 | generation, show the installed packages, with the most recently |
| 1450 | installed packages shown last. Note that the zeroth generation is never |
| 1451 | shown. |
| 1452 | |
| 1453 | For each installed package, print the following items, separated by |
| 1454 | tabs: the name of a package, its version string, the part of the package |
| 1455 | that is installed (@pxref{Packages with Multiple Outputs}), and the |
| 1456 | location of this package in the store. |
| 1457 | |
| 1458 | When @var{pattern} is used, the command returns only matching |
| 1459 | generations. Valid patterns include: |
| 1460 | |
| 1461 | @itemize |
| 1462 | @item @emph{Integers and comma-separated integers}. Both patterns denote |
| 1463 | generation numbers. For instance, @code{--list-generations=1} returns |
| 1464 | the first one. |
| 1465 | |
| 1466 | And @code{--list-generations=1,8,2} outputs three generations in the |
| 1467 | specified order. Neither spaces nor trailing commas are allowed. |
| 1468 | |
| 1469 | @item @emph{Ranges}. @code{--list-generations=2..9} prints the |
| 1470 | specified generations and everything in between. Note that the start of |
| 1471 | a range must be lesser than its end. |
| 1472 | |
| 1473 | It is also possible to omit the endpoint. For example, |
| 1474 | @code{--list-generations=2..}, returns all generations starting from the |
| 1475 | second one. |
| 1476 | |
| 1477 | @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, |
| 1478 | or months by passing an integer along with the first letter of the |
| 1479 | duration. For example, @code{--list-generations=20d} lists generations |
| 1480 | that are up to 20 days old. |
| 1481 | @end itemize |
| 1482 | |
| 1483 | @item --delete-generations[=@var{pattern}] |
| 1484 | @itemx -d [@var{pattern}] |
| 1485 | When @var{pattern} is omitted, delete all generations except the current |
| 1486 | one. |
| 1487 | |
| 1488 | This command accepts the same patterns as @option{--list-generations}. |
| 1489 | When @var{pattern} is specified, delete the matching generations. When |
| 1490 | @var{pattern} specifies a duration, generations @emph{older} than the |
| 1491 | specified duration match. For instance, @code{--delete-generations=1m} |
| 1492 | deletes generations that are more than one month old. |
| 1493 | |
| 1494 | If the current generation matches, it is @emph{not} deleted. Also, the |
| 1495 | zeroth generation is never deleted. |
| 1496 | |
| 1497 | Note that deleting generations prevents roll-back to them. |
| 1498 | Consequently, this command must be used with care. |
| 1499 | |
| 1500 | @end table |
| 1501 | |
| 1502 | Finally, since @command{guix package} may actually start build |
| 1503 | processes, it supports all the common build options that @command{guix |
| 1504 | build} supports (@pxref{Invoking guix build, common build options}). |
| 1505 | |
| 1506 | @node Substitutes |
| 1507 | @section Substitutes |
| 1508 | |
| 1509 | @cindex substitutes |
| 1510 | @cindex pre-built binaries |
| 1511 | Guix supports transparent source/binary deployment, which means that it |
| 1512 | can either build things locally, or download pre-built items from a |
| 1513 | server. We call these pre-built items @dfn{substitutes}---they are |
| 1514 | substitutes for local build results. In many cases, downloading a |
| 1515 | substitute is much faster than building things locally. |
| 1516 | |
| 1517 | Substitutes can be anything resulting from a derivation build |
| 1518 | (@pxref{Derivations}). Of course, in the common case, they are |
| 1519 | pre-built package binaries, but source tarballs, for instance, which |
| 1520 | also result from derivation builds, can be available as substitutes. |
| 1521 | |
| 1522 | The @code{hydra.gnu.org} server is a front-end to a build farm that |
| 1523 | builds packages from the GNU distribution continuously for some |
| 1524 | architectures, and makes them available as substitutes. This is the |
| 1525 | default source of substitutes; it can be overridden by passing the |
| 1526 | @option{--substitute-urls} option either to @command{guix-daemon} |
| 1527 | (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) |
| 1528 | or to client tools such as @command{guix package} |
| 1529 | (@pxref{client-substitute-urls,, client @option{--substitute-urls} |
| 1530 | option}). |
| 1531 | |
| 1532 | @cindex security |
| 1533 | @cindex digital signatures |
| 1534 | To allow Guix to download substitutes from @code{hydra.gnu.org}, you |
| 1535 | must add its public key to the access control list (ACL) of archive |
| 1536 | imports, using the @command{guix archive} command (@pxref{Invoking guix |
| 1537 | archive}). Doing so implies that you trust @code{hydra.gnu.org} to not |
| 1538 | be compromised and to serve genuine substitutes. |
| 1539 | |
| 1540 | This public key is installed along with Guix, in |
| 1541 | @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is |
| 1542 | the installation prefix of Guix. If you installed Guix from source, |
| 1543 | make sure you checked the GPG signature of |
| 1544 | @file{guix-@value{VERSION}.tar.gz}, which contains this public key file. |
| 1545 | Then, you can run something like this: |
| 1546 | |
| 1547 | @example |
| 1548 | # guix archive --authorize < hydra.gnu.org.pub |
| 1549 | @end example |
| 1550 | |
| 1551 | Once this is in place, the output of a command like @code{guix build} |
| 1552 | should change from something like: |
| 1553 | |
| 1554 | @example |
| 1555 | $ guix build emacs --dry-run |
| 1556 | The following derivations would be built: |
| 1557 | /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv |
| 1558 | /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv |
| 1559 | /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv |
| 1560 | /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv |
| 1561 | @dots{} |
| 1562 | @end example |
| 1563 | |
| 1564 | @noindent |
| 1565 | to something like: |
| 1566 | |
| 1567 | @example |
| 1568 | $ guix build emacs --dry-run |
| 1569 | The following files would be downloaded: |
| 1570 | /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 |
| 1571 | /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d |
| 1572 | /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 |
| 1573 | /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 |
| 1574 | @dots{} |
| 1575 | @end example |
| 1576 | |
| 1577 | @noindent |
| 1578 | This indicates that substitutes from @code{hydra.gnu.org} are usable and |
| 1579 | will be downloaded, when possible, for future builds. |
| 1580 | |
| 1581 | Guix ignores substitutes that are not signed, or that are not signed by |
| 1582 | one of the keys listed in the ACL. It also detects and raises an error |
| 1583 | when attempting to use a substitute that has been tampered with. |
| 1584 | |
| 1585 | The substitute mechanism can be disabled globally by running |
| 1586 | @code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking |
| 1587 | guix-daemon}). It can also be disabled temporarily by passing the |
| 1588 | @code{--no-substitutes} option to @command{guix package}, @command{guix |
| 1589 | build}, and other command-line tools. |
| 1590 | |
| 1591 | |
| 1592 | Today, each individual's control over their own computing is at the |
| 1593 | mercy of institutions, corporations, and groups with enough power and |
| 1594 | determination to subvert the computing infrastructure and exploit its |
| 1595 | weaknesses. While using @code{hydra.gnu.org} substitutes can be |
| 1596 | convenient, we encourage users to also build on their own, or even run |
| 1597 | their own build farm, such that @code{hydra.gnu.org} is less of an |
| 1598 | interesting target. One way to help is by publishing the software you |
| 1599 | build using @command{guix publish} so that others have one more choice |
| 1600 | of server to download substitutes from (@pxref{Invoking guix publish}). |
| 1601 | |
| 1602 | Guix has the foundations to maximize build reproducibility |
| 1603 | (@pxref{Features}). In most cases, independent builds of a given |
| 1604 | package or derivation should yield bit-identical results. Thus, through |
| 1605 | a diverse set of independent package builds, we can strengthen the |
| 1606 | integrity of our systems. The @command{guix challenge} command aims to |
| 1607 | help users assess substitute servers, and to assist developers in |
| 1608 | finding out about non-deterministic package builds (@pxref{Invoking guix |
| 1609 | challenge}). |
| 1610 | |
| 1611 | In the future, we want Guix to have support to publish and retrieve |
| 1612 | binaries to/from other users, in a peer-to-peer fashion. If you would |
| 1613 | like to discuss this project, join us on @email{guix-devel@@gnu.org}. |
| 1614 | |
| 1615 | |
| 1616 | @node Packages with Multiple Outputs |
| 1617 | @section Packages with Multiple Outputs |
| 1618 | |
| 1619 | @cindex multiple-output packages |
| 1620 | @cindex package outputs |
| 1621 | |
| 1622 | Often, packages defined in Guix have a single @dfn{output}---i.e., the |
| 1623 | source package leads exactly one directory in the store. When running |
| 1624 | @command{guix package -i glibc}, one installs the default output of the |
| 1625 | GNU libc package; the default output is called @code{out}, but its name |
| 1626 | can be omitted as shown in this command. In this particular case, the |
| 1627 | default output of @code{glibc} contains all the C header files, shared |
| 1628 | libraries, static libraries, Info documentation, and other supporting |
| 1629 | files. |
| 1630 | |
| 1631 | Sometimes it is more appropriate to separate the various types of files |
| 1632 | produced from a single source package into separate outputs. For |
| 1633 | instance, the GLib C library (used by GTK+ and related packages) |
| 1634 | installs more than 20 MiB of reference documentation as HTML pages. |
| 1635 | To save space for users who do not need it, the documentation goes to a |
| 1636 | separate output, called @code{doc}. To install the main GLib output, |
| 1637 | which contains everything but the documentation, one would run: |
| 1638 | |
| 1639 | @example |
| 1640 | guix package -i glib |
| 1641 | @end example |
| 1642 | |
| 1643 | The command to install its documentation is: |
| 1644 | |
| 1645 | @example |
| 1646 | guix package -i glib:doc |
| 1647 | @end example |
| 1648 | |
| 1649 | Some packages install programs with different ``dependency footprints''. |
| 1650 | For instance, the WordNet package install both command-line tools and |
| 1651 | graphical user interfaces (GUIs). The former depend solely on the C |
| 1652 | library, whereas the latter depend on Tcl/Tk and the underlying X |
| 1653 | libraries. In this case, we leave the command-line tools in the default |
| 1654 | output, whereas the GUIs are in a separate output. This allows users |
| 1655 | who do not need the GUIs to save space. The @command{guix size} command |
| 1656 | can help find out about such situations (@pxref{Invoking guix size}). |
| 1657 | @command{guix graph} can also be helpful (@pxref{Invoking guix graph}). |
| 1658 | |
| 1659 | There are several such multiple-output packages in the GNU distribution. |
| 1660 | Other conventional output names include @code{lib} for libraries and |
| 1661 | possibly header files, @code{bin} for stand-alone programs, and |
| 1662 | @code{debug} for debugging information (@pxref{Installing Debugging |
| 1663 | Files}). The outputs of a packages are listed in the third column of |
| 1664 | the output of @command{guix package --list-available} (@pxref{Invoking |
| 1665 | guix package}). |
| 1666 | |
| 1667 | |
| 1668 | @node Invoking guix gc |
| 1669 | @section Invoking @command{guix gc} |
| 1670 | |
| 1671 | @cindex garbage collector |
| 1672 | Packages that are installed but not used may be @dfn{garbage-collected}. |
| 1673 | The @command{guix gc} command allows users to explicitly run the garbage |
| 1674 | collector to reclaim space from the @file{/gnu/store} directory. It is |
| 1675 | the @emph{only} way to remove files from @file{/gnu/store}---removing |
| 1676 | files or directories manually may break it beyond repair! |
| 1677 | |
| 1678 | The garbage collector has a set of known @dfn{roots}: any file under |
| 1679 | @file{/gnu/store} reachable from a root is considered @dfn{live} and |
| 1680 | cannot be deleted; any other file is considered @dfn{dead} and may be |
| 1681 | deleted. The set of garbage collector roots includes default user |
| 1682 | profiles, and may be augmented with @command{guix build --root}, for |
| 1683 | example (@pxref{Invoking guix build}). |
| 1684 | |
| 1685 | Prior to running @code{guix gc --collect-garbage} to make space, it is |
| 1686 | often useful to remove old generations from user profiles; that way, old |
| 1687 | package builds referenced by those generations can be reclaimed. This |
| 1688 | is achieved by running @code{guix package --delete-generations} |
| 1689 | (@pxref{Invoking guix package}). |
| 1690 | |
| 1691 | The @command{guix gc} command has three modes of operation: it can be |
| 1692 | used to garbage-collect any dead files (the default), to delete specific |
| 1693 | files (the @code{--delete} option), to print garbage-collector |
| 1694 | information, or for more advanced queries. The garbage collection |
| 1695 | options are as follows: |
| 1696 | |
| 1697 | @table @code |
| 1698 | @item --collect-garbage[=@var{min}] |
| 1699 | @itemx -C [@var{min}] |
| 1700 | Collect garbage---i.e., unreachable @file{/gnu/store} files and |
| 1701 | sub-directories. This is the default operation when no option is |
| 1702 | specified. |
| 1703 | |
| 1704 | When @var{min} is given, stop once @var{min} bytes have been collected. |
| 1705 | @var{min} may be a number of bytes, or it may include a unit as a |
| 1706 | suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes |
| 1707 | (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}). |
| 1708 | |
| 1709 | When @var{min} is omitted, collect all the garbage. |
| 1710 | |
| 1711 | @item --delete |
| 1712 | @itemx -d |
| 1713 | Attempt to delete all the store files and directories specified as |
| 1714 | arguments. This fails if some of the files are not in the store, or if |
| 1715 | they are still live. |
| 1716 | |
| 1717 | @item --list-failures |
| 1718 | List store items corresponding to cached build failures. |
| 1719 | |
| 1720 | This prints nothing unless the daemon was started with |
| 1721 | @option{--cache-failures} (@pxref{Invoking guix-daemon, |
| 1722 | @option{--cache-failures}}). |
| 1723 | |
| 1724 | @item --clear-failures |
| 1725 | Remove the specified store items from the failed-build cache. |
| 1726 | |
| 1727 | Again, this option only makes sense when the daemon is started with |
| 1728 | @option{--cache-failures}. Otherwise, it does nothing. |
| 1729 | |
| 1730 | @item --list-dead |
| 1731 | Show the list of dead files and directories still present in the |
| 1732 | store---i.e., files and directories no longer reachable from any root. |
| 1733 | |
| 1734 | @item --list-live |
| 1735 | Show the list of live store files and directories. |
| 1736 | |
| 1737 | @end table |
| 1738 | |
| 1739 | In addition, the references among existing store files can be queried: |
| 1740 | |
| 1741 | @table @code |
| 1742 | |
| 1743 | @item --references |
| 1744 | @itemx --referrers |
| 1745 | List the references (respectively, the referrers) of store files given |
| 1746 | as arguments. |
| 1747 | |
| 1748 | @item --requisites |
| 1749 | @itemx -R |
| 1750 | @cindex closure |
| 1751 | List the requisites of the store files passed as arguments. Requisites |
| 1752 | include the store files themselves, their references, and the references |
| 1753 | of these, recursively. In other words, the returned list is the |
| 1754 | @dfn{transitive closure} of the store files. |
| 1755 | |
| 1756 | @xref{Invoking guix size}, for a tool to profile the size of an |
| 1757 | element's closure. @xref{Invoking guix graph}, for a tool to visualize |
| 1758 | the graph of references. |
| 1759 | |
| 1760 | @end table |
| 1761 | |
| 1762 | Lastly, the following options allow you to check the integrity of the |
| 1763 | store and to control disk usage. |
| 1764 | |
| 1765 | @table @option |
| 1766 | |
| 1767 | @item --verify[=@var{options}] |
| 1768 | @cindex integrity, of the store |
| 1769 | @cindex integrity checking |
| 1770 | Verify the integrity of the store. |
| 1771 | |
| 1772 | By default, make sure that all the store items marked as valid in the |
| 1773 | daemon's database actually exist in @file{/gnu/store}. |
| 1774 | |
| 1775 | When provided, @var{options} must a comma-separated list containing one |
| 1776 | or more of @code{contents} and @code{repair}. |
| 1777 | |
| 1778 | When passing @option{--verify=contents}, the daemon will compute the |
| 1779 | content hash of each store item and compare it against its hash in the |
| 1780 | database. Hash mismatches are reported as data corruptions. Because it |
| 1781 | traverses @emph{all the files in the store}, this command can take a |
| 1782 | long time, especially on systems with a slow disk drive. |
| 1783 | |
| 1784 | @cindex repairing the store |
| 1785 | Using @option{--verify=repair} or @option{--verify=contents,repair} |
| 1786 | causes the daemon to try to repair corrupt store items by fetching |
| 1787 | substitutes for them (@pxref{Substitutes}). Because repairing is not |
| 1788 | atomic, and thus potentially dangerous, it is available only to the |
| 1789 | system administrator. |
| 1790 | |
| 1791 | @item --optimize |
| 1792 | @cindex deduplication |
| 1793 | Optimize the store by hard-linking identical files---this is |
| 1794 | @dfn{deduplication}. |
| 1795 | |
| 1796 | The daemon performs deduplication after each successful build or archive |
| 1797 | import, unless it was started with @code{--disable-deduplication} |
| 1798 | (@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus, |
| 1799 | this option is primarily useful when the daemon was running with |
| 1800 | @code{--disable-deduplication}. |
| 1801 | |
| 1802 | @end table |
| 1803 | |
| 1804 | @node Invoking guix pull |
| 1805 | @section Invoking @command{guix pull} |
| 1806 | |
| 1807 | Packages are installed or upgraded to the latest version available in |
| 1808 | the distribution currently available on your local machine. To update |
| 1809 | that distribution, along with the Guix tools, you must run @command{guix |
| 1810 | pull}: the command downloads the latest Guix source code and package |
| 1811 | descriptions, and deploys it. |
| 1812 | |
| 1813 | On completion, @command{guix package} will use packages and package |
| 1814 | versions from this just-retrieved copy of Guix. Not only that, but all |
| 1815 | the Guix commands and Scheme modules will also be taken from that latest |
| 1816 | version. New @command{guix} sub-commands added by the update also |
| 1817 | become available@footnote{Under the hood, @command{guix pull} updates |
| 1818 | the @file{~/.config/guix/latest} symbolic link to point to the latest |
| 1819 | Guix, and the @command{guix} command loads code from there.}. |
| 1820 | |
| 1821 | The @command{guix pull} command is usually invoked with no arguments, |
| 1822 | but it supports the following options: |
| 1823 | |
| 1824 | @table @code |
| 1825 | @item --verbose |
| 1826 | Produce verbose output, writing build logs to the standard error output. |
| 1827 | |
| 1828 | @item --url=@var{url} |
| 1829 | Download the source tarball of Guix from @var{url}. |
| 1830 | |
| 1831 | By default, the tarball is taken from its canonical address at |
| 1832 | @code{gnu.org}, for the stable branch of Guix. |
| 1833 | |
| 1834 | @item --bootstrap |
| 1835 | Use the bootstrap Guile to build the latest Guix. This option is only |
| 1836 | useful to Guix developers. |
| 1837 | @end table |
| 1838 | |
| 1839 | |
| 1840 | @node Invoking guix archive |
| 1841 | @section Invoking @command{guix archive} |
| 1842 | |
| 1843 | The @command{guix archive} command allows users to @dfn{export} files |
| 1844 | from the store into a single archive, and to later @dfn{import} them. |
| 1845 | In particular, it allows store files to be transferred from one machine |
| 1846 | to another machine's store. For example, to transfer the @code{emacs} |
| 1847 | package to a machine connected over SSH, one would run: |
| 1848 | |
| 1849 | @example |
| 1850 | guix archive --export -r emacs | ssh the-machine guix archive --import |
| 1851 | @end example |
| 1852 | |
| 1853 | @noindent |
| 1854 | Similarly, a complete user profile may be transferred from one machine |
| 1855 | to another like this: |
| 1856 | |
| 1857 | @example |
| 1858 | guix archive --export -r $(readlink -f ~/.guix-profile) | \ |
| 1859 | ssh the-machine guix-archive --import |
| 1860 | @end example |
| 1861 | |
| 1862 | @noindent |
| 1863 | However, note that, in both examples, all of @code{emacs} and the |
| 1864 | profile as well as all of their dependencies are transferred (due to |
| 1865 | @code{-r}), regardless of what is already available in the target |
| 1866 | machine's store. The @code{--missing} option can help figure out which |
| 1867 | items are missing from the target's store. |
| 1868 | |
| 1869 | Archives are stored in the ``Nix archive'' or ``Nar'' format, which is |
| 1870 | comparable in spirit to `tar', but with a few noteworthy differences |
| 1871 | that make it more appropriate for our purposes. First, rather than |
| 1872 | recording all Unix meta-data for each file, the Nar format only mentions |
| 1873 | the file type (regular, directory, or symbolic link); Unix permissions |
| 1874 | and owner/group are dismissed. Second, the order in which directory |
| 1875 | entries are stored always follows the order of file names according to |
| 1876 | the C locale collation order. This makes archive production fully |
| 1877 | deterministic. |
| 1878 | |
| 1879 | When exporting, the daemon digitally signs the contents of the archive, |
| 1880 | and that digital signature is appended. When importing, the daemon |
| 1881 | verifies the signature and rejects the import in case of an invalid |
| 1882 | signature or if the signing key is not authorized. |
| 1883 | @c FIXME: Add xref to daemon doc about signatures. |
| 1884 | |
| 1885 | The main options are: |
| 1886 | |
| 1887 | @table @code |
| 1888 | @item --export |
| 1889 | Export the specified store files or packages (see below.) Write the |
| 1890 | resulting archive to the standard output. |
| 1891 | |
| 1892 | Dependencies are @emph{not} included in the output, unless |
| 1893 | @code{--recursive} is passed. |
| 1894 | |
| 1895 | @item -r |
| 1896 | @itemx --recursive |
| 1897 | When combined with @code{--export}, this instructs @command{guix |
| 1898 | archive} to include dependencies of the given items in the archive. |
| 1899 | Thus, the resulting archive is self-contained: it contains the closure |
| 1900 | of the exported store items. |
| 1901 | |
| 1902 | @item --import |
| 1903 | Read an archive from the standard input, and import the files listed |
| 1904 | therein into the store. Abort if the archive has an invalid digital |
| 1905 | signature, or if it is signed by a public key not among the authorized |
| 1906 | keys (see @code{--authorize} below.) |
| 1907 | |
| 1908 | @item --missing |
| 1909 | Read a list of store file names from the standard input, one per line, |
| 1910 | and write on the standard output the subset of these files missing from |
| 1911 | the store. |
| 1912 | |
| 1913 | @item --generate-key[=@var{parameters}] |
| 1914 | @cindex signing, archives |
| 1915 | Generate a new key pair for the daemons. This is a prerequisite before |
| 1916 | archives can be exported with @code{--export}. Note that this operation |
| 1917 | usually takes time, because it needs to gather enough entropy to |
| 1918 | generate the key pair. |
| 1919 | |
| 1920 | The generated key pair is typically stored under @file{/etc/guix}, in |
| 1921 | @file{signing-key.pub} (public key) and @file{signing-key.sec} (private |
| 1922 | key, which must be kept secret.) When @var{parameters} is omitted, |
| 1923 | an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt |
| 1924 | versions before 1.6.0, it is a 4096-bit RSA key. |
| 1925 | Alternately, @var{parameters} can specify |
| 1926 | @code{genkey} parameters suitable for Libgcrypt (@pxref{General |
| 1927 | public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The |
| 1928 | Libgcrypt Reference Manual}). |
| 1929 | |
| 1930 | @item --authorize |
| 1931 | @cindex authorizing, archives |
| 1932 | Authorize imports signed by the public key passed on standard input. |
| 1933 | The public key must be in ``s-expression advanced format''---i.e., the |
| 1934 | same format as the @file{signing-key.pub} file. |
| 1935 | |
| 1936 | The list of authorized keys is kept in the human-editable file |
| 1937 | @file{/etc/guix/acl}. The file contains |
| 1938 | @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format |
| 1939 | s-expressions''} and is structured as an access-control list in the |
| 1940 | @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure |
| 1941 | (SPKI)}. |
| 1942 | |
| 1943 | @item --extract=@var{directory} |
| 1944 | @itemx -x @var{directory} |
| 1945 | Read a single-item archive as served by substitute servers |
| 1946 | (@pxref{Substitutes}) and extract it to @var{directory}. This is a |
| 1947 | low-level operation needed in only very narrow use cases; see below. |
| 1948 | |
| 1949 | For example, the following command extracts the substitute for Emacs |
| 1950 | served by @code{hydra.gnu.org} to @file{/tmp/emacs}: |
| 1951 | |
| 1952 | @example |
| 1953 | $ wget -O - \ |
| 1954 | http://hydra.gnu.org/nar/@dots{}-emacs-24.5 \ |
| 1955 | | bunzip2 | guix archive -x /tmp/emacs |
| 1956 | @end example |
| 1957 | |
| 1958 | Single-item archives are different from multiple-item archives produced |
| 1959 | by @command{guix archive --export}; they contain a single store item, |
| 1960 | and they do @emph{not} embed a signature. Thus this operation does |
| 1961 | @emph{no} signature verification and its output should be considered |
| 1962 | unsafe. |
| 1963 | |
| 1964 | The primary purpose of this operation is to facilitate inspection of |
| 1965 | archive contents coming from possibly untrusted substitute servers. |
| 1966 | |
| 1967 | @end table |
| 1968 | |
| 1969 | To export store files as an archive to the standard output, run: |
| 1970 | |
| 1971 | @example |
| 1972 | guix archive --export @var{options} @var{specifications}... |
| 1973 | @end example |
| 1974 | |
| 1975 | @var{specifications} may be either store file names or package |
| 1976 | specifications, as for @command{guix package} (@pxref{Invoking guix |
| 1977 | package}). For instance, the following command creates an archive |
| 1978 | containing the @code{gui} output of the @code{git} package and the main |
| 1979 | output of @code{emacs}: |
| 1980 | |
| 1981 | @example |
| 1982 | guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar |
| 1983 | @end example |
| 1984 | |
| 1985 | If the specified packages are not built yet, @command{guix archive} |
| 1986 | automatically builds them. The build process may be controlled with the |
| 1987 | same options that can be passed to the @command{guix build} command |
| 1988 | (@pxref{Invoking guix build, common build options}). |
| 1989 | |
| 1990 | @c ********************************************************************* |
| 1991 | @include emacs.texi |
| 1992 | |
| 1993 | @c ********************************************************************* |
| 1994 | @node Programming Interface |
| 1995 | @chapter Programming Interface |
| 1996 | |
| 1997 | GNU Guix provides several Scheme programming interfaces (APIs) to |
| 1998 | define, build, and query packages. The first interface allows users to |
| 1999 | write high-level package definitions. These definitions refer to |
| 2000 | familiar packaging concepts, such as the name and version of a package, |
| 2001 | its build system, and its dependencies. These definitions can then be |
| 2002 | turned into concrete build actions. |
| 2003 | |
| 2004 | Build actions are performed by the Guix daemon, on behalf of users. In a |
| 2005 | standard setup, the daemon has write access to the store---the |
| 2006 | @file{/gnu/store} directory---whereas users do not. The recommended |
| 2007 | setup also has the daemon perform builds in chroots, under a specific |
| 2008 | build users, to minimize interference with the rest of the system. |
| 2009 | |
| 2010 | @cindex derivation |
| 2011 | Lower-level APIs are available to interact with the daemon and the |
| 2012 | store. To instruct the daemon to perform a build action, users actually |
| 2013 | provide it with a @dfn{derivation}. A derivation is a low-level |
| 2014 | representation of the build actions to be taken, and the environment in |
| 2015 | which they should occur---derivations are to package definitions what |
| 2016 | assembly is to C programs. The term ``derivation'' comes from the fact |
| 2017 | that build results @emph{derive} from them. |
| 2018 | |
| 2019 | This chapter describes all these APIs in turn, starting from high-level |
| 2020 | package definitions. |
| 2021 | |
| 2022 | @menu |
| 2023 | * Defining Packages:: Defining new packages. |
| 2024 | * Build Systems:: Specifying how packages are built. |
| 2025 | * The Store:: Manipulating the package store. |
| 2026 | * Derivations:: Low-level interface to package derivations. |
| 2027 | * The Store Monad:: Purely functional interface to the store. |
| 2028 | * G-Expressions:: Manipulating build expressions. |
| 2029 | @end menu |
| 2030 | |
| 2031 | @node Defining Packages |
| 2032 | @section Defining Packages |
| 2033 | |
| 2034 | The high-level interface to package definitions is implemented in the |
| 2035 | @code{(guix packages)} and @code{(guix build-system)} modules. As an |
| 2036 | example, the package definition, or @dfn{recipe}, for the GNU Hello |
| 2037 | package looks like this: |
| 2038 | |
| 2039 | @example |
| 2040 | (define-module (gnu packages hello) |
| 2041 | #:use-module (guix packages) |
| 2042 | #:use-module (guix download) |
| 2043 | #:use-module (guix build-system gnu) |
| 2044 | #:use-module (guix licenses) |
| 2045 | #:use-module (gnu packages gawk)) |
| 2046 | |
| 2047 | (define-public hello |
| 2048 | (package |
| 2049 | (name "hello") |
| 2050 | (version "2.10") |
| 2051 | (source (origin |
| 2052 | (method url-fetch) |
| 2053 | (uri (string-append "mirror://gnu/hello/hello-" version |
| 2054 | ".tar.gz")) |
| 2055 | (sha256 |
| 2056 | (base32 |
| 2057 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) |
| 2058 | (build-system gnu-build-system) |
| 2059 | (arguments `(#:configure-flags '("--enable-silent-rules"))) |
| 2060 | (inputs `(("gawk" ,gawk))) |
| 2061 | (synopsis "Hello, GNU world: An example GNU package") |
| 2062 | (description "Guess what GNU Hello prints!") |
| 2063 | (home-page "http://www.gnu.org/software/hello/") |
| 2064 | (license gpl3+))) |
| 2065 | @end example |
| 2066 | |
| 2067 | @noindent |
| 2068 | Without being a Scheme expert, the reader may have guessed the meaning |
| 2069 | of the various fields here. This expression binds variable @code{hello} |
| 2070 | to a @code{<package>} object, which is essentially a record |
| 2071 | (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}). |
| 2072 | This package object can be inspected using procedures found in the |
| 2073 | @code{(guix packages)} module; for instance, @code{(package-name hello)} |
| 2074 | returns---surprise!---@code{"hello"}. |
| 2075 | |
| 2076 | With luck, you may be able to import part or all of the definition of |
| 2077 | the package you are interested in from another repository, using the |
| 2078 | @code{guix import} command (@pxref{Invoking guix import}). |
| 2079 | |
| 2080 | In the example above, @var{hello} is defined into a module of its own, |
| 2081 | @code{(gnu packages hello)}. Technically, this is not strictly |
| 2082 | necessary, but it is convenient to do so: all the packages defined in |
| 2083 | modules under @code{(gnu packages @dots{})} are automatically known to |
| 2084 | the command-line tools (@pxref{Package Modules}). |
| 2085 | |
| 2086 | There are a few points worth noting in the above package definition: |
| 2087 | |
| 2088 | @itemize |
| 2089 | @item |
| 2090 | The @code{source} field of the package is an @code{<origin>} object |
| 2091 | (@pxref{origin Reference}, for the complete reference). |
| 2092 | Here, the @code{url-fetch} method from @code{(guix download)} is used, |
| 2093 | meaning that the source is a file to be downloaded over FTP or HTTP. |
| 2094 | |
| 2095 | The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of |
| 2096 | the GNU mirrors defined in @code{(guix download)}. |
| 2097 | |
| 2098 | The @code{sha256} field specifies the expected SHA256 hash of the file |
| 2099 | being downloaded. It is mandatory, and allows Guix to check the |
| 2100 | integrity of the file. The @code{(base32 @dots{})} form introduces the |
| 2101 | base32 representation of the hash. You can obtain this information with |
| 2102 | @code{guix download} (@pxref{Invoking guix download}) and @code{guix |
| 2103 | hash} (@pxref{Invoking guix hash}). |
| 2104 | |
| 2105 | @cindex patches |
| 2106 | When needed, the @code{origin} form can also have a @code{patches} field |
| 2107 | listing patches to be applied, and a @code{snippet} field giving a |
| 2108 | Scheme expression to modify the source code. |
| 2109 | |
| 2110 | @item |
| 2111 | @cindex GNU Build System |
| 2112 | The @code{build-system} field specifies the procedure to build the |
| 2113 | package (@pxref{Build Systems}). Here, @var{gnu-build-system} |
| 2114 | represents the familiar GNU Build System, where packages may be |
| 2115 | configured, built, and installed with the usual @code{./configure && |
| 2116 | make && make check && make install} command sequence. |
| 2117 | |
| 2118 | @item |
| 2119 | The @code{arguments} field specifies options for the build system |
| 2120 | (@pxref{Build Systems}). Here it is interpreted by |
| 2121 | @var{gnu-build-system} as a request run @file{configure} with the |
| 2122 | @code{--enable-silent-rules} flag. |
| 2123 | |
| 2124 | @item |
| 2125 | The @code{inputs} field specifies inputs to the build process---i.e., |
| 2126 | build-time or run-time dependencies of the package. Here, we define an |
| 2127 | input called @code{"gawk"} whose value is that of the @var{gawk} |
| 2128 | variable; @var{gawk} is itself bound to a @code{<package>} object. |
| 2129 | |
| 2130 | Note that GCC, Coreutils, Bash, and other essential tools do not need to |
| 2131 | be specified as inputs here. Instead, @var{gnu-build-system} takes care |
| 2132 | of ensuring that they are present (@pxref{Build Systems}). |
| 2133 | |
| 2134 | However, any other dependencies need to be specified in the |
| 2135 | @code{inputs} field. Any dependency not specified here will simply be |
| 2136 | unavailable to the build process, possibly leading to a build failure. |
| 2137 | @end itemize |
| 2138 | |
| 2139 | @xref{package Reference}, for a full description of possible fields. |
| 2140 | |
| 2141 | Once a package definition is in place, the |
| 2142 | package may actually be built using the @code{guix build} command-line |
| 2143 | tool (@pxref{Invoking guix build}). You can easily jump back to the |
| 2144 | package definition using the @command{guix edit} command |
| 2145 | (@pxref{Invoking guix edit}). |
| 2146 | @xref{Packaging Guidelines}, for |
| 2147 | more information on how to test package definitions, and |
| 2148 | @ref{Invoking guix lint}, for information on how to check a definition |
| 2149 | for style conformance. |
| 2150 | |
| 2151 | Eventually, updating the package definition to a new upstream version |
| 2152 | can be partly automated by the @command{guix refresh} command |
| 2153 | (@pxref{Invoking guix refresh}). |
| 2154 | |
| 2155 | Behind the scenes, a derivation corresponding to the @code{<package>} |
| 2156 | object is first computed by the @code{package-derivation} procedure. |
| 2157 | That derivation is stored in a @code{.drv} file under @file{/gnu/store}. |
| 2158 | The build actions it prescribes may then be realized by using the |
| 2159 | @code{build-derivations} procedure (@pxref{The Store}). |
| 2160 | |
| 2161 | @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] |
| 2162 | Return the @code{<derivation>} object of @var{package} for @var{system} |
| 2163 | (@pxref{Derivations}). |
| 2164 | |
| 2165 | @var{package} must be a valid @code{<package>} object, and @var{system} |
| 2166 | must be a string denoting the target system type---e.g., |
| 2167 | @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store} |
| 2168 | must be a connection to the daemon, which operates on the store |
| 2169 | (@pxref{The Store}). |
| 2170 | @end deffn |
| 2171 | |
| 2172 | @noindent |
| 2173 | @cindex cross-compilation |
| 2174 | Similarly, it is possible to compute a derivation that cross-builds a |
| 2175 | package for some other system: |
| 2176 | |
| 2177 | @deffn {Scheme Procedure} package-cross-derivation @var{store} @ |
| 2178 | @var{package} @var{target} [@var{system}] |
| 2179 | Return the @code{<derivation>} object of @var{package} cross-built from |
| 2180 | @var{system} to @var{target}. |
| 2181 | |
| 2182 | @var{target} must be a valid GNU triplet denoting the target hardware |
| 2183 | and operating system, such as @code{"mips64el-linux-gnu"} |
| 2184 | (@pxref{Configuration Names, GNU configuration triplets,, configure, GNU |
| 2185 | Configure and Build System}). |
| 2186 | @end deffn |
| 2187 | |
| 2188 | @menu |
| 2189 | * package Reference :: The package data type. |
| 2190 | * origin Reference:: The origin data type. |
| 2191 | @end menu |
| 2192 | |
| 2193 | |
| 2194 | @node package Reference |
| 2195 | @subsection @code{package} Reference |
| 2196 | |
| 2197 | This section summarizes all the options available in @code{package} |
| 2198 | declarations (@pxref{Defining Packages}). |
| 2199 | |
| 2200 | @deftp {Data Type} package |
| 2201 | This is the data type representing a package recipe. |
| 2202 | |
| 2203 | @table @asis |
| 2204 | @item @code{name} |
| 2205 | The name of the package, as a string. |
| 2206 | |
| 2207 | @item @code{version} |
| 2208 | The version of the package, as a string. |
| 2209 | |
| 2210 | @item @code{source} |
| 2211 | An origin object telling how the source code for the package should be |
| 2212 | acquired (@pxref{origin Reference}). |
| 2213 | |
| 2214 | @item @code{build-system} |
| 2215 | The build system that should be used to build the package (@pxref{Build |
| 2216 | Systems}). |
| 2217 | |
| 2218 | @item @code{arguments} (default: @code{'()}) |
| 2219 | The arguments that should be passed to the build system. This is a |
| 2220 | list, typically containing sequential keyword-value pairs. |
| 2221 | |
| 2222 | @item @code{inputs} (default: @code{'()}) |
| 2223 | Package or derivation inputs to the build. This is a list of lists, |
| 2224 | where each list has the name of the input (a string) as its first |
| 2225 | element, a package or derivation object as its second element, and |
| 2226 | optionally the name of the output of the package or derivation that |
| 2227 | should be used, which defaults to @code{"out"}. |
| 2228 | |
| 2229 | @item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()}) |
| 2230 | @cindex propagated inputs |
| 2231 | This field is like @code{inputs}, but the specified packages will be |
| 2232 | force-installed alongside the package they belong to |
| 2233 | (@pxref{package-cmd-propagated-inputs, @command{guix package}}, for |
| 2234 | information on how @command{guix package} deals with propagated inputs.) |
| 2235 | |
| 2236 | For example this is necessary when a library needs headers of another |
| 2237 | library to compile, or needs another shared library to be linked |
| 2238 | alongside itself when a program wants to link to it. |
| 2239 | |
| 2240 | @item @code{native-inputs} (default: @code{'()}) |
| 2241 | This field is like @code{inputs}, but in case of a cross-compilation it |
| 2242 | will be ensured that packages for the architecture of the build machine |
| 2243 | are present, such that executables from them can be used during the |
| 2244 | build. |
| 2245 | |
| 2246 | This is typically where you would list tools needed at build time but |
| 2247 | not at run time, such as Autoconf, Automake, pkg-config, Gettext, or |
| 2248 | Bison. @command{guix lint} can report likely mistakes in this area |
| 2249 | (@pxref{Invoking guix lint}). |
| 2250 | |
| 2251 | @item @code{self-native-input?} (default: @code{#f}) |
| 2252 | This is a Boolean field telling whether the package should use itself as |
| 2253 | a native input when cross-compiling. |
| 2254 | |
| 2255 | @item @code{outputs} (default: @code{'("out")}) |
| 2256 | The list of output names of the package. @xref{Packages with Multiple |
| 2257 | Outputs}, for typical uses of additional outputs. |
| 2258 | |
| 2259 | @item @code{native-search-paths} (default: @code{'()}) |
| 2260 | @itemx @code{search-paths} (default: @code{'()}) |
| 2261 | A list of @code{search-path-specification} objects describing |
| 2262 | search-path environment variables honored by the package. |
| 2263 | |
| 2264 | @item @code{replacement} (default: @code{#f}) |
| 2265 | This must either @code{#f} or a package object that will be used as a |
| 2266 | @dfn{replacement} for this package. @xref{Security Updates, grafts}, |
| 2267 | for details. |
| 2268 | |
| 2269 | @item @code{synopsis} |
| 2270 | A one-line description of the package. |
| 2271 | |
| 2272 | @item @code{description} |
| 2273 | A more elaborate description of the package. |
| 2274 | |
| 2275 | @item @code{license} |
| 2276 | The license of the package; a value from @code{(guix licenses)}. |
| 2277 | |
| 2278 | @item @code{home-page} |
| 2279 | The URL to the home-page of the package, as a string. |
| 2280 | |
| 2281 | @item @code{supported-systems} (default: @var{%supported-systems}) |
| 2282 | The list of systems supported by the package, as strings of the form |
| 2283 | @code{architecture-kernel}, for example @code{"x86_64-linux"}. |
| 2284 | |
| 2285 | @item @code{maintainers} (default: @code{'()}) |
| 2286 | The list of maintainers of the package, as @code{maintainer} objects. |
| 2287 | |
| 2288 | @item @code{location} (default: source location of the @code{package} form) |
| 2289 | The source location of the package. It's useful to override this when |
| 2290 | inheriting from another package, in which case this field is not |
| 2291 | automatically corrected. |
| 2292 | @end table |
| 2293 | @end deftp |
| 2294 | |
| 2295 | |
| 2296 | @node origin Reference |
| 2297 | @subsection @code{origin} Reference |
| 2298 | |
| 2299 | This section summarizes all the options available in @code{origin} |
| 2300 | declarations (@pxref{Defining Packages}). |
| 2301 | |
| 2302 | @deftp {Data Type} origin |
| 2303 | This is the data type representing a source code origin. |
| 2304 | |
| 2305 | @table @asis |
| 2306 | @item @code{uri} |
| 2307 | An object containing the URI of the source. The object type depends on |
| 2308 | the @code{method} (see below). For example, when using the |
| 2309 | @var{url-fetch} method of @code{(guix download)}, the valid @code{uri} |
| 2310 | values are: a URL represented as a string, or a list thereof. |
| 2311 | |
| 2312 | @item @code{method} |
| 2313 | A procedure that will handle the URI. |
| 2314 | |
| 2315 | Examples include: |
| 2316 | |
| 2317 | @table @asis |
| 2318 | @item @var{url-fetch} from @code{(guix download)} |
| 2319 | download a file the HTTP, HTTPS, or FTP URL specified in the |
| 2320 | @code{uri} field; |
| 2321 | |
| 2322 | @item @var{git-fetch} from @code{(guix git-download)} |
| 2323 | clone the Git version control repository, and check out the revision |
| 2324 | specified in the @code{uri} field as a @code{git-reference} object; a |
| 2325 | @code{git-reference} looks like this: |
| 2326 | |
| 2327 | @example |
| 2328 | (git-reference |
| 2329 | (url "git://git.debian.org/git/pkg-shadow/shadow") |
| 2330 | (commit "v4.1.5.1")) |
| 2331 | @end example |
| 2332 | @end table |
| 2333 | |
| 2334 | @item @code{sha256} |
| 2335 | A bytevector containing the SHA-256 hash of the source. Typically the |
| 2336 | @code{base32} form is used here to generate the bytevector from a |
| 2337 | base-32 string. |
| 2338 | |
| 2339 | @item @code{file-name} (default: @code{#f}) |
| 2340 | The file name under which the source code should be saved. When this is |
| 2341 | @code{#f}, a sensible default value will be used in most cases. In case |
| 2342 | the source is fetched from a URL, the file name from the URL will be |
| 2343 | used. For version control checkouts, it's recommended to provide the |
| 2344 | file name explicitly because the default is not very descriptive. |
| 2345 | |
| 2346 | @item @code{patches} (default: @code{'()}) |
| 2347 | A list of file names containing patches to be applied to the source. |
| 2348 | |
| 2349 | @item @code{snippet} (default: @code{#f}) |
| 2350 | A quoted piece of code that will be run in the source directory to make |
| 2351 | any modifications, which is sometimes more convenient than a patch. |
| 2352 | |
| 2353 | @item @code{patch-flags} (default: @code{'("-p1")}) |
| 2354 | A list of command-line flags that should be passed to the @code{patch} |
| 2355 | command. |
| 2356 | |
| 2357 | @item @code{patch-inputs} (default: @code{#f}) |
| 2358 | Input packages or derivations to the patching process. When this is |
| 2359 | @code{#f}, the usual set of inputs necessary for patching are provided, |
| 2360 | such as GNU@tie{}Patch. |
| 2361 | |
| 2362 | @item @code{modules} (default: @code{'()}) |
| 2363 | A list of Guile modules that should be loaded during the patching |
| 2364 | process and while running the code in the @code{snippet} field. |
| 2365 | |
| 2366 | @item @code{imported-modules} (default: @code{'()}) |
| 2367 | The list of Guile modules to import in the patch derivation, for use by |
| 2368 | the @code{snippet}. |
| 2369 | |
| 2370 | @item @code{patch-guile} (default: @code{#f}) |
| 2371 | The Guile package that should be used in the patching process. When |
| 2372 | this is @code{#f}, a sensible default is used. |
| 2373 | @end table |
| 2374 | @end deftp |
| 2375 | |
| 2376 | |
| 2377 | @node Build Systems |
| 2378 | @section Build Systems |
| 2379 | |
| 2380 | @cindex build system |
| 2381 | Each package definition specifies a @dfn{build system} and arguments for |
| 2382 | that build system (@pxref{Defining Packages}). This @code{build-system} |
| 2383 | field represents the build procedure of the package, as well implicit |
| 2384 | dependencies of that build procedure. |
| 2385 | |
| 2386 | Build systems are @code{<build-system>} objects. The interface to |
| 2387 | create and manipulate them is provided by the @code{(guix build-system)} |
| 2388 | module, and actual build systems are exported by specific modules. |
| 2389 | |
| 2390 | @cindex bag (low-level package representation) |
| 2391 | Under the hood, build systems first compile package objects to |
| 2392 | @dfn{bags}. A @dfn{bag} is like a package, but with less |
| 2393 | ornamentation---in other words, a bag is a lower-level representation of |
| 2394 | a package, which includes all the inputs of that package, including some |
| 2395 | that were implicitly added by the build system. This intermediate |
| 2396 | representation is then compiled to a derivation (@pxref{Derivations}). |
| 2397 | |
| 2398 | Build systems accept an optional list of @dfn{arguments}. In package |
| 2399 | definitions, these are passed @i{via} the @code{arguments} field |
| 2400 | (@pxref{Defining Packages}). They are typically keyword arguments |
| 2401 | (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU |
| 2402 | Guile Reference Manual}). The value of these arguments is usually |
| 2403 | evaluated in the @dfn{build stratum}---i.e., by a Guile process launched |
| 2404 | by the daemon (@pxref{Derivations}). |
| 2405 | |
| 2406 | The main build system is @var{gnu-build-system}, which implements the |
| 2407 | standard build procedure for GNU packages and many other packages. It |
| 2408 | is provided by the @code{(guix build-system gnu)} module. |
| 2409 | |
| 2410 | @defvr {Scheme Variable} gnu-build-system |
| 2411 | @var{gnu-build-system} represents the GNU Build System, and variants |
| 2412 | thereof (@pxref{Configuration, configuration and makefile conventions,, |
| 2413 | standards, GNU Coding Standards}). |
| 2414 | |
| 2415 | @cindex build phases |
| 2416 | In a nutshell, packages using it configured, built, and installed with |
| 2417 | the usual @code{./configure && make && make check && make install} |
| 2418 | command sequence. In practice, a few additional steps are often needed. |
| 2419 | All these steps are split up in separate @dfn{phases}, |
| 2420 | notably@footnote{Please see the @code{(guix build gnu-build-system)} |
| 2421 | modules for more details about the build phases.}: |
| 2422 | |
| 2423 | @table @code |
| 2424 | @item unpack |
| 2425 | Unpack the source tarball, and change the current directory to the |
| 2426 | extracted source tree. If the source is actually a directory, copy it |
| 2427 | to the build tree, and enter that directory. |
| 2428 | |
| 2429 | @item patch-source-shebangs |
| 2430 | Patch shebangs encountered in source files so they refer to the right |
| 2431 | store file names. For instance, this changes @code{#!/bin/sh} to |
| 2432 | @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. |
| 2433 | |
| 2434 | @item configure |
| 2435 | Run the @file{configure} script with a number of default options, such |
| 2436 | as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified |
| 2437 | by the @code{#:configure-flags} argument. |
| 2438 | |
| 2439 | @item build |
| 2440 | Run @code{make} with the list of flags specified with |
| 2441 | @code{#:make-flags}. If the @code{#:parallel-builds?} argument is true |
| 2442 | (the default), build with @code{make -j}. |
| 2443 | |
| 2444 | @item check |
| 2445 | Run @code{make check}, or some other target specified with |
| 2446 | @code{#:test-target}, unless @code{#:tests? #f} is passed. If the |
| 2447 | @code{#:parallel-tests?} argument is true (the default), run @code{make |
| 2448 | check -j}. |
| 2449 | |
| 2450 | @item install |
| 2451 | Run @code{make install} with the flags listed in @code{#:make-flags}. |
| 2452 | |
| 2453 | @item patch-shebangs |
| 2454 | Patch shebangs on the installed executable files. |
| 2455 | |
| 2456 | @item strip |
| 2457 | Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} |
| 2458 | is false), copying them to the @code{debug} output when available |
| 2459 | (@pxref{Installing Debugging Files}). |
| 2460 | @end table |
| 2461 | |
| 2462 | @vindex %standard-phases |
| 2463 | The build-side module @code{(guix build gnu-build-system)} defines |
| 2464 | @var{%standard-phases} as the default list of build phases. |
| 2465 | @var{%standard-phases} is a list of symbol/procedure pairs, where the |
| 2466 | procedure implements the actual phase. |
| 2467 | |
| 2468 | The list of phases used for a particular package can be changed with the |
| 2469 | @code{#:phases} parameter. For instance, passing: |
| 2470 | |
| 2471 | @example |
| 2472 | #:phases (alist-delete 'configure %standard-phases) |
| 2473 | @end example |
| 2474 | |
| 2475 | means that all the phases described above will be used, except the |
| 2476 | @code{configure} phase. |
| 2477 | |
| 2478 | In addition, this build system ensures that the ``standard'' environment |
| 2479 | for GNU packages is available. This includes tools such as GCC, libc, |
| 2480 | Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix |
| 2481 | build-system gnu)} module for a complete list.) We call these the |
| 2482 | @dfn{implicit inputs} of a package, because package definitions don't |
| 2483 | have to mention them. |
| 2484 | @end defvr |
| 2485 | |
| 2486 | Other @code{<build-system>} objects are defined to support other |
| 2487 | conventions and tools used by free software packages. They inherit most |
| 2488 | of @var{gnu-build-system}, and differ mainly in the set of inputs |
| 2489 | implicitly added to the build process, and in the list of phases |
| 2490 | executed. Some of these build systems are listed below. |
| 2491 | |
| 2492 | @defvr {Scheme Variable} cmake-build-system |
| 2493 | This variable is exported by @code{(guix build-system cmake)}. It |
| 2494 | implements the build procedure for packages using the |
| 2495 | @url{http://www.cmake.org, CMake build tool}. |
| 2496 | |
| 2497 | It automatically adds the @code{cmake} package to the set of inputs. |
| 2498 | Which package is used can be specified with the @code{#:cmake} |
| 2499 | parameter. |
| 2500 | |
| 2501 | The @code{#:configure-flags} parameter is taken as a list of flags |
| 2502 | passed to the @command{cmake} command. The @code{#:build-type} |
| 2503 | parameter specifies in abstract terms the flags passed to the compiler; |
| 2504 | it defaults to @code{"RelWithDebInfo"} (short for ``release mode with |
| 2505 | debugging information''), which roughly means that code is compiled with |
| 2506 | @code{-O2 -g}, as is the case for Autoconf-based packages by default. |
| 2507 | @end defvr |
| 2508 | |
| 2509 | @defvr {Scheme Variable} glib-or-gtk-build-system |
| 2510 | This variable is exported by @code{(guix build-system glib-or-gtk)}. It |
| 2511 | is intended for use with packages making use of GLib or GTK+. |
| 2512 | |
| 2513 | This build system adds the following two phases to the ones defined by |
| 2514 | @var{gnu-build-system}: |
| 2515 | |
| 2516 | @table @code |
| 2517 | @item glib-or-gtk-wrap |
| 2518 | The phase @code{glib-or-gtk-wrap} ensures that programs found under |
| 2519 | @file{bin/} are able to find GLib's ``schemas'' and |
| 2520 | @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+ |
| 2521 | modules}. This is achieved by wrapping the programs in launch scripts |
| 2522 | that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH} |
| 2523 | environment variables. |
| 2524 | |
| 2525 | It is possible to exclude specific package outputs from that wrapping |
| 2526 | process by listing their names in the |
| 2527 | @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful |
| 2528 | when an output is known not to contain any GLib or GTK+ binaries, and |
| 2529 | where wrapping would gratuitously add a dependency of that output on |
| 2530 | GLib and GTK+. |
| 2531 | |
| 2532 | @item glib-or-gtk-compile-schemas |
| 2533 | The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's |
| 2534 | @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, |
| 2535 | GSettings schemas} are compiled. Compilation is performed by the |
| 2536 | @command{glib-compile-schemas} program. It is provided by the package |
| 2537 | @code{glib:bin} which is automatically imported by the build system. |
| 2538 | The @code{glib} package providing @command{glib-compile-schemas} can be |
| 2539 | specified with the @code{#:glib} parameter. |
| 2540 | @end table |
| 2541 | |
| 2542 | Both phases are executed after the @code{install} phase. |
| 2543 | @end defvr |
| 2544 | |
| 2545 | @defvr {Scheme Variable} python-build-system |
| 2546 | This variable is exported by @code{(guix build-system python)}. It |
| 2547 | implements the more or less standard build procedure used by Python |
| 2548 | packages, which consists in running @code{python setup.py build} and |
| 2549 | then @code{python setup.py install --prefix=/gnu/store/@dots{}}. |
| 2550 | |
| 2551 | For packages that install stand-alone Python programs under @code{bin/}, |
| 2552 | it takes care of wrapping these programs so their @code{PYTHONPATH} |
| 2553 | environment variable points to all the Python libraries they depend on. |
| 2554 | |
| 2555 | Which Python package is used can be specified with the @code{#:python} |
| 2556 | parameter. |
| 2557 | @end defvr |
| 2558 | |
| 2559 | @defvr {Scheme Variable} perl-build-system |
| 2560 | This variable is exported by @code{(guix build-system perl)}. It |
| 2561 | implements the standard build procedure for Perl packages, which either |
| 2562 | consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, |
| 2563 | followed by @code{Build} and @code{Build install}; or in running |
| 2564 | @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by |
| 2565 | @code{make} and @code{make install}; depending on which of |
| 2566 | @code{Build.PL} or @code{Makefile.PL} is present in the package |
| 2567 | distribution. Preference is given to the former if both @code{Build.PL} |
| 2568 | and @code{Makefile.PL} exist in the package distribution. This |
| 2569 | preference can be reversed by specifying @code{#t} for the |
| 2570 | @code{#:make-maker?} parameter. |
| 2571 | |
| 2572 | The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation |
| 2573 | passes flags specified by the @code{#:make-maker-flags} or |
| 2574 | @code{#:module-build-flags} parameter, respectively. |
| 2575 | |
| 2576 | Which Perl package is used can be specified with @code{#:perl}. |
| 2577 | @end defvr |
| 2578 | |
| 2579 | @defvr {Scheme Variable} r-build-system |
| 2580 | This variable is exported by @code{(guix build-system r)}. It |
| 2581 | implements the build procedure used by @uref{http://r-project.org, R} |
| 2582 | packages, which essentially is little more than running @code{R CMD |
| 2583 | INSTALL --library=/gnu/store/@dots{}} in an environment where |
| 2584 | @code{R_LIBS_SITE} contains the paths to all R package inputs. Tests |
| 2585 | are run after installation using the R function |
| 2586 | @code{tools::testInstalledPackage}. |
| 2587 | @end defvr |
| 2588 | |
| 2589 | @defvr {Scheme Variable} ruby-build-system |
| 2590 | This variable is exported by @code{(guix build-system ruby)}. It |
| 2591 | implements the RubyGems build procedure used by Ruby packages, which |
| 2592 | involves running @code{gem build} followed by @code{gem install}. |
| 2593 | |
| 2594 | The @code{source} field of a package that uses this build system |
| 2595 | typically references a gem archive, since this is the format that Ruby |
| 2596 | developers use when releasing their software. The build system unpacks |
| 2597 | the gem archive, potentially patches the source, runs the test suite, |
| 2598 | repackages the gem, and installs it. Additionally, directories and |
| 2599 | tarballs may be referenced to allow building unreleased gems from Git or |
| 2600 | a traditional source release tarball. |
| 2601 | |
| 2602 | Which Ruby package is used can be specified with the @code{#:ruby} |
| 2603 | parameter. A list of additional flags to be passed to the @command{gem} |
| 2604 | command can be specified with the @code{#:gem-flags} parameter. |
| 2605 | @end defvr |
| 2606 | |
| 2607 | @defvr {Scheme Variable} waf-build-system |
| 2608 | This variable is exported by @code{(guix build-system waf)}. It |
| 2609 | implements a build procedure around the @code{waf} script. The common |
| 2610 | phases---@code{configure}, @code{build}, and @code{install}---are |
| 2611 | implemented by passing their names as arguments to the @code{waf} |
| 2612 | script. |
| 2613 | |
| 2614 | The @code{waf} script is executed by the Python interpreter. Which |
| 2615 | Python package is used to run the script can be specified with the |
| 2616 | @code{#:python} parameter. |
| 2617 | @end defvr |
| 2618 | |
| 2619 | @defvr {Scheme Variable} haskell-build-system |
| 2620 | This variable is exported by @code{(guix build-system haskell)}. It |
| 2621 | implements the Cabal build procedure used by Haskell packages, which |
| 2622 | involves running @code{runhaskell Setup.hs configure |
| 2623 | --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}. |
| 2624 | Instead of installing the package by running @code{runhaskell Setup.hs |
| 2625 | install}, to avoid trying to register libraries in the read-only |
| 2626 | compiler store directory, the build system uses @code{runhaskell |
| 2627 | Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In |
| 2628 | addition, the build system generates the package documentation by |
| 2629 | running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f} |
| 2630 | is passed. Optional Haddock parameters can be passed with the help of |
| 2631 | the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is |
| 2632 | not found, the build system looks for @code{Setup.lhs} instead. |
| 2633 | |
| 2634 | Which Haskell compiler is used can be specified with the @code{#:haskell} |
| 2635 | parameter which defaults to @code{ghc}. |
| 2636 | @end defvr |
| 2637 | |
| 2638 | @defvr {Scheme Variable} emacs-build-system |
| 2639 | This variable is exported by @code{(guix build-system emacs)}. It |
| 2640 | implements an installation procedure similar to the one of Emacs' own |
| 2641 | packaging system (@pxref{Packages,,, emacs, The GNU Emacs Manual}). |
| 2642 | |
| 2643 | It first creates the @code{@var{package}-autoloads.el} file, then it |
| 2644 | byte compiles all Emacs Lisp files. Differently from the Emacs |
| 2645 | packaging system, the Info documentation files are moved to the standard |
| 2646 | documentation directory and the @file{dir} file is deleted. Each |
| 2647 | package is installed in its own directory under |
| 2648 | @file{share/emacs/site-lisp/guix.d}. |
| 2649 | @end defvr |
| 2650 | |
| 2651 | Lastly, for packages that do not need anything as sophisticated, a |
| 2652 | ``trivial'' build system is provided. It is trivial in the sense that |
| 2653 | it provides basically no support: it does not pull any implicit inputs, |
| 2654 | and does not have a notion of build phases. |
| 2655 | |
| 2656 | @defvr {Scheme Variable} trivial-build-system |
| 2657 | This variable is exported by @code{(guix build-system trivial)}. |
| 2658 | |
| 2659 | This build system requires a @code{#:builder} argument. This argument |
| 2660 | must be a Scheme expression that builds the package's output(s)---as |
| 2661 | with @code{build-expression->derivation} (@pxref{Derivations, |
| 2662 | @code{build-expression->derivation}}). |
| 2663 | @end defvr |
| 2664 | |
| 2665 | @node The Store |
| 2666 | @section The Store |
| 2667 | |
| 2668 | @cindex store |
| 2669 | @cindex store paths |
| 2670 | |
| 2671 | Conceptually, the @dfn{store} is where derivations that have been |
| 2672 | successfully built are stored---by default, under @file{/gnu/store}. |
| 2673 | Sub-directories in the store are referred to as @dfn{store paths}. The |
| 2674 | store has an associated database that contains information such as the |
| 2675 | store paths referred to by each store path, and the list of @emph{valid} |
| 2676 | store paths---paths that result from a successful build. |
| 2677 | |
| 2678 | The store is always accessed by the daemon on behalf of its clients |
| 2679 | (@pxref{Invoking guix-daemon}). To manipulate the store, clients |
| 2680 | connect to the daemon over a Unix-domain socket, send it requests, and |
| 2681 | read the result---these are remote procedure calls, or RPCs. |
| 2682 | |
| 2683 | The @code{(guix store)} module provides procedures to connect to the |
| 2684 | daemon, and to perform RPCs. These are described below. |
| 2685 | |
| 2686 | @deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t] |
| 2687 | Connect to the daemon over the Unix-domain socket at @var{file}. When |
| 2688 | @var{reserve-space?} is true, instruct it to reserve a little bit of |
| 2689 | extra space on the file system so that the garbage collector can still |
| 2690 | operate, should the disk become full. Return a server object. |
| 2691 | |
| 2692 | @var{file} defaults to @var{%default-socket-path}, which is the normal |
| 2693 | location given the options that were passed to @command{configure}. |
| 2694 | @end deffn |
| 2695 | |
| 2696 | @deffn {Scheme Procedure} close-connection @var{server} |
| 2697 | Close the connection to @var{server}. |
| 2698 | @end deffn |
| 2699 | |
| 2700 | @defvr {Scheme Variable} current-build-output-port |
| 2701 | This variable is bound to a SRFI-39 parameter, which refers to the port |
| 2702 | where build and error logs sent by the daemon should be written. |
| 2703 | @end defvr |
| 2704 | |
| 2705 | Procedures that make RPCs all take a server object as their first |
| 2706 | argument. |
| 2707 | |
| 2708 | @deffn {Scheme Procedure} valid-path? @var{server} @var{path} |
| 2709 | Return @code{#t} when @var{path} is a valid store path. |
| 2710 | @end deffn |
| 2711 | |
| 2712 | @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] |
| 2713 | Add @var{text} under file @var{name} in the store, and return its store |
| 2714 | path. @var{references} is the list of store paths referred to by the |
| 2715 | resulting store path. |
| 2716 | @end deffn |
| 2717 | |
| 2718 | @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations} |
| 2719 | Build @var{derivations} (a list of @code{<derivation>} objects or |
| 2720 | derivation paths), and return when the worker is done building them. |
| 2721 | Return @code{#t} on success. |
| 2722 | @end deffn |
| 2723 | |
| 2724 | Note that the @code{(guix monads)} module provides a monad as well as |
| 2725 | monadic versions of the above procedures, with the goal of making it |
| 2726 | more convenient to work with code that accesses the store (@pxref{The |
| 2727 | Store Monad}). |
| 2728 | |
| 2729 | @c FIXME |
| 2730 | @i{This section is currently incomplete.} |
| 2731 | |
| 2732 | @node Derivations |
| 2733 | @section Derivations |
| 2734 | |
| 2735 | @cindex derivations |
| 2736 | Low-level build actions and the environment in which they are performed |
| 2737 | are represented by @dfn{derivations}. A derivation contain the |
| 2738 | following pieces of information: |
| 2739 | |
| 2740 | @itemize |
| 2741 | @item |
| 2742 | The outputs of the derivation---derivations produce at least one file or |
| 2743 | directory in the store, but may produce more. |
| 2744 | |
| 2745 | @item |
| 2746 | The inputs of the derivations, which may be other derivations or plain |
| 2747 | files in the store (patches, build scripts, etc.) |
| 2748 | |
| 2749 | @item |
| 2750 | The system type targeted by the derivation---e.g., @code{x86_64-linux}. |
| 2751 | |
| 2752 | @item |
| 2753 | The file name of a build script in the store, along with the arguments |
| 2754 | to be passed. |
| 2755 | |
| 2756 | @item |
| 2757 | A list of environment variables to be defined. |
| 2758 | |
| 2759 | @end itemize |
| 2760 | |
| 2761 | @cindex derivation path |
| 2762 | Derivations allow clients of the daemon to communicate build actions to |
| 2763 | the store. They exist in two forms: as an in-memory representation, |
| 2764 | both on the client- and daemon-side, and as files in the store whose |
| 2765 | name end in @code{.drv}---these files are referred to as @dfn{derivation |
| 2766 | paths}. Derivations paths can be passed to the @code{build-derivations} |
| 2767 | procedure to perform the build actions they prescribe (@pxref{The |
| 2768 | Store}). |
| 2769 | |
| 2770 | The @code{(guix derivations)} module provides a representation of |
| 2771 | derivations as Scheme objects, along with procedures to create and |
| 2772 | otherwise manipulate derivations. The lowest-level primitive to create |
| 2773 | a derivation is the @code{derivation} procedure: |
| 2774 | |
| 2775 | @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @ |
| 2776 | @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ |
| 2777 | [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @ |
| 2778 | [#:system (%current-system)] [#:references-graphs #f] @ |
| 2779 | [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f] @ |
| 2780 | [#:substitutable? #t] |
| 2781 | Build a derivation with the given arguments, and return the resulting |
| 2782 | @code{<derivation>} object. |
| 2783 | |
| 2784 | When @var{hash} and @var{hash-algo} are given, a |
| 2785 | @dfn{fixed-output derivation} is created---i.e., one whose result is |
| 2786 | known in advance, such as a file download. If, in addition, |
| 2787 | @var{recursive?} is true, then that fixed output may be an executable |
| 2788 | file or a directory and @var{hash} must be the hash of an archive |
| 2789 | containing this output. |
| 2790 | |
| 2791 | When @var{references-graphs} is true, it must be a list of file |
| 2792 | name/store path pairs. In that case, the reference graph of each store |
| 2793 | path is exported in the build environment in the corresponding file, in |
| 2794 | a simple text format. |
| 2795 | |
| 2796 | When @var{allowed-references} is true, it must be a list of store items |
| 2797 | or outputs that the derivation's output may refer to. |
| 2798 | |
| 2799 | When @var{leaked-env-vars} is true, it must be a list of strings |
| 2800 | denoting environment variables that are allowed to ``leak'' from the |
| 2801 | daemon's environment to the build environment. This is only applicable |
| 2802 | to fixed-output derivations---i.e., when @var{hash} is true. The main |
| 2803 | use is to allow variables such as @code{http_proxy} to be passed to |
| 2804 | derivations that download files. |
| 2805 | |
| 2806 | When @var{local-build?} is true, declare that the derivation is not a |
| 2807 | good candidate for offloading and should rather be built locally |
| 2808 | (@pxref{Daemon Offload Setup}). This is the case for small derivations |
| 2809 | where the costs of data transfers would outweigh the benefits. |
| 2810 | |
| 2811 | When @var{substitutable?} is false, declare that substitutes of the |
| 2812 | derivation's output should not be used (@pxref{Substitutes}). This is |
| 2813 | useful, for instance, when building packages that capture details of the |
| 2814 | host CPU instruction set. |
| 2815 | @end deffn |
| 2816 | |
| 2817 | @noindent |
| 2818 | Here's an example with a shell script as its builder, assuming |
| 2819 | @var{store} is an open connection to the daemon, and @var{bash} points |
| 2820 | to a Bash executable in the store: |
| 2821 | |
| 2822 | @lisp |
| 2823 | (use-modules (guix utils) |
| 2824 | (guix store) |
| 2825 | (guix derivations)) |
| 2826 | |
| 2827 | (let ((builder ; add the Bash script to the store |
| 2828 | (add-text-to-store store "my-builder.sh" |
| 2829 | "echo hello world > $out\n" '()))) |
| 2830 | (derivation store "foo" |
| 2831 | bash `("-e" ,builder) |
| 2832 | #:inputs `((,bash) (,builder)) |
| 2833 | #:env-vars '(("HOME" . "/homeless")))) |
| 2834 | @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> |
| 2835 | @end lisp |
| 2836 | |
| 2837 | As can be guessed, this primitive is cumbersome to use directly. A |
| 2838 | better approach is to write build scripts in Scheme, of course! The |
| 2839 | best course of action for that is to write the build code as a |
| 2840 | ``G-expression'', and to pass it to @code{gexp->derivation}. For more |
| 2841 | information, @pxref{G-Expressions}. |
| 2842 | |
| 2843 | Once upon a time, @code{gexp->derivation} did not exist and constructing |
| 2844 | derivations with build code written in Scheme was achieved with |
| 2845 | @code{build-expression->derivation}, documented below. This procedure |
| 2846 | is now deprecated in favor of the much nicer @code{gexp->derivation}. |
| 2847 | |
| 2848 | @deffn {Scheme Procedure} build-expression->derivation @var{store} @ |
| 2849 | @var{name} @var{exp} @ |
| 2850 | [#:system (%current-system)] [#:inputs '()] @ |
| 2851 | [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ |
| 2852 | [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ |
| 2853 | [#:references-graphs #f] [#:allowed-references #f] @ |
| 2854 | [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] |
| 2855 | Return a derivation that executes Scheme expression @var{exp} as a |
| 2856 | builder for derivation @var{name}. @var{inputs} must be a list of |
| 2857 | @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted, |
| 2858 | @code{"out"} is assumed. @var{modules} is a list of names of Guile |
| 2859 | modules from the current search path to be copied in the store, |
| 2860 | compiled, and made available in the load path during the execution of |
| 2861 | @var{exp}---e.g., @code{((guix build utils) (guix build |
| 2862 | gnu-build-system))}. |
| 2863 | |
| 2864 | @var{exp} is evaluated in an environment where @code{%outputs} is bound |
| 2865 | to a list of output/path pairs, and where @code{%build-inputs} is bound |
| 2866 | to a list of string/output-path pairs made from @var{inputs}. |
| 2867 | Optionally, @var{env-vars} is a list of string pairs specifying the name |
| 2868 | and value of environment variables visible to the builder. The builder |
| 2869 | terminates by passing the result of @var{exp} to @code{exit}; thus, when |
| 2870 | @var{exp} returns @code{#f}, the build is considered to have failed. |
| 2871 | |
| 2872 | @var{exp} is built using @var{guile-for-build} (a derivation). When |
| 2873 | @var{guile-for-build} is omitted or is @code{#f}, the value of the |
| 2874 | @code{%guile-for-build} fluid is used instead. |
| 2875 | |
| 2876 | See the @code{derivation} procedure for the meaning of |
| 2877 | @var{references-graphs}, @var{allowed-references}, @var{local-build?}, |
| 2878 | and @var{substitutable?}. |
| 2879 | @end deffn |
| 2880 | |
| 2881 | @noindent |
| 2882 | Here's an example of a single-output derivation that creates a directory |
| 2883 | containing one file: |
| 2884 | |
| 2885 | @lisp |
| 2886 | (let ((builder '(let ((out (assoc-ref %outputs "out"))) |
| 2887 | (mkdir out) ; create /gnu/store/@dots{}-goo |
| 2888 | (call-with-output-file (string-append out "/test") |
| 2889 | (lambda (p) |
| 2890 | (display '(hello guix) p)))))) |
| 2891 | (build-expression->derivation store "goo" builder)) |
| 2892 | |
| 2893 | @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> |
| 2894 | @end lisp |
| 2895 | |
| 2896 | |
| 2897 | @node The Store Monad |
| 2898 | @section The Store Monad |
| 2899 | |
| 2900 | @cindex monad |
| 2901 | |
| 2902 | The procedures that operate on the store described in the previous |
| 2903 | sections all take an open connection to the build daemon as their first |
| 2904 | argument. Although the underlying model is functional, they either have |
| 2905 | side effects or depend on the current state of the store. |
| 2906 | |
| 2907 | The former is inconvenient: the connection to the build daemon has to be |
| 2908 | carried around in all those functions, making it impossible to compose |
| 2909 | functions that do not take that parameter with functions that do. The |
| 2910 | latter can be problematic: since store operations have side effects |
| 2911 | and/or depend on external state, they have to be properly sequenced. |
| 2912 | |
| 2913 | @cindex monadic values |
| 2914 | @cindex monadic functions |
| 2915 | This is where the @code{(guix monads)} module comes in. This module |
| 2916 | provides a framework for working with @dfn{monads}, and a particularly |
| 2917 | useful monad for our uses, the @dfn{store monad}. Monads are a |
| 2918 | construct that allows two things: associating ``context'' with values |
| 2919 | (in our case, the context is the store), and building sequences of |
| 2920 | computations (here computations include accesses to the store.) Values |
| 2921 | in a monad---values that carry this additional context---are called |
| 2922 | @dfn{monadic values}; procedures that return such values are called |
| 2923 | @dfn{monadic procedures}. |
| 2924 | |
| 2925 | Consider this ``normal'' procedure: |
| 2926 | |
| 2927 | @example |
| 2928 | (define (sh-symlink store) |
| 2929 | ;; Return a derivation that symlinks the 'bash' executable. |
| 2930 | (let* ((drv (package-derivation store bash)) |
| 2931 | (out (derivation->output-path drv)) |
| 2932 | (sh (string-append out "/bin/bash"))) |
| 2933 | (build-expression->derivation store "sh" |
| 2934 | `(symlink ,sh %output)))) |
| 2935 | @end example |
| 2936 | |
| 2937 | Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten |
| 2938 | as a monadic function: |
| 2939 | |
| 2940 | @example |
| 2941 | (define (sh-symlink) |
| 2942 | ;; Same, but return a monadic value. |
| 2943 | (mlet %store-monad ((drv (package->derivation bash))) |
| 2944 | (gexp->derivation "sh" |
| 2945 | #~(symlink (string-append #$drv "/bin/bash") |
| 2946 | #$output)))) |
| 2947 | @end example |
| 2948 | |
| 2949 | There several things to note in the second version: the @code{store} |
| 2950 | parameter is now implicit and is ``threaded'' in the calls to the |
| 2951 | @code{package->derivation} and @code{gexp->derivation} monadic |
| 2952 | procedures, and the monadic value returned by @code{package->derivation} |
| 2953 | is @dfn{bound} using @code{mlet} instead of plain @code{let}. |
| 2954 | |
| 2955 | As it turns out, the call to @code{package->derivation} can even be |
| 2956 | omitted since it will take place implicitly, as we will see later |
| 2957 | (@pxref{G-Expressions}): |
| 2958 | |
| 2959 | @example |
| 2960 | (define (sh-symlink) |
| 2961 | (gexp->derivation "sh" |
| 2962 | #~(symlink (string-append #$bash "/bin/bash") |
| 2963 | #$output))) |
| 2964 | @end example |
| 2965 | |
| 2966 | @c See |
| 2967 | @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> |
| 2968 | @c for the funny quote. |
| 2969 | Calling the monadic @code{sh-symlink} has no effect. As someone once |
| 2970 | said, ``you exit a monad like you exit a building on fire: by running''. |
| 2971 | So, to exit the monad and get the desired effect, one must use |
| 2972 | @code{run-with-store}: |
| 2973 | |
| 2974 | @example |
| 2975 | (run-with-store (open-connection) (sh-symlink)) |
| 2976 | @result{} /gnu/store/...-sh-symlink |
| 2977 | @end example |
| 2978 | |
| 2979 | Note that the @code{(guix monad-repl)} module extends Guile's REPL with |
| 2980 | new ``meta-commands'' to make it easier to deal with monadic procedures: |
| 2981 | @code{run-in-store}, and @code{enter-store-monad}. The former, is used |
| 2982 | to ``run'' a single monadic value through the store: |
| 2983 | |
| 2984 | @example |
| 2985 | scheme@@(guile-user)> ,run-in-store (package->derivation hello) |
| 2986 | $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> |
| 2987 | @end example |
| 2988 | |
| 2989 | The latter enters a recursive REPL, where all the return values are |
| 2990 | automatically run through the store: |
| 2991 | |
| 2992 | @example |
| 2993 | scheme@@(guile-user)> ,enter-store-monad |
| 2994 | store-monad@@(guile-user) [1]> (package->derivation hello) |
| 2995 | $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> |
| 2996 | store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") |
| 2997 | $3 = "/gnu/store/@dots{}-foo" |
| 2998 | store-monad@@(guile-user) [1]> ,q |
| 2999 | scheme@@(guile-user)> |
| 3000 | @end example |
| 3001 | |
| 3002 | @noindent |
| 3003 | Note that non-monadic values cannot be returned in the |
| 3004 | @code{store-monad} REPL. |
| 3005 | |
| 3006 | The main syntactic forms to deal with monads in general are provided by |
| 3007 | the @code{(guix monads)} module and are described below. |
| 3008 | |
| 3009 | @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ... |
| 3010 | Evaluate any @code{>>=} or @code{return} forms in @var{body} as being |
| 3011 | in @var{monad}. |
| 3012 | @end deffn |
| 3013 | |
| 3014 | @deffn {Scheme Syntax} return @var{val} |
| 3015 | Return a monadic value that encapsulates @var{val}. |
| 3016 | @end deffn |
| 3017 | |
| 3018 | @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ... |
| 3019 | @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic |
| 3020 | procedures @var{mproc}@dots{}@footnote{This operation is commonly |
| 3021 | referred to as ``bind'', but that name denotes an unrelated procedure in |
| 3022 | Guile. Thus we use this somewhat cryptic symbol inherited from the |
| 3023 | Haskell language.}. There can be one @var{mproc} or several of them, as |
| 3024 | in this example: |
| 3025 | |
| 3026 | @example |
| 3027 | (run-with-state |
| 3028 | (with-monad %state-monad |
| 3029 | (>>= (return 1) |
| 3030 | (lambda (x) (return (+ 1 x))) |
| 3031 | (lambda (x) (return (* 2 x))))) |
| 3032 | 'some-state) |
| 3033 | |
| 3034 | @result{} 4 |
| 3035 | @result{} some-state |
| 3036 | @end example |
| 3037 | @end deffn |
| 3038 | |
| 3039 | @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ |
| 3040 | @var{body} ... |
| 3041 | @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ |
| 3042 | @var{body} ... |
| 3043 | Bind the variables @var{var} to the monadic values @var{mval} in |
| 3044 | @var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the |
| 3045 | ``normal'' value @var{val}, as per @code{let}. |
| 3046 | |
| 3047 | @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} |
| 3048 | (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). |
| 3049 | @end deffn |
| 3050 | |
| 3051 | @deffn {Scheme System} mbegin @var{monad} @var{mexp} ... |
| 3052 | Bind @var{mexp} and the following monadic expressions in sequence, |
| 3053 | returning the result of the last expression. |
| 3054 | |
| 3055 | This is akin to @code{mlet}, except that the return values of the |
| 3056 | monadic expressions are ignored. In that sense, it is analogous to |
| 3057 | @code{begin}, but applied to monadic expressions. |
| 3058 | @end deffn |
| 3059 | |
| 3060 | @cindex state monad |
| 3061 | The @code{(guix monads)} module provides the @dfn{state monad}, which |
| 3062 | allows an additional value---the state---to be @emph{threaded} through |
| 3063 | monadic procedure calls. |
| 3064 | |
| 3065 | @defvr {Scheme Variable} %state-monad |
| 3066 | The state monad. Procedures in the state monad can access and change |
| 3067 | the state that is threaded. |
| 3068 | |
| 3069 | Consider the example below. The @code{square} procedure returns a value |
| 3070 | in the state monad. It returns the square of its argument, but also |
| 3071 | increments the current state value: |
| 3072 | |
| 3073 | @example |
| 3074 | (define (square x) |
| 3075 | (mlet %state-monad ((count (current-state))) |
| 3076 | (mbegin %state-monad |
| 3077 | (set-current-state (+ 1 count)) |
| 3078 | (return (* x x))))) |
| 3079 | |
| 3080 | (run-with-state (sequence %state-monad (map square (iota 3))) 0) |
| 3081 | @result{} (0 1 4) |
| 3082 | @result{} 3 |
| 3083 | @end example |
| 3084 | |
| 3085 | When ``run'' through @var{%state-monad}, we obtain that additional state |
| 3086 | value, which is the number of @code{square} calls. |
| 3087 | @end defvr |
| 3088 | |
| 3089 | @deffn {Monadic Procedure} current-state |
| 3090 | Return the current state as a monadic value. |
| 3091 | @end deffn |
| 3092 | |
| 3093 | @deffn {Monadic Procedure} set-current-state @var{value} |
| 3094 | Set the current state to @var{value} and return the previous state as a |
| 3095 | monadic value. |
| 3096 | @end deffn |
| 3097 | |
| 3098 | @deffn {Monadic Procedure} state-push @var{value} |
| 3099 | Push @var{value} to the current state, which is assumed to be a list, |
| 3100 | and return the previous state as a monadic value. |
| 3101 | @end deffn |
| 3102 | |
| 3103 | @deffn {Monadic Procedure} state-pop |
| 3104 | Pop a value from the current state and return it as a monadic value. |
| 3105 | The state is assumed to be a list. |
| 3106 | @end deffn |
| 3107 | |
| 3108 | @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}] |
| 3109 | Run monadic value @var{mval} starting with @var{state} as the initial |
| 3110 | state. Return two values: the resulting value, and the resulting state. |
| 3111 | @end deffn |
| 3112 | |
| 3113 | The main interface to the store monad, provided by the @code{(guix |
| 3114 | store)} module, is as follows. |
| 3115 | |
| 3116 | @defvr {Scheme Variable} %store-monad |
| 3117 | The store monad---an alias for @var{%state-monad}. |
| 3118 | |
| 3119 | Values in the store monad encapsulate accesses to the store. When its |
| 3120 | effect is needed, a value of the store monad must be ``evaluated'' by |
| 3121 | passing it to the @code{run-with-store} procedure (see below.) |
| 3122 | @end defvr |
| 3123 | |
| 3124 | @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] |
| 3125 | Run @var{mval}, a monadic value in the store monad, in @var{store}, an |
| 3126 | open store connection. |
| 3127 | @end deffn |
| 3128 | |
| 3129 | @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}] |
| 3130 | Return as a monadic value the absolute file name in the store of the file |
| 3131 | containing @var{text}, a string. @var{references} is a list of store items that the |
| 3132 | resulting text file refers to; it defaults to the empty list. |
| 3133 | @end deffn |
| 3134 | |
| 3135 | @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @ |
| 3136 | [#:recursive? #t] |
| 3137 | Return the name of @var{file} once interned in the store. Use |
| 3138 | @var{name} as its store name, or the basename of @var{file} if |
| 3139 | @var{name} is omitted. |
| 3140 | |
| 3141 | When @var{recursive?} is true, the contents of @var{file} are added |
| 3142 | recursively; if @var{file} designates a flat file and @var{recursive?} |
| 3143 | is true, its contents are added, and its permission bits are kept. |
| 3144 | |
| 3145 | The example below adds a file to the store, under two different names: |
| 3146 | |
| 3147 | @example |
| 3148 | (run-with-store (open-connection) |
| 3149 | (mlet %store-monad ((a (interned-file "README")) |
| 3150 | (b (interned-file "README" "LEGU-MIN"))) |
| 3151 | (return (list a b)))) |
| 3152 | |
| 3153 | @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN") |
| 3154 | @end example |
| 3155 | |
| 3156 | @end deffn |
| 3157 | |
| 3158 | The @code{(guix packages)} module exports the following package-related |
| 3159 | monadic procedures: |
| 3160 | |
| 3161 | @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @ |
| 3162 | [#:system (%current-system)] [#:target #f] @ |
| 3163 | [#:output "out"] Return as a monadic |
| 3164 | value in the absolute file name of @var{file} within the @var{output} |
| 3165 | directory of @var{package}. When @var{file} is omitted, return the name |
| 3166 | of the @var{output} directory of @var{package}. When @var{target} is |
| 3167 | true, use it as a cross-compilation target triplet. |
| 3168 | @end deffn |
| 3169 | |
| 3170 | @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}] |
| 3171 | @deffnx {Monadic Procedure} package->cross-derivation @var{package} @ |
| 3172 | @var{target} [@var{system}] |
| 3173 | Monadic version of @code{package-derivation} and |
| 3174 | @code{package-cross-derivation} (@pxref{Defining Packages}). |
| 3175 | @end deffn |
| 3176 | |
| 3177 | |
| 3178 | @node G-Expressions |
| 3179 | @section G-Expressions |
| 3180 | |
| 3181 | @cindex G-expression |
| 3182 | @cindex build code quoting |
| 3183 | So we have ``derivations'', which represent a sequence of build actions |
| 3184 | to be performed to produce an item in the store (@pxref{Derivations}). |
| 3185 | Those build actions are performed when asking the daemon to actually |
| 3186 | build the derivations; they are run by the daemon in a container |
| 3187 | (@pxref{Invoking guix-daemon}). |
| 3188 | |
| 3189 | @cindex strata of code |
| 3190 | It should come as no surprise that we like to write those build actions |
| 3191 | in Scheme. When we do that, we end up with two @dfn{strata} of Scheme |
| 3192 | code@footnote{The term @dfn{stratum} in this context was coined by |
| 3193 | Manuel Serrano et al.@: in the context of their work on Hop. Oleg |
| 3194 | Kiselyov, who has written insightful |
| 3195 | @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code |
| 3196 | on this topic}, refers to this kind of code generation as |
| 3197 | @dfn{staging}.}: the ``host code''---code that defines packages, talks |
| 3198 | to the daemon, etc.---and the ``build code''---code that actually |
| 3199 | performs build actions, such as making directories, invoking |
| 3200 | @command{make}, etc. |
| 3201 | |
| 3202 | To describe a derivation and its build actions, one typically needs to |
| 3203 | embed build code inside host code. It boils down to manipulating build |
| 3204 | code as data, and Scheme's homoiconicity---code has a direct |
| 3205 | representation as data---comes in handy for that. But we need more than |
| 3206 | Scheme's normal @code{quasiquote} mechanism to construct build |
| 3207 | expressions. |
| 3208 | |
| 3209 | The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of |
| 3210 | S-expressions adapted to build expressions. G-expressions, or |
| 3211 | @dfn{gexps}, consist essentially in three syntactic forms: @code{gexp}, |
| 3212 | @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~}, |
| 3213 | @code{#$}, and @code{#$@@}), which are comparable respectively to |
| 3214 | @code{quasiquote}, @code{unquote}, and @code{unquote-splicing} |
| 3215 | (@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile |
| 3216 | Reference Manual}). However, there are major differences: |
| 3217 | |
| 3218 | @itemize |
| 3219 | @item |
| 3220 | Gexps are meant to be written to a file and run or manipulated by other |
| 3221 | processes. |
| 3222 | |
| 3223 | @item |
| 3224 | When a high-level object such as a package or derivation is unquoted |
| 3225 | inside a gexp, the result is as if its output file name had been |
| 3226 | introduced. |
| 3227 | |
| 3228 | @item |
| 3229 | Gexps carry information about the packages or derivations they refer to, |
| 3230 | and these dependencies are automatically added as inputs to the build |
| 3231 | processes that use them. |
| 3232 | @end itemize |
| 3233 | |
| 3234 | @cindex lowering, of high-level objects in gexps |
| 3235 | This mechanism is not limited to package and derivation |
| 3236 | objects: @dfn{compilers} able to ``lower'' other high-level objects to |
| 3237 | derivations or files in the store can be defined, |
| 3238 | such that these objects can also be inserted |
| 3239 | into gexps. For example, a useful type of high-level object that can be |
| 3240 | inserted in a gexp is ``file-like objects'', which make it easy to |
| 3241 | add files to the store and refer to them in |
| 3242 | derivations and such (see @code{local-file} and @code{plain-file} |
| 3243 | below.) |
| 3244 | |
| 3245 | To illustrate the idea, here is an example of a gexp: |
| 3246 | |
| 3247 | @example |
| 3248 | (define build-exp |
| 3249 | #~(begin |
| 3250 | (mkdir #$output) |
| 3251 | (chdir #$output) |
| 3252 | (symlink (string-append #$coreutils "/bin/ls") |
| 3253 | "list-files"))) |
| 3254 | @end example |
| 3255 | |
| 3256 | This gexp can be passed to @code{gexp->derivation}; we obtain a |
| 3257 | derivation that builds a directory containing exactly one symlink to |
| 3258 | @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: |
| 3259 | |
| 3260 | @example |
| 3261 | (gexp->derivation "the-thing" build-exp) |
| 3262 | @end example |
| 3263 | |
| 3264 | As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is |
| 3265 | substituted to the reference to the @var{coreutils} package in the |
| 3266 | actual build code, and @var{coreutils} is automatically made an input to |
| 3267 | the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp |
| 3268 | output)}) is replaced by a string containing the derivation's output |
| 3269 | directory name. |
| 3270 | |
| 3271 | @cindex cross compilation |
| 3272 | In a cross-compilation context, it is useful to distinguish between |
| 3273 | references to the @emph{native} build of a package---that can run on the |
| 3274 | host---versus references to cross builds of a package. To that end, the |
| 3275 | @code{#+} plays the same role as @code{#$}, but is a reference to a |
| 3276 | native package build: |
| 3277 | |
| 3278 | @example |
| 3279 | (gexp->derivation "vi" |
| 3280 | #~(begin |
| 3281 | (mkdir #$output) |
| 3282 | (system* (string-append #+coreutils "/bin/ln") |
| 3283 | "-s" |
| 3284 | (string-append #$emacs "/bin/emacs") |
| 3285 | (string-append #$output "/bin/vi"))) |
| 3286 | #:target "mips64el-linux") |
| 3287 | @end example |
| 3288 | |
| 3289 | @noindent |
| 3290 | In the example above, the native build of @var{coreutils} is used, so |
| 3291 | that @command{ln} can actually run on the host; but then the |
| 3292 | cross-compiled build of @var{emacs} is referenced. |
| 3293 | |
| 3294 | The syntactic form to construct gexps is summarized below. |
| 3295 | |
| 3296 | @deffn {Scheme Syntax} #~@var{exp} |
| 3297 | @deffnx {Scheme Syntax} (gexp @var{exp}) |
| 3298 | Return a G-expression containing @var{exp}. @var{exp} may contain one |
| 3299 | or more of the following forms: |
| 3300 | |
| 3301 | @table @code |
| 3302 | @item #$@var{obj} |
| 3303 | @itemx (ungexp @var{obj}) |
| 3304 | Introduce a reference to @var{obj}. @var{obj} may have one of the |
| 3305 | supported types, for example a package or a |
| 3306 | derivation, in which case the @code{ungexp} form is replaced by its |
| 3307 | output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}. |
| 3308 | |
| 3309 | If @var{obj} is a list, it is traversed and references to supported |
| 3310 | objects are substituted similarly. |
| 3311 | |
| 3312 | If @var{obj} is another gexp, its contents are inserted and its |
| 3313 | dependencies are added to those of the containing gexp. |
| 3314 | |
| 3315 | If @var{obj} is another kind of object, it is inserted as is. |
| 3316 | |
| 3317 | @item #$@var{obj}:@var{output} |
| 3318 | @itemx (ungexp @var{obj} @var{output}) |
| 3319 | This is like the form above, but referring explicitly to the |
| 3320 | @var{output} of @var{obj}---this is useful when @var{obj} produces |
| 3321 | multiple outputs (@pxref{Packages with Multiple Outputs}). |
| 3322 | |
| 3323 | @item #+@var{obj} |
| 3324 | @itemx #+@var{obj}:output |
| 3325 | @itemx (ungexp-native @var{obj}) |
| 3326 | @itemx (ungexp-native @var{obj} @var{output}) |
| 3327 | Same as @code{ungexp}, but produces a reference to the @emph{native} |
| 3328 | build of @var{obj} when used in a cross compilation context. |
| 3329 | |
| 3330 | @item #$output[:@var{output}] |
| 3331 | @itemx (ungexp output [@var{output}]) |
| 3332 | Insert a reference to derivation output @var{output}, or to the main |
| 3333 | output when @var{output} is omitted. |
| 3334 | |
| 3335 | This only makes sense for gexps passed to @code{gexp->derivation}. |
| 3336 | |
| 3337 | @item #$@@@var{lst} |
| 3338 | @itemx (ungexp-splicing @var{lst}) |
| 3339 | Like the above, but splices the contents of @var{lst} inside the |
| 3340 | containing list. |
| 3341 | |
| 3342 | @item #+@@@var{lst} |
| 3343 | @itemx (ungexp-native-splicing @var{lst}) |
| 3344 | Like the above, but refers to native builds of the objects listed in |
| 3345 | @var{lst}. |
| 3346 | |
| 3347 | @end table |
| 3348 | |
| 3349 | G-expressions created by @code{gexp} or @code{#~} are run-time objects |
| 3350 | of the @code{gexp?} type (see below.) |
| 3351 | @end deffn |
| 3352 | |
| 3353 | @deffn {Scheme Procedure} gexp? @var{obj} |
| 3354 | Return @code{#t} if @var{obj} is a G-expression. |
| 3355 | @end deffn |
| 3356 | |
| 3357 | G-expressions are meant to be written to disk, either as code building |
| 3358 | some derivation, or as plain files in the store. The monadic procedures |
| 3359 | below allow you to do that (@pxref{The Store Monad}, for more |
| 3360 | information about monads.) |
| 3361 | |
| 3362 | @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @ |
| 3363 | [#:system (%current-system)] [#:target #f] [#:graft? #t] @ |
| 3364 | [#:hash #f] [#:hash-algo #f] @ |
| 3365 | [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ |
| 3366 | [#:module-path @var{%load-path}] @ |
| 3367 | [#:references-graphs #f] [#:allowed-references #f] @ |
| 3368 | [#:leaked-env-vars #f] @ |
| 3369 | [#:script-name (string-append @var{name} "-builder")] @ |
| 3370 | [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] |
| 3371 | Return a derivation @var{name} that runs @var{exp} (a gexp) with |
| 3372 | @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is |
| 3373 | stored in a file called @var{script-name}. When @var{target} is true, |
| 3374 | it is used as the cross-compilation target triplet for packages referred |
| 3375 | to by @var{exp}. |
| 3376 | |
| 3377 | Make @var{modules} available in the evaluation context of @var{exp}; |
| 3378 | @var{modules} is a list of names of Guile modules searched in |
| 3379 | @var{module-path} to be copied in the store, compiled, and made available in |
| 3380 | the load path during the execution of @var{exp}---e.g., @code{((guix |
| 3381 | build utils) (guix build gnu-build-system))}. |
| 3382 | |
| 3383 | @var{graft?} determines whether packages referred to by @var{exp} should be grafted when |
| 3384 | applicable. |
| 3385 | |
| 3386 | When @var{references-graphs} is true, it must be a list of tuples of one of the |
| 3387 | following forms: |
| 3388 | |
| 3389 | @example |
| 3390 | (@var{file-name} @var{package}) |
| 3391 | (@var{file-name} @var{package} @var{output}) |
| 3392 | (@var{file-name} @var{derivation}) |
| 3393 | (@var{file-name} @var{derivation} @var{output}) |
| 3394 | (@var{file-name} @var{store-item}) |
| 3395 | @end example |
| 3396 | |
| 3397 | The right-hand-side of each element of @var{references-graphs} is automatically made |
| 3398 | an input of the build process of @var{exp}. In the build environment, each |
| 3399 | @var{file-name} contains the reference graph of the corresponding item, in a simple |
| 3400 | text format. |
| 3401 | |
| 3402 | @var{allowed-references} must be either @code{#f} or a list of output names and packages. |
| 3403 | In the latter case, the list denotes store items that the result is allowed to |
| 3404 | refer to. Any reference to another store item will lead to a build error. |
| 3405 | |
| 3406 | The other arguments are as for @code{derivation} (@pxref{Derivations}). |
| 3407 | @end deffn |
| 3408 | |
| 3409 | @cindex file-like objects |
| 3410 | The @code{local-file}, @code{plain-file}, @code{computed-file}, |
| 3411 | @code{program-file}, and @code{scheme-file} procedures below return |
| 3412 | @dfn{file-like objects}. That is, when unquoted in a G-expression, |
| 3413 | these objects lead to a file in the store. Consider this G-expression: |
| 3414 | |
| 3415 | @example |
| 3416 | #~(system* (string-append #$glibc "/sbin/nscd") "-f" |
| 3417 | #$(local-file "/tmp/my-nscd.conf")) |
| 3418 | @end example |
| 3419 | |
| 3420 | The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it |
| 3421 | to the store. Once expanded, for instance @i{via} |
| 3422 | @code{gexp->derivation}, the G-expression refers to that copy under |
| 3423 | @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp} |
| 3424 | does not have any effect on what the G-expression does. |
| 3425 | @code{plain-file} can be used similarly; it differs in that the file |
| 3426 | content is directly passed as a string. |
| 3427 | |
| 3428 | @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @ |
| 3429 | [#:recursive? #t] |
| 3430 | Return an object representing local file @var{file} to add to the store; this |
| 3431 | object can be used in a gexp. @var{file} will be added to the store under @var{name}--by |
| 3432 | default the base name of @var{file}. |
| 3433 | |
| 3434 | When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file} |
| 3435 | designates a flat file and @var{recursive?} is true, its contents are added, and its |
| 3436 | permission bits are kept. |
| 3437 | |
| 3438 | This is the declarative counterpart of the @code{interned-file} monadic |
| 3439 | procedure (@pxref{The Store Monad, @code{interned-file}}). |
| 3440 | @end deffn |
| 3441 | |
| 3442 | @deffn {Scheme Procedure} plain-file @var{name} @var{content} |
| 3443 | Return an object representing a text file called @var{name} with the given |
| 3444 | @var{content} (a string) to be added to the store. |
| 3445 | |
| 3446 | This is the declarative counterpart of @code{text-file}. |
| 3447 | @end deffn |
| 3448 | |
| 3449 | @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ |
| 3450 | [#:modules '()] [#:options '(#:local-build? #t)] |
| 3451 | Return an object representing the store item @var{name}, a file or |
| 3452 | directory computed by @var{gexp}. @var{modules} specifies the set of |
| 3453 | modules visible in the execution context of @var{gexp}. @var{options} |
| 3454 | is a list of additional arguments to pass to @code{gexp->derivation}. |
| 3455 | |
| 3456 | This is the declarative counterpart of @code{gexp->derivation}. |
| 3457 | @end deffn |
| 3458 | |
| 3459 | @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} |
| 3460 | Return an executable script @var{name} that runs @var{exp} using |
| 3461 | @var{guile} with @var{modules} in its search path. |
| 3462 | |
| 3463 | The example below builds a script that simply invokes the @command{ls} |
| 3464 | command: |
| 3465 | |
| 3466 | @example |
| 3467 | (use-modules (guix gexp) (gnu packages base)) |
| 3468 | |
| 3469 | (gexp->script "list-files" |
| 3470 | #~(execl (string-append #$coreutils "/bin/ls") |
| 3471 | "ls")) |
| 3472 | @end example |
| 3473 | |
| 3474 | When ``running'' it through the store (@pxref{The Store Monad, |
| 3475 | @code{run-with-store}}), we obtain a derivation that produces an |
| 3476 | executable file @file{/gnu/store/@dots{}-list-files} along these lines: |
| 3477 | |
| 3478 | @example |
| 3479 | #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds |
| 3480 | !# |
| 3481 | (execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls") |
| 3482 | "ls") |
| 3483 | @end example |
| 3484 | @end deffn |
| 3485 | |
| 3486 | @deffn {Scheme Procedure} program-file @var{name} @var{exp} @ |
| 3487 | [#:modules '()] [#:guile #f] |
| 3488 | Return an object representing the executable store item @var{name} that |
| 3489 | runs @var{gexp}. @var{guile} is the Guile package used to execute that |
| 3490 | script, and @var{modules} is the list of modules visible to that script. |
| 3491 | |
| 3492 | This is the declarative counterpart of @code{gexp->script}. |
| 3493 | @end deffn |
| 3494 | |
| 3495 | @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} |
| 3496 | Return a derivation that builds a file @var{name} containing @var{exp}. |
| 3497 | |
| 3498 | The resulting file holds references to all the dependencies of @var{exp} |
| 3499 | or a subset thereof. |
| 3500 | @end deffn |
| 3501 | |
| 3502 | @deffn {Scheme Procedure} scheme-file @var{name} @var{exp} |
| 3503 | Return an object representing the Scheme file @var{name} that contains |
| 3504 | @var{exp}. |
| 3505 | |
| 3506 | This is the declarative counterpart of @code{gexp->file}. |
| 3507 | @end deffn |
| 3508 | |
| 3509 | @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} |
| 3510 | Return as a monadic value a derivation that builds a text file |
| 3511 | containing all of @var{text}. @var{text} may list, in addition to |
| 3512 | strings, objects of any type that can be used in a gexp: packages, |
| 3513 | derivations, local file objects, etc. The resulting store file holds |
| 3514 | references to all these. |
| 3515 | |
| 3516 | This variant should be preferred over @code{text-file} anytime the file |
| 3517 | to create will reference items from the store. This is typically the |
| 3518 | case when building a configuration file that embeds store file names, |
| 3519 | like this: |
| 3520 | |
| 3521 | @example |
| 3522 | (define (profile.sh) |
| 3523 | ;; Return the name of a shell script in the store that |
| 3524 | ;; initializes the 'PATH' environment variable. |
| 3525 | (text-file* "profile.sh" |
| 3526 | "export PATH=" coreutils "/bin:" |
| 3527 | grep "/bin:" sed "/bin\n")) |
| 3528 | @end example |
| 3529 | |
| 3530 | In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file |
| 3531 | will references @var{coreutils}, @var{grep}, and @var{sed}, thereby |
| 3532 | preventing them from being garbage-collected during its lifetime. |
| 3533 | @end deffn |
| 3534 | |
| 3535 | @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{} |
| 3536 | Return an object representing store file @var{name} containing |
| 3537 | @var{text}. @var{text} is a sequence of strings and file-like objects, |
| 3538 | as in: |
| 3539 | |
| 3540 | @example |
| 3541 | (mixed-text-file "profile" |
| 3542 | "export PATH=" coreutils "/bin:" grep "/bin") |
| 3543 | @end example |
| 3544 | |
| 3545 | This is the declarative counterpart of @code{text-file*}. |
| 3546 | @end deffn |
| 3547 | |
| 3548 | Of course, in addition to gexps embedded in ``host'' code, there are |
| 3549 | also modules containing build tools. To make it clear that they are |
| 3550 | meant to be used in the build stratum, these modules are kept in the |
| 3551 | @code{(guix build @dots{})} name space. |
| 3552 | |
| 3553 | @cindex lowering, of high-level objects in gexps |
| 3554 | Internally, high-level objects are @dfn{lowered}, using their compiler, |
| 3555 | to either derivations or store items. For instance, lowering a package |
| 3556 | yields a derivation, and lowering a @code{plain-file} yields a store |
| 3557 | item. This is achieved using the @code{lower-object} monadic procedure. |
| 3558 | |
| 3559 | @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @ |
| 3560 | [#:target #f] |
| 3561 | Return as a value in @var{%store-monad} the derivation or store item |
| 3562 | corresponding to @var{obj} for @var{system}, cross-compiling for |
| 3563 | @var{target} if @var{target} is true. @var{obj} must be an object that |
| 3564 | has an associated gexp compiler, such as a @code{<package>}. |
| 3565 | @end deffn |
| 3566 | |
| 3567 | |
| 3568 | @c ********************************************************************* |
| 3569 | @node Utilities |
| 3570 | @chapter Utilities |
| 3571 | |
| 3572 | This section describes tools primarily targeted at developers and users |
| 3573 | who write new package definitions. They complement the Scheme |
| 3574 | programming interface of Guix in a convenient way. |
| 3575 | |
| 3576 | @menu |
| 3577 | * Invoking guix build:: Building packages from the command line. |
| 3578 | * Invoking guix edit:: Editing package definitions. |
| 3579 | * Invoking guix download:: Downloading a file and printing its hash. |
| 3580 | * Invoking guix hash:: Computing the cryptographic hash of a file. |
| 3581 | * Invoking guix import:: Importing package definitions. |
| 3582 | * Invoking guix refresh:: Updating package definitions. |
| 3583 | * Invoking guix lint:: Finding errors in package definitions. |
| 3584 | * Invoking guix size:: Profiling disk usage. |
| 3585 | * Invoking guix graph:: Visualizing the graph of packages. |
| 3586 | * Invoking guix environment:: Setting up development environments. |
| 3587 | * Invoking guix publish:: Sharing substitutes. |
| 3588 | * Invoking guix challenge:: Challenging substitute servers. |
| 3589 | * Invoking guix container:: Process isolation. |
| 3590 | @end menu |
| 3591 | |
| 3592 | @node Invoking guix build |
| 3593 | @section Invoking @command{guix build} |
| 3594 | |
| 3595 | The @command{guix build} command builds packages or derivations and |
| 3596 | their dependencies, and prints the resulting store paths. Note that it |
| 3597 | does not modify the user's profile---this is the job of the |
| 3598 | @command{guix package} command (@pxref{Invoking guix package}). Thus, |
| 3599 | it is mainly useful for distribution developers. |
| 3600 | |
| 3601 | The general syntax is: |
| 3602 | |
| 3603 | @example |
| 3604 | guix build @var{options} @var{package-or-derivation}@dots{} |
| 3605 | @end example |
| 3606 | |
| 3607 | @var{package-or-derivation} may be either the name of a package found in |
| 3608 | the software distribution such as @code{coreutils} or |
| 3609 | @code{coreutils-8.20}, or a derivation such as |
| 3610 | @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a |
| 3611 | package with the corresponding name (and optionally version) is searched |
| 3612 | for among the GNU distribution modules (@pxref{Package Modules}). |
| 3613 | |
| 3614 | Alternatively, the @code{--expression} option may be used to specify a |
| 3615 | Scheme expression that evaluates to a package; this is useful when |
| 3616 | disambiguation among several same-named packages or package variants is |
| 3617 | needed. |
| 3618 | |
| 3619 | The @var{options} may be zero or more of the following: |
| 3620 | |
| 3621 | @table @code |
| 3622 | |
| 3623 | @item --file=@var{file} |
| 3624 | @itemx -f @var{file} |
| 3625 | |
| 3626 | Build the package or derivation that the code within @var{file} |
| 3627 | evaluates to. |
| 3628 | |
| 3629 | As an example, @var{file} might contain a package definition like this |
| 3630 | (@pxref{Defining Packages}): |
| 3631 | |
| 3632 | @example |
| 3633 | @verbatiminclude package-hello.scm |
| 3634 | @end example |
| 3635 | |
| 3636 | @item --expression=@var{expr} |
| 3637 | @itemx -e @var{expr} |
| 3638 | Build the package or derivation @var{expr} evaluates to. |
| 3639 | |
| 3640 | For example, @var{expr} may be @code{(@@ (gnu packages guile) |
| 3641 | guile-1.8)}, which unambiguously designates this specific variant of |
| 3642 | version 1.8 of Guile. |
| 3643 | |
| 3644 | Alternately, @var{expr} may be a G-expression, in which case it is used |
| 3645 | as a build program passed to @code{gexp->derivation} |
| 3646 | (@pxref{G-Expressions}). |
| 3647 | |
| 3648 | Lastly, @var{expr} may refer to a zero-argument monadic procedure |
| 3649 | (@pxref{The Store Monad}). The procedure must return a derivation as a |
| 3650 | monadic value, which is then passed through @code{run-with-store}. |
| 3651 | |
| 3652 | @item --source |
| 3653 | @itemx -S |
| 3654 | Build the packages' source derivations, rather than the packages |
| 3655 | themselves. |
| 3656 | |
| 3657 | For instance, @code{guix build -S gcc} returns something like |
| 3658 | @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball. |
| 3659 | |
| 3660 | The returned source tarball is the result of applying any patches and |
| 3661 | code snippets specified in the package's @code{origin} (@pxref{Defining |
| 3662 | Packages}). |
| 3663 | |
| 3664 | @item --sources |
| 3665 | Fetch and return the source of @var{package-or-derivation} and all their |
| 3666 | dependencies, recursively. This is a handy way to obtain a local copy |
| 3667 | of all the source code needed to build @var{packages}, allowing you to |
| 3668 | eventually build them even without network access. It is an extension |
| 3669 | of the @code{--source} option and can accept one of the following |
| 3670 | optional argument values: |
| 3671 | |
| 3672 | @table @code |
| 3673 | @item package |
| 3674 | This value causes the @code{--sources} option to behave in the same way |
| 3675 | as the @code{--source} option. |
| 3676 | |
| 3677 | @item all |
| 3678 | Build all packages' source derivations, including any source that might |
| 3679 | be listed as @code{inputs}. This is the default value. |
| 3680 | |
| 3681 | @example |
| 3682 | $ guix build --sources tzdata |
| 3683 | The following derivations will be built: |
| 3684 | /gnu/store/@dots{}-tzdata2015b.tar.gz.drv |
| 3685 | /gnu/store/@dots{}-tzcode2015b.tar.gz.drv |
| 3686 | @end example |
| 3687 | |
| 3688 | @item transitive |
| 3689 | Build all packages' source derivations, as well as all source |
| 3690 | derivations for packages' transitive inputs. This can be used e.g. to |
| 3691 | prefetch package source for later offline building. |
| 3692 | |
| 3693 | @example |
| 3694 | $ guix build --sources=transitive tzdata |
| 3695 | The following derivations will be built: |
| 3696 | /gnu/store/@dots{}-tzcode2015b.tar.gz.drv |
| 3697 | /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv |
| 3698 | /gnu/store/@dots{}-grep-2.21.tar.xz.drv |
| 3699 | /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv |
| 3700 | /gnu/store/@dots{}-make-4.1.tar.xz.drv |
| 3701 | /gnu/store/@dots{}-bash-4.3.tar.xz.drv |
| 3702 | @dots{} |
| 3703 | @end example |
| 3704 | |
| 3705 | @end table |
| 3706 | |
| 3707 | @item --system=@var{system} |
| 3708 | @itemx -s @var{system} |
| 3709 | Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of |
| 3710 | the host's system type. |
| 3711 | |
| 3712 | An example use of this is on Linux-based systems, which can emulate |
| 3713 | different personalities. For instance, passing |
| 3714 | @code{--system=i686-linux} on an @code{x86_64-linux} system allows users |
| 3715 | to build packages in a complete 32-bit environment. |
| 3716 | |
| 3717 | @item --target=@var{triplet} |
| 3718 | @cindex cross-compilation |
| 3719 | Cross-build for @var{triplet}, which must be a valid GNU triplet, such |
| 3720 | as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU |
| 3721 | configuration triplets,, configure, GNU Configure and Build System}). |
| 3722 | |
| 3723 | @item --with-source=@var{source} |
| 3724 | Use @var{source} as the source of the corresponding package. |
| 3725 | @var{source} must be a file name or a URL, as for @command{guix |
| 3726 | download} (@pxref{Invoking guix download}). |
| 3727 | |
| 3728 | The ``corresponding package'' is taken to be one specified on the |
| 3729 | command line whose name matches the base of @var{source}---e.g., if |
| 3730 | @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding |
| 3731 | package is @code{guile}. Likewise, the version string is inferred from |
| 3732 | @var{source}; in the previous example, it's @code{2.0.10}. |
| 3733 | |
| 3734 | This option allows users to try out versions of packages other than the |
| 3735 | one provided by the distribution. The example below downloads |
| 3736 | @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for |
| 3737 | the @code{ed} package: |
| 3738 | |
| 3739 | @example |
| 3740 | guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz |
| 3741 | @end example |
| 3742 | |
| 3743 | As a developer, @code{--with-source} makes it easy to test release |
| 3744 | candidates: |
| 3745 | |
| 3746 | @example |
| 3747 | guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz |
| 3748 | @end example |
| 3749 | |
| 3750 | @dots{} or to build from a checkout in a pristine environment: |
| 3751 | |
| 3752 | @example |
| 3753 | $ git clone git://git.sv.gnu.org/guix.git |
| 3754 | $ guix build guix --with-source=./guix |
| 3755 | @end example |
| 3756 | |
| 3757 | @item --no-grafts |
| 3758 | Do not ``graft'' packages. In practice, this means that package updates |
| 3759 | available as grafts are not applied. @xref{Security Updates}, for more |
| 3760 | information on grafts. |
| 3761 | |
| 3762 | @item --derivations |
| 3763 | @itemx -d |
| 3764 | Return the derivation paths, not the output paths, of the given |
| 3765 | packages. |
| 3766 | |
| 3767 | @item --root=@var{file} |
| 3768 | @itemx -r @var{file} |
| 3769 | Make @var{file} a symlink to the result, and register it as a garbage |
| 3770 | collector root. |
| 3771 | |
| 3772 | @item --log-file |
| 3773 | Return the build log file names or URLs for the given |
| 3774 | @var{package-or-derivation}s, or raise an error if build logs are |
| 3775 | missing. |
| 3776 | |
| 3777 | This works regardless of how packages or derivations are specified. For |
| 3778 | instance, the following invocations are equivalent: |
| 3779 | |
| 3780 | @example |
| 3781 | guix build --log-file `guix build -d guile` |
| 3782 | guix build --log-file `guix build guile` |
| 3783 | guix build --log-file guile |
| 3784 | guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' |
| 3785 | @end example |
| 3786 | |
| 3787 | If a log is unavailable locally, and unless @code{--no-substitutes} is |
| 3788 | passed, the command looks for a corresponding log on one of the |
| 3789 | substitute servers (as specified with @code{--substitute-urls}.) |
| 3790 | |
| 3791 | So for instance, let's say you want to see the build log of GDB on MIPS |
| 3792 | but you're actually on an @code{x86_64} machine: |
| 3793 | |
| 3794 | @example |
| 3795 | $ guix build --log-file gdb -s mips64el-linux |
| 3796 | http://hydra.gnu.org/log/@dots{}-gdb-7.10 |
| 3797 | @end example |
| 3798 | |
| 3799 | You can freely access a huge library of build logs! |
| 3800 | @end table |
| 3801 | |
| 3802 | @cindex common build options |
| 3803 | In addition, a number of options that control the build process are |
| 3804 | common to @command{guix build} and other commands that can spawn builds, |
| 3805 | such as @command{guix package} or @command{guix archive}. These are the |
| 3806 | following: |
| 3807 | |
| 3808 | @table @code |
| 3809 | |
| 3810 | @item --load-path=@var{directory} |
| 3811 | @itemx -L @var{directory} |
| 3812 | Add @var{directory} to the front of the package module search path |
| 3813 | (@pxref{Package Modules}). |
| 3814 | |
| 3815 | This allows users to define their own packages and make them visible to |
| 3816 | the command-line tools. |
| 3817 | |
| 3818 | @item --keep-failed |
| 3819 | @itemx -K |
| 3820 | Keep the build tree of failed builds. Thus, if a build fail, its build |
| 3821 | tree is kept under @file{/tmp}, in a directory whose name is shown at |
| 3822 | the end of the build log. This is useful when debugging build issues. |
| 3823 | |
| 3824 | @item --dry-run |
| 3825 | @itemx -n |
| 3826 | Do not build the derivations. |
| 3827 | |
| 3828 | @item --fallback |
| 3829 | When substituting a pre-built binary fails, fall back to building |
| 3830 | packages locally. |
| 3831 | |
| 3832 | @item --substitute-urls=@var{urls} |
| 3833 | @anchor{client-substitute-urls} |
| 3834 | Consider @var{urls} the whitespace-separated list of substitute source |
| 3835 | URLs, overriding the default list of URLs of @command{guix-daemon} |
| 3836 | (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}). |
| 3837 | |
| 3838 | This means that substitutes may be downloaded from @var{urls}, provided |
| 3839 | they are signed by a key authorized by the system administrator |
| 3840 | (@pxref{Substitutes}). |
| 3841 | |
| 3842 | @item --no-substitutes |
| 3843 | Do not use substitutes for build products. That is, always build things |
| 3844 | locally instead of allowing downloads of pre-built binaries |
| 3845 | (@pxref{Substitutes}). |
| 3846 | |
| 3847 | @item --no-build-hook |
| 3848 | Do not attempt to offload builds @i{via} the daemon's ``build hook'' |
| 3849 | (@pxref{Daemon Offload Setup}). That is, always build things locally |
| 3850 | instead of offloading builds to remote machines. |
| 3851 | |
| 3852 | @item --max-silent-time=@var{seconds} |
| 3853 | When the build or substitution process remains silent for more than |
| 3854 | @var{seconds}, terminate it and report a build failure. |
| 3855 | |
| 3856 | @item --timeout=@var{seconds} |
| 3857 | Likewise, when the build or substitution process lasts for more than |
| 3858 | @var{seconds}, terminate it and report a build failure. |
| 3859 | |
| 3860 | By default there is no timeout. This behavior can be restored with |
| 3861 | @code{--timeout=0}. |
| 3862 | |
| 3863 | @item --verbosity=@var{level} |
| 3864 | Use the given verbosity level. @var{level} must be an integer between 0 |
| 3865 | and 5; higher means more verbose output. Setting a level of 4 or more |
| 3866 | may be helpful when debugging setup issues with the build daemon. |
| 3867 | |
| 3868 | @item --cores=@var{n} |
| 3869 | @itemx -c @var{n} |
| 3870 | Allow the use of up to @var{n} CPU cores for the build. The special |
| 3871 | value @code{0} means to use as many CPU cores as available. |
| 3872 | |
| 3873 | @item --max-jobs=@var{n} |
| 3874 | @itemx -M @var{n} |
| 3875 | Allow at most @var{n} build jobs in parallel. @xref{Invoking |
| 3876 | guix-daemon, @code{--max-jobs}}, for details about this option and the |
| 3877 | equivalent @command{guix-daemon} option. |
| 3878 | |
| 3879 | @end table |
| 3880 | |
| 3881 | Behind the scenes, @command{guix build} is essentially an interface to |
| 3882 | the @code{package-derivation} procedure of the @code{(guix packages)} |
| 3883 | module, and to the @code{build-derivations} procedure of the @code{(guix |
| 3884 | derivations)} module. |
| 3885 | |
| 3886 | In addition to options explicitly passed on the command line, |
| 3887 | @command{guix build} and other @command{guix} commands that support |
| 3888 | building honor the @code{GUIX_BUILD_OPTIONS} environment variable. |
| 3889 | |
| 3890 | @defvr {Environment Variable} GUIX_BUILD_OPTIONS |
| 3891 | Users can define this variable to a list of command line options that |
| 3892 | will automatically be used by @command{guix build} and other |
| 3893 | @command{guix} commands that can perform builds, as in the example |
| 3894 | below: |
| 3895 | |
| 3896 | @example |
| 3897 | $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" |
| 3898 | @end example |
| 3899 | |
| 3900 | These options are parsed independently, and the result is appended to |
| 3901 | the parsed command-line options. |
| 3902 | @end defvr |
| 3903 | |
| 3904 | |
| 3905 | @node Invoking guix edit |
| 3906 | @section Invoking @command{guix edit} |
| 3907 | |
| 3908 | @cindex package definition, editing |
| 3909 | So many packages, so many source files! The @command{guix edit} command |
| 3910 | facilitates the life of packagers by pointing their editor at the source |
| 3911 | file containing the definition of the specified packages. For instance: |
| 3912 | |
| 3913 | @example |
| 3914 | guix edit gcc-4.8 vim |
| 3915 | @end example |
| 3916 | |
| 3917 | @noindent |
| 3918 | launches the program specified in the @code{EDITOR} environment variable |
| 3919 | to edit the recipe of GCC@tie{}4.8.4 and that of Vim. |
| 3920 | |
| 3921 | If you are using Emacs, note that the Emacs user interface provides |
| 3922 | similar functionality in the ``package info'' and ``package list'' |
| 3923 | buffers created by @kbd{M-x guix-search-by-name} and similar commands |
| 3924 | (@pxref{Emacs Commands}). |
| 3925 | |
| 3926 | |
| 3927 | @node Invoking guix download |
| 3928 | @section Invoking @command{guix download} |
| 3929 | |
| 3930 | When writing a package definition, developers typically need to download |
| 3931 | the package's source tarball, compute its SHA256 hash, and write that |
| 3932 | hash in the package definition (@pxref{Defining Packages}). The |
| 3933 | @command{guix download} tool helps with this task: it downloads a file |
| 3934 | from the given URI, adds it to the store, and prints both its file name |
| 3935 | in the store and its SHA256 hash. |
| 3936 | |
| 3937 | The fact that the downloaded file is added to the store saves bandwidth: |
| 3938 | when the developer eventually tries to build the newly defined package |
| 3939 | with @command{guix build}, the source tarball will not have to be |
| 3940 | downloaded again because it is already in the store. It is also a |
| 3941 | convenient way to temporarily stash files, which may be deleted |
| 3942 | eventually (@pxref{Invoking guix gc}). |
| 3943 | |
| 3944 | The @command{guix download} command supports the same URIs as used in |
| 3945 | package definitions. In particular, it supports @code{mirror://} URIs. |
| 3946 | @code{https} URIs (HTTP over TLS) are supported @emph{provided} the |
| 3947 | Guile bindings for GnuTLS are available in the user's environment; when |
| 3948 | they are not available, an error is raised. @xref{Guile Preparations, |
| 3949 | how to install the GnuTLS bindings for Guile,, gnutls-guile, |
| 3950 | GnuTLS-Guile}, for more information. |
| 3951 | |
| 3952 | The following option is available: |
| 3953 | |
| 3954 | @table @code |
| 3955 | @item --format=@var{fmt} |
| 3956 | @itemx -f @var{fmt} |
| 3957 | Write the hash in the format specified by @var{fmt}. For more |
| 3958 | information on the valid values for @var{fmt}, @pxref{Invoking guix hash}. |
| 3959 | @end table |
| 3960 | |
| 3961 | @node Invoking guix hash |
| 3962 | @section Invoking @command{guix hash} |
| 3963 | |
| 3964 | The @command{guix hash} command computes the SHA256 hash of a file. |
| 3965 | It is primarily a convenience tool for anyone contributing to the |
| 3966 | distribution: it computes the cryptographic hash of a file, which can be |
| 3967 | used in the definition of a package (@pxref{Defining Packages}). |
| 3968 | |
| 3969 | The general syntax is: |
| 3970 | |
| 3971 | @example |
| 3972 | guix hash @var{option} @var{file} |
| 3973 | @end example |
| 3974 | |
| 3975 | @command{guix hash} has the following option: |
| 3976 | |
| 3977 | @table @code |
| 3978 | |
| 3979 | @item --format=@var{fmt} |
| 3980 | @itemx -f @var{fmt} |
| 3981 | Write the hash in the format specified by @var{fmt}. |
| 3982 | |
| 3983 | Supported formats: @code{nix-base32}, @code{base32}, @code{base16} |
| 3984 | (@code{hex} and @code{hexadecimal} can be used as well). |
| 3985 | |
| 3986 | If the @option{--format} option is not specified, @command{guix hash} |
| 3987 | will output the hash in @code{nix-base32}. This representation is used |
| 3988 | in the definitions of packages. |
| 3989 | |
| 3990 | @item --recursive |
| 3991 | @itemx -r |
| 3992 | Compute the hash on @var{file} recursively. |
| 3993 | |
| 3994 | In this case, the hash is computed on an archive containing @var{file}, |
| 3995 | including its children if it is a directory. Some of @var{file}'s |
| 3996 | meta-data is part of the archive; for instance, when @var{file} is a |
| 3997 | regular file, the hash is different depending on whether @var{file} is |
| 3998 | executable or not. Meta-data such as time stamps has no impact on the |
| 3999 | hash (@pxref{Invoking guix archive}). |
| 4000 | @c FIXME: Replace xref above with xref to an ``Archive'' section when |
| 4001 | @c it exists. |
| 4002 | |
| 4003 | @end table |
| 4004 | |
| 4005 | @node Invoking guix import |
| 4006 | @section Invoking @command{guix import} |
| 4007 | |
| 4008 | @cindex importing packages |
| 4009 | @cindex package import |
| 4010 | @cindex package conversion |
| 4011 | The @command{guix import} command is useful for people willing to add a |
| 4012 | package to the distribution but who'd rather do as little work as |
| 4013 | possible to get there---a legitimate demand. The command knows of a few |
| 4014 | repositories from which it can ``import'' package meta-data. The result |
| 4015 | is a package definition, or a template thereof, in the format we know |
| 4016 | (@pxref{Defining Packages}). |
| 4017 | |
| 4018 | The general syntax is: |
| 4019 | |
| 4020 | @example |
| 4021 | guix import @var{importer} @var{options}@dots{} |
| 4022 | @end example |
| 4023 | |
| 4024 | @var{importer} specifies the source from which to import package |
| 4025 | meta-data, and @var{options} specifies a package identifier and other |
| 4026 | options specific to @var{importer}. Currently, the available |
| 4027 | ``importers'' are: |
| 4028 | |
| 4029 | @table @code |
| 4030 | @item gnu |
| 4031 | Import meta-data for the given GNU package. This provides a template |
| 4032 | for the latest version of that GNU package, including the hash of its |
| 4033 | source tarball, and its canonical synopsis and description. |
| 4034 | |
| 4035 | Additional information such as the package's dependencies and its |
| 4036 | license needs to be figured out manually. |
| 4037 | |
| 4038 | For example, the following command returns a package definition for |
| 4039 | GNU@tie{}Hello: |
| 4040 | |
| 4041 | @example |
| 4042 | guix import gnu hello |
| 4043 | @end example |
| 4044 | |
| 4045 | Specific command-line options are: |
| 4046 | |
| 4047 | @table @code |
| 4048 | @item --key-download=@var{policy} |
| 4049 | As for @code{guix refresh}, specify the policy to handle missing OpenPGP |
| 4050 | keys when verifying the package's signature. @xref{Invoking guix |
| 4051 | refresh, @code{--key-download}}. |
| 4052 | @end table |
| 4053 | |
| 4054 | @item pypi |
| 4055 | @cindex pypi |
| 4056 | Import meta-data from the @uref{https://pypi.python.org/, Python Package |
| 4057 | Index}@footnote{This functionality requires Guile-JSON to be installed. |
| 4058 | @xref{Requirements}.}. Information is taken from the JSON-formatted |
| 4059 | description available at @code{pypi.python.org} and usually includes all |
| 4060 | the relevant information, including package dependencies. |
| 4061 | |
| 4062 | The command below imports meta-data for the @code{itsdangerous} Python |
| 4063 | package: |
| 4064 | |
| 4065 | @example |
| 4066 | guix import pypi itsdangerous |
| 4067 | @end example |
| 4068 | |
| 4069 | @item gem |
| 4070 | @cindex gem |
| 4071 | Import meta-data from @uref{https://rubygems.org/, |
| 4072 | RubyGems}@footnote{This functionality requires Guile-JSON to be |
| 4073 | installed. @xref{Requirements}.}. Information is taken from the |
| 4074 | JSON-formatted description available at @code{rubygems.org} and includes |
| 4075 | most relevant information, including runtime dependencies. There are |
| 4076 | some caveats, however. The meta-data doesn't distinguish between |
| 4077 | synopses and descriptions, so the same string is used for both fields. |
| 4078 | Additionally, the details of non-Ruby dependencies required to build |
| 4079 | native extensions is unavailable and left as an exercise to the |
| 4080 | packager. |
| 4081 | |
| 4082 | The command below imports meta-data for the @code{rails} Ruby package: |
| 4083 | |
| 4084 | @example |
| 4085 | guix import gem rails |
| 4086 | @end example |
| 4087 | |
| 4088 | @item cpan |
| 4089 | @cindex CPAN |
| 4090 | Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}. |
| 4091 | Information is taken from the JSON-formatted meta-data provided through |
| 4092 | @uref{https://api.metacpan.org/, MetaCPAN's API} and includes most |
| 4093 | relevant information, such as module dependencies. License information |
| 4094 | should be checked closely. If Perl is available in the store, then the |
| 4095 | @code{corelist} utility will be used to filter core modules out of the |
| 4096 | list of dependencies. |
| 4097 | |
| 4098 | The command command below imports meta-data for the @code{Acme::Boolean} |
| 4099 | Perl module: |
| 4100 | |
| 4101 | @example |
| 4102 | guix import cpan Acme::Boolean |
| 4103 | @end example |
| 4104 | |
| 4105 | @item cran |
| 4106 | @cindex CRAN |
| 4107 | Import meta-data from @uref{http://cran.r-project.org/, CRAN}, the |
| 4108 | central repository for the @uref{http://r-project.org, GNU@tie{}R |
| 4109 | statistical and graphical environment}. |
| 4110 | |
| 4111 | Information is extracted from the HTML package description. |
| 4112 | |
| 4113 | The command command below imports meta-data for the @code{Cairo} |
| 4114 | R package: |
| 4115 | |
| 4116 | @example |
| 4117 | guix import cran Cairo |
| 4118 | @end example |
| 4119 | |
| 4120 | @item nix |
| 4121 | Import meta-data from a local copy of the source of the |
| 4122 | @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This |
| 4123 | relies on the @command{nix-instantiate} command of |
| 4124 | @uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are |
| 4125 | typically written in a mixture of Nix-language and Bash code. This |
| 4126 | command only imports the high-level package structure that is written in |
| 4127 | the Nix language. It normally includes all the basic fields of a |
| 4128 | package definition. |
| 4129 | |
| 4130 | When importing a GNU package, the synopsis and descriptions are replaced |
| 4131 | by their canonical upstream variant. |
| 4132 | |
| 4133 | As an example, the command below imports the package definition of |
| 4134 | LibreOffice (more precisely, it imports the definition of the package |
| 4135 | bound to the @code{libreoffice} top-level attribute): |
| 4136 | |
| 4137 | @example |
| 4138 | guix import nix ~/path/to/nixpkgs libreoffice |
| 4139 | @end example |
| 4140 | |
| 4141 | @item hackage |
| 4142 | @cindex hackage |
| 4143 | Import meta-data from Haskell community's central package archive |
| 4144 | @uref{https://hackage.haskell.org/, Hackage}. Information is taken from |
| 4145 | Cabal files and includes all the relevant information, including package |
| 4146 | dependencies. |
| 4147 | |
| 4148 | Specific command-line options are: |
| 4149 | |
| 4150 | @table @code |
| 4151 | @item --stdin |
| 4152 | @itemx -s |
| 4153 | Read a Cabal file from the standard input. |
| 4154 | @item --no-test-dependencies |
| 4155 | @itemx -t |
| 4156 | Do not include dependencies required by the test suites only. |
| 4157 | @item --cabal-environment=@var{alist} |
| 4158 | @itemx -e @var{alist} |
| 4159 | @var{alist} is a Scheme alist defining the environment in which the |
| 4160 | Cabal conditionals are evaluated. The accepted keys are: @code{os}, |
| 4161 | @code{arch}, @code{impl} and a string representing the name of a flag. |
| 4162 | The value associated with a flag has to be either the symbol |
| 4163 | @code{true} or @code{false}. The value associated with other keys |
| 4164 | has to conform to the Cabal file format definition. The default value |
| 4165 | associated with the keys @code{os}, @code{arch} and @code{impl} is |
| 4166 | @samp{linux}, @samp{x86_64} and @samp{ghc} respectively. |
| 4167 | @end table |
| 4168 | |
| 4169 | The command below imports meta-data for the latest version of the |
| 4170 | @code{HTTP} Haskell package without including test dependencies and |
| 4171 | specifying the value of the flag @samp{network-uri} as @code{false}: |
| 4172 | |
| 4173 | @example |
| 4174 | guix import hackage -t -e "'((\"network-uri\" . false))" HTTP |
| 4175 | @end example |
| 4176 | |
| 4177 | A specific package version may optionally be specified by following the |
| 4178 | package name by a hyphen and a version number as in the following example: |
| 4179 | |
| 4180 | @example |
| 4181 | guix import hackage mtl-2.1.3.1 |
| 4182 | @end example |
| 4183 | |
| 4184 | @item elpa |
| 4185 | @cindex elpa |
| 4186 | Import meta-data from an Emacs Lisp Package Archive (ELPA) package |
| 4187 | repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}). |
| 4188 | |
| 4189 | Specific command-line options are: |
| 4190 | |
| 4191 | @table @code |
| 4192 | @item --archive=@var{repo} |
| 4193 | @itemx -a @var{repo} |
| 4194 | @var{repo} identifies the archive repository from which to retrieve the |
| 4195 | information. Currently the supported repositories and their identifiers |
| 4196 | are: |
| 4197 | @itemize - |
| 4198 | @item |
| 4199 | @uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} |
| 4200 | identifier. This is the default. |
| 4201 | |
| 4202 | @item |
| 4203 | @uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the |
| 4204 | @code{melpa-stable} identifier. |
| 4205 | |
| 4206 | @item |
| 4207 | @uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} |
| 4208 | identifier. |
| 4209 | @end itemize |
| 4210 | @end table |
| 4211 | @end table |
| 4212 | |
| 4213 | The structure of the @command{guix import} code is modular. It would be |
| 4214 | useful to have more importers for other package formats, and your help |
| 4215 | is welcome here (@pxref{Contributing}). |
| 4216 | |
| 4217 | @node Invoking guix refresh |
| 4218 | @section Invoking @command{guix refresh} |
| 4219 | |
| 4220 | The primary audience of the @command{guix refresh} command is developers |
| 4221 | of the GNU software distribution. By default, it reports any packages |
| 4222 | provided by the distribution that are outdated compared to the latest |
| 4223 | upstream version, like this: |
| 4224 | |
| 4225 | @example |
| 4226 | $ guix refresh |
| 4227 | gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1 |
| 4228 | gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0 |
| 4229 | @end example |
| 4230 | |
| 4231 | It does so by browsing each package's FTP directory and determining the |
| 4232 | highest version number of the source tarballs therein. The command |
| 4233 | knows how to update specific types of packages: GNU packages, ELPA |
| 4234 | packages, etc.---see the documentation for @option{--type} below. The |
| 4235 | are many packages, though, for which it lacks a method to determine |
| 4236 | whether a new upstream release is available. However, the mechanism is |
| 4237 | extensible, so feel free to get in touch with us to add a new method! |
| 4238 | |
| 4239 | When passed @code{--update}, it modifies distribution source files to |
| 4240 | update the version numbers and source tarball hashes of those packages' |
| 4241 | recipes (@pxref{Defining Packages}). This is achieved by downloading |
| 4242 | each package's latest source tarball and its associated OpenPGP |
| 4243 | signature, authenticating the downloaded tarball against its signature |
| 4244 | using @command{gpg}, and finally computing its hash. When the public |
| 4245 | key used to sign the tarball is missing from the user's keyring, an |
| 4246 | attempt is made to automatically retrieve it from a public key server; |
| 4247 | when it's successful, the key is added to the user's keyring; otherwise, |
| 4248 | @command{guix refresh} reports an error. |
| 4249 | |
| 4250 | The following options are supported: |
| 4251 | |
| 4252 | @table @code |
| 4253 | |
| 4254 | @item --update |
| 4255 | @itemx -u |
| 4256 | Update distribution source files (package recipes) in place. This is |
| 4257 | usually run from a checkout of the Guix source tree (@pxref{Running |
| 4258 | Guix Before It Is Installed}): |
| 4259 | |
| 4260 | @example |
| 4261 | $ ./pre-inst-env guix refresh -s non-core |
| 4262 | @end example |
| 4263 | |
| 4264 | @xref{Defining Packages}, for more information on package definitions. |
| 4265 | |
| 4266 | @item --select=[@var{subset}] |
| 4267 | @itemx -s @var{subset} |
| 4268 | Select all the packages in @var{subset}, one of @code{core} or |
| 4269 | @code{non-core}. |
| 4270 | |
| 4271 | The @code{core} subset refers to all the packages at the core of the |
| 4272 | distribution---i.e., packages that are used to build ``everything |
| 4273 | else''. This includes GCC, libc, Binutils, Bash, etc. Usually, |
| 4274 | changing one of these packages in the distribution entails a rebuild of |
| 4275 | all the others. Thus, such updates are an inconvenience to users in |
| 4276 | terms of build time or bandwidth used to achieve the upgrade. |
| 4277 | |
| 4278 | The @code{non-core} subset refers to the remaining packages. It is |
| 4279 | typically useful in cases where an update of the core packages would be |
| 4280 | inconvenient. |
| 4281 | |
| 4282 | @item --type=@var{updater} |
| 4283 | @itemx -t @var{updater} |
| 4284 | Select only packages handled by @var{updater} (may be a comma-separated |
| 4285 | list of updaters). Currently, @var{updater} may be one of: |
| 4286 | |
| 4287 | @table @code |
| 4288 | @item gnu |
| 4289 | the updater for GNU packages; |
| 4290 | @item elpa |
| 4291 | the updater for @uref{http://elpa.gnu.org/, ELPA} packages; |
| 4292 | @item cran |
| 4293 | the updater fro @uref{http://cran.r-project.org/, CRAN} packages. |
| 4294 | @item pypi |
| 4295 | the updater fro @uref{https://pypi.python.org, PyPI} packages. |
| 4296 | @end table |
| 4297 | |
| 4298 | For instance, the following commands only checks for updates of Emacs |
| 4299 | packages hosted at @code{elpa.gnu.org} and updates of CRAN packages: |
| 4300 | |
| 4301 | @example |
| 4302 | $ guix refresh --type=elpa,cran |
| 4303 | gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0 |
| 4304 | gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9 |
| 4305 | @end example |
| 4306 | |
| 4307 | @end table |
| 4308 | |
| 4309 | In addition, @command{guix refresh} can be passed one or more package |
| 4310 | names, as in this example: |
| 4311 | |
| 4312 | @example |
| 4313 | $ ./pre-inst-env guix refresh -u emacs idutils gcc-4.8.4 |
| 4314 | @end example |
| 4315 | |
| 4316 | @noindent |
| 4317 | The command above specifically updates the @code{emacs} and |
| 4318 | @code{idutils} packages. The @code{--select} option would have no |
| 4319 | effect in this case. |
| 4320 | |
| 4321 | When considering whether to upgrade a package, it is sometimes |
| 4322 | convenient to know which packages would be affected by the upgrade and |
| 4323 | should be checked for compatibility. For this the following option may |
| 4324 | be used when passing @command{guix refresh} one or more package names: |
| 4325 | |
| 4326 | @table @code |
| 4327 | |
| 4328 | @item --list-updaters |
| 4329 | @itemx -L |
| 4330 | List available updaters and exit (see @option{--type} above.) |
| 4331 | |
| 4332 | @item --list-dependent |
| 4333 | @itemx -l |
| 4334 | List top-level dependent packages that would need to be rebuilt as a |
| 4335 | result of upgrading one or more packages. |
| 4336 | |
| 4337 | @end table |
| 4338 | |
| 4339 | Be aware that the @code{--list-dependent} option only |
| 4340 | @emph{approximates} the rebuilds that would be required as a result of |
| 4341 | an upgrade. More rebuilds might be required under some circumstances. |
| 4342 | |
| 4343 | @example |
| 4344 | $ guix refresh --list-dependent flex |
| 4345 | Building the following 120 packages would ensure 213 dependent packages are rebuilt: |
| 4346 | hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{} |
| 4347 | @end example |
| 4348 | |
| 4349 | The command above lists a set of packages that could be built to check |
| 4350 | for compatibility with an upgraded @code{flex} package. |
| 4351 | |
| 4352 | The following options can be used to customize GnuPG operation: |
| 4353 | |
| 4354 | @table @code |
| 4355 | |
| 4356 | @item --gpg=@var{command} |
| 4357 | Use @var{command} as the GnuPG 2.x command. @var{command} is searched |
| 4358 | for in @code{$PATH}. |
| 4359 | |
| 4360 | @item --key-download=@var{policy} |
| 4361 | Handle missing OpenPGP keys according to @var{policy}, which may be one |
| 4362 | of: |
| 4363 | |
| 4364 | @table @code |
| 4365 | @item always |
| 4366 | Always download missing OpenPGP keys from the key server, and add them |
| 4367 | to the user's GnuPG keyring. |
| 4368 | |
| 4369 | @item never |
| 4370 | Never try to download missing OpenPGP keys. Instead just bail out. |
| 4371 | |
| 4372 | @item interactive |
| 4373 | When a package signed with an unknown OpenPGP key is encountered, ask |
| 4374 | the user whether to download it or not. This is the default behavior. |
| 4375 | @end table |
| 4376 | |
| 4377 | @item --key-server=@var{host} |
| 4378 | Use @var{host} as the OpenPGP key server when importing a public key. |
| 4379 | |
| 4380 | @end table |
| 4381 | |
| 4382 | @node Invoking guix lint |
| 4383 | @section Invoking @command{guix lint} |
| 4384 | The @command{guix lint} is meant to help package developers avoid common |
| 4385 | errors and use a consistent style. It runs a number of checks on a |
| 4386 | given set of packages in order to find common mistakes in their |
| 4387 | definitions. Available @dfn{checkers} include (see |
| 4388 | @code{--list-checkers} for a complete list): |
| 4389 | |
| 4390 | @table @code |
| 4391 | @item synopsis |
| 4392 | @itemx description |
| 4393 | Validate certain typographical and stylistic rules about package |
| 4394 | descriptions and synopses. |
| 4395 | |
| 4396 | @item inputs-should-be-native |
| 4397 | Identify inputs that should most likely be native inputs. |
| 4398 | |
| 4399 | @item source |
| 4400 | @itemx home-page |
| 4401 | @itemx source-file-name |
| 4402 | Probe @code{home-page} and @code{source} URLs and report those that are |
| 4403 | invalid. Check that the source file name is meaningful, e.g. is not |
| 4404 | just a version number or ``git-checkout'', and should not have a |
| 4405 | @code{file-name} declared (@pxref{origin Reference}). |
| 4406 | |
| 4407 | @item formatting |
| 4408 | Warn about obvious source code formatting issues: trailing white space, |
| 4409 | use of tabulations, etc. |
| 4410 | @end table |
| 4411 | |
| 4412 | The general syntax is: |
| 4413 | |
| 4414 | @example |
| 4415 | guix lint @var{options} @var{package}@dots{} |
| 4416 | @end example |
| 4417 | |
| 4418 | If no package is given on the command line, then all packages are checked. |
| 4419 | The @var{options} may be zero or more of the following: |
| 4420 | |
| 4421 | @table @code |
| 4422 | |
| 4423 | @item --checkers |
| 4424 | @itemx -c |
| 4425 | Only enable the checkers specified in a comma-separated list using the |
| 4426 | names returned by @code{--list-checkers}. |
| 4427 | |
| 4428 | @item --list-checkers |
| 4429 | @itemx -l |
| 4430 | List and describe all the available checkers that will be run on packages |
| 4431 | and exit. |
| 4432 | |
| 4433 | @end table |
| 4434 | |
| 4435 | @node Invoking guix size |
| 4436 | @section Invoking @command{guix size} |
| 4437 | |
| 4438 | The @command{guix size} command helps package developers profile the |
| 4439 | disk usage of packages. It is easy to overlook the impact of an |
| 4440 | additional dependency added to a package, or the impact of using a |
| 4441 | single output for a package that could easily be split (@pxref{Packages |
| 4442 | with Multiple Outputs}). These are the typical issues that |
| 4443 | @command{guix size} can highlight. |
| 4444 | |
| 4445 | The command can be passed a package specification such as @code{gcc-4.8} |
| 4446 | or @code{guile:debug}, or a file name in the store. Consider this |
| 4447 | example: |
| 4448 | |
| 4449 | @example |
| 4450 | $ guix size coreutils |
| 4451 | store item total self |
| 4452 | /gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8% |
| 4453 | /gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6% |
| 4454 | /gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7% |
| 4455 | /gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5% |
| 4456 | /gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4% |
| 4457 | /gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1% |
| 4458 | @end example |
| 4459 | |
| 4460 | @cindex closure |
| 4461 | The store items listed here constitute the @dfn{transitive closure} of |
| 4462 | Coreutils---i.e., Coreutils and all its dependencies, recursively---as |
| 4463 | would be returned by: |
| 4464 | |
| 4465 | @example |
| 4466 | $ guix gc -R /gnu/store/@dots{}-coreutils-8.23 |
| 4467 | @end example |
| 4468 | |
| 4469 | Here the output shows 3 columns next to store items. The first column, |
| 4470 | labeled ``total'', shows the size in mebibytes (MiB) of the closure of |
| 4471 | the store item---that is, its own size plus the size of all its |
| 4472 | dependencies. The next column, labeled ``self'', shows the size of the |
| 4473 | item itself. The last column shows the ratio of the item's size to the |
| 4474 | space occupied by all the items listed here. |
| 4475 | |
| 4476 | In this example, we see that the closure of Coreutils weighs in at |
| 4477 | 70@tie{}MiB, half of which is taken by libc. (That libc represents a |
| 4478 | large fraction of the closure is not a problem @i{per se} because it is |
| 4479 | always available on the system anyway.) |
| 4480 | |
| 4481 | When the package passed to @command{guix size} is available in the |
| 4482 | store, @command{guix size} queries the daemon to determine its |
| 4483 | dependencies, and measures its size in the store, similar to @command{du |
| 4484 | -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU |
| 4485 | Coreutils}). |
| 4486 | |
| 4487 | When the given package is @emph{not} in the store, @command{guix size} |
| 4488 | reports information based on information about the available substitutes |
| 4489 | (@pxref{Substitutes}). This allows it to profile disk usage of store |
| 4490 | items that are not even on disk, only available remotely. |
| 4491 | |
| 4492 | The available options are: |
| 4493 | |
| 4494 | @table @option |
| 4495 | |
| 4496 | @item --substitute-urls=@var{urls} |
| 4497 | Use substitute information from @var{urls}. |
| 4498 | @xref{client-substitute-urls, the same option for @code{guix build}}. |
| 4499 | |
| 4500 | @item --map-file=@var{file} |
| 4501 | Write to @var{file} a graphical map of disk usage as a PNG file. |
| 4502 | |
| 4503 | For the example above, the map looks like this: |
| 4504 | |
| 4505 | @image{images/coreutils-size-map,5in,, map of Coreutils disk usage |
| 4506 | produced by @command{guix size}} |
| 4507 | |
| 4508 | This option requires that |
| 4509 | @uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be |
| 4510 | installed and visible in Guile's module search path. When that is not |
| 4511 | the case, @command{guix size} fails as it tries to load it. |
| 4512 | |
| 4513 | @item --system=@var{system} |
| 4514 | @itemx -s @var{system} |
| 4515 | Consider packages for @var{system}---e.g., @code{x86_64-linux}. |
| 4516 | |
| 4517 | @end table |
| 4518 | |
| 4519 | @node Invoking guix graph |
| 4520 | @section Invoking @command{guix graph} |
| 4521 | |
| 4522 | @cindex DAG |
| 4523 | Packages and their dependencies form a @dfn{graph}, specifically a |
| 4524 | directed acyclic graph (DAG). It can quickly become difficult to have a |
| 4525 | mental model of the package DAG, so the @command{guix graph} command is |
| 4526 | here to provide a visual representation of the DAG. @command{guix |
| 4527 | graph} emits a DAG representation in the input format of |
| 4528 | @uref{http://www.graphviz.org/, Graphviz}, so its output can be passed |
| 4529 | directly to Graphviz's @command{dot} command, for instance. The general |
| 4530 | syntax is: |
| 4531 | |
| 4532 | @example |
| 4533 | guix graph @var{options} @var{package}@dots{} |
| 4534 | @end example |
| 4535 | |
| 4536 | For example, the following command generates a PDF file representing the |
| 4537 | package DAG for the GNU@tie{}Core Utilities, showing its build-time |
| 4538 | dependencies: |
| 4539 | |
| 4540 | @example |
| 4541 | guix graph coreutils | dot -Tpdf > dag.pdf |
| 4542 | @end example |
| 4543 | |
| 4544 | The output looks like this: |
| 4545 | |
| 4546 | @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils} |
| 4547 | |
| 4548 | Nice little graph, no? |
| 4549 | |
| 4550 | But there's more than one graph! The one above is concise: it's the |
| 4551 | graph of package objects, omitting implicit inputs such as GCC, libc, |
| 4552 | grep, etc. It's often useful to have such a concise graph, but |
| 4553 | sometimes you want to see more details. @command{guix graph} supports |
| 4554 | several types of graphs, allowing you to choose the level of details: |
| 4555 | |
| 4556 | @table @code |
| 4557 | @item package |
| 4558 | This is the default type, the one we used above. It shows the DAG of |
| 4559 | package objects, excluding implicit dependencies. It is concise, but |
| 4560 | filters out many details. |
| 4561 | |
| 4562 | @item bag-emerged |
| 4563 | This is the package DAG, @emph{including} implicit inputs. |
| 4564 | |
| 4565 | For instance, the following command: |
| 4566 | |
| 4567 | @example |
| 4568 | guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf |
| 4569 | @end example |
| 4570 | |
| 4571 | ... yields this bigger graph: |
| 4572 | |
| 4573 | @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils} |
| 4574 | |
| 4575 | At the bottom of the graph, we see all the implicit inputs of |
| 4576 | @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}). |
| 4577 | |
| 4578 | Now, note that the dependencies of those implicit inputs---that is, the |
| 4579 | @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown |
| 4580 | here, for conciseness. |
| 4581 | |
| 4582 | @item bag |
| 4583 | Similar to @code{bag-emerged}, but this time including all the bootstrap |
| 4584 | dependencies. |
| 4585 | |
| 4586 | @item derivations |
| 4587 | This is the most detailed representation: It shows the DAG of |
| 4588 | derivations (@pxref{Derivations}) and plain store items. Compared to |
| 4589 | the above representation, many additional nodes are visible, including |
| 4590 | builds scripts, patches, Guile modules, etc. |
| 4591 | |
| 4592 | @end table |
| 4593 | |
| 4594 | All the above types correspond to @emph{build-time dependencies}. The |
| 4595 | following graph type represents the @emph{run-time dependencies}: |
| 4596 | |
| 4597 | @table @code |
| 4598 | @item references |
| 4599 | This is the graph of @dfn{references} of a package output, as returned |
| 4600 | by @command{guix gc --references} (@pxref{Invoking guix gc}). |
| 4601 | |
| 4602 | If the given package output is not available in the store, @command{guix |
| 4603 | graph} attempts to obtain dependency information from substitutes. |
| 4604 | @end table |
| 4605 | |
| 4606 | The available options are the following: |
| 4607 | |
| 4608 | @table @option |
| 4609 | @item --type=@var{type} |
| 4610 | @itemx -t @var{type} |
| 4611 | Produce a graph output of @var{type}, where @var{type} must be one of |
| 4612 | the values listed above. |
| 4613 | |
| 4614 | @item --list-types |
| 4615 | List the supported graph types. |
| 4616 | |
| 4617 | @item --expression=@var{expr} |
| 4618 | @itemx -e @var{expr} |
| 4619 | Consider the package @var{expr} evaluates to. |
| 4620 | |
| 4621 | This is useful to precisely refer to a package, as in this example: |
| 4622 | |
| 4623 | @example |
| 4624 | guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' |
| 4625 | @end example |
| 4626 | @end table |
| 4627 | |
| 4628 | |
| 4629 | @node Invoking guix environment |
| 4630 | @section Invoking @command{guix environment} |
| 4631 | |
| 4632 | @cindex reproducible build environments |
| 4633 | @cindex development environments |
| 4634 | The purpose of @command{guix environment} is to assist hackers in |
| 4635 | creating reproducible development environments without polluting their |
| 4636 | package profile. The @command{guix environment} tool takes one or more |
| 4637 | packages, builds all of the necessary inputs, and creates a shell |
| 4638 | environment to use them. |
| 4639 | |
| 4640 | The general syntax is: |
| 4641 | |
| 4642 | @example |
| 4643 | guix environment @var{options} @var{package}@dots{} |
| 4644 | @end example |
| 4645 | |
| 4646 | The following example spawns a new shell set up for the development of |
| 4647 | GNU@tie{}Guile: |
| 4648 | |
| 4649 | @example |
| 4650 | guix environment guile |
| 4651 | @end example |
| 4652 | |
| 4653 | If the specified packages are not built yet, @command{guix environment} |
| 4654 | automatically builds them. The new shell's environment is an augmented |
| 4655 | version of the environment that @command{guix environment} was run in. |
| 4656 | It contains the necessary search paths for building the given package |
| 4657 | added to the existing environment variables. To create a ``pure'' |
| 4658 | environment in which the original environment variables have been unset, |
| 4659 | use the @code{--pure} option@footnote{Users sometimes wrongfully augment |
| 4660 | environment variables such as @code{PATH} in their @file{~/.bashrc} |
| 4661 | file. As a consequence, when @code{guix environment} launches it, Bash |
| 4662 | may read @file{~/.bashrc}, thereby introducing ``impurities'' in these |
| 4663 | environment variables. It is an error to define such environment |
| 4664 | variables in @file{.bashrc}; instead, they should be defined in |
| 4665 | @file{.bash_profile}, which is sourced only by log-in shells. |
| 4666 | @xref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}, for |
| 4667 | details on Bash start-up files.}. |
| 4668 | |
| 4669 | @vindex GUIX_ENVIRONMENT |
| 4670 | @command{guix environment} defines the @code{GUIX_ENVIRONMENT} |
| 4671 | variable in the shell it spaws. This allows users to, say, define a |
| 4672 | specific prompt for development environments in their @file{.bashrc} |
| 4673 | (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}): |
| 4674 | |
| 4675 | @example |
| 4676 | if [ -n "$GUIX_ENVIRONMENT" ] |
| 4677 | then |
| 4678 | export PS1="\u@@\h \w [dev]\$ " |
| 4679 | fi |
| 4680 | @end example |
| 4681 | |
| 4682 | Additionally, more than one package may be specified, in which case the |
| 4683 | union of the inputs for the given packages are used. For example, the |
| 4684 | command below spawns a shell where all of the dependencies of both Guile |
| 4685 | and Emacs are available: |
| 4686 | |
| 4687 | @example |
| 4688 | guix environment guile emacs |
| 4689 | @end example |
| 4690 | |
| 4691 | Sometimes an interactive shell session is not desired. An arbitrary |
| 4692 | command may be invoked by placing the @code{--} token to separate the |
| 4693 | command from the rest of the arguments: |
| 4694 | |
| 4695 | @example |
| 4696 | guix environment guile -- make -j4 |
| 4697 | @end example |
| 4698 | |
| 4699 | In other situations, it is more convenient to specify the list of |
| 4700 | packages needed in the environment. For example, the following command |
| 4701 | runs @command{python} from an environment containing Python@tie{}2.7 and |
| 4702 | NumPy: |
| 4703 | |
| 4704 | @example |
| 4705 | guix environment --ad-hoc python2-numpy python-2.7 -- python |
| 4706 | @end example |
| 4707 | |
| 4708 | Furthermore, one might want the dependencies of a package and also some |
| 4709 | additional packages that are not build-time or runtime dependencies, but |
| 4710 | are useful when developing nonetheless. Because of this, the |
| 4711 | @code{--ad-hoc} flag is positional. Packages appearing before |
| 4712 | @code{--ad-hoc} are interpreted as packages whose dependencies will be |
| 4713 | added to the environment. Packages appearing after are interpreted as |
| 4714 | packages that will be added to the environment directly. For example, |
| 4715 | the following command creates a Guix development environment that |
| 4716 | additionally includes Git and strace: |
| 4717 | |
| 4718 | @example |
| 4719 | guix environment guix --ad-hoc git strace |
| 4720 | @end example |
| 4721 | |
| 4722 | Sometimes it is desirable to isolate the environment as much as |
| 4723 | possible, for maximal purity and reproducibility. In particular, when |
| 4724 | using Guix on a host distro that is not GuixSD, it is desirable to |
| 4725 | prevent access to @file{/usr/bin} and other system-wide resources from |
| 4726 | the development environment. For example, the following command spawns |
| 4727 | a Guile REPL in a ``container'' where only the store and the current |
| 4728 | working directory are mounted: |
| 4729 | |
| 4730 | @example |
| 4731 | guix environment --ad-hoc --container guile -- guile |
| 4732 | @end example |
| 4733 | |
| 4734 | @quotation Note |
| 4735 | The @code{--container} option requires Linux-libre 3.19 or newer. |
| 4736 | @end quotation |
| 4737 | |
| 4738 | The available options are summarized below. |
| 4739 | |
| 4740 | @table @code |
| 4741 | @item --expression=@var{expr} |
| 4742 | @itemx -e @var{expr} |
| 4743 | Create an environment for the package or list of packages that |
| 4744 | @var{expr} evaluates to. |
| 4745 | |
| 4746 | For example, running: |
| 4747 | |
| 4748 | @example |
| 4749 | guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' |
| 4750 | @end example |
| 4751 | |
| 4752 | starts a shell with the environment for this specific variant of the |
| 4753 | PETSc package. |
| 4754 | |
| 4755 | Running: |
| 4756 | |
| 4757 | @example |
| 4758 | guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' |
| 4759 | @end example |
| 4760 | |
| 4761 | starts a shell with all the GuixSD base packages available. |
| 4762 | |
| 4763 | @item --load=@var{file} |
| 4764 | @itemx -l @var{file} |
| 4765 | Create an environment for the package or list of packages that the code |
| 4766 | within @var{file} evaluates to. |
| 4767 | |
| 4768 | As an example, @var{file} might contain a definition like this |
| 4769 | (@pxref{Defining Packages}): |
| 4770 | |
| 4771 | @example |
| 4772 | @verbatiminclude environment-gdb.scm |
| 4773 | @end example |
| 4774 | |
| 4775 | @item --ad-hoc |
| 4776 | Include all specified packages in the resulting environment, as if an |
| 4777 | @i{ad hoc} package were defined with them as inputs. This option is |
| 4778 | useful for quickly creating an environment without having to write a |
| 4779 | package expression to contain the desired inputs. |
| 4780 | |
| 4781 | For instance, the command: |
| 4782 | |
| 4783 | @example |
| 4784 | guix environment --ad-hoc guile guile-sdl -- guile |
| 4785 | @end example |
| 4786 | |
| 4787 | runs @command{guile} in an environment where Guile and Guile-SDL are |
| 4788 | available. |
| 4789 | |
| 4790 | Note that this example implicitly asks for the default output of |
| 4791 | @code{guile} and @code{guile-sdl} but it is possible to ask for a |
| 4792 | specific output---e.g., @code{glib:bin} asks for the @code{bin} output |
| 4793 | of @code{glib} (@pxref{Packages with Multiple Outputs}). |
| 4794 | |
| 4795 | This option may be composed with the default behavior of @command{guix |
| 4796 | environment}. Packages appearing before @code{--ad-hoc} are interpreted |
| 4797 | as packages whose dependencies will be added to the environment, the |
| 4798 | default behavior. Packages appearing after are interpreted as packages |
| 4799 | that will be added to the environment directly. |
| 4800 | |
| 4801 | @item --pure |
| 4802 | Unset existing environment variables when building the new environment. |
| 4803 | This has the effect of creating an environment in which search paths |
| 4804 | only contain package inputs. |
| 4805 | |
| 4806 | @item --search-paths |
| 4807 | Display the environment variable definitions that make up the |
| 4808 | environment. |
| 4809 | |
| 4810 | @item --system=@var{system} |
| 4811 | @itemx -s @var{system} |
| 4812 | Attempt to build for @var{system}---e.g., @code{i686-linux}. |
| 4813 | |
| 4814 | @item --container |
| 4815 | @itemx -C |
| 4816 | @cindex container |
| 4817 | Run @var{command} within an isolated container. The current working |
| 4818 | directory outside the container is mapped to @file{/env} inside the |
| 4819 | container. Additionally, the spawned process runs as the current user |
| 4820 | outside the container, but has root privileges in the context of the |
| 4821 | container. |
| 4822 | |
| 4823 | @item --network |
| 4824 | @itemx -N |
| 4825 | For containers, share the network namespace with the host system. |
| 4826 | Containers created without this flag only have access to the loopback |
| 4827 | device. |
| 4828 | |
| 4829 | @item --expose=@var{source}[=@var{target}] |
| 4830 | For containers, expose the file system @var{source} from the host system |
| 4831 | as the read-only file system @var{target} within the container. If |
| 4832 | @var{target} is not specified, @var{source} is used as the target mount |
| 4833 | point in the container. |
| 4834 | |
| 4835 | The example below spawns a Guile REPL in a container in which the user's |
| 4836 | home directory is accessible read-only via the @file{/exchange} |
| 4837 | directory: |
| 4838 | |
| 4839 | @example |
| 4840 | guix environment --container --expose=$HOME=/exchange guile -- guile |
| 4841 | @end example |
| 4842 | |
| 4843 | @item --share=@var{source}[=@var{target}] |
| 4844 | For containers, share the file system @var{source} from the host system |
| 4845 | as the writable file system @var{target} within the container. If |
| 4846 | @var{target} is not specified, @var{source} is used as the target mount |
| 4847 | point in the container. |
| 4848 | |
| 4849 | The example below spawns a Guile REPL in a container in which the user's |
| 4850 | home directory is accessible for both reading and writing via the |
| 4851 | @file{/exchange} directory: |
| 4852 | |
| 4853 | @example |
| 4854 | guix environment --container --share=$HOME=/exchange guile -- guile |
| 4855 | @end example |
| 4856 | @end table |
| 4857 | |
| 4858 | It also supports all of the common build options that @command{guix |
| 4859 | build} supports (@pxref{Invoking guix build, common build options}). |
| 4860 | |
| 4861 | @node Invoking guix publish |
| 4862 | @section Invoking @command{guix publish} |
| 4863 | |
| 4864 | The purpose of @command{guix publish} is to enable users to easily share |
| 4865 | their store with others, which can then use it as a substitute server |
| 4866 | (@pxref{Substitutes}). |
| 4867 | |
| 4868 | When @command{guix publish} runs, it spawns an HTTP server which allows |
| 4869 | anyone with network access to obtain substitutes from it. This means |
| 4870 | that any machine running Guix can also act as if it were a build farm, |
| 4871 | since the HTTP interface is compatible with Hydra, the software behind |
| 4872 | the @code{hydra.gnu.org} build farm. |
| 4873 | |
| 4874 | For security, each substitute is signed, allowing recipients to check |
| 4875 | their authenticity and integrity (@pxref{Substitutes}). Because |
| 4876 | @command{guix publish} uses the system's signing key, which is only |
| 4877 | readable by the system administrator, it must be started as root; the |
| 4878 | @code{--user} option makes it drop root privileges early on. |
| 4879 | |
| 4880 | The signing key pair must be generated before @command{guix publish} is |
| 4881 | launched, using @command{guix archive --generate-key} (@pxref{Invoking |
| 4882 | guix archive}). |
| 4883 | |
| 4884 | The general syntax is: |
| 4885 | |
| 4886 | @example |
| 4887 | guix publish @var{options}@dots{} |
| 4888 | @end example |
| 4889 | |
| 4890 | Running @command{guix publish} without any additional arguments will |
| 4891 | spawn an HTTP server on port 8080: |
| 4892 | |
| 4893 | @example |
| 4894 | guix publish |
| 4895 | @end example |
| 4896 | |
| 4897 | Once a publishing server has been authorized (@pxref{Invoking guix |
| 4898 | archive}), the daemon may download substitutes from it: |
| 4899 | |
| 4900 | @example |
| 4901 | guix-daemon --substitute-urls=http://example.org:8080 |
| 4902 | @end example |
| 4903 | |
| 4904 | The following options are available: |
| 4905 | |
| 4906 | @table @code |
| 4907 | @item --port=@var{port} |
| 4908 | @itemx -p @var{port} |
| 4909 | Listen for HTTP requests on @var{port}. |
| 4910 | |
| 4911 | @item --listen=@var{host} |
| 4912 | Listen on the network interface for @var{host}. The default is to |
| 4913 | accept connections from any interface. |
| 4914 | |
| 4915 | @item --user=@var{user} |
| 4916 | @itemx -u @var{user} |
| 4917 | Change privileges to @var{user} as soon as possible---i.e., once the |
| 4918 | server socket is open and the signing key has been read. |
| 4919 | |
| 4920 | @item --repl[=@var{port}] |
| 4921 | @itemx -r [@var{port}] |
| 4922 | Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile |
| 4923 | Reference Manual}) on @var{port} (37146 by default). This is used |
| 4924 | primarily for debugging a running @command{guix publish} server. |
| 4925 | @end table |
| 4926 | |
| 4927 | Enabling @command{guix publish} on a GuixSD system is a one-liner: just |
| 4928 | add a call to @code{guix-publish-service} in the @code{services} field |
| 4929 | of the @code{operating-system} declaration (@pxref{guix-publish-service, |
| 4930 | @code{guix-publish-service}}). |
| 4931 | |
| 4932 | |
| 4933 | @node Invoking guix challenge |
| 4934 | @section Invoking @command{guix challenge} |
| 4935 | |
| 4936 | @cindex reproducible builds |
| 4937 | @cindex verifiable builds |
| 4938 | |
| 4939 | Do the binaries provided by this server really correspond to the source |
| 4940 | code it claims to build? Is this package's build process deterministic? |
| 4941 | These are the questions the @command{guix challenge} command attempts to |
| 4942 | answer. |
| 4943 | |
| 4944 | The former is obviously an important question: Before using a substitute |
| 4945 | server (@pxref{Substitutes}), you'd rather @emph{verify} that it |
| 4946 | provides the right binaries, and thus @emph{challenge} it. The latter |
| 4947 | is what enables the former: If package builds are deterministic, then |
| 4948 | independent builds of the package should yield the exact same result, |
| 4949 | bit for bit; if a server provides a binary different from the one |
| 4950 | obtained locally, it may be either corrupt or malicious. |
| 4951 | |
| 4952 | We know that the hash that shows up in @file{/gnu/store} file names is |
| 4953 | the hash of all the inputs of the process that built the file or |
| 4954 | directory---compilers, libraries, build scripts, |
| 4955 | etc. (@pxref{Introduction}). Assuming deterministic build processes, |
| 4956 | one store file name should map to exactly one build output. |
| 4957 | @command{guix challenge} checks whether there is, indeed, a single |
| 4958 | mapping by comparing the build outputs of several independent builds of |
| 4959 | any given store item. |
| 4960 | |
| 4961 | The command's output looks like this: |
| 4962 | |
| 4963 | @smallexample |
| 4964 | $ guix challenge --substitute-urls="http://hydra.gnu.org http://guix.example.org" |
| 4965 | updating list of substitutes from 'http://hydra.gnu.org'... 100.0% |
| 4966 | updating list of substitutes from 'http://guix.example.org'... 100.0% |
| 4967 | /gnu/store/@dots{}-openssl-1.0.2d contents differ: |
| 4968 | local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q |
| 4969 | http://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q |
| 4970 | http://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim |
| 4971 | /gnu/store/@dots{}-git-2.5.0 contents differ: |
| 4972 | local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha |
| 4973 | http://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f |
| 4974 | http://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 |
| 4975 | /gnu/store/@dots{}-pius-2.1.1 contents differ: |
| 4976 | local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax |
| 4977 | http://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax |
| 4978 | http://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs |
| 4979 | @end smallexample |
| 4980 | |
| 4981 | @noindent |
| 4982 | In this example, @command{guix challenge} first scans the store to |
| 4983 | determine the set of locally-built derivations---as opposed to store |
| 4984 | items that were downloaded from a substitute server---and then queries |
| 4985 | all the substitute servers. It then reports those store items for which |
| 4986 | the servers obtained a result different from the local build. |
| 4987 | |
| 4988 | @cindex non-determinism, in package builds |
| 4989 | As an example, @code{guix.example.org} always gets a different answer. |
| 4990 | Conversely, @code{hydra.gnu.org} agrees with local builds, except in the |
| 4991 | case of Git. This might indicate that the build process of Git is |
| 4992 | non-deterministic, meaning that its output varies as a function of |
| 4993 | various things that Guix does not fully control, in spite of building |
| 4994 | packages in isolated environments (@pxref{Features}). Most common |
| 4995 | sources of non-determinism include the addition of timestamps in build |
| 4996 | results, the inclusion of random numbers, and directory listings sorted |
| 4997 | by inode number. See @uref{http://reproducible.debian.net/howto/}, for |
| 4998 | more information. |
| 4999 | |
| 5000 | To find out what's wrong with this Git binary, we can do something along |
| 5001 | these lines (@pxref{Invoking guix archive}): |
| 5002 | |
| 5003 | @example |
| 5004 | $ wget -q -O - http://hydra.gnu.org/nar/@dots{}-git-2.5.0 \ |
| 5005 | | guix archive -x /tmp/git |
| 5006 | $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git |
| 5007 | @end example |
| 5008 | |
| 5009 | This command shows the difference between the files resulting from the |
| 5010 | local build, and the files resulting from the build on |
| 5011 | @code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,, |
| 5012 | diffutils, Comparing and Merging Files}). The @command{diff} command |
| 5013 | works great for text files. When binary files differ, a better option |
| 5014 | is @uref{http://diffoscope.org/, Diffoscope}, a tool that helps |
| 5015 | visualize differences for all kinds of files. |
| 5016 | |
| 5017 | Once you've done that work, you can tell whether the differences are due |
| 5018 | to a non-deterministic build process or to a malicious server. We try |
| 5019 | hard to remove sources of non-determinism in packages to make it easier |
| 5020 | to verify substitutes, but of course, this is a process, one that |
| 5021 | involves not just Guix but a large part of the free software community. |
| 5022 | In the meantime, @command{guix challenge} is one tool to help address |
| 5023 | the problem. |
| 5024 | |
| 5025 | If you are writing packages for Guix, you are encouraged to check |
| 5026 | whether @code{hydra.gnu.org} and other substitute servers obtain the |
| 5027 | same build result as you did with: |
| 5028 | |
| 5029 | @example |
| 5030 | $ guix challenge @var{package} |
| 5031 | @end example |
| 5032 | |
| 5033 | @noindent |
| 5034 | ... where @var{package} is a package specification such as |
| 5035 | @code{guile-2.0} or @code{glibc:debug}. |
| 5036 | |
| 5037 | The general syntax is: |
| 5038 | |
| 5039 | @example |
| 5040 | guix challenge @var{options} [@var{packages}@dots{}] |
| 5041 | @end example |
| 5042 | |
| 5043 | The one option that matters is: |
| 5044 | |
| 5045 | @table @code |
| 5046 | |
| 5047 | @item --substitute-urls=@var{urls} |
| 5048 | Consider @var{urls} the whitespace-separated list of substitute source |
| 5049 | URLs to compare to. |
| 5050 | |
| 5051 | @end table |
| 5052 | |
| 5053 | |
| 5054 | @node Invoking guix container |
| 5055 | @section Invoking @command{guix container} |
| 5056 | @cindex container |
| 5057 | |
| 5058 | @quotation Note |
| 5059 | As of version @value{VERSION}, this tool is experimental. The interface |
| 5060 | is subject to radical change in the future. |
| 5061 | @end quotation |
| 5062 | |
| 5063 | The purpose of @command{guix container} is to manipulate processes |
| 5064 | running within an isolated environment, commonly known as a |
| 5065 | ``container'', typically created by the @command{guix environment} |
| 5066 | (@pxref{Invoking guix environment}) and @command{guix system container} |
| 5067 | (@pxref{Invoking guix system}) commands. |
| 5068 | |
| 5069 | The general syntax is: |
| 5070 | |
| 5071 | @example |
| 5072 | guix container @var{action} @var{options}@dots{} |
| 5073 | @end example |
| 5074 | |
| 5075 | @var{action} specifies the operation to perform with a container, and |
| 5076 | @var{options} specifies the context-specific arguments for the action. |
| 5077 | |
| 5078 | The following actions are available: |
| 5079 | |
| 5080 | @table @code |
| 5081 | @item exec |
| 5082 | Execute a command within the context of a running container. |
| 5083 | |
| 5084 | The syntax is: |
| 5085 | |
| 5086 | @example |
| 5087 | guix container exec @var{pid} @var{program} @var{arguments}@dots{} |
| 5088 | @end example |
| 5089 | |
| 5090 | @var{pid} specifies the process ID of the running container. |
| 5091 | @var{program} specifies an executable file name within the container's |
| 5092 | root file system. @var{arguments} are the additional options that will |
| 5093 | be passed to @var{program}. |
| 5094 | |
| 5095 | The following command launches an interactive login shell inside a |
| 5096 | GuixSD container, started by @command{guix system container}, and whose |
| 5097 | process ID is 9001: |
| 5098 | |
| 5099 | @example |
| 5100 | guix container exec 9001 /run/current-system/profile/bin/bash --login |
| 5101 | @end example |
| 5102 | |
| 5103 | Note that the @var{pid} cannot be the parent process of a container. It |
| 5104 | must be the container's PID 1 or one of its child processes. |
| 5105 | |
| 5106 | @end table |
| 5107 | |
| 5108 | @c ********************************************************************* |
| 5109 | @node GNU Distribution |
| 5110 | @chapter GNU Distribution |
| 5111 | |
| 5112 | @cindex Guix System Distribution |
| 5113 | @cindex GuixSD |
| 5114 | Guix comes with a distribution of the GNU system consisting entirely of |
| 5115 | free software@footnote{The term ``free'' here refers to the |
| 5116 | @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to |
| 5117 | users of that software}.}. The |
| 5118 | distribution can be installed on its own (@pxref{System Installation}), |
| 5119 | but it is also possible to install Guix as a package manager on top of |
| 5120 | an installed GNU/Linux system (@pxref{Installation}). To distinguish |
| 5121 | between the two, we refer to the standalone distribution as the Guix |
| 5122 | System Distribution, or GuixSD. |
| 5123 | |
| 5124 | The distribution provides core GNU packages such as GNU libc, GCC, and |
| 5125 | Binutils, as well as many GNU and non-GNU applications. The complete |
| 5126 | list of available packages can be browsed |
| 5127 | @url{http://www.gnu.org/software/guix/packages,on-line} or by |
| 5128 | running @command{guix package} (@pxref{Invoking guix package}): |
| 5129 | |
| 5130 | @example |
| 5131 | guix package --list-available |
| 5132 | @end example |
| 5133 | |
| 5134 | Our goal has been to provide a practical 100% free software distribution of |
| 5135 | Linux-based and other variants of GNU, with a focus on the promotion and |
| 5136 | tight integration of GNU components, and an emphasis on programs and |
| 5137 | tools that help users exert that freedom. |
| 5138 | |
| 5139 | Packages are currently available on the following platforms: |
| 5140 | |
| 5141 | @table @code |
| 5142 | |
| 5143 | @item x86_64-linux |
| 5144 | Intel/AMD @code{x86_64} architecture, Linux-Libre kernel; |
| 5145 | |
| 5146 | @item i686-linux |
| 5147 | Intel 32-bit architecture (IA32), Linux-Libre kernel; |
| 5148 | |
| 5149 | @item armhf-linux |
| 5150 | ARMv7-A architecture with hard float, Thumb-2 and NEON, |
| 5151 | using the EABI hard-float ABI, and Linux-Libre kernel. |
| 5152 | |
| 5153 | @item mips64el-linux |
| 5154 | little-endian 64-bit MIPS processors, specifically the Loongson series, |
| 5155 | n32 application binary interface (ABI), and Linux-Libre kernel. |
| 5156 | |
| 5157 | @end table |
| 5158 | |
| 5159 | GuixSD itself is currently only available on @code{i686} and @code{x86_64}. |
| 5160 | |
| 5161 | @noindent |
| 5162 | For information on porting to other architectures or kernels, |
| 5163 | @xref{Porting}. |
| 5164 | |
| 5165 | @menu |
| 5166 | * System Installation:: Installing the whole operating system. |
| 5167 | * System Configuration:: Configuring the operating system. |
| 5168 | * Installing Debugging Files:: Feeding the debugger. |
| 5169 | * Security Updates:: Deploying security fixes quickly. |
| 5170 | * Package Modules:: Packages from the programmer's viewpoint. |
| 5171 | * Packaging Guidelines:: Growing the distribution. |
| 5172 | * Bootstrapping:: GNU/Linux built from scratch. |
| 5173 | * Porting:: Targeting another platform or kernel. |
| 5174 | @end menu |
| 5175 | |
| 5176 | Building this distribution is a cooperative effort, and you are invited |
| 5177 | to join! @xref{Contributing}, for information about how you can help. |
| 5178 | |
| 5179 | @node System Installation |
| 5180 | @section System Installation |
| 5181 | |
| 5182 | @cindex Guix System Distribution |
| 5183 | This section explains how to install the Guix System Distribution |
| 5184 | on a machine. The Guix package manager can |
| 5185 | also be installed on top of a running GNU/Linux system, |
| 5186 | @pxref{Installation}. |
| 5187 | |
| 5188 | @ifinfo |
| 5189 | @c This paragraph is for people reading this from tty2 of the |
| 5190 | @c installation image. |
| 5191 | You're reading this documentation with an Info reader. For details on |
| 5192 | how to use it, hit the @key{RET} key (``return'' or ``enter'') on the |
| 5193 | link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit |
| 5194 | @kbd{l} afterwards to come back here. |
| 5195 | @end ifinfo |
| 5196 | |
| 5197 | @subsection Limitations |
| 5198 | |
| 5199 | As of version @value{VERSION}, the Guix System Distribution (GuixSD) is |
| 5200 | not production-ready. It may contain bugs and lack important |
| 5201 | features. Thus, if you are looking for a stable production system that |
| 5202 | respects your freedom as a computer user, a good solution at this point |
| 5203 | is to consider @url{http://www.gnu.org/distros/free-distros.html, one of |
| 5204 | more established GNU/Linux distributions}. We hope you can soon switch |
| 5205 | to the GuixSD without fear, of course. In the meantime, you can |
| 5206 | also keep using your distribution and try out the package manager on top |
| 5207 | of it (@pxref{Installation}). |
| 5208 | |
| 5209 | Before you proceed with the installation, be aware of the following |
| 5210 | noteworthy limitations applicable to version @value{VERSION}: |
| 5211 | |
| 5212 | @itemize |
| 5213 | @item |
| 5214 | The installation process does not include a graphical user interface and |
| 5215 | requires familiarity with GNU/Linux (see the following subsections to |
| 5216 | get a feel of what that means.) |
| 5217 | |
| 5218 | @item |
| 5219 | The system does not yet provide full GNOME and KDE desktops. Xfce and |
| 5220 | Enlightenment are available though, if graphical desktop environments |
| 5221 | are your thing, as well as a number of X11 window managers. |
| 5222 | |
| 5223 | @item |
| 5224 | Support for the Logical Volume Manager (LVM) is missing. |
| 5225 | |
| 5226 | @item |
| 5227 | Few system services are currently supported out-of-the-box |
| 5228 | (@pxref{Services}). |
| 5229 | |
| 5230 | @item |
| 5231 | More than 2,000 packages are available, but you may |
| 5232 | occasionally find that a useful package is missing. |
| 5233 | @end itemize |
| 5234 | |
| 5235 | You've been warned. But more than a disclaimer, this is an invitation |
| 5236 | to report issues (and success stories!), and join us in improving it. |
| 5237 | @xref{Contributing}, for more info. |
| 5238 | |
| 5239 | @subsection USB Stick Installation |
| 5240 | |
| 5241 | An installation image for USB sticks can be downloaded from |
| 5242 | @indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz}, |
| 5243 | where @var{system} is one of: |
| 5244 | |
| 5245 | @table @code |
| 5246 | @item x86_64-linux |
| 5247 | for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs; |
| 5248 | |
| 5249 | @item i686-linux |
| 5250 | for a 32-bit GNU/Linux system on Intel-compatible CPUs. |
| 5251 | @end table |
| 5252 | |
| 5253 | This image contains a single partition with the tools necessary for an |
| 5254 | installation. It is meant to be copied @emph{as is} to a large-enough |
| 5255 | USB stick. |
| 5256 | |
| 5257 | To copy the image to a USB stick, follow these steps: |
| 5258 | |
| 5259 | @enumerate |
| 5260 | @item |
| 5261 | Decompress the image using the @command{xz} command: |
| 5262 | |
| 5263 | @example |
| 5264 | xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz |
| 5265 | @end example |
| 5266 | |
| 5267 | @item |
| 5268 | Insert a USB stick of 1@tie{}GiB or more in your machine, and determine |
| 5269 | its device name. Assuming that USB stick is known as @file{/dev/sdX}, |
| 5270 | copy the image with: |
| 5271 | |
| 5272 | @example |
| 5273 | dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX |
| 5274 | @end example |
| 5275 | |
| 5276 | Access to @file{/dev/sdX} usually requires root privileges. |
| 5277 | @end enumerate |
| 5278 | |
| 5279 | Once this is done, you should be able to reboot the system and boot from |
| 5280 | the USB stick. The latter usually requires you to get in the BIOS' boot |
| 5281 | menu, where you can choose to boot from the USB stick. |
| 5282 | |
| 5283 | @subsection Preparing for Installation |
| 5284 | |
| 5285 | Once you have successfully booted the image on the USB stick, you should |
| 5286 | end up with a root prompt. Several console TTYs are configured and can |
| 5287 | be used to run commands as root. TTY2 shows this documentation, |
| 5288 | browsable using the Info reader commands (@pxref{Help,,, info, Info: An |
| 5289 | Introduction}). |
| 5290 | |
| 5291 | To install the system, you would: |
| 5292 | |
| 5293 | @enumerate |
| 5294 | |
| 5295 | @item |
| 5296 | Configure the network, by running @command{ifconfig eno1 up && dhclient |
| 5297 | eno1} (to get an automatically assigned IP address from the wired |
| 5298 | network interface controller@footnote{ |
| 5299 | @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 |
| 5300 | The name @code{eno1} is for the first on-board Ethernet controller. The |
| 5301 | interface name for an Ethernet controller that is in the first slot of |
| 5302 | the first PCI bus, for instance, would be @code{enp1s0}. Use |
| 5303 | @command{ifconfig -a} to list all the available network interfaces.}), |
| 5304 | or using the @command{ifconfig} command. |
| 5305 | |
| 5306 | The system automatically loads drivers for your network interface |
| 5307 | controllers. |
| 5308 | |
| 5309 | Setting up network access is almost always a requirement because the |
| 5310 | image does not contain all the software and tools that may be needed. |
| 5311 | |
| 5312 | @item |
| 5313 | Unless this has already been done, you must partition, optionally |
| 5314 | encrypt, and then format the target partitions. |
| 5315 | |
| 5316 | Preferably, assign partitions a label so that you can easily and |
| 5317 | reliably refer to them in @code{file-system} declarations (@pxref{File |
| 5318 | Systems}). This is typically done using the @code{-L} option of |
| 5319 | @command{mkfs.ext4} and related commands. |
| 5320 | |
| 5321 | A typical command sequence may be: |
| 5322 | |
| 5323 | @example |
| 5324 | # fdisk /dev/sdX |
| 5325 | @dots{} Create partitions etc.@dots{} |
| 5326 | # cryptsetup luksFormat /dev/sdX1 |
| 5327 | # cryptsetup open --type luks /dev/sdX1 my-partition |
| 5328 | # mkfs.ext4 -L my-root /dev/mapper/my-partition |
| 5329 | @end example |
| 5330 | |
| 5331 | The installation image includes Parted (@pxref{Overview,,, parted, GNU |
| 5332 | Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk |
| 5333 | encryption, and e2fsprogs, the suite of tools to manipulate |
| 5334 | ext2/ext3/ext4 file systems. |
| 5335 | |
| 5336 | @item |
| 5337 | Once that is done, mount the target root partition under @file{/mnt}. |
| 5338 | |
| 5339 | @item |
| 5340 | Lastly, run @code{deco start cow-store /mnt}. |
| 5341 | |
| 5342 | This will make @file{/gnu/store} copy-on-write, such that packages added |
| 5343 | to it during the installation phase will be written to the target disk |
| 5344 | rather than kept in memory. |
| 5345 | |
| 5346 | @end enumerate |
| 5347 | |
| 5348 | |
| 5349 | @subsection Proceeding with the Installation |
| 5350 | |
| 5351 | With the target partitions ready, you now have to edit a file and |
| 5352 | provide the declaration of the operating system to be installed. To |
| 5353 | that end, the installation system comes with two text editors: GNU nano |
| 5354 | (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone. |
| 5355 | It is better to store that file on the target root file system, say, as |
| 5356 | @file{/mnt/etc/config.scm}. |
| 5357 | |
| 5358 | @xref{Using the Configuration System}, for examples of operating system |
| 5359 | configurations. These examples are available under |
| 5360 | @file{/etc/configuration} in the installation image, so you can copy |
| 5361 | them and use them as a starting point for your own configuration. |
| 5362 | |
| 5363 | Once you are done preparing the configuration file, the new system must |
| 5364 | be initialized (remember that the target root file system is mounted |
| 5365 | under @file{/mnt}): |
| 5366 | |
| 5367 | @example |
| 5368 | guix system init /mnt/etc/config.scm /mnt |
| 5369 | @end example |
| 5370 | |
| 5371 | @noindent |
| 5372 | This will copy all the necessary files, and install GRUB on |
| 5373 | @file{/dev/sdX}, unless you pass the @option{--no-grub} option. For |
| 5374 | more information, @pxref{Invoking guix system}. This command may trigger |
| 5375 | downloads or builds of missing packages, which can take some time. |
| 5376 | |
| 5377 | Once that command has completed---and hopefully succeeded!---you can run |
| 5378 | @command{reboot} and boot into the new system. The @code{root} password |
| 5379 | in the new system is initially empty; other users' passwords need to be |
| 5380 | initialized by running the @command{passwd} command as @code{root}, |
| 5381 | unless your configuration specifies otherwise |
| 5382 | (@pxref{user-account-password, user account passwords}). |
| 5383 | |
| 5384 | Join us on @code{#guix} on the Freenode IRC network or on |
| 5385 | @file{guix-devel@@gnu.org} to share your experience---good or not so |
| 5386 | good. |
| 5387 | |
| 5388 | @subsection Building the Installation Image |
| 5389 | |
| 5390 | The installation image described above was built using the @command{guix |
| 5391 | system} command, specifically: |
| 5392 | |
| 5393 | @example |
| 5394 | guix system disk-image --image-size=850MiB gnu/system/install.scm |
| 5395 | @end example |
| 5396 | |
| 5397 | @xref{Invoking guix system}, for more information. See |
| 5398 | @file{gnu/system/install.scm} in the source tree for more information |
| 5399 | about the installation image. |
| 5400 | |
| 5401 | @node System Configuration |
| 5402 | @section System Configuration |
| 5403 | |
| 5404 | @cindex system configuration |
| 5405 | The Guix System Distribution supports a consistent whole-system configuration |
| 5406 | mechanism. By that we mean that all aspects of the global system |
| 5407 | configuration---such as the available system services, timezone and |
| 5408 | locale settings, user accounts---are declared in a single place. Such |
| 5409 | a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected. |
| 5410 | |
| 5411 | One of the advantages of putting all the system configuration under the |
| 5412 | control of Guix is that it supports transactional system upgrades, and |
| 5413 | makes it possible to roll-back to a previous system instantiation, |
| 5414 | should something go wrong with the new one (@pxref{Features}). Another |
| 5415 | one is that it makes it easy to replicate the exact same configuration |
| 5416 | across different machines, or at different points in time, without |
| 5417 | having to resort to additional administration tools layered on top of |
| 5418 | the system's own tools. |
| 5419 | @c Yes, we're talking of Puppet, Chef, & co. here. ↑ |
| 5420 | |
| 5421 | This section describes this mechanism. First we focus on the system |
| 5422 | administrator's viewpoint---explaining how the system is configured and |
| 5423 | instantiated. Then we show how this mechanism can be extended, for |
| 5424 | instance to support new system services. |
| 5425 | |
| 5426 | @menu |
| 5427 | * Using the Configuration System:: Customizing your GNU system. |
| 5428 | * operating-system Reference:: Detail of operating-system declarations. |
| 5429 | * File Systems:: Configuring file system mounts. |
| 5430 | * Mapped Devices:: Block device extra processing. |
| 5431 | * User Accounts:: Specifying user accounts. |
| 5432 | * Locales:: Language and cultural convention settings. |
| 5433 | * Services:: Specifying system services. |
| 5434 | * Setuid Programs:: Programs running with root privileges. |
| 5435 | * X.509 Certificates:: Authenticating HTTPS servers. |
| 5436 | * Name Service Switch:: Configuring libc's name service switch. |
| 5437 | * Initial RAM Disk:: Linux-Libre bootstrapping. |
| 5438 | * GRUB Configuration:: Configuring the boot loader. |
| 5439 | * Invoking guix system:: Instantiating a system configuration. |
| 5440 | * Defining Services:: Adding new service definitions. |
| 5441 | @end menu |
| 5442 | |
| 5443 | @node Using the Configuration System |
| 5444 | @subsection Using the Configuration System |
| 5445 | |
| 5446 | The operating system is configured by providing an |
| 5447 | @code{operating-system} declaration in a file that can then be passed to |
| 5448 | the @command{guix system} command (@pxref{Invoking guix system}). A |
| 5449 | simple setup, with the default system services, the default Linux-Libre |
| 5450 | kernel, initial RAM disk, and boot loader looks like this: |
| 5451 | |
| 5452 | @findex operating-system |
| 5453 | @lisp |
| 5454 | @include os-config-bare-bones.texi |
| 5455 | @end lisp |
| 5456 | |
| 5457 | This example should be self-describing. Some of the fields defined |
| 5458 | above, such as @code{host-name} and @code{bootloader}, are mandatory. |
| 5459 | Others, such as @code{packages} and @code{services}, can be omitted, in |
| 5460 | which case they get a default value. |
| 5461 | |
| 5462 | @vindex %base-packages |
| 5463 | The @code{packages} field lists |
| 5464 | packages that will be globally visible on the system, for all user |
| 5465 | accounts---i.e., in every user's @code{PATH} environment variable---in |
| 5466 | addition to the per-user profiles (@pxref{Invoking guix package}). The |
| 5467 | @var{%base-packages} variable provides all the tools one would expect |
| 5468 | for basic user and administrator tasks---including the GNU Core |
| 5469 | Utilities, the GNU Networking Utilities, the GNU Zile lightweight text |
| 5470 | editor, @command{find}, @command{grep}, etc. The example above adds |
| 5471 | tcpdump to those, taken from the @code{(gnu packages admin)} module |
| 5472 | (@pxref{Package Modules}). |
| 5473 | |
| 5474 | @vindex %base-services |
| 5475 | The @code{services} field lists @dfn{system services} to be made |
| 5476 | available when the system starts (@pxref{Services}). |
| 5477 | The @code{operating-system} declaration above specifies that, in |
| 5478 | addition to the basic services, we want the @command{lshd} secure shell |
| 5479 | daemon listening on port 2222 (@pxref{Networking Services, |
| 5480 | @code{lsh-service}}). Under the hood, |
| 5481 | @code{lsh-service} arranges so that @code{lshd} is started with the |
| 5482 | right command-line options, possibly with supporting configuration files |
| 5483 | generated as needed (@pxref{Defining Services}). |
| 5484 | |
| 5485 | @cindex customization, of services |
| 5486 | @findex modify-services |
| 5487 | Occasionally, instead of using the base services as is, you will want to |
| 5488 | customize them. For instance, to change the configuration of |
| 5489 | @code{guix-daemon} and Mingetty (the console log-in), you may write the |
| 5490 | following instead of @var{%base-services}: |
| 5491 | |
| 5492 | @lisp |
| 5493 | (modify-services %base-services |
| 5494 | (guix-service-type config => |
| 5495 | (guix-configuration |
| 5496 | (inherit config) |
| 5497 | (use-substitutes? #f) |
| 5498 | (extra-options '("--gc-keep-outputs")))) |
| 5499 | (mingetty-service-type config => |
| 5500 | (mingetty-configuration |
| 5501 | (inherit config) |
| 5502 | (motd (plain-file "motd" "Hi there!"))))) |
| 5503 | @end lisp |
| 5504 | |
| 5505 | @noindent |
| 5506 | The effect here is to change the options passed to @command{guix-daemon} |
| 5507 | when it is started, as well as the ``message of the day'' that appears |
| 5508 | when logging in at the console. @xref{Service Reference, |
| 5509 | @code{modify-services}}, for more on that. |
| 5510 | |
| 5511 | The configuration for a typical ``desktop'' usage, with the X11 display |
| 5512 | server, a desktop environment, network management, power management, and |
| 5513 | more, would look like this: |
| 5514 | |
| 5515 | @lisp |
| 5516 | @include os-config-desktop.texi |
| 5517 | @end lisp |
| 5518 | |
| 5519 | @xref{Desktop Services}, for the exact list of services provided by |
| 5520 | @var{%desktop-services}. @xref{X.509 Certificates}, for background |
| 5521 | information about the @code{nss-certs} package that is used here. |
| 5522 | @xref{operating-system Reference}, for details about all the available |
| 5523 | @code{operating-system} fields. |
| 5524 | |
| 5525 | Assuming the above snippet is stored in the @file{my-system-config.scm} |
| 5526 | file, the @command{guix system reconfigure my-system-config.scm} command |
| 5527 | instantiates that configuration, and makes it the default GRUB boot |
| 5528 | entry (@pxref{Invoking guix system}). |
| 5529 | |
| 5530 | The normal way to change the system's configuration is by updating this |
| 5531 | file and re-running @command{guix system reconfigure}. One should never |
| 5532 | have to touch files in @command{/etc} or to run commands that modify the |
| 5533 | system state such as @command{useradd} or @command{grub-install}. In |
| 5534 | fact, you must avoid that since that would not only void your warranty |
| 5535 | but also prevent you from rolling back to previous versions of your |
| 5536 | system, should you ever need to. |
| 5537 | |
| 5538 | @cindex roll-back, of the operating system |
| 5539 | Speaking of roll-back, each time you run @command{guix system |
| 5540 | reconfigure}, a new @dfn{generation} of the system is created---without |
| 5541 | modifying or deleting previous generations. Old system generations get |
| 5542 | an entry in the GRUB boot menu, allowing you to boot them in case |
| 5543 | something went wrong with the latest generation. Reassuring, no? The |
| 5544 | @command{guix system list-generations} command lists the system |
| 5545 | generations available on disk. |
| 5546 | |
| 5547 | At the Scheme level, the bulk of an @code{operating-system} declaration |
| 5548 | is instantiated with the following monadic procedure (@pxref{The Store |
| 5549 | Monad}): |
| 5550 | |
| 5551 | @deffn {Monadic Procedure} operating-system-derivation os |
| 5552 | Return a derivation that builds @var{os}, an @code{operating-system} |
| 5553 | object (@pxref{Derivations}). |
| 5554 | |
| 5555 | The output of the derivation is a single directory that refers to all |
| 5556 | the packages, configuration files, and other supporting files needed to |
| 5557 | instantiate @var{os}. |
| 5558 | @end deffn |
| 5559 | |
| 5560 | @node operating-system Reference |
| 5561 | @subsection @code{operating-system} Reference |
| 5562 | |
| 5563 | This section summarizes all the options available in |
| 5564 | @code{operating-system} declarations (@pxref{Using the Configuration |
| 5565 | System}). |
| 5566 | |
| 5567 | @deftp {Data Type} operating-system |
| 5568 | This is the data type representing an operating system configuration. |
| 5569 | By that, we mean all the global system configuration, not per-user |
| 5570 | configuration (@pxref{Using the Configuration System}). |
| 5571 | |
| 5572 | @table @asis |
| 5573 | @item @code{kernel} (default: @var{linux-libre}) |
| 5574 | The package object of the operating system kernel to use@footnote{Currently |
| 5575 | only the Linux-libre kernel is supported. In the future, it will be |
| 5576 | possible to use the GNU@tie{}Hurd.}. |
| 5577 | |
| 5578 | @item @code{kernel-arguments} (default: @code{'()}) |
| 5579 | List of strings or gexps representing additional arguments to pass on |
| 5580 | the kernel's command-line---e.g., @code{("console=ttyS0")}. |
| 5581 | |
| 5582 | @item @code{bootloader} |
| 5583 | The system bootloader configuration object. @xref{GRUB Configuration}. |
| 5584 | |
| 5585 | @item @code{initrd} (default: @code{base-initrd}) |
| 5586 | A two-argument monadic procedure that returns an initial RAM disk for |
| 5587 | the Linux kernel. @xref{Initial RAM Disk}. |
| 5588 | |
| 5589 | @item @code{firmware} (default: @var{%base-firmware}) |
| 5590 | @cindex firmware |
| 5591 | List of firmware packages loadable by the operating system kernel. |
| 5592 | |
| 5593 | The default includes firmware needed for Atheros-based WiFi devices |
| 5594 | (Linux-libre module @code{ath9k}.) |
| 5595 | |
| 5596 | @item @code{host-name} |
| 5597 | The host name. |
| 5598 | |
| 5599 | @item @code{hosts-file} |
| 5600 | @cindex hosts file |
| 5601 | A file-like object (@pxref{G-Expressions, file-like objects}) for use as |
| 5602 | @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library |
| 5603 | Reference Manual}). The default is a file with entries for |
| 5604 | @code{localhost} and @var{host-name}. |
| 5605 | |
| 5606 | @item @code{mapped-devices} (default: @code{'()}) |
| 5607 | A list of mapped devices. @xref{Mapped Devices}. |
| 5608 | |
| 5609 | @item @code{file-systems} |
| 5610 | A list of file systems. @xref{File Systems}. |
| 5611 | |
| 5612 | @item @code{swap-devices} (default: @code{'()}) |
| 5613 | @cindex swap devices |
| 5614 | A list of strings identifying devices to be used for ``swap space'' |
| 5615 | (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). |
| 5616 | For example, @code{'("/dev/sda3")}. |
| 5617 | |
| 5618 | @item @code{users} (default: @code{%base-user-accounts}) |
| 5619 | @itemx @code{groups} (default: @var{%base-groups}) |
| 5620 | List of user accounts and groups. @xref{User Accounts}. |
| 5621 | |
| 5622 | @item @code{skeletons} (default: @code{(default-skeletons)}) |
| 5623 | A monadic list of pairs of target file name and files. These are the |
| 5624 | files that will be used as skeletons as new accounts are created. |
| 5625 | |
| 5626 | For instance, a valid value may look like this: |
| 5627 | |
| 5628 | @example |
| 5629 | (mlet %store-monad ((bashrc (text-file "bashrc" "\ |
| 5630 | export PATH=$HOME/.guix-profile/bin"))) |
| 5631 | (return `((".bashrc" ,bashrc)))) |
| 5632 | @end example |
| 5633 | |
| 5634 | @item @code{issue} (default: @var{%default-issue}) |
| 5635 | A string denoting the contents of the @file{/etc/issue} file, which is |
| 5636 | what displayed when users log in on a text console. |
| 5637 | |
| 5638 | @item @code{packages} (default: @var{%base-packages}) |
| 5639 | The set of packages installed in the global profile, which is accessible |
| 5640 | at @file{/run/current-system/profile}. |
| 5641 | |
| 5642 | The default set includes core utilities, but it is good practice to |
| 5643 | install non-core utilities in user profiles (@pxref{Invoking guix |
| 5644 | package}). |
| 5645 | |
| 5646 | @item @code{timezone} |
| 5647 | A timezone identifying string---e.g., @code{"Europe/Paris"}. |
| 5648 | |
| 5649 | @item @code{locale} (default: @code{"en_US.utf8"}) |
| 5650 | The name of the default locale (@pxref{Locale Names,,, libc, The GNU C |
| 5651 | Library Reference Manual}). @xref{Locales}, for more information. |
| 5652 | |
| 5653 | @item @code{locale-definitions} (default: @var{%default-locale-definitions}) |
| 5654 | The list of locale definitions to be compiled and that may be used at |
| 5655 | run time. @xref{Locales}. |
| 5656 | |
| 5657 | @item @code{locale-libcs} (default: @code{(list @var{glibc})}) |
| 5658 | The list of GNU@tie{}libc packages whose locale data and tools are used |
| 5659 | to build the locale definitions. @xref{Locales}, for compatibility |
| 5660 | considerations that justify this option. |
| 5661 | |
| 5662 | @item @code{name-service-switch} (default: @var{%default-nss}) |
| 5663 | Configuration of libc's name service switch (NSS)---a |
| 5664 | @code{<name-service-switch>} object. @xref{Name Service Switch}, for |
| 5665 | details. |
| 5666 | |
| 5667 | @item @code{services} (default: @var{%base-services}) |
| 5668 | A list of monadic values denoting system services. @xref{Services}. |
| 5669 | |
| 5670 | @item @code{pam-services} (default: @code{(base-pam-services)}) |
| 5671 | @cindex PAM |
| 5672 | @cindex pluggable authentication modules |
| 5673 | Linux @dfn{pluggable authentication module} (PAM) services. |
| 5674 | @c FIXME: Add xref to PAM services section. |
| 5675 | |
| 5676 | @item @code{setuid-programs} (default: @var{%setuid-programs}) |
| 5677 | List of string-valued G-expressions denoting setuid programs. |
| 5678 | @xref{Setuid Programs}. |
| 5679 | |
| 5680 | @item @code{sudoers-file} (default: @var{%sudoers-specification}) |
| 5681 | @cindex sudoers file |
| 5682 | The contents of the @file{/etc/sudoers} file as a file-like object |
| 5683 | (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}). |
| 5684 | |
| 5685 | This file specifies which users can use the @command{sudo} command, what |
| 5686 | they are allowed to do, and what privileges they may gain. The default |
| 5687 | is that only @code{root} and members of the @code{wheel} group may use |
| 5688 | @code{sudo}. |
| 5689 | |
| 5690 | @end table |
| 5691 | @end deftp |
| 5692 | |
| 5693 | @node File Systems |
| 5694 | @subsection File Systems |
| 5695 | |
| 5696 | The list of file systems to be mounted is specified in the |
| 5697 | @code{file-systems} field of the operating system's declaration |
| 5698 | (@pxref{Using the Configuration System}). Each file system is declared |
| 5699 | using the @code{file-system} form, like this: |
| 5700 | |
| 5701 | @example |
| 5702 | (file-system |
| 5703 | (mount-point "/home") |
| 5704 | (device "/dev/sda3") |
| 5705 | (type "ext4")) |
| 5706 | @end example |
| 5707 | |
| 5708 | As usual, some of the fields are mandatory---those shown in the example |
| 5709 | above---while others can be omitted. These are described below. |
| 5710 | |
| 5711 | @deftp {Data Type} file-system |
| 5712 | Objects of this type represent file systems to be mounted. They |
| 5713 | contain the following members: |
| 5714 | |
| 5715 | @table @asis |
| 5716 | @item @code{type} |
| 5717 | This is a string specifying the type of the file system---e.g., |
| 5718 | @code{"ext4"}. |
| 5719 | |
| 5720 | @item @code{mount-point} |
| 5721 | This designates the place where the file system is to be mounted. |
| 5722 | |
| 5723 | @item @code{device} |
| 5724 | This names the ``source'' of the file system. By default it is the name |
| 5725 | of a node under @file{/dev}, but its meaning depends on the @code{title} |
| 5726 | field described below. |
| 5727 | |
| 5728 | @item @code{title} (default: @code{'device}) |
| 5729 | This is a symbol that specifies how the @code{device} field is to be |
| 5730 | interpreted. |
| 5731 | |
| 5732 | When it is the symbol @code{device}, then the @code{device} field is |
| 5733 | interpreted as a file name; when it is @code{label}, then @code{device} |
| 5734 | is interpreted as a partition label name; when it is @code{uuid}, |
| 5735 | @code{device} is interpreted as a partition unique identifier (UUID). |
| 5736 | |
| 5737 | UUIDs may be converted from their string representation (as shown by the |
| 5738 | @command{tune2fs -l} command) using the @code{uuid} form, like this: |
| 5739 | |
| 5740 | @example |
| 5741 | (file-system |
| 5742 | (mount-point "/home") |
| 5743 | (type "ext4") |
| 5744 | (title 'uuid) |
| 5745 | (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) |
| 5746 | @end example |
| 5747 | |
| 5748 | The @code{label} and @code{uuid} options offer a way to refer to disk |
| 5749 | partitions without having to hard-code their actual device |
| 5750 | name@footnote{Note that, while it is tempting to use |
| 5751 | @file{/dev/disk/by-uuid} and similar device names to achieve the same |
| 5752 | result, this is not recommended: These special device nodes are created |
| 5753 | by the udev daemon and may be unavailable at the time the device is |
| 5754 | mounted.}. |
| 5755 | |
| 5756 | However, when a file system's source is a mapped device (@pxref{Mapped |
| 5757 | Devices}), its @code{device} field @emph{must} refer to the mapped |
| 5758 | device name---e.g., @file{/dev/mapper/root-partition}---and consequently |
| 5759 | @code{title} must be set to @code{'device}. This is required so that |
| 5760 | the system knows that mounting the file system depends on having the |
| 5761 | corresponding device mapping established. |
| 5762 | |
| 5763 | @item @code{flags} (default: @code{'()}) |
| 5764 | This is a list of symbols denoting mount flags. Recognized flags |
| 5765 | include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow |
| 5766 | access to special files), @code{no-suid} (ignore setuid and setgid |
| 5767 | bits), and @code{no-exec} (disallow program execution.) |
| 5768 | |
| 5769 | @item @code{options} (default: @code{#f}) |
| 5770 | This is either @code{#f}, or a string denoting mount options. |
| 5771 | |
| 5772 | @item @code{needed-for-boot?} (default: @code{#f}) |
| 5773 | This Boolean value indicates whether the file system is needed when |
| 5774 | booting. If that is true, then the file system is mounted when the |
| 5775 | initial RAM disk (initrd) is loaded. This is always the case, for |
| 5776 | instance, for the root file system. |
| 5777 | |
| 5778 | @item @code{check?} (default: @code{#t}) |
| 5779 | This Boolean indicates whether the file system needs to be checked for |
| 5780 | errors before being mounted. |
| 5781 | |
| 5782 | @item @code{create-mount-point?} (default: @code{#f}) |
| 5783 | When true, the mount point is created if it does not exist yet. |
| 5784 | |
| 5785 | @item @code{dependencies} (default: @code{'()}) |
| 5786 | This is a list of @code{<file-system>} objects representing file systems |
| 5787 | that must be mounted before (and unmounted after) this one. |
| 5788 | |
| 5789 | As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is |
| 5790 | a dependency of @file{/sys/fs/cgroup/cpu} and |
| 5791 | @file{/sys/fs/cgroup/memory}. |
| 5792 | |
| 5793 | @end table |
| 5794 | @end deftp |
| 5795 | |
| 5796 | The @code{(gnu system file-systems)} exports the following useful |
| 5797 | variables. |
| 5798 | |
| 5799 | @defvr {Scheme Variable} %base-file-systems |
| 5800 | These are essential file systems that are required on normal systems, |
| 5801 | such as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see |
| 5802 | below.) Operating system declarations should always contain at least |
| 5803 | these. |
| 5804 | @end defvr |
| 5805 | |
| 5806 | @defvr {Scheme Variable} %pseudo-terminal-file-system |
| 5807 | This is the file system to be mounted as @file{/dev/pts}. It supports |
| 5808 | @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar |
| 5809 | functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference |
| 5810 | Manual}). Pseudo-terminals are used by terminal emulators such as |
| 5811 | @command{xterm}. |
| 5812 | @end defvr |
| 5813 | |
| 5814 | @defvr {Scheme Variable} %shared-memory-file-system |
| 5815 | This file system is mounted as @file{/dev/shm} and is used to support |
| 5816 | memory sharing across processes (@pxref{Memory-mapped I/O, |
| 5817 | @code{shm_open},, libc, The GNU C Library Reference Manual}). |
| 5818 | @end defvr |
| 5819 | |
| 5820 | @defvr {Scheme Variable} %immutable-store |
| 5821 | This file system performs a read-only ``bind mount'' of |
| 5822 | @file{/gnu/store}, making it read-only for all the users including |
| 5823 | @code{root}. This prevents against accidental modification by software |
| 5824 | running as @code{root} or by system administrators. |
| 5825 | |
| 5826 | The daemon itself is still able to write to the store: it remounts it |
| 5827 | read-write in its own ``name space.'' |
| 5828 | @end defvr |
| 5829 | |
| 5830 | @defvr {Scheme Variable} %binary-format-file-system |
| 5831 | The @code{binfmt_misc} file system, which allows handling of arbitrary |
| 5832 | executable file types to be delegated to user space. This requires the |
| 5833 | @code{binfmt.ko} kernel module to be loaded. |
| 5834 | @end defvr |
| 5835 | |
| 5836 | @defvr {Scheme Variable} %fuse-control-file-system |
| 5837 | The @code{fusectl} file system, which allows unprivileged users to mount |
| 5838 | and unmount user-space FUSE file systems. This requires the |
| 5839 | @code{fuse.ko} kernel module to be loaded. |
| 5840 | @end defvr |
| 5841 | |
| 5842 | @node Mapped Devices |
| 5843 | @subsection Mapped Devices |
| 5844 | |
| 5845 | @cindex device mapping |
| 5846 | @cindex mapped devices |
| 5847 | The Linux kernel has a notion of @dfn{device mapping}: a block device, |
| 5848 | such as a hard disk partition, can be @dfn{mapped} into another device, |
| 5849 | with additional processing over the data that flows through |
| 5850 | it@footnote{Note that the GNU@tie{}Hurd makes no difference between the |
| 5851 | concept of a ``mapped device'' and that of a file system: both boil down |
| 5852 | to @emph{translating} input/output operations made on a file to |
| 5853 | operations on its backing store. Thus, the Hurd implements mapped |
| 5854 | devices, like file systems, using the generic @dfn{translator} mechanism |
| 5855 | (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A |
| 5856 | typical example is encryption device mapping: all writes to the mapped |
| 5857 | device are encrypted, and all reads are deciphered, transparently. |
| 5858 | |
| 5859 | Mapped devices are declared using the @code{mapped-device} form: |
| 5860 | |
| 5861 | @example |
| 5862 | (mapped-device |
| 5863 | (source "/dev/sda3") |
| 5864 | (target "home") |
| 5865 | (type luks-device-mapping)) |
| 5866 | @end example |
| 5867 | |
| 5868 | @noindent |
| 5869 | @cindex disk encryption |
| 5870 | @cindex LUKS |
| 5871 | This example specifies a mapping from @file{/dev/sda3} to |
| 5872 | @file{/dev/mapper/home} using LUKS---the |
| 5873 | @url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a |
| 5874 | standard mechanism for disk encryption. The @file{/dev/mapper/home} |
| 5875 | device can then be used as the @code{device} of a @code{file-system} |
| 5876 | declaration (@pxref{File Systems}). The @code{mapped-device} form is |
| 5877 | detailed below. |
| 5878 | |
| 5879 | @deftp {Data Type} mapped-device |
| 5880 | Objects of this type represent device mappings that will be made when |
| 5881 | the system boots up. |
| 5882 | |
| 5883 | @table @code |
| 5884 | @item source |
| 5885 | This string specifies the name of the block device to be mapped, such as |
| 5886 | @code{"/dev/sda3"}. |
| 5887 | |
| 5888 | @item target |
| 5889 | This string specifies the name of the mapping to be established. For |
| 5890 | example, specifying @code{"my-partition"} will lead to the creation of |
| 5891 | the @code{"/dev/mapper/my-partition"} device. |
| 5892 | |
| 5893 | @item type |
| 5894 | This must be a @code{mapped-device-kind} object, which specifies how |
| 5895 | @var{source} is mapped to @var{target}. |
| 5896 | @end table |
| 5897 | @end deftp |
| 5898 | |
| 5899 | @defvr {Scheme Variable} luks-device-mapping |
| 5900 | This defines LUKS block device encryption using the @command{cryptsetup} |
| 5901 | command, from the same-named package. This relies on the |
| 5902 | @code{dm-crypt} Linux kernel module. |
| 5903 | @end defvr |
| 5904 | |
| 5905 | @node User Accounts |
| 5906 | @subsection User Accounts |
| 5907 | |
| 5908 | User accounts and groups are entirely managed through the |
| 5909 | @code{operating-system} declaration. They are specified with the |
| 5910 | @code{user-account} and @code{user-group} forms: |
| 5911 | |
| 5912 | @example |
| 5913 | (user-account |
| 5914 | (name "alice") |
| 5915 | (group "users") |
| 5916 | (supplementary-groups '("wheel" ;allow use of sudo, etc. |
| 5917 | "audio" ;sound card |
| 5918 | "video" ;video devices such as webcams |
| 5919 | "cdrom")) ;the good ol' CD-ROM |
| 5920 | (comment "Bob's sister") |
| 5921 | (home-directory "/home/alice")) |
| 5922 | @end example |
| 5923 | |
| 5924 | When booting or upon completion of @command{guix system reconfigure}, |
| 5925 | the system ensures that only the user accounts and groups specified in |
| 5926 | the @code{operating-system} declaration exist, and with the specified |
| 5927 | properties. Thus, account or group creations or modifications made by |
| 5928 | directly invoking commands such as @command{useradd} are lost upon |
| 5929 | reconfiguration or reboot. This ensures that the system remains exactly |
| 5930 | as declared. |
| 5931 | |
| 5932 | @deftp {Data Type} user-account |
| 5933 | Objects of this type represent user accounts. The following members may |
| 5934 | be specified: |
| 5935 | |
| 5936 | @table @asis |
| 5937 | @item @code{name} |
| 5938 | The name of the user account. |
| 5939 | |
| 5940 | @item @code{group} |
| 5941 | This is the name (a string) or identifier (a number) of the user group |
| 5942 | this account belongs to. |
| 5943 | |
| 5944 | @item @code{supplementary-groups} (default: @code{'()}) |
| 5945 | Optionally, this can be defined as a list of group names that this |
| 5946 | account belongs to. |
| 5947 | |
| 5948 | @item @code{uid} (default: @code{#f}) |
| 5949 | This is the user ID for this account (a number), or @code{#f}. In the |
| 5950 | latter case, a number is automatically chosen by the system when the |
| 5951 | account is created. |
| 5952 | |
| 5953 | @item @code{comment} (default: @code{""}) |
| 5954 | A comment about the account, such as the account's owner full name. |
| 5955 | |
| 5956 | @item @code{home-directory} |
| 5957 | This is the name of the home directory for the account. |
| 5958 | |
| 5959 | @item @code{shell} (default: Bash) |
| 5960 | This is a G-expression denoting the file name of a program to be used as |
| 5961 | the shell (@pxref{G-Expressions}). |
| 5962 | |
| 5963 | @item @code{system?} (default: @code{#f}) |
| 5964 | This Boolean value indicates whether the account is a ``system'' |
| 5965 | account. System accounts are sometimes treated specially; for instance, |
| 5966 | graphical login managers do not list them. |
| 5967 | |
| 5968 | @anchor{user-account-password} |
| 5969 | @item @code{password} (default: @code{#f}) |
| 5970 | You would normally leave this field to @code{#f}, initialize user |
| 5971 | passwords as @code{root} with the @command{passwd} command, and then let |
| 5972 | users change it with @command{passwd}. Passwords set with |
| 5973 | @command{passwd} are of course preserved across reboot and |
| 5974 | reconfiguration. |
| 5975 | |
| 5976 | If you @emph{do} want to have a preset password for an account, then |
| 5977 | this field must contain the encrypted password, as a string. |
| 5978 | @xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information |
| 5979 | on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference |
| 5980 | Manual}, for information on Guile's @code{crypt} procedure. |
| 5981 | |
| 5982 | @end table |
| 5983 | @end deftp |
| 5984 | |
| 5985 | User group declarations are even simpler: |
| 5986 | |
| 5987 | @example |
| 5988 | (user-group (name "students")) |
| 5989 | @end example |
| 5990 | |
| 5991 | @deftp {Data Type} user-group |
| 5992 | This type is for, well, user groups. There are just a few fields: |
| 5993 | |
| 5994 | @table @asis |
| 5995 | @item @code{name} |
| 5996 | The group's name. |
| 5997 | |
| 5998 | @item @code{id} (default: @code{#f}) |
| 5999 | The group identifier (a number). If @code{#f}, a new number is |
| 6000 | automatically allocated when the group is created. |
| 6001 | |
| 6002 | @item @code{system?} (default: @code{#f}) |
| 6003 | This Boolean value indicates whether the group is a ``system'' group. |
| 6004 | System groups have low numerical IDs. |
| 6005 | |
| 6006 | @item @code{password} (default: @code{#f}) |
| 6007 | What, user groups can have a password? Well, apparently yes. Unless |
| 6008 | @code{#f}, this field specifies the group's password. |
| 6009 | |
| 6010 | @end table |
| 6011 | @end deftp |
| 6012 | |
| 6013 | For convenience, a variable lists all the basic user groups one may |
| 6014 | expect: |
| 6015 | |
| 6016 | @defvr {Scheme Variable} %base-groups |
| 6017 | This is the list of basic user groups that users and/or packages expect |
| 6018 | to be present on the system. This includes groups such as ``root'', |
| 6019 | ``wheel'', and ``users'', as well as groups used to control access to |
| 6020 | specific devices such as ``audio'', ``disk'', and ``cdrom''. |
| 6021 | @end defvr |
| 6022 | |
| 6023 | @defvr {Scheme Variable} %base-user-accounts |
| 6024 | This is the list of basic system accounts that programs may expect to |
| 6025 | find on a GNU/Linux system, such as the ``nobody'' account. |
| 6026 | |
| 6027 | Note that the ``root'' account is not included here. It is a |
| 6028 | special-case and is automatically added whether or not it is specified. |
| 6029 | @end defvr |
| 6030 | |
| 6031 | @node Locales |
| 6032 | @subsection Locales |
| 6033 | |
| 6034 | @cindex locale |
| 6035 | A @dfn{locale} defines cultural conventions for a particular language |
| 6036 | and region of the world (@pxref{Locales,,, libc, The GNU C Library |
| 6037 | Reference Manual}). Each locale has a name that typically has the form |
| 6038 | @code{@var{language}_@var{territory}.@var{codeset}}---e.g., |
| 6039 | @code{fr_LU.utf8} designates the locale for the French language, with |
| 6040 | cultural conventions from Luxembourg, and using the UTF-8 encoding. |
| 6041 | |
| 6042 | @cindex locale definition |
| 6043 | Usually, you will want to specify the default locale for the machine |
| 6044 | using the @code{locale} field of the @code{operating-system} declaration |
| 6045 | (@pxref{operating-system Reference, @code{locale}}). |
| 6046 | |
| 6047 | That locale must be among the @dfn{locale definitions} that are known to |
| 6048 | the system---and these are specified in the @code{locale-definitions} |
| 6049 | slot of @code{operating-system}. The default value includes locale |
| 6050 | definition for some widely used locales, but not for all the available |
| 6051 | locales, in order to save space. |
| 6052 | |
| 6053 | If the locale specified in the @code{locale} field is not among the |
| 6054 | definitions listed in @code{locale-definitions}, @command{guix system} |
| 6055 | raises an error. In that case, you should add the locale definition to |
| 6056 | the @code{locale-definitions} field. For instance, to add the North |
| 6057 | Frisian locale for Germany, the value of that field may be: |
| 6058 | |
| 6059 | @example |
| 6060 | (cons (locale-definition |
| 6061 | (name "fy_DE.utf8") (source "fy_DE")) |
| 6062 | %default-locale-definitions) |
| 6063 | @end example |
| 6064 | |
| 6065 | Likewise, to save space, one might want @code{locale-definitions} to |
| 6066 | list only the locales that are actually used, as in: |
| 6067 | |
| 6068 | @example |
| 6069 | (list (locale-definition |
| 6070 | (name "ja_JP.eucjp") (source "ja_JP") |
| 6071 | (charset "EUC-JP"))) |
| 6072 | @end example |
| 6073 | |
| 6074 | @vindex LOCPATH |
| 6075 | The compiled locale definitions are available at |
| 6076 | @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc |
| 6077 | version, which is the default location where the GNU@tie{}libc provided |
| 6078 | by Guix looks for locale data. This can be overridden using the |
| 6079 | @code{LOCPATH} environment variable (@pxref{locales-and-locpath, |
| 6080 | @code{LOCPATH} and locale packages}). |
| 6081 | |
| 6082 | The @code{locale-definition} form is provided by the @code{(gnu system |
| 6083 | locale)} module. Details are given below. |
| 6084 | |
| 6085 | @deftp {Data Type} locale-definition |
| 6086 | This is the data type of a locale definition. |
| 6087 | |
| 6088 | @table @asis |
| 6089 | |
| 6090 | @item @code{name} |
| 6091 | The name of the locale. @xref{Locale Names,,, libc, The GNU C Library |
| 6092 | Reference Manual}, for more information on locale names. |
| 6093 | |
| 6094 | @item @code{source} |
| 6095 | The name of the source for that locale. This is typically the |
| 6096 | @code{@var{language}_@var{territory}} part of the locale name. |
| 6097 | |
| 6098 | @item @code{charset} (default: @code{"UTF-8"}) |
| 6099 | The ``character set'' or ``code set'' for that locale, |
| 6100 | @uref{http://www.iana.org/assignments/character-sets, as defined by |
| 6101 | IANA}. |
| 6102 | |
| 6103 | @end table |
| 6104 | @end deftp |
| 6105 | |
| 6106 | @defvr {Scheme Variable} %default-locale-definitions |
| 6107 | An arbitrary list of commonly used UTF-8 locales, used as the default |
| 6108 | value of the @code{locale-definitions} field of @code{operating-system} |
| 6109 | declarations. |
| 6110 | |
| 6111 | @cindex locale name |
| 6112 | @cindex normalized codeset in locale names |
| 6113 | These locale definitions use the @dfn{normalized codeset} for the part |
| 6114 | that follows the dot in the name (@pxref{Using gettextized software, |
| 6115 | normalized codeset,, libc, The GNU C Library Reference Manual}). So for |
| 6116 | instance it has @code{uk_UA.utf8} but @emph{not}, say, |
| 6117 | @code{uk_UA.UTF-8}. |
| 6118 | @end defvr |
| 6119 | |
| 6120 | @subsubsection Locale Data Compatibility Considerations |
| 6121 | |
| 6122 | @cindex incompatibility, of locale data |
| 6123 | @code{operating-system} declarations provide a @code{locale-libcs} field |
| 6124 | to specify the GNU@tie{}libc packages that are used to compile locale |
| 6125 | declarations (@pxref{operating-system Reference}). ``Why would I |
| 6126 | care?'', you may ask. Well, it turns out that the binary format of |
| 6127 | locale data is occasionally incompatible from one libc version to |
| 6128 | another. |
| 6129 | |
| 6130 | @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> |
| 6131 | @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. |
| 6132 | For instance, a program linked against libc version 2.21 is unable to |
| 6133 | read locale data produced with libc 2.22; worse, that program |
| 6134 | @emph{aborts} instead of simply ignoring the incompatible locale |
| 6135 | data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip |
| 6136 | the incompatible locale data, which is already an improvement.}. |
| 6137 | Similarly, a program linked against libc 2.22 can read most, but not |
| 6138 | all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE} |
| 6139 | data is incompatible); thus calls to @code{setlocale} may fail, but |
| 6140 | programs will not abort. |
| 6141 | |
| 6142 | The ``problem'' in GuixSD is that users have a lot of freedom: They can |
| 6143 | choose whether and when to upgrade software in their profiles, and might |
| 6144 | be using a libc version different from the one the system administrator |
| 6145 | used to build the system-wide locale data. |
| 6146 | |
| 6147 | Fortunately, unprivileged users can also install their own locale data |
| 6148 | and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath, |
| 6149 | @code{GUIX_LOCPATH} and locale packages}). |
| 6150 | |
| 6151 | Still, it is best if the system-wide locale data at |
| 6152 | @file{/run/current-system/locale} is built for all the libc versions |
| 6153 | actually in use on the system, so that all the programs can access |
| 6154 | it---this is especially crucial on a multi-user system. To do that, the |
| 6155 | administrator can specify several libc packages in the |
| 6156 | @code{locale-libcs} field of @code{operating-system}: |
| 6157 | |
| 6158 | @example |
| 6159 | (use-package-modules base) |
| 6160 | |
| 6161 | (operating-system |
| 6162 | ;; @dots{} |
| 6163 | (locale-libcs (list glibc-2.21 (canonical-package glibc)))) |
| 6164 | @end example |
| 6165 | |
| 6166 | This example would lead to a system containing locale definitions for |
| 6167 | both libc 2.21 and the current version of libc in |
| 6168 | @file{/run/current-system/locale}. |
| 6169 | |
| 6170 | |
| 6171 | @node Services |
| 6172 | @subsection Services |
| 6173 | |
| 6174 | @cindex system services |
| 6175 | An important part of preparing an @code{operating-system} declaration is |
| 6176 | listing @dfn{system services} and their configuration (@pxref{Using the |
| 6177 | Configuration System}). System services are typically daemons launched |
| 6178 | when the system boots, or other actions needed at that time---e.g., |
| 6179 | configuring network access. |
| 6180 | |
| 6181 | Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU |
| 6182 | dmd Manual}). On a running system, the @command{deco} command allows |
| 6183 | you to list the available services, show their status, start and stop |
| 6184 | them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd |
| 6185 | Manual}). For example: |
| 6186 | |
| 6187 | @example |
| 6188 | # deco status dmd |
| 6189 | @end example |
| 6190 | |
| 6191 | The above command, run as @code{root}, lists the currently defined |
| 6192 | services. The @command{deco doc} command shows a synopsis of the given |
| 6193 | service: |
| 6194 | |
| 6195 | @example |
| 6196 | # deco doc nscd |
| 6197 | Run libc's name service cache daemon (nscd). |
| 6198 | @end example |
| 6199 | |
| 6200 | The @command{start}, @command{stop}, and @command{restart} sub-commands |
| 6201 | have the effect you would expect. For instance, the commands below stop |
| 6202 | the nscd service and restart the Xorg display server: |
| 6203 | |
| 6204 | @example |
| 6205 | # deco stop nscd |
| 6206 | Service nscd has been stopped. |
| 6207 | # deco restart xorg-server |
| 6208 | Service xorg-server has been stopped. |
| 6209 | Service xorg-server has been started. |
| 6210 | @end example |
| 6211 | |
| 6212 | The following sections document the available services, starting with |
| 6213 | the core services, that may be used in an @code{operating-system} |
| 6214 | declaration. |
| 6215 | |
| 6216 | @menu |
| 6217 | * Base Services:: Essential system services. |
| 6218 | * Networking Services:: Network setup, SSH daemon, etc. |
| 6219 | * X Window:: Graphical display. |
| 6220 | * Desktop Services:: D-Bus and desktop services. |
| 6221 | * Database Services:: SQL databases. |
| 6222 | * Web Services:: Web servers. |
| 6223 | * Various Services:: Other services. |
| 6224 | @end menu |
| 6225 | |
| 6226 | @node Base Services |
| 6227 | @subsubsection Base Services |
| 6228 | |
| 6229 | The @code{(gnu services base)} module provides definitions for the basic |
| 6230 | services that one expects from the system. The services exported by |
| 6231 | this module are listed below. |
| 6232 | |
| 6233 | @defvr {Scheme Variable} %base-services |
| 6234 | This variable contains a list of basic services@footnote{Technically, |
| 6235 | this is a list of monadic services. @xref{The Store Monad}.} one would |
| 6236 | expect from the system: a login service (mingetty) on each tty, syslogd, |
| 6237 | libc's name service cache daemon (nscd), the udev device manager, and |
| 6238 | more. |
| 6239 | |
| 6240 | This is the default value of the @code{services} field of |
| 6241 | @code{operating-system} declarations. Usually, when customizing a |
| 6242 | system, you will want to append services to @var{%base-services}, like |
| 6243 | this: |
| 6244 | |
| 6245 | @example |
| 6246 | (cons* (avahi-service) (lsh-service) %base-services) |
| 6247 | @end example |
| 6248 | @end defvr |
| 6249 | |
| 6250 | @deffn {Scheme Procedure} host-name-service @var{name} |
| 6251 | Return a service that sets the host name to @var{name}. |
| 6252 | @end deffn |
| 6253 | |
| 6254 | @deffn {Scheme Procedure} mingetty-service @var{config} |
| 6255 | Return a service to run mingetty according to @var{config}, a |
| 6256 | @code{<mingetty-configuration>} object, which specifies the tty to run, among |
| 6257 | other things. |
| 6258 | @end deffn |
| 6259 | |
| 6260 | @deftp {Data Type} mingetty-configuration |
| 6261 | This is the data type representing the configuration of Mingetty, which |
| 6262 | implements console log-in. |
| 6263 | |
| 6264 | @table @asis |
| 6265 | |
| 6266 | @item @code{tty} |
| 6267 | The name of the console this Mingetty runs on---e.g., @code{"tty1"}. |
| 6268 | |
| 6269 | @item @code{motd} |
| 6270 | A file-like object containing the ``message of the day''. |
| 6271 | |
| 6272 | @item @code{auto-login} (default: @code{#f}) |
| 6273 | When true, this field must be a string denoting the user name under |
| 6274 | which the the system automatically logs in. When it is @code{#f}, a |
| 6275 | user name and password must be entered to log in. |
| 6276 | |
| 6277 | @item @code{login-program} (default: @code{#f}) |
| 6278 | This must be either @code{#f}, in which case the default log-in program |
| 6279 | is used (@command{login} from the Shadow tool suite), or a gexp denoting |
| 6280 | the name of the log-in program. |
| 6281 | |
| 6282 | @item @code{login-pause?} (default: @code{#f}) |
| 6283 | When set to @code{#t} in conjunction with @var{auto-login}, the user |
| 6284 | will have to press a key before the log-in shell is launched. |
| 6285 | |
| 6286 | @item @code{mingetty} (default: @var{mingetty}) |
| 6287 | The Mingetty package to use. |
| 6288 | |
| 6289 | @end table |
| 6290 | @end deftp |
| 6291 | |
| 6292 | @cindex name service cache daemon |
| 6293 | @cindex nscd |
| 6294 | @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @ |
| 6295 | [#:name-services '()] |
| 6296 | Return a service that runs libc's name service cache daemon (nscd) with the |
| 6297 | given @var{config}---an @code{<nscd-configuration>} object. @xref{Name |
| 6298 | Service Switch}, for an example. |
| 6299 | @end deffn |
| 6300 | |
| 6301 | @defvr {Scheme Variable} %nscd-default-configuration |
| 6302 | This is the default @code{<nscd-configuration>} value (see below) used |
| 6303 | by @code{nscd-service}. This uses the caches defined by |
| 6304 | @var{%nscd-default-caches}; see below. |
| 6305 | @end defvr |
| 6306 | |
| 6307 | @deftp {Data Type} nscd-configuration |
| 6308 | This is the type representing the name service cache daemon (nscd) |
| 6309 | configuration. |
| 6310 | |
| 6311 | @table @asis |
| 6312 | |
| 6313 | @item @code{name-services} (default: @code{'()}) |
| 6314 | List of packages denoting @dfn{name services} that must be visible to |
| 6315 | the nscd---e.g., @code{(list @var{nss-mdns})}. |
| 6316 | |
| 6317 | @item @code{glibc} (default: @var{glibc}) |
| 6318 | Package object denoting the GNU C Library providing the @command{nscd} |
| 6319 | command. |
| 6320 | |
| 6321 | @item @code{log-file} (default: @code{"/var/log/nscd.log"}) |
| 6322 | Name of nscd's log file. This is where debugging output goes when |
| 6323 | @code{debug-level} is strictly positive. |
| 6324 | |
| 6325 | @item @code{debug-level} (default: @code{0}) |
| 6326 | Integer denoting the debugging levels. Higher numbers mean more |
| 6327 | debugging output is logged. |
| 6328 | |
| 6329 | @item @code{caches} (default: @var{%nscd-default-caches}) |
| 6330 | List of @code{<nscd-cache>} objects denoting things to be cached; see |
| 6331 | below. |
| 6332 | |
| 6333 | @end table |
| 6334 | @end deftp |
| 6335 | |
| 6336 | @deftp {Data Type} nscd-cache |
| 6337 | Data type representing a cache database of nscd and its parameters. |
| 6338 | |
| 6339 | @table @asis |
| 6340 | |
| 6341 | @item @code{database} |
| 6342 | This is a symbol representing the name of the database to be cached. |
| 6343 | Valid values are @code{passwd}, @code{group}, @code{hosts}, and |
| 6344 | @code{services}, which designate the corresponding NSS database |
| 6345 | (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}). |
| 6346 | |
| 6347 | @item @code{positive-time-to-live} |
| 6348 | @itemx @code{negative-time-to-live} (default: @code{20}) |
| 6349 | A number representing the number of seconds during which a positive or |
| 6350 | negative lookup result remains in cache. |
| 6351 | |
| 6352 | @item @code{check-files?} (default: @code{#t}) |
| 6353 | Whether to check for updates of the files corresponding to |
| 6354 | @var{database}. |
| 6355 | |
| 6356 | For instance, when @var{database} is @code{hosts}, setting this flag |
| 6357 | instructs nscd to check for updates in @file{/etc/hosts} and to take |
| 6358 | them into account. |
| 6359 | |
| 6360 | @item @code{persistent?} (default: @code{#t}) |
| 6361 | Whether the cache should be stored persistently on disk. |
| 6362 | |
| 6363 | @item @code{shared?} (default: @code{#t}) |
| 6364 | Whether the cache should be shared among users. |
| 6365 | |
| 6366 | @item @code{max-database-size} (default: 32@tie{}MiB) |
| 6367 | Maximum size in bytes of the database cache. |
| 6368 | |
| 6369 | @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert |
| 6370 | @c settings, so leave them out. |
| 6371 | |
| 6372 | @end table |
| 6373 | @end deftp |
| 6374 | |
| 6375 | @defvr {Scheme Variable} %nscd-default-caches |
| 6376 | List of @code{<nscd-cache>} objects used by default by |
| 6377 | @code{nscd-configuration} (see above.) |
| 6378 | |
| 6379 | It enables persistent and aggressive caching of service and host name |
| 6380 | lookups. The latter provides better host name lookup performance, |
| 6381 | resilience in the face of unreliable name servers, and also better |
| 6382 | privacy---often the result of host name lookups is in local cache, so |
| 6383 | external name servers do not even need to be queried. |
| 6384 | @end defvr |
| 6385 | |
| 6386 | |
| 6387 | @deffn {Scheme Procedure} syslog-service [#:config-file #f] |
| 6388 | Return a service that runs @code{syslogd}. If configuration file name |
| 6389 | @var{config-file} is not specified, use some reasonable default |
| 6390 | settings. |
| 6391 | @end deffn |
| 6392 | |
| 6393 | @anchor{guix-configuration-type} |
| 6394 | @deftp {Data Type} guix-configuration |
| 6395 | This data type represents the configuration of the Guix build daemon. |
| 6396 | @xref{Invoking guix-daemon}, for more information. |
| 6397 | |
| 6398 | @table @asis |
| 6399 | @item @code{guix} (default: @var{guix}) |
| 6400 | The Guix package to use. |
| 6401 | |
| 6402 | @item @code{build-group} (default: @code{"guixbuild"}) |
| 6403 | Name of the group for build user accounts. |
| 6404 | |
| 6405 | @item @code{build-accounts} (default: @code{10}) |
| 6406 | Number of build user accounts to create. |
| 6407 | |
| 6408 | @item @code{authorize-key?} (default: @code{#t}) |
| 6409 | Whether to authorize the substitute key for @code{hydra.gnu.org} |
| 6410 | (@pxref{Substitutes}). |
| 6411 | |
| 6412 | @item @code{use-substitutes?} (default: @code{#t}) |
| 6413 | Whether to use substitutes. |
| 6414 | |
| 6415 | @item @code{substitute-urls} (default: @var{%default-substitute-urls}) |
| 6416 | The list of URLs where to look for substitutes by default. |
| 6417 | |
| 6418 | @item @code{extra-options} (default: @code{'()}) |
| 6419 | List of extra command-line options for @command{guix-daemon}. |
| 6420 | |
| 6421 | @item @code{lsof} (default: @var{lsof}) |
| 6422 | @itemx @code{lsh} (default: @var{lsh}) |
| 6423 | The lsof and lsh packages to use. |
| 6424 | |
| 6425 | @end table |
| 6426 | @end deftp |
| 6427 | |
| 6428 | @deffn {Scheme Procedure} guix-service @var{config} |
| 6429 | Return a service that runs the Guix build daemon according to |
| 6430 | @var{config}. |
| 6431 | @end deffn |
| 6432 | |
| 6433 | @deffn {Scheme Procedure} udev-service [#:udev udev] |
| 6434 | Run @var{udev}, which populates the @file{/dev} directory dynamically. |
| 6435 | @end deffn |
| 6436 | |
| 6437 | @deffn {Scheme Procedure} console-keymap-service @var{file} |
| 6438 | Return a service to load console keymap from @var{file} using |
| 6439 | @command{loadkeys} command. |
| 6440 | @end deffn |
| 6441 | |
| 6442 | @anchor{guix-publish-service} |
| 6443 | @deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @ |
| 6444 | [#:port 80] [#:host "localhost"] |
| 6445 | Return a service that runs @command{guix publish} listening on @var{host} |
| 6446 | and @var{port} (@pxref{Invoking guix publish}). |
| 6447 | |
| 6448 | This assumes that @file{/etc/guix} already contains a signing key pair as |
| 6449 | created by @command{guix archive --generate-key} (@pxref{Invoking guix |
| 6450 | archive}). If that is not the case, the service will fail to start. |
| 6451 | @end deffn |
| 6452 | |
| 6453 | |
| 6454 | @node Networking Services |
| 6455 | @subsubsection Networking Services |
| 6456 | |
| 6457 | The @code{(gnu services networking)} module provides services to configure |
| 6458 | the network interface. |
| 6459 | |
| 6460 | @cindex DHCP, networking service |
| 6461 | @deffn {Scheme Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}] |
| 6462 | Return a service that runs @var{dhcp}, a Dynamic Host Configuration |
| 6463 | Protocol (DHCP) client, on all the non-loopback network interfaces. |
| 6464 | @end deffn |
| 6465 | |
| 6466 | @deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ |
| 6467 | [#:gateway #f] [#:name-services @code{'()}] |
| 6468 | Return a service that starts @var{interface} with address @var{ip}. If |
| 6469 | @var{gateway} is true, it must be a string specifying the default network |
| 6470 | gateway. |
| 6471 | @end deffn |
| 6472 | |
| 6473 | @cindex wicd |
| 6474 | @cindex network management |
| 6475 | @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] |
| 6476 | Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network |
| 6477 | management daemon that aims to simplify wired and wireless networking. |
| 6478 | |
| 6479 | This service adds the @var{wicd} package to the global profile, providing |
| 6480 | several commands to interact with the daemon and configure networking: |
| 6481 | @command{wicd-client}, a graphical user interface, and the @command{wicd-cli} |
| 6482 | and @command{wicd-curses} user interfaces. |
| 6483 | @end deffn |
| 6484 | |
| 6485 | @deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @ |
| 6486 | [#:name-service @var{%ntp-servers}] |
| 6487 | Return a service that runs the daemon from @var{ntp}, the |
| 6488 | @uref{http://www.ntp.org, Network Time Protocol package}. The daemon will |
| 6489 | keep the system clock synchronized with that of @var{servers}. |
| 6490 | @end deffn |
| 6491 | |
| 6492 | @defvr {Scheme Variable} %ntp-servers |
| 6493 | List of host names used as the default NTP servers. |
| 6494 | @end defvr |
| 6495 | |
| 6496 | @deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}] |
| 6497 | Return a service to run the @uref{https://torproject.org, Tor} anonymous |
| 6498 | networking daemon. |
| 6499 | |
| 6500 | The daemon runs as the @code{tor} unprivileged user. It is passed |
| 6501 | @var{config-file}, a file-like object, with an additional @code{User tor} |
| 6502 | line. Run @command{man tor} for information about the configuration file. |
| 6503 | @end deffn |
| 6504 | |
| 6505 | @deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @ |
| 6506 | [#:interface "127.0.0.1"] [#:port 6667] @ |
| 6507 | [#:extra-settings ""] |
| 6508 | Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that |
| 6509 | acts as a gateway between IRC and chat networks. |
| 6510 | |
| 6511 | The daemon will listen to the interface corresponding to the IP address |
| 6512 | specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only |
| 6513 | local clients can connect, whereas @code{0.0.0.0} means that connections can |
| 6514 | come from any networking interface. |
| 6515 | |
| 6516 | In addition, @var{extra-settings} specifies a string to append to the |
| 6517 | configuration file. |
| 6518 | @end deffn |
| 6519 | |
| 6520 | Furthermore, @code{(gnu services ssh)} provides the following service. |
| 6521 | |
| 6522 | @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ |
| 6523 | [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ |
| 6524 | [#:allow-empty-passwords? #f] [#:root-login? #f] @ |
| 6525 | [#:syslog-output? #t] [#:x11-forwarding? #t] @ |
| 6526 | [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @ |
| 6527 | [#:public-key-authentication? #t] [#:initialize? #t] |
| 6528 | Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}. |
| 6529 | @var{host-key} must designate a file containing the host key, and readable |
| 6530 | only by root. |
| 6531 | |
| 6532 | When @var{daemonic?} is true, @command{lshd} will detach from the |
| 6533 | controlling terminal and log its output to syslogd, unless one sets |
| 6534 | @var{syslog-output?} to false. Obviously, it also makes lsh-service |
| 6535 | depend on existence of syslogd service. When @var{pid-file?} is true, |
| 6536 | @command{lshd} writes its PID to the file called @var{pid-file}. |
| 6537 | |
| 6538 | When @var{initialize?} is true, automatically create the seed and host key |
| 6539 | upon service activation if they do not exist yet. This may take long and |
| 6540 | require interaction. |
| 6541 | |
| 6542 | When @var{initialize?} is false, it is up to the user to initialize the |
| 6543 | randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create |
| 6544 | a key pair with the private key stored in file @var{host-key} (@pxref{lshd |
| 6545 | basics,,, lsh, LSH Manual}). |
| 6546 | |
| 6547 | When @var{interfaces} is empty, lshd listens for connections on all the |
| 6548 | network interfaces; otherwise, @var{interfaces} must be a list of host names |
| 6549 | or addresses. |
| 6550 | |
| 6551 | @var{allow-empty-passwords?} specifies whether to accept log-ins with empty |
| 6552 | passwords, and @var{root-login?} specifies whether to accept log-ins as |
| 6553 | root. |
| 6554 | |
| 6555 | The other options should be self-descriptive. |
| 6556 | @end deffn |
| 6557 | |
| 6558 | @defvr {Scheme Variable} %facebook-host-aliases |
| 6559 | This variable contains a string for use in @file{/etc/hosts} |
| 6560 | (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each |
| 6561 | line contains a entry that maps a known server name of the Facebook |
| 6562 | on-line service---e.g., @code{www.facebook.com}---to the local |
| 6563 | host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}. |
| 6564 | |
| 6565 | This variable is typically used in the @code{hosts-file} field of an |
| 6566 | @code{operating-system} declaration (@pxref{operating-system Reference, |
| 6567 | @file{/etc/hosts}}): |
| 6568 | |
| 6569 | @example |
| 6570 | (use-modules (gnu) (guix)) |
| 6571 | |
| 6572 | (operating-system |
| 6573 | (host-name "mymachine") |
| 6574 | ;; ... |
| 6575 | (hosts-file |
| 6576 | ;; Create a /etc/hosts file with aliases for "localhost" |
| 6577 | ;; and "mymachine", as well as for Facebook servers. |
| 6578 | (plain-file "hosts" |
| 6579 | (string-append (local-host-aliases host-name) |
| 6580 | %facebook-host-aliases)))) |
| 6581 | @end example |
| 6582 | |
| 6583 | This mechanism can prevent programs running locally, such as Web |
| 6584 | browsers, from accessing Facebook. |
| 6585 | @end defvr |
| 6586 | |
| 6587 | The @code{(gnu services avahi)} provides the following definition. |
| 6588 | |
| 6589 | @deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @ |
| 6590 | [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @ |
| 6591 | [#:ipv6? #t] [#:wide-area? #f] @ |
| 6592 | [#:domains-to-browse '()] |
| 6593 | Return a service that runs @command{avahi-daemon}, a system-wide |
| 6594 | mDNS/DNS-SD responder that allows for service discovery and |
| 6595 | "zero-configuration" host name lookups (see @uref{http://avahi.org/}), and |
| 6596 | extends the name service cache daemon (nscd) so that it can resolve |
| 6597 | @code{.local} host names using |
| 6598 | @uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally, |
| 6599 | add the @var{avahi} package to the system profile so that commands such as |
| 6600 | @command{avahi-browse} are directly usable. |
| 6601 | |
| 6602 | If @var{host-name} is different from @code{#f}, use that as the host name to |
| 6603 | publish for this machine; otherwise, use the machine's actual host name. |
| 6604 | |
| 6605 | When @var{publish?} is true, publishing of host names and services is allowed; |
| 6606 | in particular, avahi-daemon will publish the machine's host name and IP |
| 6607 | address via mDNS on the local network. |
| 6608 | |
| 6609 | When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled. |
| 6610 | |
| 6611 | Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6 |
| 6612 | sockets. |
| 6613 | @end deffn |
| 6614 | |
| 6615 | |
| 6616 | @node X Window |
| 6617 | @subsubsection X Window |
| 6618 | |
| 6619 | Support for the X Window graphical display system---specifically |
| 6620 | Xorg---is provided by the @code{(gnu services xorg)} module. Note that |
| 6621 | there is no @code{xorg-service} procedure. Instead, the X server is |
| 6622 | started by the @dfn{login manager}, currently SLiM. |
| 6623 | |
| 6624 | @deffn {Scheme Procedure} slim-service [#:allow-empty-passwords? #f] @ |
| 6625 | [#:auto-login? #f] [#:default-user ""] [#:startx] @ |
| 6626 | [#:theme @var{%default-slim-theme}] @ |
| 6627 | [#:theme-name @var{%default-slim-theme-name}] |
| 6628 | Return a service that spawns the SLiM graphical login manager, which in |
| 6629 | turn starts the X display server with @var{startx}, a command as returned by |
| 6630 | @code{xorg-start-command}. |
| 6631 | |
| 6632 | @cindex X session |
| 6633 | |
| 6634 | SLiM automatically looks for session types described by the @file{.desktop} |
| 6635 | files in @file{/run/current-system/profile/share/xsessions} and allows users |
| 6636 | to choose a session from the log-in screen using @kbd{F1}. Packages such as |
| 6637 | @var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files; |
| 6638 | adding them to the system-wide set of packages automatically makes them |
| 6639 | available at the log-in screen. |
| 6640 | |
| 6641 | In addition, @file{~/.xsession} files are honored. When available, |
| 6642 | @file{~/.xsession} must be an executable that starts a window manager |
| 6643 | and/or other X clients. |
| 6644 | |
| 6645 | When @var{allow-empty-passwords?} is true, allow logins with an empty |
| 6646 | password. When @var{auto-login?} is true, log in automatically as |
| 6647 | @var{default-user}. |
| 6648 | |
| 6649 | If @var{theme} is @code{#f}, the use the default log-in theme; otherwise |
| 6650 | @var{theme} must be a gexp denoting the name of a directory containing the |
| 6651 | theme to use. In that case, @var{theme-name} specifies the name of the |
| 6652 | theme. |
| 6653 | @end deffn |
| 6654 | |
| 6655 | @defvr {Scheme Variable} %default-theme |
| 6656 | @defvrx {Scheme Variable} %default-theme-name |
| 6657 | The G-Expression denoting the default SLiM theme and its name. |
| 6658 | @end defvr |
| 6659 | |
| 6660 | @deffn {Scheme Procedure} xorg-start-command [#:guile] @ |
| 6661 | [#:configuration-file #f] [#:xorg-server @var{xorg-server}] |
| 6662 | Return a derivation that builds a @var{guile} script to start the X server |
| 6663 | from @var{xorg-server}. @var{configuration-file} is the server configuration |
| 6664 | file or a derivation that builds it; when omitted, the result of |
| 6665 | @code{xorg-configuration-file} is used. |
| 6666 | |
| 6667 | Usually the X server is started by a login manager. |
| 6668 | @end deffn |
| 6669 | |
| 6670 | @deffn {Scheme Procedure} xorg-configuration-file @ |
| 6671 | [#:drivers '()] [#:resolutions '()] [#:extra-config '()] |
| 6672 | Return a configuration file for the Xorg server containing search paths for |
| 6673 | all the common drivers. |
| 6674 | |
| 6675 | @var{drivers} must be either the empty list, in which case Xorg chooses a |
| 6676 | graphics driver automatically, or a list of driver names that will be tried in |
| 6677 | this order---e.g., @code{(\"modesetting\" \"vesa\")}. |
| 6678 | |
| 6679 | Likewise, when @var{resolutions} is the empty list, Xorg chooses an |
| 6680 | appropriate screen resolution; otherwise, it must be a list of |
| 6681 | resolutions---e.g., @code{((1024 768) (640 480))}. |
| 6682 | |
| 6683 | Last, @var{extra-config} is a list of strings or objects appended to the |
| 6684 | @code{text-file*} argument list. It is used to pass extra text to be added |
| 6685 | verbatim to the configuration file. |
| 6686 | @end deffn |
| 6687 | |
| 6688 | @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}] |
| 6689 | Add @var{package}, a package for a screen-locker or screen-saver whose |
| 6690 | command is @var{program}, to the set of setuid programs and add a PAM entry |
| 6691 | for it. For example: |
| 6692 | |
| 6693 | @lisp |
| 6694 | (screen-locker-service xlockmore "xlock") |
| 6695 | @end lisp |
| 6696 | |
| 6697 | makes the good ol' XlockMore usable. |
| 6698 | @end deffn |
| 6699 | |
| 6700 | |
| 6701 | @node Desktop Services |
| 6702 | @subsubsection Desktop Services |
| 6703 | |
| 6704 | The @code{(gnu services desktop)} module provides services that are |
| 6705 | usually useful in the context of a ``desktop'' setup---that is, on a |
| 6706 | machine running a graphical display server, possibly with graphical user |
| 6707 | interfaces, etc. |
| 6708 | |
| 6709 | To simplify things, the module defines a variable containing the set of |
| 6710 | services that users typically expect on a machine with a graphical |
| 6711 | environment and networking: |
| 6712 | |
| 6713 | @defvr {Scheme Variable} %desktop-services |
| 6714 | This is a list of services that builds upon @var{%base-services} and |
| 6715 | adds or adjust services for a typical ``desktop'' setup. |
| 6716 | |
| 6717 | In particular, it adds a graphical login manager (@pxref{X Window, |
| 6718 | @code{slim-service}}), screen lockers, |
| 6719 | a network management tool (@pxref{Networking |
| 6720 | Services, @code{wicd-service}}), energy and color management services, |
| 6721 | the @code{elogind} login and seat manager, the Polkit privilege service, |
| 6722 | the GeoClue location service, an NTP client (@pxref{Networking |
| 6723 | Services}), the Avahi daemon, and has the name service switch service |
| 6724 | configured to be able to use @code{nss-mdns} (@pxref{Name Service |
| 6725 | Switch, mDNS}). |
| 6726 | @end defvr |
| 6727 | |
| 6728 | The @var{%desktop-services} variable can be used as the @code{services} |
| 6729 | field of an @code{operating-system} declaration (@pxref{operating-system |
| 6730 | Reference, @code{services}}). |
| 6731 | |
| 6732 | The actual service definitions provided by @code{(gnu services dbus)} |
| 6733 | and @code{(gnu services desktop)} are described below. |
| 6734 | |
| 6735 | @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] |
| 6736 | Return a service that runs the ``system bus'', using @var{dbus}, with |
| 6737 | support for @var{services}. |
| 6738 | |
| 6739 | @uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication |
| 6740 | facility. Its system bus is used to allow system services to communicate |
| 6741 | and be notified of system-wide events. |
| 6742 | |
| 6743 | @var{services} must be a list of packages that provide an |
| 6744 | @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration |
| 6745 | and policy files. For example, to allow avahi-daemon to use the system bus, |
| 6746 | @var{services} must be equal to @code{(list avahi)}. |
| 6747 | @end deffn |
| 6748 | |
| 6749 | @deffn {Scheme Procedure} elogind-service [#:config @var{config}] |
| 6750 | Return a service that runs the @code{elogind} login and |
| 6751 | seat management daemon. @uref{https://github.com/andywingo/elogind, |
| 6752 | Elogind} exposes a D-Bus interface that can be used to know which users |
| 6753 | are logged in, know what kind of sessions they have open, suspend the |
| 6754 | system, inhibit system suspend, reboot the system, and other tasks. |
| 6755 | |
| 6756 | Elogind handles most system-level power events for a computer, for |
| 6757 | example suspending the system when a lid is closed, or shutting it down |
| 6758 | when the power button is pressed. |
| 6759 | |
| 6760 | The @var{config} keyword argument specifies the configuration for |
| 6761 | elogind, and should be the result of a @code{(elogind-configuration |
| 6762 | (@var{parameter} @var{value})...)} invocation. Available parameters and |
| 6763 | their default values are: |
| 6764 | |
| 6765 | @table @code |
| 6766 | @item kill-user-processes? |
| 6767 | @code{#f} |
| 6768 | @item kill-only-users |
| 6769 | @code{()} |
| 6770 | @item kill-exclude-users |
| 6771 | @code{("root")} |
| 6772 | @item inhibit-delay-max-seconds |
| 6773 | @code{5} |
| 6774 | @item handle-power-key |
| 6775 | @code{poweroff} |
| 6776 | @item handle-suspend-key |
| 6777 | @code{suspend} |
| 6778 | @item handle-hibernate-key |
| 6779 | @code{hibernate} |
| 6780 | @item handle-lid-switch |
| 6781 | @code{suspend} |
| 6782 | @item handle-lid-switch-docked |
| 6783 | @code{ignore} |
| 6784 | @item power-key-ignore-inhibited? |
| 6785 | @code{#f} |
| 6786 | @item suspend-key-ignore-inhibited? |
| 6787 | @code{#f} |
| 6788 | @item hibernate-key-ignore-inhibited? |
| 6789 | @code{#f} |
| 6790 | @item lid-switch-ignore-inhibited? |
| 6791 | @code{#t} |
| 6792 | @item holdoff-timeout-seconds |
| 6793 | @code{30} |
| 6794 | @item idle-action |
| 6795 | @code{ignore} |
| 6796 | @item idle-action-seconds |
| 6797 | @code{(* 30 60)} |
| 6798 | @item runtime-directory-size-percent |
| 6799 | @code{10} |
| 6800 | @item runtime-directory-size |
| 6801 | @code{#f} |
| 6802 | @item remove-ipc? |
| 6803 | @code{#t} |
| 6804 | @item suspend-state |
| 6805 | @code{("mem" "standby" "freeze")} |
| 6806 | @item suspend-mode |
| 6807 | @code{()} |
| 6808 | @item hibernate-state |
| 6809 | @code{("disk")} |
| 6810 | @item hibernate-mode |
| 6811 | @code{("platform" "shutdown")} |
| 6812 | @item hybrid-sleep-state |
| 6813 | @code{("disk")} |
| 6814 | @item hybrid-sleep-mode |
| 6815 | @code{("suspend" "platform" "shutdown")} |
| 6816 | @end table |
| 6817 | @end deffn |
| 6818 | |
| 6819 | @deffn {Scheme Procedure} polkit-service @ |
| 6820 | [#:polkit @var{polkit}] |
| 6821 | Return a service that runs the |
| 6822 | @uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege |
| 6823 | management service}, which allows system administrators to grant access to |
| 6824 | privileged operations in a structured way. By querying the Polkit service, a |
| 6825 | privileged system component can know when it should grant additional |
| 6826 | capabilities to ordinary users. For example, an ordinary user can be granted |
| 6827 | the capability to suspend the system if the user is logged in locally. |
| 6828 | @end deffn |
| 6829 | |
| 6830 | @deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @ |
| 6831 | [#:watts-up-pro? #f] @ |
| 6832 | [#:poll-batteries? #t] @ |
| 6833 | [#:ignore-lid? #f] @ |
| 6834 | [#:use-percentage-for-policy? #f] @ |
| 6835 | [#:percentage-low 10] @ |
| 6836 | [#:percentage-critical 3] @ |
| 6837 | [#:percentage-action 2] @ |
| 6838 | [#:time-low 1200] @ |
| 6839 | [#:time-critical 300] @ |
| 6840 | [#:time-action 120] @ |
| 6841 | [#:critical-power-action 'hybrid-sleep] |
| 6842 | Return a service that runs @uref{http://upower.freedesktop.org/, |
| 6843 | @command{upowerd}}, a system-wide monitor for power consumption and battery |
| 6844 | levels, with the given configuration settings. It implements the |
| 6845 | @code{org.freedesktop.UPower} D-Bus interface, and is notably used by |
| 6846 | GNOME. |
| 6847 | @end deffn |
| 6848 | |
| 6849 | @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] |
| 6850 | Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, |
| 6851 | UDisks}, a @dfn{disk management} daemon that provides user interfaces with |
| 6852 | notifications and ways to mount/unmount disks. Programs that talk to UDisks |
| 6853 | include the @command{udisksctl} command, part of UDisks, and GNOME Disks. |
| 6854 | @end deffn |
| 6855 | |
| 6856 | @deffn {Scheme Procedure} colord-service [#:colord @var{colord}] |
| 6857 | Return a service that runs @command{colord}, a system service with a D-Bus |
| 6858 | interface to manage the color profiles of input and output devices such as |
| 6859 | screens and scanners. It is notably used by the GNOME Color Manager graphical |
| 6860 | tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web |
| 6861 | site} for more information. |
| 6862 | @end deffn |
| 6863 | |
| 6864 | @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] |
| 6865 | Return an configuration allowing an application to access GeoClue |
| 6866 | location data. @var{name} is the Desktop ID of the application, without |
| 6867 | the @code{.desktop} part. If @var{allowed?} is true, the application |
| 6868 | will have access to location information by default. The boolean |
| 6869 | @var{system?} value indicates that an application is a system component |
| 6870 | or not. Finally @var{users} is a list of UIDs of all users for which |
| 6871 | this application is allowed location info access. An empty users list |
| 6872 | means that all users are allowed. |
| 6873 | @end deffn |
| 6874 | |
| 6875 | @defvr {Scheme Variable} %standard-geoclue-applications |
| 6876 | The standard list of well-known GeoClue application configurations, |
| 6877 | granting authority to GNOME's date-and-time utility to ask for the |
| 6878 | current location in order to set the time zone, and allowing the Firefox |
| 6879 | (IceCat) and Epiphany web browsers to request location information. |
| 6880 | Firefox and Epiphany both query the user before allowing a web page to |
| 6881 | know the user's location. |
| 6882 | @end defvr |
| 6883 | |
| 6884 | @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ |
| 6885 | [#:whitelist '()] @ |
| 6886 | [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ |
| 6887 | [#:submit-data? #f] |
| 6888 | [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @ |
| 6889 | [#:submission-nick "geoclue"] @ |
| 6890 | [#:applications %standard-geoclue-applications] |
| 6891 | Return a service that runs the GeoClue location service. This service |
| 6892 | provides a D-Bus interface to allow applications to request access to a |
| 6893 | user's physical location, and optionally to add information to online |
| 6894 | location databases. See |
| 6895 | @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue |
| 6896 | web site} for more information. |
| 6897 | @end deffn |
| 6898 | |
| 6899 | @node Database Services |
| 6900 | @subsubsection Database Services |
| 6901 | |
| 6902 | The @code{(gnu services databases)} module provides the following service. |
| 6903 | |
| 6904 | @deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @ |
| 6905 | [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] |
| 6906 | Return a service that runs @var{postgresql}, the PostgreSQL database |
| 6907 | server. |
| 6908 | |
| 6909 | The PostgreSQL daemon loads its runtime configuration from |
| 6910 | @var{config-file} and stores the database cluster in |
| 6911 | @var{data-directory}. |
| 6912 | @end deffn |
| 6913 | |
| 6914 | @node Web Services |
| 6915 | @subsubsection Web Services |
| 6916 | |
| 6917 | The @code{(gnu services web)} module provides the following service: |
| 6918 | |
| 6919 | @deffn {Scheme Procedure} nginx-service [#:nginx nginx] @ |
| 6920 | [#:log-directory ``/var/log/nginx''] @ |
| 6921 | [#:run-directory ``/var/run/nginx''] @ |
| 6922 | [#:config-file] |
| 6923 | |
| 6924 | Return a service that runs @var{nginx}, the nginx web server. |
| 6925 | |
| 6926 | The nginx daemon loads its runtime configuration from @var{config-file}. |
| 6927 | Log files are written to @var{log-directory} and temporary runtime data |
| 6928 | files are written to @var{run-directory}. For proper operation, these |
| 6929 | arguments should match what is in @var{config-file} to ensure that the |
| 6930 | directories are created when the service is activated. |
| 6931 | |
| 6932 | @end deffn |
| 6933 | |
| 6934 | @node Various Services |
| 6935 | @subsubsection Various Services |
| 6936 | |
| 6937 | The @code{(gnu services lirc)} module provides the following service. |
| 6938 | |
| 6939 | @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ |
| 6940 | [#:device #f] [#:driver #f] [#:config-file #f] @ |
| 6941 | [#:extra-options '()] |
| 6942 | Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that |
| 6943 | decodes infrared signals from remote controls. |
| 6944 | |
| 6945 | Optionally, @var{device}, @var{driver} and @var{config-file} |
| 6946 | (configuration file name) may be specified. See @command{lircd} manual |
| 6947 | for details. |
| 6948 | |
| 6949 | Finally, @var{extra-options} is a list of additional command-line options |
| 6950 | passed to @command{lircd}. |
| 6951 | @end deffn |
| 6952 | |
| 6953 | |
| 6954 | @node Setuid Programs |
| 6955 | @subsection Setuid Programs |
| 6956 | |
| 6957 | @cindex setuid programs |
| 6958 | Some programs need to run with ``root'' privileges, even when they are |
| 6959 | launched by unprivileged users. A notorious example is the |
| 6960 | @command{passwd} program, which users can run to change their |
| 6961 | password, and which needs to access the @file{/etc/passwd} and |
| 6962 | @file{/etc/shadow} files---something normally restricted to root, for |
| 6963 | obvious security reasons. To address that, these executables are |
| 6964 | @dfn{setuid-root}, meaning that they always run with root privileges |
| 6965 | (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual}, |
| 6966 | for more info about the setuid mechanisms.) |
| 6967 | |
| 6968 | The store itself @emph{cannot} contain setuid programs: that would be a |
| 6969 | security issue since any user on the system can write derivations that |
| 6970 | populate the store (@pxref{The Store}). Thus, a different mechanism is |
| 6971 | used: instead of changing the setuid bit directly on files that are in |
| 6972 | the store, we let the system administrator @emph{declare} which programs |
| 6973 | should be setuid root. |
| 6974 | |
| 6975 | The @code{setuid-programs} field of an @code{operating-system} |
| 6976 | declaration contains a list of G-expressions denoting the names of |
| 6977 | programs to be setuid-root (@pxref{Using the Configuration System}). |
| 6978 | For instance, the @command{passwd} program, which is part of the Shadow |
| 6979 | package, can be designated by this G-expression (@pxref{G-Expressions}): |
| 6980 | |
| 6981 | @example |
| 6982 | #~(string-append #$shadow "/bin/passwd") |
| 6983 | @end example |
| 6984 | |
| 6985 | A default set of setuid programs is defined by the |
| 6986 | @code{%setuid-programs} variable of the @code{(gnu system)} module. |
| 6987 | |
| 6988 | @defvr {Scheme Variable} %setuid-programs |
| 6989 | A list of G-expressions denoting common programs that are setuid-root. |
| 6990 | |
| 6991 | The list includes commands such as @command{passwd}, @command{ping}, |
| 6992 | @command{su}, and @command{sudo}. |
| 6993 | @end defvr |
| 6994 | |
| 6995 | Under the hood, the actual setuid programs are created in the |
| 6996 | @file{/run/setuid-programs} directory at system activation time. The |
| 6997 | files in this directory refer to the ``real'' binaries, which are in the |
| 6998 | store. |
| 6999 | |
| 7000 | @node X.509 Certificates |
| 7001 | @subsection X.509 Certificates |
| 7002 | |
| 7003 | @cindex HTTPS, certificates |
| 7004 | @cindex X.509 certificates |
| 7005 | @cindex TLS |
| 7006 | Web servers available over HTTPS (that is, HTTP over the transport-layer |
| 7007 | security mechanism, TLS) send client programs an @dfn{X.509 certificate} |
| 7008 | that the client can then use to @emph{authenticate} the server. To do |
| 7009 | that, clients verify that the server's certificate is signed by a |
| 7010 | so-called @dfn{certificate authority} (CA). But to verify the CA's |
| 7011 | signature, clients must have first acquired the CA's certificate. |
| 7012 | |
| 7013 | Web browsers such as GNU@tie{}IceCat include their own set of CA |
| 7014 | certificates, such that they are able to verify CA signatures |
| 7015 | out-of-the-box. |
| 7016 | |
| 7017 | However, most other programs that can talk HTTPS---@command{wget}, |
| 7018 | @command{git}, @command{w3m}, etc.---need to be told where CA |
| 7019 | certificates can be found. |
| 7020 | |
| 7021 | @cindex @code{nss-certs} |
| 7022 | In GuixSD, this is done by adding a package that provides certificates |
| 7023 | to the @code{packages} field of the @code{operating-system} declaration |
| 7024 | (@pxref{operating-system Reference}). GuixSD includes one such package, |
| 7025 | @code{nss-certs}, which is a set of CA certificates provided as part of |
| 7026 | Mozilla's Network Security Services. |
| 7027 | |
| 7028 | Note that it is @emph{not} part of @var{%base-packages}, so you need to |
| 7029 | explicitly add it. The @file{/etc/ssl/certs} directory, which is where |
| 7030 | most applications and libraries look for certificates by default, points |
| 7031 | to the certificates installed globally. |
| 7032 | |
| 7033 | Unprivileged users can also install their own certificate package in |
| 7034 | their profile. A number of environment variables need to be defined so |
| 7035 | that applications and libraries know where to find them. Namely, the |
| 7036 | OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE} |
| 7037 | variables. Some applications add their own environment variables; for |
| 7038 | instance, the Git version control system honors the certificate bundle |
| 7039 | pointed to by the @code{GIT_SSL_CAINFO} environment variable. |
| 7040 | |
| 7041 | |
| 7042 | @node Name Service Switch |
| 7043 | @subsection Name Service Switch |
| 7044 | |
| 7045 | @cindex name service switch |
| 7046 | @cindex NSS |
| 7047 | The @code{(gnu system nss)} module provides bindings to the |
| 7048 | configuration file of libc's @dfn{name service switch} or @dfn{NSS} |
| 7049 | (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference |
| 7050 | Manual}). In a nutshell, the NSS is a mechanism that allows libc to be |
| 7051 | extended with new ``name'' lookup methods for system databases, which |
| 7052 | includes host names, service names, user accounts, and more (@pxref{Name |
| 7053 | Service Switch, System Databases and Name Service Switch,, libc, The GNU |
| 7054 | C Library Reference Manual}). |
| 7055 | |
| 7056 | The NSS configuration specifies, for each system database, which lookup |
| 7057 | method is to be used, and how the various methods are chained |
| 7058 | together---for instance, under which circumstances NSS should try the |
| 7059 | next method in the list. The NSS configuration is given in the |
| 7060 | @code{name-service-switch} field of @code{operating-system} declarations |
| 7061 | (@pxref{operating-system Reference, @code{name-service-switch}}). |
| 7062 | |
| 7063 | @cindex nss-mdns |
| 7064 | @cindex .local, host name lookup |
| 7065 | As an example, the declaration below configures the NSS to use the |
| 7066 | @uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns} |
| 7067 | back-end}, which supports host name lookups over multicast DNS (mDNS) |
| 7068 | for host names ending in @code{.local}: |
| 7069 | |
| 7070 | @example |
| 7071 | (name-service-switch |
| 7072 | (hosts (list %files ;first, check /etc/hosts |
| 7073 | |
| 7074 | ;; If the above did not succeed, try |
| 7075 | ;; with 'mdns_minimal'. |
| 7076 | (name-service |
| 7077 | (name "mdns_minimal") |
| 7078 | |
| 7079 | ;; 'mdns_minimal' is authoritative for |
| 7080 | ;; '.local'. When it returns "not found", |
| 7081 | ;; no need to try the next methods. |
| 7082 | (reaction (lookup-specification |
| 7083 | (not-found => return)))) |
| 7084 | |
| 7085 | ;; Then fall back to DNS. |
| 7086 | (name-service |
| 7087 | (name "dns")) |
| 7088 | |
| 7089 | ;; Finally, try with the "full" 'mdns'. |
| 7090 | (name-service |
| 7091 | (name "mdns"))))) |
| 7092 | @end example |
| 7093 | |
| 7094 | Don't worry: the @code{%mdns-host-lookup-nss} variable (see below) |
| 7095 | contains this configuration, so you won't have to type it if all you |
| 7096 | want is to have @code{.local} host lookup working. |
| 7097 | |
| 7098 | Note that, in this case, in addition to setting the |
| 7099 | @code{name-service-switch} of the @code{operating-system} declaration, |
| 7100 | you also need to use @code{avahi-service} (@pxref{Networking Services, |
| 7101 | @code{avahi-service}}), or @var{%desktop-services}, which includes it |
| 7102 | (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible |
| 7103 | to the name service cache daemon (@pxref{Base Services, |
| 7104 | @code{nscd-service}}). |
| 7105 | |
| 7106 | For convenience, the following variables provide typical NSS |
| 7107 | configurations. |
| 7108 | |
| 7109 | @defvr {Scheme Variable} %default-nss |
| 7110 | This is the default name service switch configuration, a |
| 7111 | @code{name-service-switch} object. |
| 7112 | @end defvr |
| 7113 | |
| 7114 | @defvr {Scheme Variable} %mdns-host-lookup-nss |
| 7115 | This is the name service switch configuration with support for host name |
| 7116 | lookup over multicast DNS (mDNS) for host names ending in @code{.local}. |
| 7117 | @end defvr |
| 7118 | |
| 7119 | The reference for name service switch configuration is given below. It |
| 7120 | is a direct mapping of the C library's configuration file format, so |
| 7121 | please refer to the C library manual for more information (@pxref{NSS |
| 7122 | Configuration File,,, libc, The GNU C Library Reference Manual}). |
| 7123 | Compared to libc's NSS configuration file format, it has the advantage |
| 7124 | not only of adding this warm parenthetic feel that we like, but also |
| 7125 | static checks: you'll know about syntax errors and typos as soon as you |
| 7126 | run @command{guix system}. |
| 7127 | |
| 7128 | @deftp {Data Type} name-service-switch |
| 7129 | |
| 7130 | This is the data type representation the configuration of libc's name |
| 7131 | service switch (NSS). Each field below represents one of the supported |
| 7132 | system databases. |
| 7133 | |
| 7134 | @table @code |
| 7135 | @item aliases |
| 7136 | @itemx ethers |
| 7137 | @itemx group |
| 7138 | @itemx gshadow |
| 7139 | @itemx hosts |
| 7140 | @itemx initgroups |
| 7141 | @itemx netgroup |
| 7142 | @itemx networks |
| 7143 | @itemx password |
| 7144 | @itemx public-key |
| 7145 | @itemx rpc |
| 7146 | @itemx services |
| 7147 | @itemx shadow |
| 7148 | The system databases handled by the NSS. Each of these fields must be a |
| 7149 | list of @code{<name-service>} objects (see below.) |
| 7150 | @end table |
| 7151 | @end deftp |
| 7152 | |
| 7153 | @deftp {Data Type} name-service |
| 7154 | |
| 7155 | This is the data type representing an actual name service and the |
| 7156 | associated lookup action. |
| 7157 | |
| 7158 | @table @code |
| 7159 | @item name |
| 7160 | A string denoting the name service (@pxref{Services in the NSS |
| 7161 | configuration,,, libc, The GNU C Library Reference Manual}). |
| 7162 | |
| 7163 | Note that name services listed here must be visible to nscd. This is |
| 7164 | achieved by passing the @code{#:name-services} argument to |
| 7165 | @code{nscd-service} the list of packages providing the needed name |
| 7166 | services (@pxref{Base Services, @code{nscd-service}}). |
| 7167 | |
| 7168 | @item reaction |
| 7169 | An action specified using the @code{lookup-specification} macro |
| 7170 | (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library |
| 7171 | Reference Manual}). For example: |
| 7172 | |
| 7173 | @example |
| 7174 | (lookup-specification (unavailable => continue) |
| 7175 | (success => return)) |
| 7176 | @end example |
| 7177 | @end table |
| 7178 | @end deftp |
| 7179 | |
| 7180 | @node Initial RAM Disk |
| 7181 | @subsection Initial RAM Disk |
| 7182 | |
| 7183 | @cindex initial RAM disk (initrd) |
| 7184 | @cindex initrd (initial RAM disk) |
| 7185 | For bootstrapping purposes, the Linux-Libre kernel is passed an |
| 7186 | @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary |
| 7187 | root file system, as well as an initialization script. The latter is |
| 7188 | responsible for mounting the real root file system, and for loading any |
| 7189 | kernel modules that may be needed to achieve that. |
| 7190 | |
| 7191 | The @code{initrd} field of an @code{operating-system} declaration allows |
| 7192 | you to specify which initrd you would like to use. The @code{(gnu |
| 7193 | system linux-initrd)} module provides two ways to build an initrd: the |
| 7194 | high-level @code{base-initrd} procedure, and the low-level |
| 7195 | @code{expression->initrd} procedure. |
| 7196 | |
| 7197 | The @code{base-initrd} procedure is intended to cover most common uses. |
| 7198 | For example, if you want to add a bunch of kernel modules to be loaded |
| 7199 | at boot time, you can define the @code{initrd} field of the operating |
| 7200 | system declaration like this: |
| 7201 | |
| 7202 | @example |
| 7203 | (initrd (lambda (file-systems . rest) |
| 7204 | ;; Create a standard initrd that has modules "foo.ko" |
| 7205 | ;; and "bar.ko", as well as their dependencies, in |
| 7206 | ;; addition to the modules available by default. |
| 7207 | (apply base-initrd file-systems |
| 7208 | #:extra-modules '("foo" "bar") |
| 7209 | rest))) |
| 7210 | @end example |
| 7211 | |
| 7212 | The @code{base-initrd} procedure also handles common use cases that |
| 7213 | involves using the system as a QEMU guest, or as a ``live'' system whose |
| 7214 | root file system is volatile. |
| 7215 | |
| 7216 | @deffn {Monadic Procedure} base-initrd @var{file-systems} @ |
| 7217 | [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @ |
| 7218 | [#:extra-modules '()] [#:mapped-devices '()] |
| 7219 | Return a monadic derivation that builds a generic initrd. @var{file-systems} is |
| 7220 | a list of file-systems to be mounted by the initrd, possibly in addition to |
| 7221 | the root file system specified on the kernel command line via @code{--root}. |
| 7222 | @var{mapped-devices} is a list of device mappings to realize before |
| 7223 | @var{file-systems} are mounted (@pxref{Mapped Devices}). |
| 7224 | |
| 7225 | When @var{qemu-networking?} is true, set up networking with the standard QEMU |
| 7226 | parameters. When @var{virtio?} is true, load additional modules so the initrd can |
| 7227 | be used as a QEMU guest with para-virtualized I/O drivers. |
| 7228 | |
| 7229 | When @var{volatile-root?} is true, the root file system is writable but any changes |
| 7230 | to it are lost. |
| 7231 | |
| 7232 | The initrd is automatically populated with all the kernel modules necessary |
| 7233 | for @var{file-systems} and for the given options. However, additional kernel |
| 7234 | modules can be listed in @var{extra-modules}. They will be added to the initrd, and |
| 7235 | loaded at boot time in the order in which they appear. |
| 7236 | @end deffn |
| 7237 | |
| 7238 | Needless to say, the initrds we produce and use embed a |
| 7239 | statically-linked Guile, and the initialization program is a Guile |
| 7240 | program. That gives a lot of flexibility. The |
| 7241 | @code{expression->initrd} procedure builds such an initrd, given the |
| 7242 | program to run in that initrd. |
| 7243 | |
| 7244 | @deffn {Monadic Procedure} expression->initrd @var{exp} @ |
| 7245 | [#:guile %guile-static-stripped] [#:name "guile-initrd"] @ |
| 7246 | [#:modules '()] |
| 7247 | Return a derivation that builds a Linux initrd (a gzipped cpio archive) |
| 7248 | containing @var{guile} and that evaluates @var{exp}, a G-expression, |
| 7249 | upon booting. All the derivations referenced by @var{exp} are |
| 7250 | automatically copied to the initrd. |
| 7251 | |
| 7252 | @var{modules} is a list of Guile module names to be embedded in the |
| 7253 | initrd. |
| 7254 | @end deffn |
| 7255 | |
| 7256 | @node GRUB Configuration |
| 7257 | @subsection GRUB Configuration |
| 7258 | |
| 7259 | @cindex GRUB |
| 7260 | @cindex boot loader |
| 7261 | |
| 7262 | The operating system uses GNU@tie{}GRUB as its boot loader |
| 7263 | (@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is |
| 7264 | configured using @code{grub-configuration} declarations. This data type |
| 7265 | is exported by the @code{(gnu system grub)} module, and described below. |
| 7266 | |
| 7267 | @deftp {Data Type} grub-configuration |
| 7268 | The type of a GRUB configuration declaration. |
| 7269 | |
| 7270 | @table @asis |
| 7271 | |
| 7272 | @item @code{device} |
| 7273 | This is a string denoting the boot device. It must be a device name |
| 7274 | understood by the @command{grub-install} command, such as |
| 7275 | @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub, |
| 7276 | GNU GRUB Manual}). |
| 7277 | |
| 7278 | @item @code{menu-entries} (default: @code{()}) |
| 7279 | A possibly empty list of @code{menu-entry} objects (see below), denoting |
| 7280 | entries to appear in the GRUB boot menu, in addition to the current |
| 7281 | system entry and the entry pointing to previous system generations. |
| 7282 | |
| 7283 | @item @code{default-entry} (default: @code{0}) |
| 7284 | The index of the default boot menu entry. Index 0 is for the current |
| 7285 | system's entry. |
| 7286 | |
| 7287 | @item @code{timeout} (default: @code{5}) |
| 7288 | The number of seconds to wait for keyboard input before booting. Set to |
| 7289 | 0 to boot immediately, and to -1 to wait indefinitely. |
| 7290 | |
| 7291 | @item @code{theme} (default: @var{%default-theme}) |
| 7292 | The @code{grub-theme} object describing the theme to use. |
| 7293 | @end table |
| 7294 | |
| 7295 | @end deftp |
| 7296 | |
| 7297 | Should you want to list additional boot menu entries @i{via} the |
| 7298 | @code{menu-entries} field above, you will need to create them with the |
| 7299 | @code{menu-entry} form: |
| 7300 | |
| 7301 | @deftp {Data Type} menu-entry |
| 7302 | The type of an entry in the GRUB boot menu. |
| 7303 | |
| 7304 | @table @asis |
| 7305 | |
| 7306 | @item @code{label} |
| 7307 | The label to show in the menu---e.g., @code{"GNU"}. |
| 7308 | |
| 7309 | @item @code{linux} |
| 7310 | The Linux kernel to boot. |
| 7311 | |
| 7312 | @item @code{linux-arguments} (default: @code{()}) |
| 7313 | The list of extra Linux kernel command-line arguments---e.g., |
| 7314 | @code{("console=ttyS0")}. |
| 7315 | |
| 7316 | @item @code{initrd} |
| 7317 | A G-Expression or string denoting the file name of the initial RAM disk |
| 7318 | to use (@pxref{G-Expressions}). |
| 7319 | |
| 7320 | @end table |
| 7321 | @end deftp |
| 7322 | |
| 7323 | @c FIXME: Write documentation once it's stable. |
| 7324 | Themes are created using the @code{grub-theme} form, which is not |
| 7325 | documented yet. |
| 7326 | |
| 7327 | @defvr {Scheme Variable} %default-theme |
| 7328 | This is the default GRUB theme used by the operating system, with a |
| 7329 | fancy background image displaying the GNU and Guix logos. |
| 7330 | @end defvr |
| 7331 | |
| 7332 | |
| 7333 | @node Invoking guix system |
| 7334 | @subsection Invoking @code{guix system} |
| 7335 | |
| 7336 | Once you have written an operating system declaration, as seen in the |
| 7337 | previous section, it can be @dfn{instantiated} using the @command{guix |
| 7338 | system} command. The synopsis is: |
| 7339 | |
| 7340 | @example |
| 7341 | guix system @var{options}@dots{} @var{action} @var{file} |
| 7342 | @end example |
| 7343 | |
| 7344 | @var{file} must be the name of a file containing an |
| 7345 | @code{operating-system} declaration. @var{action} specifies how the |
| 7346 | operating system is instantiate. Currently the following values are |
| 7347 | supported: |
| 7348 | |
| 7349 | @table @code |
| 7350 | @item reconfigure |
| 7351 | Build the operating system described in @var{file}, activate it, and |
| 7352 | switch to it@footnote{This action is usable only on systems already |
| 7353 | running GuixSD.}. |
| 7354 | |
| 7355 | This effects all the configuration specified in @var{file}: user |
| 7356 | accounts, system services, global package list, setuid programs, etc. |
| 7357 | |
| 7358 | It also adds a GRUB menu entry for the new OS configuration, and moves |
| 7359 | entries for older configurations to a submenu---unless |
| 7360 | @option{--no-grub} is passed. |
| 7361 | |
| 7362 | @c The paragraph below refers to the problem discussed at |
| 7363 | @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. |
| 7364 | It is highly recommended to run @command{guix pull} once before you run |
| 7365 | @command{guix system reconfigure} for the first time (@pxref{Invoking |
| 7366 | guix pull}). Failing to do that you would see an older version of Guix |
| 7367 | once @command{reconfigure} has completed. |
| 7368 | |
| 7369 | @item build |
| 7370 | Build the operating system's derivation, which includes all the |
| 7371 | configuration files and programs needed to boot and run the system. |
| 7372 | This action does not actually install anything. |
| 7373 | |
| 7374 | @item init |
| 7375 | Populate the given directory with all the files necessary to run the |
| 7376 | operating system specified in @var{file}. This is useful for first-time |
| 7377 | installations of GuixSD. For instance: |
| 7378 | |
| 7379 | @example |
| 7380 | guix system init my-os-config.scm /mnt |
| 7381 | @end example |
| 7382 | |
| 7383 | copies to @file{/mnt} all the store items required by the configuration |
| 7384 | specified in @file{my-os-config.scm}. This includes configuration |
| 7385 | files, packages, and so on. It also creates other essential files |
| 7386 | needed for the system to operate correctly---e.g., the @file{/etc}, |
| 7387 | @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. |
| 7388 | |
| 7389 | This command also installs GRUB on the device specified in |
| 7390 | @file{my-os-config}, unless the @option{--no-grub} option was passed. |
| 7391 | |
| 7392 | @item vm |
| 7393 | @cindex virtual machine |
| 7394 | @cindex VM |
| 7395 | @anchor{guix system vm} |
| 7396 | Build a virtual machine that contain the operating system declared in |
| 7397 | @var{file}, and return a script to run that virtual machine (VM). |
| 7398 | Arguments given to the script are passed as is to QEMU. |
| 7399 | |
| 7400 | The VM shares its store with the host system. |
| 7401 | |
| 7402 | Additional file systems can be shared between the host and the VM using |
| 7403 | the @code{--share} and @code{--expose} command-line options: the former |
| 7404 | specifies a directory to be shared with write access, while the latter |
| 7405 | provides read-only access to the shared directory. |
| 7406 | |
| 7407 | The example below creates a VM in which the user's home directory is |
| 7408 | accessible read-only, and where the @file{/exchange} directory is a |
| 7409 | read-write mapping of the host's @file{$HOME/tmp}: |
| 7410 | |
| 7411 | @example |
| 7412 | guix system vm my-config.scm \ |
| 7413 | --expose=$HOME --share=$HOME/tmp=/exchange |
| 7414 | @end example |
| 7415 | |
| 7416 | On GNU/Linux, the default is to boot directly to the kernel; this has |
| 7417 | the advantage of requiring only a very tiny root disk image since the |
| 7418 | host's store can then be mounted. |
| 7419 | |
| 7420 | The @code{--full-boot} option forces a complete boot sequence, starting |
| 7421 | with the bootloader. This requires more disk space since a root image |
| 7422 | containing at least the kernel, initrd, and bootloader data files must |
| 7423 | be created. The @code{--image-size} option can be used to specify the |
| 7424 | image's size. |
| 7425 | |
| 7426 | @item vm-image |
| 7427 | @itemx disk-image |
| 7428 | Return a virtual machine or disk image of the operating system declared |
| 7429 | in @var{file} that stands alone. Use the @option{--image-size} option |
| 7430 | to specify the size of the image. |
| 7431 | |
| 7432 | When using @code{vm-image}, the returned image is in qcow2 format, which |
| 7433 | the QEMU emulator can efficiently use. |
| 7434 | |
| 7435 | When using @code{disk-image}, a raw disk image is produced; it can be |
| 7436 | copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is |
| 7437 | the device corresponding to a USB stick, one can copy the image on it |
| 7438 | using the following command: |
| 7439 | |
| 7440 | @example |
| 7441 | # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc |
| 7442 | @end example |
| 7443 | |
| 7444 | @item container |
| 7445 | Return a script to run the operating system declared in @var{file} |
| 7446 | within a container. Containers are a set of lightweight isolation |
| 7447 | mechanisms provided by the kernel Linux-libre. Containers are |
| 7448 | substantially less resource-demanding than full virtual machines since |
| 7449 | the kernel, shared objects, and other resources can be shared with the |
| 7450 | host system; this also means they provide thinner isolation. |
| 7451 | |
| 7452 | Currently, the script must be run as root in order to support more than |
| 7453 | a single user and group. The container shares its store with the host |
| 7454 | system. |
| 7455 | |
| 7456 | As with the @code{vm} action (@pxref{guix system vm}), additional file |
| 7457 | systems to be shared between the host and container can be specified |
| 7458 | using the @option{--share} and @option{--expose} options: |
| 7459 | |
| 7460 | @example |
| 7461 | guix system container my-config.scm \ |
| 7462 | --expose=$HOME --share=$HOME/tmp=/exchange |
| 7463 | @end example |
| 7464 | |
| 7465 | @quotation Note |
| 7466 | This option requires Linux-libre 3.19 or newer. |
| 7467 | @end quotation |
| 7468 | |
| 7469 | @end table |
| 7470 | |
| 7471 | @var{options} can contain any of the common build options provided by |
| 7472 | @command{guix build} (@pxref{Invoking guix build}). In addition, |
| 7473 | @var{options} can contain one of the following: |
| 7474 | |
| 7475 | @table @option |
| 7476 | @item --system=@var{system} |
| 7477 | @itemx -s @var{system} |
| 7478 | Attempt to build for @var{system} instead of the host's system type. |
| 7479 | This works as per @command{guix build} (@pxref{Invoking guix build}). |
| 7480 | |
| 7481 | @item --derivation |
| 7482 | @itemx -d |
| 7483 | Return the derivation file name of the given operating system without |
| 7484 | building anything. |
| 7485 | |
| 7486 | @item --image-size=@var{size} |
| 7487 | For the @code{vm-image} and @code{disk-image} actions, create an image |
| 7488 | of the given @var{size}. @var{size} may be a number of bytes, or it may |
| 7489 | include a unit as a suffix (@pxref{Block size, size specifications,, |
| 7490 | coreutils, GNU Coreutils}). |
| 7491 | |
| 7492 | @item --on-error=@var{strategy} |
| 7493 | Apply @var{strategy} when an error occurs when reading @var{file}. |
| 7494 | @var{strategy} may be one of the following: |
| 7495 | |
| 7496 | @table @code |
| 7497 | @item nothing-special |
| 7498 | Report the error concisely and exit. This is the default strategy. |
| 7499 | |
| 7500 | @item backtrace |
| 7501 | Likewise, but also display a backtrace. |
| 7502 | |
| 7503 | @item debug |
| 7504 | Report the error and enter Guile's debugger. From there, you can run |
| 7505 | commands such as @code{,bt} to get a backtrace, @code{,locals} to |
| 7506 | display local variable values, and more generally inspect the program's |
| 7507 | state. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for |
| 7508 | a list of available debugging commands. |
| 7509 | @end table |
| 7510 | @end table |
| 7511 | |
| 7512 | Note that all the actions above, except @code{build} and @code{init}, |
| 7513 | rely on KVM support in the Linux-Libre kernel. Specifically, the |
| 7514 | machine should have hardware virtualization support, the corresponding |
| 7515 | KVM kernel module should be loaded, and the @file{/dev/kvm} device node |
| 7516 | must exist and be readable and writable by the user and by the daemon's |
| 7517 | build users. |
| 7518 | |
| 7519 | Once you have built, configured, re-configured, and re-re-configured |
| 7520 | your GuixSD installation, you may find it useful to list the operating |
| 7521 | system generations available on disk---and that you can choose from the |
| 7522 | GRUB boot menu: |
| 7523 | |
| 7524 | @table @code |
| 7525 | |
| 7526 | @item list-generations |
| 7527 | List a summary of each generation of the operating system available on |
| 7528 | disk, in a human-readable way. This is similar to the |
| 7529 | @option{--list-generations} option of @command{guix package} |
| 7530 | (@pxref{Invoking guix package}). |
| 7531 | |
| 7532 | Optionally, one can specify a pattern, with the same syntax that is used |
| 7533 | in @command{guix package --list-generations}, to restrict the list of |
| 7534 | generations displayed. For instance, the following command displays |
| 7535 | generations up to 10-day old: |
| 7536 | |
| 7537 | @example |
| 7538 | $ guix system list-generations 10d |
| 7539 | @end example |
| 7540 | |
| 7541 | @end table |
| 7542 | |
| 7543 | The @command{guix system} command has even more to offer! The following |
| 7544 | sub-commands allow you to visualize how your system services relate to |
| 7545 | each other: |
| 7546 | |
| 7547 | @anchor{system-extension-graph} |
| 7548 | @table @code |
| 7549 | |
| 7550 | @item extension-graph |
| 7551 | Emit in Dot/Graphviz format to standard output the @dfn{service |
| 7552 | extension graph} of the operating system defined in @var{file} |
| 7553 | (@pxref{Service Composition}, for more information on service |
| 7554 | extensions.) |
| 7555 | |
| 7556 | The command: |
| 7557 | |
| 7558 | @example |
| 7559 | $ guix system extension-graph @var{file} | dot -Tpdf > services.pdf |
| 7560 | @end example |
| 7561 | |
| 7562 | produces a PDF file showing the extension relations among services. |
| 7563 | |
| 7564 | @anchor{system-dmd-graph} |
| 7565 | @item dmd-graph |
| 7566 | Emit in Dot/Graphviz format to standard output the @dfn{dependency |
| 7567 | graph} of dmd services of the operating system defined in @var{file}. |
| 7568 | @xref{dmd Services}, for more information and for an example graph. |
| 7569 | |
| 7570 | @end table |
| 7571 | |
| 7572 | |
| 7573 | @node Defining Services |
| 7574 | @subsection Defining Services |
| 7575 | |
| 7576 | The previous sections show the available services and how one can combine |
| 7577 | them in an @code{operating-system} declaration. But how do we define |
| 7578 | them in the first place? And what is a service anyway? |
| 7579 | |
| 7580 | @menu |
| 7581 | * Service Composition:: The model for composing services. |
| 7582 | * Service Types and Services:: Types and services. |
| 7583 | * Service Reference:: API reference. |
| 7584 | * dmd Services:: A particular type of service. |
| 7585 | @end menu |
| 7586 | |
| 7587 | @node Service Composition |
| 7588 | @subsubsection Service Composition |
| 7589 | |
| 7590 | @cindex services |
| 7591 | @cindex daemons |
| 7592 | Here we define a @dfn{service} as, broadly, something that extends the |
| 7593 | operating system's functionality. Often a service is a process---a |
| 7594 | @dfn{daemon}---started when the system boots: a secure shell server, a |
| 7595 | Web server, the Guix build daemon, etc. Sometimes a service is a daemon |
| 7596 | whose execution can be triggered by another daemon---e.g., an FTP server |
| 7597 | started by @command{inetd} or a D-Bus service activated by |
| 7598 | @command{dbus-daemon}. Occasionally, a service does not map to a |
| 7599 | daemon. For instance, the ``account'' service collects user accounts |
| 7600 | and makes sure they exist when the system runs; the ``udev'' service |
| 7601 | collects device management rules and makes them available to the eudev |
| 7602 | daemon; the @file{/etc} service populates the system's @file{/etc} |
| 7603 | directory. |
| 7604 | |
| 7605 | @cindex service extensions |
| 7606 | GuixSD services are connected by @dfn{extensions}. For instance, the |
| 7607 | secure shell service @emph{extends} dmd---GuixSD's initialization system, |
| 7608 | running as PID@tie{}1---by giving it the command lines to start and stop |
| 7609 | the secure shell daemon (@pxref{Networking Services, |
| 7610 | @code{lsh-service}}); the UPower service extends the D-Bus service by |
| 7611 | passing it its @file{.service} specification, and extends the udev |
| 7612 | service by passing it device management rules (@pxref{Desktop Services, |
| 7613 | @code{upower-service}}); the Guix daemon service extends dmd by passing |
| 7614 | it the command lines to start and stop the daemon, and extends the |
| 7615 | account service by passing it a list of required build user accounts |
| 7616 | (@pxref{Base Services}). |
| 7617 | |
| 7618 | All in all, services and their ``extends'' relations form a directed |
| 7619 | acyclic graph (DAG). If we represent services as boxes and extensions |
| 7620 | as arrows, a typical system might provide something like this: |
| 7621 | |
| 7622 | @image{images/service-graph,,5in,Typical service extension graph.} |
| 7623 | |
| 7624 | @cindex system service |
| 7625 | At the bottom, we see the @dfn{system service}, which produces the |
| 7626 | directory containing everything to run and boot the system, as returned |
| 7627 | by the @command{guix system build} command. @xref{Service Reference}, |
| 7628 | to learn about the other service types shown here. |
| 7629 | @xref{system-extension-graph, the @command{guix system extension-graph} |
| 7630 | command}, for information on how to generate this representation for a |
| 7631 | particular operating system definition. |
| 7632 | |
| 7633 | @cindex service types |
| 7634 | Technically, developers can define @dfn{service types} to express these |
| 7635 | relations. There can be any number of services of a given type on the |
| 7636 | system---for instance, a system running two instances of the GNU secure |
| 7637 | shell server (lsh) has two instances of @var{lsh-service-type}, with |
| 7638 | different parameters. |
| 7639 | |
| 7640 | The following section describes the programming interface for service |
| 7641 | types and services. |
| 7642 | |
| 7643 | @node Service Types and Services |
| 7644 | @subsubsection Service Types and Services |
| 7645 | |
| 7646 | A @dfn{service type} is a node in the DAG described above. Let us start |
| 7647 | with a simple example, the service type for the Guix build daemon |
| 7648 | (@pxref{Invoking guix-daemon}): |
| 7649 | |
| 7650 | @example |
| 7651 | (define guix-service-type |
| 7652 | (service-type |
| 7653 | (name 'guix) |
| 7654 | (extensions |
| 7655 | (list (service-extension dmd-root-service-type guix-dmd-service) |
| 7656 | (service-extension account-service-type guix-accounts) |
| 7657 | (service-extension activation-service-type guix-activation))))) |
| 7658 | @end example |
| 7659 | |
| 7660 | @noindent |
| 7661 | It defines a two things: |
| 7662 | |
| 7663 | @enumerate |
| 7664 | @item |
| 7665 | A name, whose sole purpose is to make inspection and debugging easier. |
| 7666 | |
| 7667 | @item |
| 7668 | A list of @dfn{service extensions}, where each extension designates the |
| 7669 | target service type and a procedure that, given the service's |
| 7670 | parameters, returns a list of object to extend the service of that type. |
| 7671 | |
| 7672 | Every service type has at least one service extension. The only |
| 7673 | exception is the @dfn{boot service type}, which is the ultimate service. |
| 7674 | @end enumerate |
| 7675 | |
| 7676 | In this example, @var{guix-service-type} extends three services: |
| 7677 | |
| 7678 | @table @var |
| 7679 | @item dmd-root-service-type |
| 7680 | The @var{guix-dmd-service} procedure defines how the dmd service is |
| 7681 | extended. Namely, it returns a @code{<dmd-service>} object that defines |
| 7682 | how @command{guix-daemon} is started and stopped (@pxref{dmd Services}). |
| 7683 | |
| 7684 | @item account-service-type |
| 7685 | This extension for this service is computed by @var{guix-accounts}, |
| 7686 | which returns a list of @code{user-group} and @code{user-account} |
| 7687 | objects representing the build user accounts (@pxref{Invoking |
| 7688 | guix-daemon}). |
| 7689 | |
| 7690 | @item activation-service-type |
| 7691 | Here @var{guix-activation} is a procedure that returns a gexp, which is |
| 7692 | a code snippet to run at ``activation time''---e.g., when the service is |
| 7693 | booted. |
| 7694 | @end table |
| 7695 | |
| 7696 | A service of this type is instantiated like this: |
| 7697 | |
| 7698 | @example |
| 7699 | (service guix-service-type |
| 7700 | (guix-configuration |
| 7701 | (build-accounts 5) |
| 7702 | (use-substitutes? #f))) |
| 7703 | @end example |
| 7704 | |
| 7705 | The second argument to the @code{service} form is a value representing |
| 7706 | the parameters of this specific service instance. |
| 7707 | @xref{guix-configuration-type, @code{guix-configuration}}, for |
| 7708 | information about the @code{guix-configuration} data type. |
| 7709 | |
| 7710 | @var{guix-service-type} is quite simple because it extends other |
| 7711 | services but is not extensible itself. |
| 7712 | |
| 7713 | @c @subsubsubsection Extensible Service Types |
| 7714 | |
| 7715 | The service type for an @emph{extensible} service looks like this: |
| 7716 | |
| 7717 | @example |
| 7718 | (define udev-service-type |
| 7719 | (service-type (name 'udev) |
| 7720 | (extensions |
| 7721 | (list (service-extension dmd-root-service-type |
| 7722 | udev-dmd-service))) |
| 7723 | |
| 7724 | (compose concatenate) ;concatenate the list of rules |
| 7725 | (extend (lambda (config rules) |
| 7726 | (match config |
| 7727 | (($ <udev-configuration> udev initial-rules) |
| 7728 | (udev-configuration |
| 7729 | (udev udev) ;the udev package to use |
| 7730 | (rules (append initial-rules rules))))))))) |
| 7731 | @end example |
| 7732 | |
| 7733 | This is the service type for the |
| 7734 | @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device |
| 7735 | management daemon}. Compared to the previous example, in addition to an |
| 7736 | extension of @var{dmd-root-service-type}, we see two new fields: |
| 7737 | |
| 7738 | @table @code |
| 7739 | @item compose |
| 7740 | This is the procedure to @dfn{compose} the list of extensions to |
| 7741 | services of this type. |
| 7742 | |
| 7743 | Services can extend the udev service by passing it lists of rules; we |
| 7744 | compose those extensions simply by concatenating them. |
| 7745 | |
| 7746 | @item extend |
| 7747 | This procedure defines how the service's value is @dfn{extended} with |
| 7748 | the composition of the extensions. |
| 7749 | |
| 7750 | Udev extensions are composed into a list of rules, but the udev service |
| 7751 | value is itself a @code{<udev-configuration>} record. So here, we |
| 7752 | extend that record by appending the list of rules is contains to the |
| 7753 | list of contributed rules. |
| 7754 | @end table |
| 7755 | |
| 7756 | There can be only one instance of an extensible service type such as |
| 7757 | @var{udev-service-type}. If there were more, the |
| 7758 | @code{service-extension} specifications would be ambiguous. |
| 7759 | |
| 7760 | Still here? The next section provides a reference of the programming |
| 7761 | interface for services. |
| 7762 | |
| 7763 | @node Service Reference |
| 7764 | @subsubsection Service Reference |
| 7765 | |
| 7766 | We have seen an overview of service types (@pxref{Service Types and |
| 7767 | Services}). This section provides a reference on how to manipulate |
| 7768 | services and service types. This interface is provided by the |
| 7769 | @code{(gnu services)} module. |
| 7770 | |
| 7771 | @deffn {Scheme Procedure} service @var{type} @var{value} |
| 7772 | Return a new service of @var{type}, a @code{<service-type>} object (see |
| 7773 | below.) @var{value} can be any object; it represents the parameters of |
| 7774 | this particular service instance. |
| 7775 | @end deffn |
| 7776 | |
| 7777 | @deffn {Scheme Procedure} service? @var{obj} |
| 7778 | Return true if @var{obj} is a service. |
| 7779 | @end deffn |
| 7780 | |
| 7781 | @deffn {Scheme Procedure} service-kind @var{service} |
| 7782 | Return the type of @var{service}---i.e., a @code{<service-type>} object. |
| 7783 | @end deffn |
| 7784 | |
| 7785 | @deffn {Scheme Procedure} service-parameters @var{service} |
| 7786 | Return the value associated with @var{service}. It represents its |
| 7787 | parameters. |
| 7788 | @end deffn |
| 7789 | |
| 7790 | Here is an example of how a service is created and manipulated: |
| 7791 | |
| 7792 | @example |
| 7793 | (define s |
| 7794 | (service nginx-service-type |
| 7795 | (nginx-configuration |
| 7796 | (nginx nginx) |
| 7797 | (log-directory log-directory) |
| 7798 | (run-directory run-directory) |
| 7799 | (file config-file)))) |
| 7800 | |
| 7801 | (service? s) |
| 7802 | @result{} #t |
| 7803 | |
| 7804 | (eq? (service-kind s) nginx-service-type) |
| 7805 | @result{} #t |
| 7806 | @end example |
| 7807 | |
| 7808 | The @code{modify-services} form provides a handy way to change the |
| 7809 | parameters of some of the services of a list such as |
| 7810 | @var{%base-services} (@pxref{Base Services, @code{%base-services}}). Of |
| 7811 | course, you could always use standard list combinators such as |
| 7812 | @code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, |
| 7813 | guile, GNU Guile Reference Manual}); @code{modify-services} simply |
| 7814 | provides a more concise form for this common pattern. |
| 7815 | |
| 7816 | @deffn {Scheme Syntax} modify-services @var{services} @ |
| 7817 | (@var{type} @var{variable} => @var{body}) @dots{} |
| 7818 | |
| 7819 | Modify the services listed in @var{services} according to the given |
| 7820 | clauses. Each clause has the form: |
| 7821 | |
| 7822 | @example |
| 7823 | (@var{type} @var{variable} => @var{body}) |
| 7824 | @end example |
| 7825 | |
| 7826 | where @var{type} is a service type, such as @var{guix-service-type}, and |
| 7827 | @var{variable} is an identifier that is bound within @var{body} to the |
| 7828 | value of the service of that @var{type}. @xref{Using the Configuration |
| 7829 | System}, for an example. |
| 7830 | |
| 7831 | This is a shorthand for: |
| 7832 | |
| 7833 | @example |
| 7834 | (map (lambda (service) @dots{}) @var{services}) |
| 7835 | @end example |
| 7836 | @end deffn |
| 7837 | |
| 7838 | Next comes the programming interface for service types. This is |
| 7839 | something you want to know when writing new service definitions, but not |
| 7840 | necessarily when simply looking for ways to customize your |
| 7841 | @code{operating-system} declaration. |
| 7842 | |
| 7843 | @deftp {Data Type} service-type |
| 7844 | @cindex service type |
| 7845 | This is the representation of a @dfn{service type} (@pxref{Service Types |
| 7846 | and Services}). |
| 7847 | |
| 7848 | @table @asis |
| 7849 | @item @code{name} |
| 7850 | This is a symbol, used only to simplify inspection and debugging. |
| 7851 | |
| 7852 | @item @code{extensions} |
| 7853 | A non-empty list of @code{<service-extension>} objects (see below.) |
| 7854 | |
| 7855 | @item @code{compose} (default: @code{#f}) |
| 7856 | If this is @code{#f}, then the service type denotes services that cannot |
| 7857 | be extended---i.e., services that do not receive ``values'' from other |
| 7858 | services. |
| 7859 | |
| 7860 | Otherwise, it must be a one-argument procedure. The procedure is called |
| 7861 | by @code{fold-services} and is passed a list of values collected from |
| 7862 | extensions. It must return a value that is a valid parameter value for |
| 7863 | the service instance. |
| 7864 | |
| 7865 | @item @code{extend} (default: @code{#f}) |
| 7866 | If this is @code{#f}, services of this type cannot be extended. |
| 7867 | |
| 7868 | Otherwise, it must be a two-argument procedure: @code{fold-services} |
| 7869 | calls it, passing it the service's initial value as the first argument |
| 7870 | and the result of applying @code{compose} to the extension values as the |
| 7871 | second argument. |
| 7872 | @end table |
| 7873 | |
| 7874 | @xref{Service Types and Services}, for examples. |
| 7875 | @end deftp |
| 7876 | |
| 7877 | @deffn {Scheme Procedure} service-extension @var{target-type} @ |
| 7878 | @var{compute} |
| 7879 | Return a new extension for services of type @var{target-type}. |
| 7880 | @var{compute} must be a one-argument procedure: @code{fold-services} |
| 7881 | calls it, passing it the value associated with the service that provides |
| 7882 | the extension; it must return a valid value for the target service. |
| 7883 | @end deffn |
| 7884 | |
| 7885 | @deffn {Scheme Procedure} service-extension? @var{obj} |
| 7886 | Return true if @var{obj} is a service extension. |
| 7887 | @end deffn |
| 7888 | |
| 7889 | At the core of the service abstraction lies the @code{fold-services} |
| 7890 | procedure, which is responsible for ``compiling'' a list of services |
| 7891 | down to a single directory that contains everything needed to boot and |
| 7892 | run the system---the directory shown by the @command{guix system build} |
| 7893 | command (@pxref{Invoking guix system}). In essence, it propagates |
| 7894 | service extensions down the service graph, updating each node parameters |
| 7895 | on the way, until it reaches the root node. |
| 7896 | |
| 7897 | @deffn {Scheme Procedure} fold-services @var{services} @ |
| 7898 | [#:target-type @var{system-service-type}] |
| 7899 | Fold @var{services} by propagating their extensions down to the root of |
| 7900 | type @var{target-type}; return the root service adjusted accordingly. |
| 7901 | @end deffn |
| 7902 | |
| 7903 | Lastly, the @code{(gnu services)} module also defines several essential |
| 7904 | service types, some of which are listed below. |
| 7905 | |
| 7906 | @defvr {Scheme Variable} system-service-type |
| 7907 | This is the root of the service graph. It produces the system directory |
| 7908 | as returned by the @command{guix system build} command. |
| 7909 | @end defvr |
| 7910 | |
| 7911 | @defvr {Scheme Variable} boot-service-type |
| 7912 | The type of the ``boot service'', which produces the @dfn{boot script}. |
| 7913 | The boot script is what the initial RAM disk runs when booting. |
| 7914 | @end defvr |
| 7915 | |
| 7916 | @defvr {Scheme Variable} etc-service-type |
| 7917 | The type of the @file{/etc} service. This service can be extended by |
| 7918 | passing it name/file tuples such as: |
| 7919 | |
| 7920 | @example |
| 7921 | (list `("issue" ,(plain-file "issue" "Welcome!\n"))) |
| 7922 | @end example |
| 7923 | |
| 7924 | In this example, the effect would be to add an @file{/etc/issue} file |
| 7925 | pointing to the given file. |
| 7926 | @end defvr |
| 7927 | |
| 7928 | @defvr {Scheme Variable} setuid-program-service-type |
| 7929 | Type for the ``setuid-program service''. This service collects lists of |
| 7930 | executable file names, passed as gexps, and adds them to the set of |
| 7931 | setuid-root programs on the system (@pxref{Setuid Programs}). |
| 7932 | @end defvr |
| 7933 | |
| 7934 | @defvr {Scheme Variable} profile-service-type |
| 7935 | Type of the service that populates the @dfn{system profile}---i.e., the |
| 7936 | programs under @file{/run/current-system/profile}. Other services can |
| 7937 | extend it by passing it lists of packages to add to the system profile. |
| 7938 | @end defvr |
| 7939 | |
| 7940 | |
| 7941 | @node dmd Services |
| 7942 | @subsubsection dmd Services |
| 7943 | |
| 7944 | @cindex PID 1 |
| 7945 | @cindex init system |
| 7946 | The @code{(gnu services dmd)} provides a way to define services managed |
| 7947 | by GNU@tie{}dmd, which is GuixSD initialization system---the first |
| 7948 | process that is started when the system boots, aka. PID@tie{}1 |
| 7949 | (@pxref{Introduction,,, dmd, GNU dmd Manual}). |
| 7950 | |
| 7951 | Services in dmd can depend on each other. For instance, the SSH daemon |
| 7952 | may need to be started after the syslog daemon has been started, which |
| 7953 | in turn can only happen once all the file systems have been mounted. |
| 7954 | The simple operating system defined earlier (@pxref{Using the |
| 7955 | Configuration System}) results in a service graph like this: |
| 7956 | |
| 7957 | @image{images/dmd-graph,,5in,Typical dmd service graph.} |
| 7958 | |
| 7959 | You can actually generate such a graph for any operating system |
| 7960 | definition using the @command{guix system dmd-graph} command |
| 7961 | (@pxref{system-dmd-graph, @command{guix system dmd-graph}}). |
| 7962 | |
| 7963 | The @var{%dmd-root-service} is a service object representing PID@tie{}1, |
| 7964 | of type @var{dmd-root-service-type}; it can be extended by passing it |
| 7965 | lists of @code{<dmd-service>} objects. |
| 7966 | |
| 7967 | @deftp {Data Type} dmd-service |
| 7968 | The data type representing a service managed by dmd. |
| 7969 | |
| 7970 | @table @asis |
| 7971 | @item @code{provision} |
| 7972 | This is a list of symbols denoting what the service provides. |
| 7973 | |
| 7974 | These are the names that may be passed to @command{deco start}, |
| 7975 | @command{deco status}, and similar commands (@pxref{Invoking deco,,, |
| 7976 | dmd, GNU dmd Manual}). @xref{Slots of services, the @code{provides} |
| 7977 | slot,, dmd, GNU dmd Manual}, for details. |
| 7978 | |
| 7979 | @item @code{requirements} (default: @code{'()}) |
| 7980 | List of symbols denoting the dmd services this one depends on. |
| 7981 | |
| 7982 | @item @code{respawn?} (default: @code{#t}) |
| 7983 | Whether to restart the service when it stops, for instance when the |
| 7984 | underlying process dies. |
| 7985 | |
| 7986 | @item @code{start} |
| 7987 | @itemx @code{stop} (default: @code{#~(const #f)}) |
| 7988 | The @code{start} and @code{stop} fields refer to dmd's facilities to |
| 7989 | start and stop processes (@pxref{Service De- and Constructors,,, dmd, |
| 7990 | GNU dmd Manual}). They are given as G-expressions that get expanded in |
| 7991 | the dmd configuration file (@pxref{G-Expressions}). |
| 7992 | |
| 7993 | @item @code{documentation} |
| 7994 | A documentation string, as shown when running: |
| 7995 | |
| 7996 | @example |
| 7997 | deco doc @var{service-name} |
| 7998 | @end example |
| 7999 | |
| 8000 | where @var{service-name} is one of the symbols in @var{provision} |
| 8001 | (@pxref{Invoking deco,,, dmd, GNU dmd Manual}). |
| 8002 | @end table |
| 8003 | @end deftp |
| 8004 | |
| 8005 | @defvr {Scheme Variable} dmd-root-service-type |
| 8006 | The service type for the dmd ``root service''---i.e., PID@tie{}1. |
| 8007 | |
| 8008 | This is the service type that extensions target when they want to create |
| 8009 | dmd services (@pxref{Service Types and Services}, for an example). Each |
| 8010 | extension must pass a list of @code{<dmd-service>}. |
| 8011 | @end defvr |
| 8012 | |
| 8013 | @defvr {Scheme Variable} %dmd-root-service |
| 8014 | This service represents PID@tie{}1. |
| 8015 | @end defvr |
| 8016 | |
| 8017 | |
| 8018 | @node Installing Debugging Files |
| 8019 | @section Installing Debugging Files |
| 8020 | |
| 8021 | @cindex debugging files |
| 8022 | Program binaries, as produced by the GCC compilers for instance, are |
| 8023 | typically written in the ELF format, with a section containing |
| 8024 | @dfn{debugging information}. Debugging information is what allows the |
| 8025 | debugger, GDB, to map binary code to source code; it is required to |
| 8026 | debug a compiled program in good conditions. |
| 8027 | |
| 8028 | The problem with debugging information is that is takes up a fair amount |
| 8029 | of disk space. For example, debugging information for the GNU C Library |
| 8030 | weighs in at more than 60 MiB. Thus, as a user, keeping all the |
| 8031 | debugging info of all the installed programs is usually not an option. |
| 8032 | Yet, space savings should not come at the cost of an impediment to |
| 8033 | debugging---especially in the GNU system, which should make it easier |
| 8034 | for users to exert their computing freedom (@pxref{GNU Distribution}). |
| 8035 | |
| 8036 | Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a |
| 8037 | mechanism that allows users to get the best of both worlds: debugging |
| 8038 | information can be stripped from the binaries and stored in separate |
| 8039 | files. GDB is then able to load debugging information from those files, |
| 8040 | when they are available (@pxref{Separate Debug Files,,, gdb, Debugging |
| 8041 | with GDB}). |
| 8042 | |
| 8043 | The GNU distribution takes advantage of this by storing debugging |
| 8044 | information in the @code{lib/debug} sub-directory of a separate package |
| 8045 | output unimaginatively called @code{debug} (@pxref{Packages with |
| 8046 | Multiple Outputs}). Users can choose to install the @code{debug} output |
| 8047 | of a package when they need it. For instance, the following command |
| 8048 | installs the debugging information for the GNU C Library and for GNU |
| 8049 | Guile: |
| 8050 | |
| 8051 | @example |
| 8052 | guix package -i glibc:debug guile:debug |
| 8053 | @end example |
| 8054 | |
| 8055 | GDB must then be told to look for debug files in the user's profile, by |
| 8056 | setting the @code{debug-file-directory} variable (consider setting it |
| 8057 | from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with |
| 8058 | GDB}): |
| 8059 | |
| 8060 | @example |
| 8061 | (gdb) set debug-file-directory ~/.guix-profile/lib/debug |
| 8062 | @end example |
| 8063 | |
| 8064 | From there on, GDB will pick up debugging information from the |
| 8065 | @code{.debug} files under @file{~/.guix-profile/lib/debug}. |
| 8066 | |
| 8067 | In addition, you will most likely want GDB to be able to show the source |
| 8068 | code being debugged. To do that, you will have to unpack the source |
| 8069 | code of the package of interest (obtained with @code{guix build |
| 8070 | --source}, @pxref{Invoking guix build}), and to point GDB to that source |
| 8071 | directory using the @code{directory} command (@pxref{Source Path, |
| 8072 | @code{directory},, gdb, Debugging with GDB}). |
| 8073 | |
| 8074 | @c XXX: keep me up-to-date |
| 8075 | The @code{debug} output mechanism in Guix is implemented by the |
| 8076 | @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is |
| 8077 | opt-in---debugging information is available only for those packages |
| 8078 | whose definition explicitly declares a @code{debug} output. This may be |
| 8079 | changed to opt-out in the future, if our build farm servers can handle |
| 8080 | the load. To check whether a package has a @code{debug} output, use |
| 8081 | @command{guix package --list-available} (@pxref{Invoking guix package}). |
| 8082 | |
| 8083 | |
| 8084 | @node Security Updates |
| 8085 | @section Security Updates |
| 8086 | |
| 8087 | @quotation Note |
| 8088 | As of version @value{VERSION}, the feature described in this section is |
| 8089 | experimental. |
| 8090 | @end quotation |
| 8091 | |
| 8092 | @cindex security updates |
| 8093 | Occasionally, important security vulnerabilities are discovered in core |
| 8094 | software packages and must be patched. Guix follows a functional |
| 8095 | package management discipline (@pxref{Introduction}), which implies |
| 8096 | that, when a package is changed, @emph{every package that depends on it} |
| 8097 | must be rebuilt. This can significantly slow down the deployment of |
| 8098 | fixes in core packages such as libc or Bash, since basically the whole |
| 8099 | distribution would need to be rebuilt. Using pre-built binaries helps |
| 8100 | (@pxref{Substitutes}), but deployment may still take more time than |
| 8101 | desired. |
| 8102 | |
| 8103 | @cindex grafts |
| 8104 | To address that, Guix implements @dfn{grafts}, a mechanism that allows |
| 8105 | for fast deployment of critical updates without the costs associated |
| 8106 | with a whole-distribution rebuild. The idea is to rebuild only the |
| 8107 | package that needs to be patched, and then to ``graft'' it onto packages |
| 8108 | explicitly installed by the user and that were previously referring to |
| 8109 | the original package. The cost of grafting is typically very low, and |
| 8110 | order of magnitudes lower than a full rebuild of the dependency chain. |
| 8111 | |
| 8112 | @cindex replacements of packages, for grafts |
| 8113 | For instance, suppose a security update needs to be applied to Bash. |
| 8114 | Guix developers will provide a package definition for the ``fixed'' |
| 8115 | Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining |
| 8116 | Packages}). Then, the original package definition is augmented with a |
| 8117 | @code{replacement} field pointing to the package containing the bug fix: |
| 8118 | |
| 8119 | @example |
| 8120 | (define bash |
| 8121 | (package |
| 8122 | (name "bash") |
| 8123 | ;; @dots{} |
| 8124 | (replacement bash-fixed))) |
| 8125 | @end example |
| 8126 | |
| 8127 | From there on, any package depending directly or indirectly on Bash that |
| 8128 | is installed will automatically be ``rewritten'' to refer to |
| 8129 | @var{bash-fixed} instead of @var{bash}. This grafting process takes |
| 8130 | time proportional to the size of the package, but expect less than a |
| 8131 | minute for an ``average'' package on a recent machine. |
| 8132 | |
| 8133 | Currently, the graft and the package it replaces (@var{bash-fixed} and |
| 8134 | @var{bash} in the example above) must have the exact same @code{name} |
| 8135 | and @code{version} fields. This restriction mostly comes from the fact |
| 8136 | that grafting works by patching files, including binary files, directly. |
| 8137 | Other restrictions may apply: for instance, when adding a graft to a |
| 8138 | package providing a shared library, the original shared library and its |
| 8139 | replacement must have the same @code{SONAME} and be binary-compatible. |
| 8140 | |
| 8141 | |
| 8142 | @node Package Modules |
| 8143 | @section Package Modules |
| 8144 | |
| 8145 | From a programming viewpoint, the package definitions of the |
| 8146 | GNU distribution are provided by Guile modules in the @code{(gnu packages |
| 8147 | @dots{})} name space@footnote{Note that packages under the @code{(gnu |
| 8148 | packages @dots{})} module name space are not necessarily ``GNU |
| 8149 | packages''. This module naming scheme follows the usual Guile module |
| 8150 | naming convention: @code{gnu} means that these modules are distributed |
| 8151 | as part of the GNU system, and @code{packages} identifies modules that |
| 8152 | define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile |
| 8153 | Reference Manual}). For instance, the @code{(gnu packages emacs)} |
| 8154 | module exports a variable named @code{emacs}, which is bound to a |
| 8155 | @code{<package>} object (@pxref{Defining Packages}). |
| 8156 | |
| 8157 | The @code{(gnu packages @dots{})} module name space is |
| 8158 | automatically scanned for packages by the command-line tools. For |
| 8159 | instance, when running @code{guix package -i emacs}, all the @code{(gnu |
| 8160 | packages @dots{})} modules are scanned until one that exports a package |
| 8161 | object whose name is @code{emacs} is found. This package search |
| 8162 | facility is implemented in the @code{(gnu packages)} module. |
| 8163 | |
| 8164 | @cindex customization, of packages |
| 8165 | @cindex package module search path |
| 8166 | Users can store package definitions in modules with different |
| 8167 | names---e.g., @code{(my-packages emacs)}@footnote{Note that the file |
| 8168 | name and module name must match. For instance, the @code{(my-packages |
| 8169 | emacs)} module must be stored in a @file{my-packages/emacs.scm} file |
| 8170 | relative to the load path specified with @option{--load-path} or |
| 8171 | @code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, |
| 8172 | guile, GNU Guile Reference Manual}, for details.}. These package definitions |
| 8173 | will not be visible by default. Thus, users can invoke commands such as |
| 8174 | @command{guix package} and @command{guix build} have to be used with the |
| 8175 | @code{-e} option so that they know where to find the package. Better |
| 8176 | yet, they can use the |
| 8177 | @code{-L} option of these commands to make those modules visible |
| 8178 | (@pxref{Invoking guix build, @code{--load-path}}), or define the |
| 8179 | @code{GUIX_PACKAGE_PATH} environment variable. This environment |
| 8180 | variable makes it easy to extend or customize the distribution and is |
| 8181 | honored by all the user interfaces. |
| 8182 | |
| 8183 | @defvr {Environment Variable} GUIX_PACKAGE_PATH |
| 8184 | This is a colon-separated list of directories to search for package |
| 8185 | modules. Directories listed in this variable take precedence over the |
| 8186 | distribution's own modules. |
| 8187 | @end defvr |
| 8188 | |
| 8189 | The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: |
| 8190 | each package is built based solely on other packages in the |
| 8191 | distribution. The root of this dependency graph is a small set of |
| 8192 | @dfn{bootstrap binaries}, provided by the @code{(gnu packages |
| 8193 | bootstrap)} module. For more information on bootstrapping, |
| 8194 | @pxref{Bootstrapping}. |
| 8195 | |
| 8196 | @node Packaging Guidelines |
| 8197 | @section Packaging Guidelines |
| 8198 | |
| 8199 | The GNU distribution is nascent and may well lack some of your favorite |
| 8200 | packages. This section describes how you can help make the distribution |
| 8201 | grow. @xref{Contributing}, for additional information on how you can |
| 8202 | help. |
| 8203 | |
| 8204 | Free software packages are usually distributed in the form of |
| 8205 | @dfn{source code tarballs}---typically @file{tar.gz} files that contain |
| 8206 | all the source files. Adding a package to the distribution means |
| 8207 | essentially two things: adding a @dfn{recipe} that describes how to |
| 8208 | build the package, including a list of other packages required to build |
| 8209 | it, and adding @dfn{package meta-data} along with that recipe, such as a |
| 8210 | description and licensing information. |
| 8211 | |
| 8212 | In Guix all this information is embodied in @dfn{package definitions}. |
| 8213 | Package definitions provide a high-level view of the package. They are |
| 8214 | written using the syntax of the Scheme programming language; in fact, |
| 8215 | for each package we define a variable bound to the package definition, |
| 8216 | and export that variable from a module (@pxref{Package Modules}). |
| 8217 | However, in-depth Scheme knowledge is @emph{not} a prerequisite for |
| 8218 | creating packages. For more information on package definitions, |
| 8219 | @pxref{Defining Packages}. |
| 8220 | |
| 8221 | Once a package definition is in place, stored in a file in the Guix |
| 8222 | source tree, it can be tested using the @command{guix build} command |
| 8223 | (@pxref{Invoking guix build}). For example, assuming the new package is |
| 8224 | called @code{gnew}, you may run this command from the Guix build tree |
| 8225 | (@pxref{Running Guix Before It Is Installed}): |
| 8226 | |
| 8227 | @example |
| 8228 | ./pre-inst-env guix build gnew --keep-failed |
| 8229 | @end example |
| 8230 | |
| 8231 | Using @code{--keep-failed} makes it easier to debug build failures since |
| 8232 | it provides access to the failed build tree. Another useful |
| 8233 | command-line option when debugging is @code{--log-file}, to access the |
| 8234 | build log. |
| 8235 | |
| 8236 | If the package is unknown to the @command{guix} command, it may be that |
| 8237 | the source file contains a syntax error, or lacks a @code{define-public} |
| 8238 | clause to export the package variable. To figure it out, you may load |
| 8239 | the module from Guile to get more information about the actual error: |
| 8240 | |
| 8241 | @example |
| 8242 | ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' |
| 8243 | @end example |
| 8244 | |
| 8245 | Once your package builds correctly, please send us a patch |
| 8246 | (@pxref{Contributing}). Well, if you need help, we will be happy to |
| 8247 | help you too. Once the patch is committed in the Guix repository, the |
| 8248 | new package automatically gets built on the supported platforms by |
| 8249 | @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration |
| 8250 | system}. |
| 8251 | |
| 8252 | @cindex substituter |
| 8253 | Users can obtain the new package definition simply by running |
| 8254 | @command{guix pull} (@pxref{Invoking guix pull}). When |
| 8255 | @code{hydra.gnu.org} is done building the package, installing the |
| 8256 | package automatically downloads binaries from there |
| 8257 | (@pxref{Substitutes}). The only place where human intervention is |
| 8258 | needed is to review and apply the patch. |
| 8259 | |
| 8260 | |
| 8261 | @menu |
| 8262 | * Software Freedom:: What may go into the distribution. |
| 8263 | * Package Naming:: What's in a name? |
| 8264 | * Version Numbers:: When the name is not enough. |
| 8265 | * Synopses and Descriptions:: Helping users find the right package. |
| 8266 | * Python Modules:: Taming the snake. |
| 8267 | * Perl Modules:: Little pearls. |
| 8268 | * Fonts:: Fond of fonts. |
| 8269 | @end menu |
| 8270 | |
| 8271 | @node Software Freedom |
| 8272 | @subsection Software Freedom |
| 8273 | |
| 8274 | @c Adapted from http://www.gnu.org/philosophy/philosophy.html. |
| 8275 | |
| 8276 | The GNU operating system has been developed so that users can have |
| 8277 | freedom in their computing. GNU is @dfn{free software}, meaning that |
| 8278 | users have the @url{http://www.gnu.org/philosophy/free-sw.html,four |
| 8279 | essential freedoms}: to run the program, to study and change the program |
| 8280 | in source code form, to redistribute exact copies, and to distribute |
| 8281 | modified versions. Packages found in the GNU distribution provide only |
| 8282 | software that conveys these four freedoms. |
| 8283 | |
| 8284 | In addition, the GNU distribution follow the |
| 8285 | @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free |
| 8286 | software distribution guidelines}. Among other things, these guidelines |
| 8287 | reject non-free firmware, recommendations of non-free software, and |
| 8288 | discuss ways to deal with trademarks and patents. |
| 8289 | |
| 8290 | Some packages contain a small and optional subset that violates the |
| 8291 | above guidelines, for instance because this subset is itself non-free |
| 8292 | code. When that happens, the offending items are removed with |
| 8293 | appropriate patches or code snippets in the package definition's |
| 8294 | @code{origin} form (@pxref{Defining Packages}). That way, @code{guix |
| 8295 | build --source} returns the ``freed'' source rather than the unmodified |
| 8296 | upstream source. |
| 8297 | |
| 8298 | |
| 8299 | @node Package Naming |
| 8300 | @subsection Package Naming |
| 8301 | |
| 8302 | A package has actually two names associated with it: |
| 8303 | First, there is the name of the @emph{Scheme variable}, the one following |
| 8304 | @code{define-public}. By this name, the package can be made known in the |
| 8305 | Scheme code, for instance as input to another package. Second, there is |
| 8306 | the string in the @code{name} field of a package definition. This name |
| 8307 | is used by package management commands such as |
| 8308 | @command{guix package} and @command{guix build}. |
| 8309 | |
| 8310 | Both are usually the same and correspond to the lowercase conversion of |
| 8311 | the project name chosen upstream, with underscores replaced with |
| 8312 | hyphens. For instance, GNUnet is available as @code{gnunet}, and |
| 8313 | SDL_net as @code{sdl-net}. |
| 8314 | |
| 8315 | We do not add @code{lib} prefixes for library packages, unless these are |
| 8316 | already part of the official project name. But @pxref{Python |
| 8317 | Modules} and @ref{Perl Modules} for special rules concerning modules for |
| 8318 | the Python and Perl languages. |
| 8319 | |
| 8320 | Font package names are handled differently, @pxref{Fonts}. |
| 8321 | |
| 8322 | |
| 8323 | @node Version Numbers |
| 8324 | @subsection Version Numbers |
| 8325 | |
| 8326 | We usually package only the latest version of a given free software |
| 8327 | project. But sometimes, for instance for incompatible library versions, |
| 8328 | two (or more) versions of the same package are needed. These require |
| 8329 | different Scheme variable names. We use the name as defined |
| 8330 | in @ref{Package Naming} |
| 8331 | for the most recent version; previous versions use the same name, suffixed |
| 8332 | by @code{-} and the smallest prefix of the version number that may |
| 8333 | distinguish the two versions. |
| 8334 | |
| 8335 | The name inside the package definition is the same for all versions of a |
| 8336 | package and does not contain any version number. |
| 8337 | |
| 8338 | For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: |
| 8339 | |
| 8340 | @example |
| 8341 | (define-public gtk+ |
| 8342 | (package |
| 8343 | (name "gtk+") |
| 8344 | (version "3.9.12") |
| 8345 | ...)) |
| 8346 | (define-public gtk+-2 |
| 8347 | (package |
| 8348 | (name "gtk+") |
| 8349 | (version "2.24.20") |
| 8350 | ...)) |
| 8351 | @end example |
| 8352 | If we also wanted GTK+ 3.8.2, this would be packaged as |
| 8353 | @example |
| 8354 | (define-public gtk+-3.8 |
| 8355 | (package |
| 8356 | (name "gtk+") |
| 8357 | (version "3.8.2") |
| 8358 | ...)) |
| 8359 | @end example |
| 8360 | |
| 8361 | @node Synopses and Descriptions |
| 8362 | @subsection Synopses and Descriptions |
| 8363 | |
| 8364 | As we have seen before, each package in GNU@tie{}Guix includes a |
| 8365 | synopsis and a description (@pxref{Defining Packages}). Synopses and |
| 8366 | descriptions are important: They are what @command{guix package |
| 8367 | --search} searches, and a crucial piece of information to help users |
| 8368 | determine whether a given package suits their needs. Consequently, |
| 8369 | packagers should pay attention to what goes into them. |
| 8370 | |
| 8371 | Synopses must start with a capital letter and must not end with a |
| 8372 | period. They must not start with ``a'' or ``the'', which usually does |
| 8373 | not bring anything; for instance, prefer ``File-frobbing tool'' over ``A |
| 8374 | tool that frobs files''. The synopsis should say what the package |
| 8375 | is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is |
| 8376 | used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines |
| 8377 | matching a pattern''. |
| 8378 | |
| 8379 | Keep in mind that the synopsis must be meaningful for a very wide |
| 8380 | audience. For example, ``Manipulate alignments in the SAM format'' |
| 8381 | might make sense for a seasoned bioinformatics researcher, but might be |
| 8382 | fairly unhelpful or even misleading to a non-specialized audience. It |
| 8383 | is a good idea to come up with a synopsis that gives an idea of the |
| 8384 | application domain of the package. In this example, this might give |
| 8385 | something like ``Manipulate nucleotide sequence alignments'', which |
| 8386 | hopefully gives the user a better idea of whether this is what they are |
| 8387 | looking for. |
| 8388 | |
| 8389 | @cindex Texinfo markup, in package descriptions |
| 8390 | Descriptions should take between five and ten lines. Use full |
| 8391 | sentences, and avoid using acronyms without first introducing them. |
| 8392 | Descriptions can include Texinfo markup, which is useful to introduce |
| 8393 | ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or |
| 8394 | hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you |
| 8395 | should be careful when using some characters for example @samp{@@} and |
| 8396 | curly braces which are the basic special characters in Texinfo |
| 8397 | (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces |
| 8398 | such as @command{guix package --show} take care of rendering it |
| 8399 | appropriately. |
| 8400 | |
| 8401 | Synopses and descriptions are translated by volunteers |
| 8402 | @uref{http://translationproject.org/domain/guix-packages.html, at the |
| 8403 | Translation Project} so that as many users as possible can read them in |
| 8404 | their native language. User interfaces search them and display them in |
| 8405 | the language specified by the current locale. |
| 8406 | |
| 8407 | Translation is a lot of work so, as a packager, please pay even more |
| 8408 | attention to your synopses and descriptions as every change may entail |
| 8409 | additional work for translators. In order to help them, it is possible |
| 8410 | to make recommendations or instructions visible to them by inserting |
| 8411 | special comments like this (@pxref{xgettext Invocation,,, gettext, GNU |
| 8412 | Gettext}): |
| 8413 | |
| 8414 | @example |
| 8415 | ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. |
| 8416 | (description "ARandR is designed to provide a simple visual front end |
| 8417 | for the X11 resize-and-rotate (RandR) extension. @dots{}") |
| 8418 | @end example |
| 8419 | |
| 8420 | |
| 8421 | @node Python Modules |
| 8422 | @subsection Python Modules |
| 8423 | |
| 8424 | We currently package Python 2 and Python 3, under the Scheme variable names |
| 8425 | @code{python-2} and @code{python} as explained in @ref{Version Numbers}. |
| 8426 | To avoid confusion and naming clashes with other programming languages, it |
| 8427 | seems desirable that the name of a package for a Python module contains |
| 8428 | the word @code{python}. |
| 8429 | |
| 8430 | Some modules are compatible with only one version of Python, others with both. |
| 8431 | If the package Foo compiles only with Python 3, we name it |
| 8432 | @code{python-foo}; if it compiles only with Python 2, we name it |
| 8433 | @code{python2-foo}. If it is compatible with both versions, we create two |
| 8434 | packages with the corresponding names. |
| 8435 | |
| 8436 | If a project already contains the word @code{python}, we drop this; |
| 8437 | for instance, the module python-dateutil is packaged under the names |
| 8438 | @code{python-dateutil} and @code{python2-dateutil}. |
| 8439 | |
| 8440 | |
| 8441 | @node Perl Modules |
| 8442 | @subsection Perl Modules |
| 8443 | |
| 8444 | Perl programs standing for themselves are named as any other package, |
| 8445 | using the lowercase upstream name. |
| 8446 | For Perl packages containing a single class, we use the lowercase class name, |
| 8447 | replace all occurrences of @code{::} by dashes and prepend the prefix |
| 8448 | @code{perl-}. |
| 8449 | So the class @code{XML::Parser} becomes @code{perl-xml-parser}. |
| 8450 | Modules containing several classes keep their lowercase upstream name and |
| 8451 | are also prepended by @code{perl-}. Such modules tend to have the word |
| 8452 | @code{perl} somewhere in their name, which gets dropped in favor of the |
| 8453 | prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}. |
| 8454 | |
| 8455 | |
| 8456 | @node Fonts |
| 8457 | @subsection Fonts |
| 8458 | |
| 8459 | For fonts that are in general not installed by a user for typesetting |
| 8460 | purposes, or that are distributed as part of a larger software package, |
| 8461 | we rely on the general packaging rules for software; for instance, this |
| 8462 | applies to the fonts delivered as part of the X.Org system or fonts that |
| 8463 | are part of TeX Live. |
| 8464 | |
| 8465 | To make it easier for a user to search for fonts, names for other packages |
| 8466 | containing only fonts are constructed as follows, independently of the |
| 8467 | upstream package name. |
| 8468 | |
| 8469 | The name of a package containing only one font family starts with |
| 8470 | @code{font-}; it is followed by the foundry name and a dash @code{-} |
| 8471 | if the foundry is known, and the font family name, in which spaces are |
| 8472 | replaced by dashes (and as usual, all upper case letters are transformed |
| 8473 | to lower case). |
| 8474 | For example, the Gentium font family by SIL is packaged under the name |
| 8475 | @code{font-sil-gentium}. |
| 8476 | |
| 8477 | For a package containing several font families, the name of the collection |
| 8478 | is used in the place of the font family name. |
| 8479 | For instance, the Liberation fonts consist of three families, |
| 8480 | Liberation Sans, Liberation Serif and Liberation Mono. |
| 8481 | These could be packaged separately under the names |
| 8482 | @code{font-liberation-sans} and so on; but as they are distributed together |
| 8483 | under a common name, we prefer to package them together as |
| 8484 | @code{font-liberation}. |
| 8485 | |
| 8486 | In the case where several formats of the same font family or font collection |
| 8487 | are packaged separately, a short form of the format, prepended by a dash, |
| 8488 | is added to the package name. We use @code{-ttf} for TrueType fonts, |
| 8489 | @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 |
| 8490 | fonts. |
| 8491 | |
| 8492 | |
| 8493 | |
| 8494 | @node Bootstrapping |
| 8495 | @section Bootstrapping |
| 8496 | |
| 8497 | @c Adapted from the ELS 2013 paper. |
| 8498 | |
| 8499 | @cindex bootstrapping |
| 8500 | |
| 8501 | Bootstrapping in our context refers to how the distribution gets built |
| 8502 | ``from nothing''. Remember that the build environment of a derivation |
| 8503 | contains nothing but its declared inputs (@pxref{Introduction}). So |
| 8504 | there's an obvious chicken-and-egg problem: how does the first package |
| 8505 | get built? How does the first compiler get compiled? Note that this is |
| 8506 | a question of interest only to the curious hacker, not to the regular |
| 8507 | user, so you can shamelessly skip this section if you consider yourself |
| 8508 | a ``regular user''. |
| 8509 | |
| 8510 | @cindex bootstrap binaries |
| 8511 | The GNU system is primarily made of C code, with libc at its core. The |
| 8512 | GNU build system itself assumes the availability of a Bourne shell and |
| 8513 | command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and |
| 8514 | `grep'. Furthermore, build programs---programs that run |
| 8515 | @code{./configure}, @code{make}, etc.---are written in Guile Scheme |
| 8516 | (@pxref{Derivations}). Consequently, to be able to build anything at |
| 8517 | all, from scratch, Guix relies on pre-built binaries of Guile, GCC, |
| 8518 | Binutils, libc, and the other packages mentioned above---the |
| 8519 | @dfn{bootstrap binaries}. |
| 8520 | |
| 8521 | These bootstrap binaries are ``taken for granted'', though we can also |
| 8522 | re-create them if needed (more on that later). |
| 8523 | |
| 8524 | @unnumberedsubsec Preparing to Use the Bootstrap Binaries |
| 8525 | |
| 8526 | @c As of Emacs 24.3, Info-mode displays the image, but since it's a |
| 8527 | @c large image, it's hard to scroll. Oh well. |
| 8528 | @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations} |
| 8529 | |
| 8530 | The figure above shows the very beginning of the dependency graph of the |
| 8531 | distribution, corresponding to the package definitions of the @code{(gnu |
| 8532 | packages bootstrap)} module. At this level of detail, things are |
| 8533 | slightly complex. First, Guile itself consists of an ELF executable, |
| 8534 | along with many source and compiled Scheme files that are dynamically |
| 8535 | loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz} |
| 8536 | tarball shown in this graph. This tarball is part of Guix's ``source'' |
| 8537 | distribution, and gets inserted into the store with @code{add-to-store} |
| 8538 | (@pxref{The Store}). |
| 8539 | |
| 8540 | But how do we write a derivation that unpacks this tarball and adds it |
| 8541 | to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} |
| 8542 | derivation---the first one that gets built---uses @code{bash} as its |
| 8543 | builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls |
| 8544 | @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, |
| 8545 | @file{xz}, and @file{mkdir} are statically-linked binaries, also part of |
| 8546 | the Guix source distribution, whose sole purpose is to allow the Guile |
| 8547 | tarball to be unpacked. |
| 8548 | |
| 8549 | Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning |
| 8550 | Guile that can be used to run subsequent build programs. Its first task |
| 8551 | is to download tarballs containing the other pre-built binaries---this |
| 8552 | is what the @code{.tar.xz.drv} derivations do. Guix modules such as |
| 8553 | @code{ftp-client.scm} are used for this purpose. The |
| 8554 | @code{module-import.drv} derivations import those modules in a directory |
| 8555 | in the store, using the original layout. The |
| 8556 | @code{module-import-compiled.drv} derivations compile those modules, and |
| 8557 | write them in an output directory with the right layout. This |
| 8558 | corresponds to the @code{#:modules} argument of |
| 8559 | @code{build-expression->derivation} (@pxref{Derivations}). |
| 8560 | |
| 8561 | Finally, the various tarballs are unpacked by the |
| 8562 | derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, |
| 8563 | etc., at which point we have a working C tool chain. |
| 8564 | |
| 8565 | |
| 8566 | @unnumberedsubsec Building the Build Tools |
| 8567 | |
| 8568 | @c TODO: Add a package-level dependency graph generated from (gnu |
| 8569 | @c packages base). |
| 8570 | |
| 8571 | Bootstrapping is complete when we have a full tool chain that does not |
| 8572 | depend on the pre-built bootstrap tools discussed above. This |
| 8573 | no-dependency requirement is verified by checking whether the files of |
| 8574 | the final tool chain contain references to the @file{/gnu/store} |
| 8575 | directories of the bootstrap inputs. The process that leads to this |
| 8576 | ``final'' tool chain is described by the package definitions found in |
| 8577 | the @code{(gnu packages commencement)} module. |
| 8578 | |
| 8579 | @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. |
| 8580 | The first tool that gets built with the bootstrap binaries is |
| 8581 | GNU Make, which is a prerequisite for all the following packages. |
| 8582 | From there Findutils and Diffutils get built. |
| 8583 | |
| 8584 | Then come the first-stage Binutils and GCC, built as pseudo cross |
| 8585 | tools---i.e., with @code{--target} equal to @code{--host}. They are |
| 8586 | used to build libc. Thanks to this cross-build trick, this libc is |
| 8587 | guaranteed not to hold any reference to the initial tool chain. |
| 8588 | |
| 8589 | From there the final Binutils and GCC are built. GCC uses @code{ld} |
| 8590 | from the final Binutils, and links programs against the just-built libc. |
| 8591 | This tool chain is used to build the other packages used by Guix and by |
| 8592 | the GNU Build System: Guile, Bash, Coreutils, etc. |
| 8593 | |
| 8594 | And voilà! At this point we have the complete set of build tools that |
| 8595 | the GNU Build System expects. These are in the @code{%final-inputs} |
| 8596 | variable of the @code{(gnu packages commencement)} module, and are |
| 8597 | implicitly used by any package that uses @code{gnu-build-system} |
| 8598 | (@pxref{Build Systems, @code{gnu-build-system}}). |
| 8599 | |
| 8600 | |
| 8601 | @unnumberedsubsec Building the Bootstrap Binaries |
| 8602 | |
| 8603 | Because the final tool chain does not depend on the bootstrap binaries, |
| 8604 | those rarely need to be updated. Nevertheless, it is useful to have an |
| 8605 | automated way to produce them, should an update occur, and this is what |
| 8606 | the @code{(gnu packages make-bootstrap)} module provides. |
| 8607 | |
| 8608 | The following command builds the tarballs containing the bootstrap |
| 8609 | binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture |
| 8610 | of Coreutils and other basic command-line tools): |
| 8611 | |
| 8612 | @example |
| 8613 | guix build bootstrap-tarballs |
| 8614 | @end example |
| 8615 | |
| 8616 | The generated tarballs are those that should be referred to in the |
| 8617 | @code{(gnu packages bootstrap)} module mentioned at the beginning of |
| 8618 | this section. |
| 8619 | |
| 8620 | Still here? Then perhaps by now you've started to wonder: when do we |
| 8621 | reach a fixed point? That is an interesting question! The answer is |
| 8622 | unknown, but if you would like to investigate further (and have |
| 8623 | significant computational and storage resources to do so), then let us |
| 8624 | know. |
| 8625 | |
| 8626 | @node Porting |
| 8627 | @section Porting to a New Platform |
| 8628 | |
| 8629 | As discussed above, the GNU distribution is self-contained, and |
| 8630 | self-containment is achieved by relying on pre-built ``bootstrap |
| 8631 | binaries'' (@pxref{Bootstrapping}). These binaries are specific to an |
| 8632 | operating system kernel, CPU architecture, and application binary |
| 8633 | interface (ABI). Thus, to port the distribution to a platform that is |
| 8634 | not yet supported, one must build those bootstrap binaries, and update |
| 8635 | the @code{(gnu packages bootstrap)} module to use them on that platform. |
| 8636 | |
| 8637 | Fortunately, Guix can @emph{cross compile} those bootstrap binaries. |
| 8638 | When everything goes well, and assuming the GNU tool chain supports the |
| 8639 | target platform, this can be as simple as running a command like this |
| 8640 | one: |
| 8641 | |
| 8642 | @example |
| 8643 | guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs |
| 8644 | @end example |
| 8645 | |
| 8646 | For this to work, the @code{glibc-dynamic-linker} procedure in |
| 8647 | @code{(gnu packages bootstrap)} must be augmented to return the right |
| 8648 | file name for libc's dynamic linker on that platform; likewise, |
| 8649 | @code{system->linux-architecture} in @code{(gnu packages linux)} must be |
| 8650 | taught about the new platform. |
| 8651 | |
| 8652 | Once these are built, the @code{(gnu packages bootstrap)} module needs |
| 8653 | to be updated to refer to these binaries on the target platform. That |
| 8654 | is, the hashes and URLs of the bootstrap tarballs for the new platform |
| 8655 | must be added alongside those of the currently supported platforms. The |
| 8656 | bootstrap Guile tarball is treated specially: it is expected to be |
| 8657 | available locally, and @file{gnu-system.am} has rules do download it for |
| 8658 | the supported architectures; a rule for the new platform must be added |
| 8659 | as well. |
| 8660 | |
| 8661 | In practice, there may be some complications. First, it may be that the |
| 8662 | extended GNU triplet that specifies an ABI (like the @code{eabi} suffix |
| 8663 | above) is not recognized by all the GNU tools. Typically, glibc |
| 8664 | recognizes some of these, whereas GCC uses an extra @code{--with-abi} |
| 8665 | configure flag (see @code{gcc.scm} for examples of how to handle this). |
| 8666 | Second, some of the required packages could fail to build for that |
| 8667 | platform. Lastly, the generated binaries could be broken for some |
| 8668 | reason. |
| 8669 | |
| 8670 | @c ********************************************************************* |
| 8671 | @include contributing.texi |
| 8672 | |
| 8673 | @c ********************************************************************* |
| 8674 | @node Acknowledgments |
| 8675 | @chapter Acknowledgments |
| 8676 | |
| 8677 | Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, |
| 8678 | which was designed and |
| 8679 | implemented by Eelco Dolstra, with contributions from other people (see |
| 8680 | the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package |
| 8681 | management, and promoted unprecedented features, such as transactional |
| 8682 | package upgrades and rollbacks, per-user profiles, and referentially |
| 8683 | transparent build processes. Without this work, Guix would not exist. |
| 8684 | |
| 8685 | The Nix-based software distributions, Nixpkgs and NixOS, have also been |
| 8686 | an inspiration for Guix. |
| 8687 | |
| 8688 | GNU@tie{}Guix itself is a collective work with contributions from a |
| 8689 | number of people. See the @file{AUTHORS} file in Guix for more |
| 8690 | information on these fine people. The @file{THANKS} file lists people |
| 8691 | who have helped by reporting bugs, taking care of the infrastructure, |
| 8692 | providing artwork and themes, making suggestions, and more---thank you! |
| 8693 | |
| 8694 | |
| 8695 | @c ********************************************************************* |
| 8696 | @node GNU Free Documentation License |
| 8697 | @appendix GNU Free Documentation License |
| 8698 | |
| 8699 | @include fdl-1.3.texi |
| 8700 | |
| 8701 | @c ********************************************************************* |
| 8702 | @node Concept Index |
| 8703 | @unnumbered Concept Index |
| 8704 | @printindex cp |
| 8705 | |
| 8706 | @node Programming Index |
| 8707 | @unnumbered Programming Index |
| 8708 | @syncodeindex tp fn |
| 8709 | @syncodeindex vr fn |
| 8710 | @printindex fn |
| 8711 | |
| 8712 | @bye |
| 8713 | |
| 8714 | @c Local Variables: |
| 8715 | @c ispell-local-dictionary: "american"; |
| 8716 | @c End: |