gnu: Add python-rq.
[jackhill/guix/guix.git] / doc / guix.texi
CommitLineData
568717fd
LC
1\input texinfo
2@c -*-texinfo-*-
3
4@c %**start of header
5@setfilename guix.info
6@documentencoding UTF-8
f8348b91 7@settitle GNU Guix Reference Manual
568717fd
LC
8@c %**end of header
9
10@include version.texi
7df7a74e
NK
11
12@copying
4379c35b 13Copyright @copyright{} 2012, 2013, 2014, 2015 Ludovic Courtès@*
af8a56b8 14Copyright @copyright{} 2013, 2014 Andreas Enge@*
87eafdbd
TUBK
15Copyright @copyright{} 2013 Nikita Karetnikov@*
16Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer
7df7a74e
NK
17
18Permission is granted to copy, distribute and/or modify this document
19under the terms of the GNU Free Documentation License, Version 1.3 or
20any later version published by the Free Software Foundation; with no
21Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
22copy of the license is included in the section entitled ``GNU Free
23Documentation License''.
24@end copying
568717fd 25
eeaf4427 26@dircategory Package management
568717fd
LC
27@direntry
28* guix: (guix). Guix, the functional package manager.
e49951eb 29* guix package: (guix)Invoking guix package
eeaf4427 30 Managing packages with Guix.
e49951eb 31* guix build: (guix)Invoking guix build
568717fd 32 Building packages with Guix.
054e8576
LC
33* guix system: (guix)Invoking guix system
34 Managing the operating system configuration.
568717fd 35@end direntry
568717fd 36
372c4bbc
DT
37@dircategory Software development
38@direntry
39* guix environment: (guix)Invoking guix environment
40 Building development environments with Guix.
41@end direntry
42
568717fd 43@titlepage
7730d112
LC
44@title GNU Guix Reference Manual
45@subtitle Using the GNU Guix Functional Package Manager
568717fd 46@author Ludovic Courtès
da7cabd4 47@author Andreas Enge
acc08466 48@author Nikita Karetnikov
568717fd
LC
49
50@page
51@vskip 0pt plus 1filll
52Edition @value{EDITION} @*
53@value{UPDATED} @*
54
7df7a74e 55@insertcopying
568717fd
LC
56@end titlepage
57
568717fd
LC
58@contents
59
60@c *********************************************************************
61@node Top
f8348b91 62@top GNU Guix
568717fd 63
f8348b91
LC
64This document describes GNU Guix version @value{VERSION}, a functional
65package management tool written for the GNU system.
568717fd
LC
66
67@menu
68* Introduction:: What is Guix about?
bd5e766b 69* Installation:: Installing Guix.
eeaf4427 70* Package Management:: Package installation, upgrade, etc.
568717fd
LC
71* Programming Interface:: Using Guix in Scheme.
72* Utilities:: Package management commands.
a1ba8475 73* GNU Distribution:: Software for your friendly GNU system.
9bf3c1a7 74* Contributing:: Your help needed!
568717fd
LC
75
76* Acknowledgments:: Thanks!
77* GNU Free Documentation License:: The license of this manual.
78* Concept Index:: Concepts.
a85b83d2 79* Programming Index:: Data types, functions, and variables.
aaa3eaa9
LC
80
81@detailmenu
82 --- The Detailed Node Listing ---
83
84Installation
85
1b2b8177 86* Binary Installation:: Getting Guix running in no time!
aaa3eaa9 87* Requirements:: Software needed to build and run Guix.
ec0339cd 88* Running the Test Suite:: Testing Guix.
aaa3eaa9
LC
89* Setting Up the Daemon:: Preparing the build daemon's environment.
90* Invoking guix-daemon:: Running the build daemon.
91
92Setting Up the Daemon
93
94* Build Environment Setup:: Preparing the isolated build environment.
95* Daemon Offload Setup:: Offloading builds to remote machines.
96
97Package Management
98
99* Features:: How Guix will make your life brighter.
100* Invoking guix package:: Package installation, removal, etc.
101* Emacs Interface:: Package management from Emacs.
102* Substitutes:: Downloading pre-built binaries.
103* Packages with Multiple Outputs:: Single source package, multiple outputs.
104* Invoking guix gc:: Running the garbage collector.
105* Invoking guix pull:: Fetching the latest Guix and distribution.
106* Invoking guix archive:: Exporting and importing store files.
107
108Programming Interface
109
110* Defining Packages:: Defining new packages.
111* Build Systems:: Specifying how packages are built.
112* The Store:: Manipulating the package store.
113* Derivations:: Low-level interface to package derivations.
114* The Store Monad:: Purely functional interface to the store.
115* G-Expressions:: Manipulating build expressions.
116
117Utilities
118
119* Invoking guix build:: Building packages from the command line.
120* Invoking guix download:: Downloading a file and printing its hash.
121* Invoking guix hash:: Computing the cryptographic hash of a file.
122* Invoking guix import:: Importing package definitions.
123* Invoking guix refresh:: Updating package definitions.
124* Invoking guix lint:: Finding errors in package definitions.
125* Invoking guix environment:: Setting up development environments.
aff8ce7c 126* Invoking guix publish:: Sharing substitutes.
aaa3eaa9
LC
127
128GNU Distribution
129
130* System Installation:: Installing the whole operating system.
35ed9306 131* System Configuration:: Configuring the operating system.
aaa3eaa9
LC
132* Installing Debugging Files:: Feeding the debugger.
133* Security Updates:: Deploying security fixes quickly.
134* Package Modules:: Packages from the programmer's viewpoint.
135* Packaging Guidelines:: Growing the distribution.
136* Bootstrapping:: GNU/Linux built from scratch.
137* Porting:: Targeting another platform or kernel.
138
139System Configuration
140
141* Using the Configuration System:: Customizing your GNU system.
142* operating-system Reference:: Detail of operating-system declarations.
143* File Systems:: Configuring file system mounts.
144* Mapped Devices:: Block device extra processing.
145* User Accounts:: Specifying user accounts.
598e19dc 146* Locales:: Language and cultural convention settings.
aaa3eaa9
LC
147* Services:: Specifying system services.
148* Setuid Programs:: Programs running with root privileges.
1b2b8177 149* X.509 Certificates:: Authenticating HTTPS servers.
996ed739 150* Name Service Switch:: Configuring libc's name service switch.
aaa3eaa9
LC
151* Initial RAM Disk:: Linux-Libre bootstrapping.
152* GRUB Configuration:: Configuring the boot loader.
153* Invoking guix system:: Instantiating a system configuration.
154* Defining Services:: Adding new service definitions.
155
156Services
157
158* Base Services:: Essential system services.
159* Networking Services:: Network setup, SSH daemon, etc.
160* X Window:: Graphical display.
1b2b8177
LC
161* Desktop Services:: D-Bus and desktop services.
162* Database Services:: SQL databases.
aa4ed923 163* Various Services:: Other services.
aaa3eaa9
LC
164
165Packaging Guidelines
166
ec0339cd
LC
167* Software Freedom:: What may go into the distribution.
168* Package Naming:: What's in a name?
169* Version Numbers:: When the name is not enough.
170* Python Modules:: Taming the snake.
171* Perl Modules:: Little pearls.
172* Fonts:: Fond of fonts.
aaa3eaa9
LC
173
174@end detailmenu
568717fd
LC
175@end menu
176
177@c *********************************************************************
178@node Introduction
179@chapter Introduction
180
c80e7e55
LC
181GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
182using the international phonetic alphabet (IPA).} is a functional
183package management tool for the GNU system. Package management consists
4bfc4ea3
NK
184of all activities that relate to building packages from sources,
185honoring their build-time and run-time dependencies,
c80e7e55
LC
186installing packages in user environments, upgrading installed packages
187to new versions or rolling back to a previous set, removing unused
188software packages, etc.
568717fd
LC
189
190@cindex functional package management
191The term @dfn{functional} refers to a specific package management
192discipline. In Guix, the package build and installation process is seen
4bfc4ea3
NK
193as a function, in the mathematical sense. That function takes inputs,
194such as build scripts, a compiler, and libraries, and
195returns an installed package. As a pure function, its result depends
568717fd
LC
196solely on its inputs---for instance, it cannot refer to software or
197scripts that were not explicitly passed as inputs. A build function
4bfc4ea3
NK
198always produces the same result when passed a given set of inputs. It
199cannot alter the system's environment in
568717fd
LC
200any way; for instance, it cannot create, modify, or delete files outside
201of its build and installation directories. This is achieved by running
e900c503 202build processes in isolated environments (or @dfn{containers}), where only their
4bfc4ea3 203explicit inputs are visible.
568717fd 204
e531ac2a 205@cindex store
568717fd 206The result of package build functions is @dfn{cached} in the file
e531ac2a
LC
207system, in a special directory called @dfn{the store} (@pxref{The
208Store}). Each package is installed in a directory of its own, in the
834129e0 209store---by default under @file{/gnu/store}. The directory name contains
568717fd
LC
210a hash of all the inputs used to build that package; thus, changing an
211input yields a different directory name.
212
213This approach is the foundation of Guix's salient features: support for
4bfc4ea3 214transactional package upgrade and rollback, per-user installation, and
eeaf4427 215garbage collection of packages (@pxref{Features}).
568717fd 216
4bfc4ea3 217Guix has a command-line interface, which allows users to build, install,
568717fd 218upgrade, and remove packages, as well as a Scheme programming interface.
568717fd 219
3ca2731c 220@cindex Guix System Distribution
4705641f 221@cindex GuixSD
a1ba8475 222Last but not least, Guix is used to build a distribution of the GNU
3ca2731c 223system, with many GNU and non-GNU free software packages. The Guix
4705641f
LC
224System Distribution, or GNU@tie{}GuixSD, takes advantage of the core
225properties of Guix at the system level. With GuixSD, users
3ca2731c
LC
226@emph{declare} all aspects of the operating system configuration, and
227Guix takes care of instantiating that configuration in a reproducible,
228stateless fashion. @xref{GNU Distribution}.
a1ba8475 229
bd5e766b
LC
230@c *********************************************************************
231@node Installation
232@chapter Installation
233
48febeb8
LC
234GNU Guix is available for download from its website at
235@url{http://www.gnu.org/software/guix/}. This section describes the
236software requirements of Guix, as well as how to install it and get
237ready to use it.
bd5e766b 238
5af6de3e
LC
239Note that this section is concerned with the installation of the package
240manager, which can be done on top of a running GNU/Linux system. If,
241instead, you want to install the complete GNU operating system,
6621cdb6 242@pxref{System Installation}.
5af6de3e 243
bd5e766b 244@menu
09722b11 245* Binary Installation:: Getting Guix running in no time!
bd5e766b 246* Requirements:: Software needed to build and run Guix.
ec0339cd 247* Running the Test Suite:: Testing Guix.
bd5e766b
LC
248* Setting Up the Daemon:: Preparing the build daemon's environment.
249* Invoking guix-daemon:: Running the build daemon.
250@end menu
251
09722b11
LC
252@node Binary Installation
253@section Binary Installation
254
255This section describes how to install Guix on an arbitrary system from a
256self-contained tarball providing binaries for Guix and for all its
257dependencies. This is often quicker than installing from source, which
258is described in the next sections. The only requirement is to have
259GNU@tie{}tar and Xz.
260
261Installing goes along these lines:
262
263@enumerate
264@item
265Download the binary tarball from
ae806096 266@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}@footnote{As
09722b11
LC
267usual, make sure to download the associated @file{.sig} file and to
268verify the authenticity of the tarball against it!}, where @var{system}
269is @code{x86_64-linux} for an @code{x86_64} machine already running the
270kernel Linux, and so on.
271
272@item
273As @code{root}, run:
274
275@example
276# cd /
b91d7f0f 277# tar xf guix-binary-@value{VERSION}.@var{system}.tar.xz
09722b11
LC
278@end example
279
280This creates @file{/gnu/store} (@pxref{The Store}), @file{/var/guix},
281and @file{/root/.guix-profile}. @file{/root/.guix-profile} is a
282ready-to-use profile for @code{root} where Guix is installed.
283
5dc3ce5f
LC
284Do @emph{not} unpack the tarball on a working Guix system since that
285would overwrite its own essential files.
286
09722b11 287@item
175ced41 288Run the daemon:
09722b11
LC
289
290@example
cfc149dc 291# /root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
09722b11
LC
292@end example
293
294@item
295Make the @command{guix} command available to other users on the machine,
296for instance with:
297
298@example
299# mkdir -p /usr/local/bin
300# cd /usr/local/bin
d72d05f9 301# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
09722b11 302@end example
39f8ed14
LC
303
304@item
305To use substitutes from @code{hydra.gnu.org} (@pxref{Substitutes}),
306authorize them:
307
308@example
309# guix archive --authorize < /root/.guix-profile/share/guix/hydra.gnu.org.pub
310@end example
09722b11
LC
311@end enumerate
312
313And that's it!
314
5dc3ce5f 315The @code{guix} package must remain available in @code{root}'s
09722b11
LC
316profile, or it would become subject to garbage collection---in which
317case you would find yourself badly handicapped by the lack of the
318@command{guix} command.
319
39f8ed14
LC
320The tarball in question can be (re)produced and verified simply by
321running the following command in the Guix source tree:
09722b11
LC
322
323@example
324make guix-binary.@var{system}.tar.xz
325@end example
326
327
bd5e766b
LC
328@node Requirements
329@section Requirements
330
09722b11
LC
331This section lists requirements when building Guix from source. The
332build procedure for Guix is the same as for other GNU software, and is
333not covered here. Please see the files @file{README} and @file{INSTALL}
334in the Guix source tree for additional details.
335
bd5e766b
LC
336GNU Guix depends on the following packages:
337
338@itemize
47c66da0 339@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
288dca55 340@item @url{http://gnupg.org/, GNU libgcrypt};
f0b98b84 341@item @url{http://www.gnu.org/software/make/, GNU Make}.
8a96bd4b
ID
342@end itemize
343
344The following dependencies are optional:
345
346@itemize
288dca55 347@item
8a96bd4b 348Installing
288dca55 349@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
2f7d2d91
LC
350allow you to use the @command{guix import pypi} command (@pxref{Invoking
351guix import}). It is of
288dca55 352interest primarily for developers and not for casual users.
8a96bd4b
ID
353@item
354Installing @uref{http://gnutls.org/, GnuTLS-Guile} will
355allow you to access @code{https} URLs with the @command{guix download}
d45dc6da
EB
356command (@pxref{Invoking guix download}), the @command{guix import pypi}
357command, and the @command{guix import cpan} command. This is primarily
358of interest to developers. @xref{Guile Preparations, how to install the
359GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}.
bd5e766b
LC
360@end itemize
361
362Unless @code{--disable-daemon} was passed to @command{configure}, the
363following packages are also needed:
364
365@itemize
368d08f7
LC
366@item @url{http://sqlite.org, SQLite 3};
367@item @url{http://www.bzip.org, libbz2};
368@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
369C++11 standard.
bd5e766b
LC
370@end itemize
371
4bfc4ea3
NK
372When a working installation of @url{http://nixos.org/nix/, the Nix package
373manager} is available, you
bd5e766b 374can instead configure Guix with @code{--disable-daemon}. In that case,
4bfc4ea3 375Nix replaces the three dependencies above.
bd5e766b 376
b22a12fd
LC
377Guix is compatible with Nix, so it is possible to share the same store
378between both. To do so, you must pass @command{configure} not only the
379same @code{--with-store-dir} value, but also the same
4bfc4ea3
NK
380@code{--localstatedir} value. The latter is essential because it
381specifies where the database that stores metadata about the store is
834129e0 382located, among other things. The default values for Nix are
b22a12fd 383@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
4bfc4ea3
NK
384Note that @code{--disable-daemon} is not required if
385your goal is to share the store with Nix.
b22a12fd 386
ec0339cd
LC
387@node Running the Test Suite
388@section Running the Test Suite
389
390After a successful @command{configure} and @code{make} run, it is a good
391idea to run the test suite. It can help catch issues with the setup or
392environment, or bugs in Guix itself---and really, reporting test
393failures is a good way to help improve the software. To run the test
394suite, type:
395
396@example
397make check
398@end example
399
400Test cases can run in parallel: you can use the @code{-j} option of
401GNU@tie{}make to speed things up. The first run may take a few minutes
402on a recent machine; subsequent runs will be faster because the store
403that is created for test purposes will already have various things in
404cache.
405
406Upon failure, please email @email{bug-guix@@gnu.org} and attach the
407@file{test-suite.log} file. When @file{tests/@var{something}.scm}
408fails, please also attach the @file{@var{something}.log} file available
409in the top-level build directory. Please specify the Guix version being
410used as well as version numbers of the dependencies
411(@pxref{Requirements}) in your message.
412
bd5e766b
LC
413@node Setting Up the Daemon
414@section Setting Up the Daemon
415
416@cindex daemon
417Operations such as building a package or running the garbage collector
49e6291a 418are all performed by a specialized process, the @dfn{build daemon}, on
bd5e766b
LC
419behalf of clients. Only the daemon may access the store and its
420associated database. Thus, any operation that manipulates the store
421goes through the daemon. For instance, command-line tools such as
e49951eb 422@command{guix package} and @command{guix build} communicate with the
bd5e766b
LC
423daemon (@i{via} remote procedure calls) to instruct it what to do.
424
49e6291a 425The following sections explain how to prepare the build daemon's
225dafde
LC
426environment. Also @ref{Substitutes}, for information on how to allow
427the daemon to download pre-built binaries.
49e6291a
LC
428
429@menu
430* Build Environment Setup:: Preparing the isolated build environment.
431* Daemon Offload Setup:: Offloading builds to remote machines.
432@end menu
433
434@node Build Environment Setup
435@subsection Build Environment Setup
436
bd5e766b
LC
437In a standard multi-user setup, Guix and its daemon---the
438@command{guix-daemon} program---are installed by the system
834129e0 439administrator; @file{/gnu/store} is owned by @code{root} and
bd5e766b
LC
440@command{guix-daemon} runs as @code{root}. Unprivileged users may use
441Guix tools to build packages or otherwise access the store, and the
442daemon will do it on their behalf, ensuring that the store is kept in a
443consistent state, and allowing built packages to be shared among users.
444
445@cindex build users
446When @command{guix-daemon} runs as @code{root}, you may not want package
447build processes themselves to run as @code{root} too, for obvious
448security reasons. To avoid that, a special pool of @dfn{build users}
449should be created for use by build processes started by the daemon.
450These build users need not have a shell and a home directory: they will
451just be used when the daemon drops @code{root} privileges in build
452processes. Having several such users allows the daemon to launch
453distinct build processes under separate UIDs, which guarantees that they
454do not interfere with each other---an essential feature since builds are
455regarded as pure functions (@pxref{Introduction}).
456
457On a GNU/Linux system, a build user pool may be created like this (using
458Bash syntax and the @code{shadow} commands):
459
091196b3
LC
460@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
461@c for why `-G' is needed.
bd5e766b 462@example
cfc149dc
LC
463# groupadd --system guixbuild
464# for i in `seq -w 1 10`;
bd5e766b 465 do
cfc149dc
LC
466 useradd -g guixbuild -G guixbuild \
467 -d /var/empty -s `which nologin` \
468 -c "Guix build user $i" --system \
469 guixbuilder$i;
bd5e766b
LC
470 done
471@end example
472
473@noindent
474The @code{guix-daemon} program may then be run as @code{root} with:
475
476@example
cfc149dc 477# guix-daemon --build-users-group=guixbuild
bd5e766b
LC
478@end example
479
e900c503 480@cindex chroot
b095792f
LC
481@noindent
482This way, the daemon starts build processes in a chroot, under one of
cfc149dc 483the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
6dc99317
LC
484environment contains nothing but:
485
486@c Keep this list in sync with libstore/build.cc! -----------------------
487@itemize
488@item
4743a4da
LC
489a minimal @code{/dev} directory, created mostly independently from the
490host @code{/dev}@footnote{``Mostly'', because while the set of files
491that appear in the chroot's @code{/dev} is fixed, most of these files
492can only be created if the host has them.};
493
494@item
495the @code{/proc} directory; it only shows the container's processes
496since a separate PID name space is used;
6dc99317
LC
497
498@item
499@file{/etc/passwd} with an entry for the current user and an entry for
500user @file{nobody};
501
502@item
503@file{/etc/group} with an entry for the user's group;
504
505@item
506@file{/etc/hosts} with an entry that maps @code{localhost} to
507@code{127.0.0.1};
508
509@item
510a writable @file{/tmp} directory.
511@end itemize
b095792f 512
d43eb499 513If you are installing Guix as an unprivileged user, it is still
bd5e766b
LC
514possible to run @command{guix-daemon}. However, build processes will
515not be isolated from one another, and not from the rest of the system.
516Thus, build processes may interfere with each other, and may access
517programs, libraries, and other files available on the system---making it
518much harder to view them as @emph{pure} functions.
519
49e6291a
LC
520
521@node Daemon Offload Setup
522@subsection Using the Offload Facility
523
524@cindex offloading
4ec2e92d
LC
525@cindex build hook
526When desired, the build daemon can @dfn{offload}
527derivation builds to other machines
49e6291a
LC
528running Guix, using the @code{offload} @dfn{build hook}. When that
529feature is enabled, a list of user-specified build machines is read from
530@file{/etc/guix/machines.scm}; anytime a build is requested, for
531instance via @code{guix build}, the daemon attempts to offload it to one
532of the machines that satisfies the derivation's constraints, in
533particular its system type---e.g., @file{x86_64-linux}. Missing
534prerequisites for the build are copied over SSH to the target machine,
535which then proceeds with the build; upon success the output(s) of the
536build are copied back to the initial machine.
537
4ec2e92d 538The @file{/etc/guix/machines.scm} file typically looks like this:
49e6291a
LC
539
540@example
541(list (build-machine
542 (name "eightysix.example.org")
543 (system "x86_64-linux")
544 (user "bob")
545 (speed 2.)) ; incredibly fast!
546
547 (build-machine
548 (name "meeps.example.org")
549 (system "mips64el-linux")
550 (user "alice")
551 (private-key
552 (string-append (getenv "HOME")
553 "/.ssh/id-rsa-for-guix"))))
554@end example
555
556@noindent
557In the example above we specify a list of two build machines, one for
558the @code{x86_64} architecture and one for the @code{mips64el}
4ec2e92d
LC
559architecture.
560
561In fact, this file is---not surprisingly!---a Scheme file that is
562evaluated when the @code{offload} hook is started. Its return value
563must be a list of @code{build-machine} objects. While this example
564shows a fixed list of build machines, one could imagine, say, using
565DNS-SD to return a list of potential build machines discovered in the
566local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
c678a4ee
LC
567Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
568detailed below.
4ec2e92d 569
c678a4ee
LC
570@deftp {Data Type} build-machine
571This data type represents build machines the daemon may offload builds
572to. The important fields are:
49e6291a
LC
573
574@table @code
575
576@item name
577The remote machine's host name.
578
579@item system
c678a4ee 580The remote machine's system type---e.g., @code{"x86_64-linux"}.
49e6291a
LC
581
582@item user
583The user account to use when connecting to the remote machine over SSH.
584Note that the SSH key pair must @emph{not} be passphrase-protected, to
585allow non-interactive logins.
586
587@end table
588
4ec2e92d 589A number of optional fields may be specified:
49e6291a
LC
590
591@table @code
592
cecd72d5
LC
593@item port
594Port number of the machine's SSH server (default: 22).
595
49e6291a
LC
596@item private-key
597The SSH private key file to use when connecting to the machine.
598
599@item parallel-builds
600The number of builds that may run in parallel on the machine (1 by
601default.)
602
603@item speed
604A ``relative speed factor''. The offload scheduler will tend to prefer
605machines with a higher speed factor.
606
607@item features
608A list of strings denoting specific features supported by the machine.
609An example is @code{"kvm"} for machines that have the KVM Linux modules
610and corresponding hardware support. Derivations can request features by
611name, and they will be scheduled on matching build machines.
612
613@end table
c678a4ee 614@end deftp
49e6291a
LC
615
616The @code{guix} command must be in the search path on the build
617machines, since offloading works by invoking the @code{guix archive} and
618@code{guix build} commands.
619
620There's one last thing to do once @file{machines.scm} is in place. As
621explained above, when offloading, files are transferred back and forth
622between the machine stores. For this to work, you need to generate a
623key pair to allow the daemon to export signed archives of files from the
624store (@pxref{Invoking guix archive}):
625
626@example
627# guix archive --generate-key
628@end example
629
630@noindent
631Thus, when receiving files, a machine's build daemon can make sure they
632are genuine, have not been tampered with, and that they are signed by an
633authorized key.
634
635
bd5e766b
LC
636@node Invoking guix-daemon
637@section Invoking @command{guix-daemon}
638
639The @command{guix-daemon} program implements all the functionality to
640access the store. This includes launching build processes, running the
641garbage collector, querying the availability of a build result, etc. It
642is normally run as @code{root} like this:
643
644@example
cfc149dc 645# guix-daemon --build-users-group=guixbuild
bd5e766b
LC
646@end example
647
648@noindent
081145cf 649For details on how to set it up, @pxref{Setting Up the Daemon}.
bd5e766b 650
e900c503
LC
651@cindex chroot
652@cindex container, build environment
653@cindex build environment
654@cindex reproducible builds
bd5e766b
LC
655By default, @command{guix-daemon} launches build processes under
656different UIDs, taken from the build group specified with
657@code{--build-users-group}. In addition, each build process is run in a
658chroot environment that only contains the subset of the store that the
659build process depends on, as specified by its derivation
660(@pxref{Programming Interface, derivation}), plus a set of specific
661system directories. By default, the latter contains @file{/dev} and
e900c503
LC
662@file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
663@dfn{container}: in addition to having its own file system tree, it has
664a separate mount name space, its own PID name space, network name space,
665etc. This helps achieve reproducible builds (@pxref{Features}).
bd5e766b 666
cbc538fe
LC
667When the daemon performs a build on behalf of the user, it creates a
668build directory under @file{/tmp} or under the directory specified by
669its @code{TMPDIR} environment variable; this directory is shared with
670the container for the duration of the build. Be aware that using a
671directory other than @file{/tmp} can affect build results---for example,
672with a longer directory name, a build process that uses Unix-domain
673sockets might hit the name length limitation for @code{sun_path}, which
674it would otherwise not hit.
675
676The build directory is automatically deleted upon completion, unless the
677build failed and the client specified @option{--keep-failed}
678(@pxref{Invoking guix build, @option{--keep-failed}}).
679
bd5e766b
LC
680The following command-line options are supported:
681
682@table @code
683@item --build-users-group=@var{group}
684Take users from @var{group} to run build processes (@pxref{Setting Up
685the Daemon, build users}).
686
6858f9d1 687@item --no-substitutes
b5385b52 688@cindex substitutes
6858f9d1 689Do not use substitutes for build products. That is, always build things
c4202d60
LC
690locally instead of allowing downloads of pre-built binaries
691(@pxref{Substitutes}).
6858f9d1 692
b5385b52
LC
693By default substitutes are used, unless the client---such as the
694@command{guix package} command---is explicitly invoked with
695@code{--no-substitutes}.
696
697When the daemon runs with @code{--no-substitutes}, clients can still
698explicitly enable substitution @i{via} the @code{set-build-options}
699remote procedure call (@pxref{The Store}).
700
9176607e
LC
701@item --substitute-urls=@var{urls}
702Consider @var{urls} the default whitespace-separated list of substitute
ae806096 703source URLs. When this option is omitted, @indicateurl{http://hydra.gnu.org}
9176607e
LC
704is used.
705
706This means that substitutes may be downloaded from @var{urls}, as long
707as they are signed by a trusted signature (@pxref{Substitutes}).
708
4ec2e92d
LC
709@cindex build hook
710@item --no-build-hook
711Do not use the @dfn{build hook}.
712
713The build hook is a helper program that the daemon can start and to
714which it submits build requests. This mechanism is used to offload
715builds to other machines (@pxref{Daemon Offload Setup}).
716
bd5e766b
LC
717@item --cache-failures
718Cache build failures. By default, only successful builds are cached.
719
720@item --cores=@var{n}
721@itemx -c @var{n}
722Use @var{n} CPU cores to build each derivation; @code{0} means as many
723as available.
724
6efc160e 725The default value is @code{0}, but it may be overridden by clients, such
e49951eb
MW
726as the @code{--cores} option of @command{guix build} (@pxref{Invoking
727guix build}).
bd5e766b
LC
728
729The effect is to define the @code{NIX_BUILD_CORES} environment variable
730in the build process, which can then use it to exploit internal
731parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
732
733@item --max-jobs=@var{n}
734@itemx -M @var{n}
735Allow at most @var{n} build jobs in parallel. The default value is
f6526eb3
LC
736@code{1}. Setting it to @code{0} means that no builds will be performed
737locally; instead, the daemon will offload builds (@pxref{Daemon Offload
738Setup}), or simply fail.
bd5e766b
LC
739
740@item --debug
741Produce debugging output.
742
743This is useful to debug daemon start-up issues, but then it may be
744overridden by clients, for example the @code{--verbosity} option of
e49951eb 745@command{guix build} (@pxref{Invoking guix build}).
bd5e766b
LC
746
747@item --chroot-directory=@var{dir}
748Add @var{dir} to the build chroot.
749
750Doing this may change the result of build processes---for instance if
751they use optional dependencies found in @var{dir} when it is available,
752and not otherwise. For that reason, it is not recommended to do so.
753Instead, make sure that each derivation declares all the inputs that it
754needs.
755
756@item --disable-chroot
757Disable chroot builds.
758
759Using this option is not recommended since, again, it would allow build
760processes to gain access to undeclared dependencies.
761
762@item --disable-log-compression
763Disable compression of the build logs.
764
1da983b9
LC
765Unless @code{--lose-logs} is used, all the build logs are kept in the
766@var{localstatedir}. To save space, the daemon automatically compresses
767them with bzip2 by default. This option disables that.
768
ab3893d7
LC
769@item --disable-deduplication
770@cindex deduplication
bd5e766b
LC
771Disable automatic file ``deduplication'' in the store.
772
1da983b9 773By default, files added to the store are automatically ``deduplicated'':
ab3893d7
LC
774if a newly added file is identical to another one found in the store,
775the daemon makes the new file a hard link to the other file. This can
776noticeably reduce disk usage, at the expense of slightly increasde
777input/output load at the end of a build process. This option disables
778this optimization.
1da983b9 779
6e37066e
LC
780@item --gc-keep-outputs[=yes|no]
781Tell whether the garbage collector (GC) must keep outputs of live
782derivations.
783
784When set to ``yes'', the GC will keep the outputs of any live derivation
785available in the store---the @code{.drv} files. The default is ``no'',
786meaning that derivation outputs are kept only if they are GC roots.
787
788@item --gc-keep-derivations[=yes|no]
789Tell whether the garbage collector (GC) must keep derivations
790corresponding to live outputs.
791
792When set to ``yes'', as is the case by default, the GC keeps
793derivations---i.e., @code{.drv} files---as long as at least one of their
794outputs is live. This allows users to keep track of the origins of
795items in their store. Setting it to ``no'' saves a bit of disk space.
796
797Note that when both @code{--gc-keep-derivations} and
798@code{--gc-keep-outputs} are used, the effect is to keep all the build
799prerequisites (the sources, compiler, libraries, and other build-time
800tools) of live objects in the store, regardless of whether these
801prerequisites are live. This is convenient for developers since it
802saves rebuilds or downloads.
803
bd5e766b
LC
804@item --impersonate-linux-2.6
805On Linux-based systems, impersonate Linux 2.6. This means that the
806kernel's @code{uname} system call will report 2.6 as the release number.
807
808This might be helpful to build programs that (usually wrongfully) depend
809on the kernel version number.
810
811@item --lose-logs
812Do not keep build logs. By default they are kept under
ce33631f 813@code{@var{localstatedir}/guix/log}.
bd5e766b
LC
814
815@item --system=@var{system}
816Assume @var{system} as the current system type. By default it is the
817architecture/kernel pair found at configure time, such as
818@code{x86_64-linux}.
b8d2aa26
LC
819
820@item --listen=@var{socket}
821Listen for connections on @var{socket}, the file name of a Unix-domain
822socket. The default socket is
823@file{@var{localstatedir}/daemon-socket/socket}. This option is only
824useful in exceptional circumstances, such as if you need to run several
825daemons on the same machine.
bd5e766b
LC
826@end table
827
828
eeaf4427
LC
829@c *********************************************************************
830@node Package Management
831@chapter Package Management
832
f8348b91 833The purpose of GNU Guix is to allow users to easily install, upgrade, and
eeaf4427
LC
834remove software packages, without having to know about their build
835procedure or dependencies. Guix also goes beyond this obvious set of
836features.
837
838This chapter describes the main features of Guix, as well as the package
c1941588
LC
839management tools it provides. Two user interfaces are provided for
840routine package management tasks: a command-line interface
841(@pxref{Invoking guix package, @code{guix package}}), and a visual user
842interface in Emacs (@pxref{Emacs Interface}).
eeaf4427
LC
843
844@menu
845* Features:: How Guix will make your life brighter.
e49951eb 846* Invoking guix package:: Package installation, removal, etc.
457f60fa 847* Emacs Interface:: Package management from Emacs.
c4202d60 848* Substitutes:: Downloading pre-built binaries.
760c60d6 849* Packages with Multiple Outputs:: Single source package, multiple outputs.
e49951eb 850* Invoking guix gc:: Running the garbage collector.
f651b477 851* Invoking guix pull:: Fetching the latest Guix and distribution.
760c60d6 852* Invoking guix archive:: Exporting and importing store files.
eeaf4427
LC
853@end menu
854
855@node Features
856@section Features
857
858When using Guix, each package ends up in the @dfn{package store}, in its
859own directory---something that resembles
9a130e19
AK
860@file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string
861(note that Guix comes with an Emacs extension to shorten those file
081145cf 862names, @pxref{Emacs Prettify}.)
eeaf4427
LC
863
864Instead of referring to these directories, users have their own
865@dfn{profile}, which points to the packages that they actually want to
821b0015
LC
866use. These profiles are stored within each user's home directory, at
867@code{$HOME/.guix-profile}.
eeaf4427 868
821b0015 869For example, @code{alice} installs GCC 4.7.2. As a result,
eeaf4427 870@file{/home/alice/.guix-profile/bin/gcc} points to
834129e0 871@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
821b0015
LC
872@code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
873simply continues to point to
834129e0 874@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
821b0015 875coexist on the same system without any interference.
eeaf4427 876
e49951eb
MW
877The @command{guix package} command is the central tool to manage
878packages (@pxref{Invoking guix package}). It operates on those per-user
821b0015 879profiles, and can be used @emph{with normal user privileges}.
eeaf4427
LC
880
881The command provides the obvious install, remove, and upgrade
882operations. Each invocation is actually a @emph{transaction}: either
ba55b1cb 883the specified operation succeeds, or nothing happens. Thus, if the
e49951eb 884@command{guix package} process is terminated during the transaction,
eeaf4427
LC
885or if a power outage occurs during the transaction, then the user's
886profile remains in its previous state, and remains usable.
887
888In addition, any package transaction may be @emph{rolled back}. So, if,
889for example, an upgrade installs a new version of a package that turns
890out to have a serious bug, users may roll back to the previous instance
4af2447e
LC
891of their profile, which was known to work well. Similarly, the global
892system configuration is subject to transactional upgrades and roll-back
893(@pxref{Using the Configuration System}).
eeaf4427
LC
894
895All those packages in the package store may be @emph{garbage-collected}.
896Guix can determine which packages are still referenced by the user
fe8ff028 897profiles, and remove those that are provably no longer referenced
e49951eb 898(@pxref{Invoking guix gc}). Users may also explicitly remove old
fe8ff028
LC
899generations of their profile so that the packages they refer to can be
900collected.
eeaf4427 901
e900c503
LC
902@cindex reproducibility
903@cindex reproducible builds
eeaf4427
LC
904Finally, Guix takes a @dfn{purely functional} approach to package
905management, as described in the introduction (@pxref{Introduction}).
834129e0 906Each @file{/gnu/store} package directory name contains a hash of all the
eeaf4427
LC
907inputs that were used to build that package---compiler, libraries, build
908scripts, etc. This direct correspondence allows users to make sure a
909given package installation matches the current state of their
e900c503
LC
910distribution. It also helps maximize @dfn{build reproducibility}:
911thanks to the isolated build environments that are used, a given build
912is likely to yield bit-identical files when performed on different
913machines (@pxref{Invoking guix-daemon, container}).
eeaf4427 914
c4202d60 915@cindex substitutes
eeaf4427 916This foundation allows Guix to support @dfn{transparent binary/source
c4202d60 917deployment}. When a pre-built binary for a @file{/gnu/store} item is
18f2887b 918available from an external source---a @dfn{substitute}, Guix just
c4202d60
LC
919downloads it and unpacks it;
920otherwise, it builds the package from source, locally
921(@pxref{Substitutes}).
eeaf4427 922
f5fd4fd2
LC
923Control over the build environment is a feature that is also useful for
924developers. The @command{guix environment} command allows developers of
925a package to quickly set up the right development environment for their
926package, without having to manually install the package's dependencies
927in their profile (@pxref{Invoking guix environment}).
928
e49951eb
MW
929@node Invoking guix package
930@section Invoking @command{guix package}
eeaf4427 931
e49951eb 932The @command{guix package} command is the tool that allows users to
eeaf4427
LC
933install, upgrade, and remove packages, as well as rolling back to
934previous configurations. It operates only on the user's own profile,
935and works with normal user privileges (@pxref{Features}). Its syntax
936is:
937
938@example
e49951eb 939guix package @var{options}
eeaf4427
LC
940@end example
941
ba55b1cb 942Primarily, @var{options} specifies the operations to be performed during
eeaf4427 943the transaction. Upon completion, a new profile is created, but
99bd74d5 944previous @dfn{generations} of the profile remain available, should the user
eeaf4427
LC
945want to roll back.
946
6447738c
MW
947For example, to remove @code{lua} and install @code{guile} and
948@code{guile-cairo} in a single transaction:
949
950@example
951guix package -r lua -i guile guile-cairo
952@end example
953
99bd74d5
LC
954@command{guix package} also supports a @dfn{declarative approach}
955whereby the user specifies the exact set of packages to be available and
956passes it @i{via} the @option{--manifest} option
957(@pxref{profile-manifest, @option{--manifest}}).
958
b9e5c0a9 959For each user, a symlink to the user's default profile is automatically
0ec1af59 960created in @file{$HOME/.guix-profile}. This symlink always points to the
b9e5c0a9
LC
961current generation of the user's default profile. Thus, users can add
962@file{$HOME/.guix-profile/bin} to their @code{PATH} environment
963variable, and so on.
d664f1b4
LC
964@cindex search paths
965If you are not using the Guix System Distribution, consider adding the
966following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
967Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
968shells get all the right environment variable definitions:
969
970@example
971GUIX_PROFILE="$HOME/.guix-profile" \
972source "$HOME/.guix-profile/etc/profile"
973@end example
b9e5c0a9 974
4379c35b
LC
975In a multi-user setup, user profiles are stored in a place registered as
976a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
977to (@pxref{Invoking guix gc}). That directory is normally
0ec1af59
LC
978@code{@var{localstatedir}/profiles/per-user/@var{user}}, where
979@var{localstatedir} is the value passed to @code{configure} as
4379c35b
LC
980@code{--localstatedir}, and @var{user} is the user name. The
981@file{per-user} directory is created when @command{guix-daemon} is
982started, and the @var{user} sub-directory is created by @command{guix
983package}.
0ec1af59
LC
984
985The @var{options} can be among the following:
986
eeaf4427
LC
987@table @code
988
6447738c
MW
989@item --install=@var{package} @dots{}
990@itemx -i @var{package} @dots{}
991Install the specified @var{package}s.
eeaf4427 992
6447738c 993Each @var{package} may specify either a simple package name, such as
eeaf4427 994@code{guile}, or a package name followed by a hyphen and version number,
724311a2
LC
995such as @code{guile-1.8.8} or simply @code{guile-1.8} (in the latter
996case, the newest version prefixed by @code{1.8} is selected.)
997
998If no version number is specified, the
dc5669cd
MW
999newest available version will be selected. In addition, @var{package}
1000may contain a colon, followed by the name of one of the outputs of the
6e721c4d 1001package, as in @code{gcc:doc} or @code{binutils-2.22:lib}
e7f34eb0
LC
1002(@pxref{Packages with Multiple Outputs}). Packages with a corresponding
1003name (and optionally version) are searched for among the GNU
1004distribution modules (@pxref{Package Modules}).
eeaf4427 1005
461572cc
LC
1006@cindex propagated inputs
1007Sometimes packages have @dfn{propagated inputs}: these are dependencies
21461f27
LC
1008that automatically get installed along with the required package
1009(@pxref{package-propagated-inputs, @code{propagated-inputs} in
1010@code{package} objects}, for information about propagated inputs in
1011package definitions).
461572cc 1012
21461f27 1013@anchor{package-cmd-propagated-inputs}
461572cc
LC
1014An example is the GNU MPC library: its C header files refer to those of
1015the GNU MPFR library, which in turn refer to those of the GMP library.
1016Thus, when installing MPC, the MPFR and GMP libraries also get installed
1017in the profile; removing MPC also removes MPFR and GMP---unless they had
1018also been explicitly installed independently.
1019
ba7ea5ce 1020Besides, packages sometimes rely on the definition of environment
5924080d 1021variables for their search paths (see explanation of
ba7ea5ce 1022@code{--search-paths} below). Any missing or possibly incorrect
5924080d
LC
1023environment variable definitions are reported here.
1024
ef010c0f 1025@c XXX: keep me up-to-date
5924080d 1026Finally, when installing a GNU package, the tool reports the
ef010c0f
LC
1027availability of a newer upstream version. In the future, it may provide
1028the option of installing directly from the upstream version, even if
1029that version is not yet in the distribution.
1030
5d4b411f
LC
1031@item --install-from-expression=@var{exp}
1032@itemx -e @var{exp}
1033Install the package @var{exp} evaluates to.
1034
1035@var{exp} must be a Scheme expression that evaluates to a
1036@code{<package>} object. This option is notably useful to disambiguate
1037between same-named variants of a package, with expressions such as
1038@code{(@@ (gnu packages base) guile-final)}.
1039
1040Note that this option installs the first output of the specified
1041package, which may be insufficient when needing a specific output of a
1042multiple-output package.
1043
6447738c
MW
1044@item --remove=@var{package} @dots{}
1045@itemx -r @var{package} @dots{}
1046Remove the specified @var{package}s.
eeaf4427 1047
6447738c 1048As for @code{--install}, each @var{package} may specify a version number
13ed095c
LC
1049and/or output name in addition to the package name. For instance,
1050@code{-r glibc:debug} would remove the @code{debug} output of
1051@code{glibc}.
1052
6447738c
MW
1053@item --upgrade[=@var{regexp} @dots{}]
1054@itemx -u [@var{regexp} @dots{}]
1055Upgrade all the installed packages. If one or more @var{regexp}s are
1056specified, upgrade only installed packages whose name matches a
d5f01e48 1057@var{regexp}. Also see the @code{--do-not-upgrade} option below.
eeaf4427 1058
f651b477
LC
1059Note that this upgrades package to the latest version of packages found
1060in the distribution currently installed. To update your distribution,
1061you should regularly run @command{guix pull} (@pxref{Invoking guix
1062pull}).
1063
d5f01e48
MW
1064@item --do-not-upgrade[=@var{regexp} @dots{}]
1065When used together with the @code{--upgrade} option, do @emph{not}
1066upgrade any packages whose name matches a @var{regexp}. For example, to
1067upgrade all packages in the current profile except those containing the
1068substring ``emacs'':
1069
1070@example
1071$ guix package --upgrade . --do-not-upgrade emacs
1072@end example
1073
99bd74d5 1074@item @anchor{profile-manifest}--manifest=@var{file}
1b676447 1075@itemx -m @var{file}
99bd74d5
LC
1076@cindex profile declaration
1077@cindex profile manifest
1078Create a new generation of the profile from the manifest object
1b676447
DT
1079returned by the Scheme code in @var{file}.
1080
99bd74d5
LC
1081This allows you to @emph{declare} the profile's contents rather than
1082constructing it through a sequence of @code{--install} and similar
1083commands. The advantage is that @var{file} can be put under version
1084control, copied to different machines to reproduce the same profile, and
1085so on.
1086
1087@c FIXME: Add reference to (guix profile) documentation when available.
1088@var{file} must return a @dfn{manifest} object, which is roughly a list
1089of packages:
1b676447 1090
99bd74d5 1091@findex packages->manifest
1b676447 1092@example
99bd74d5 1093(use-package-modules guile emacs)
1b676447
DT
1094
1095(packages->manifest
99bd74d5
LC
1096 (list emacs
1097 guile-2.0
1b676447 1098 ;; Use a specific package output.
99bd74d5 1099 (list guile-2.0 "debug")))
1b676447
DT
1100@end example
1101
24e262f0
LC
1102@item --roll-back
1103Roll back to the previous @dfn{generation} of the profile---i.e., undo
1104the last transaction.
1105
1106When combined with options such as @code{--install}, roll back occurs
1107before any other actions.
1108
d9307267 1109When rolling back from the first generation that actually contains
4b2bc804
NK
1110installed packages, the profile is made to point to the @dfn{zeroth
1111generation}, which contains no files apart from its own meta-data.
d9307267 1112
82fe08ed
LC
1113Installing, removing, or upgrading packages from a generation that has
1114been rolled back to overwrites previous future generations. Thus, the
1115history of a profile's generations is always linear.
1116
b3bb82f1
AK
1117@item --switch-generation=@var{pattern}
1118@itemx -S @var{pattern}
1119Switch to a particular generation defined by @var{pattern}.
1120
1121@var{pattern} may be either a generation number or a number prefixed
1122with ``+'' or ``-''. The latter means: move forward/backward by a
1123specified number of generations. For example, if you want to return to
1124the latest generation after @code{--roll-back}, use
1125@code{--switch-generation=+1}.
1126
1127The difference between @code{--roll-back} and
1128@code{--switch-generation=-1} is that @code{--switch-generation} will
1129not make a zeroth generation, so if a specified generation does not
1130exist, the current generation will not be changed.
1131
dbc31ab2 1132@item --search-paths[=@var{kind}]
5924080d
LC
1133@cindex search paths
1134Report environment variable definitions, in Bash syntax, that may be
1135needed in order to use the set of installed packages. These environment
1136variables are used to specify @dfn{search paths} for files used by some
1137of the installed packages.
1138
1139For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH}
1140environment variables to be defined so it can look for headers and
1141libraries in the user's profile (@pxref{Environment Variables,,, gcc,
1142Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
1143library are installed in the profile, then @code{--search-paths} will
1144suggest setting these variables to @code{@var{profile}/include} and
1145@code{@var{profile}/lib}, respectively.
1146
dbc31ab2
LC
1147The typical use case is to define these environment variables in the
1148shell:
1149
1150@example
1151$ eval `guix package --search-paths`
1152@end example
1153
1154@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
1155meaning that the returned environment variable definitions will either
1156be exact settings, or prefixes or suffixes of the current value of these
1157variables. When omitted, @var{kind} defaults to @code{exact}.
1158
eeaf4427
LC
1159@item --profile=@var{profile}
1160@itemx -p @var{profile}
1161Use @var{profile} instead of the user's default profile.
1162
70915c1a
LC
1163@item --verbose
1164Produce verbose output. In particular, emit the environment's build log
1165on the standard error port.
1166
eeaf4427
LC
1167@item --bootstrap
1168Use the bootstrap Guile to build the profile. This option is only
1169useful to distribution developers.
1170
1171@end table
1172
e49951eb 1173In addition to these actions @command{guix package} supports the
733b4130
LC
1174following options to query the current state of a profile, or the
1175availability of packages:
eeaf4427 1176
733b4130
LC
1177@table @option
1178
acc08466
NK
1179@item --search=@var{regexp}
1180@itemx -s @var{regexp}
5763ad92 1181List the available packages whose name, synopsis, or description matches
299112d3
LC
1182@var{regexp}. Print all the meta-data of matching packages in
1183@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
1184GNU recutils manual}).
acc08466 1185
299112d3
LC
1186This allows specific fields to be extracted using the @command{recsel}
1187command, for instance:
1188
1189@example
e49951eb 1190$ guix package -s malloc | recsel -p name,version
299112d3
LC
1191name: glibc
1192version: 2.17
1193
1194name: libgc
1195version: 7.2alpha6
1196@end example
acc08466 1197
a12d92f5
LC
1198Similarly, to show the name of all the packages available under the
1199terms of the GNU@tie{}LGPL version 3:
1200
1201@example
1202$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
1203name: elfutils
1204
1205name: gmp
1206@dots{}
1207@end example
1208
2aa6efb0
CR
1209@item --show=@var{package}
1210Show details about @var{package}, taken from the list of available packages, in
1211@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
1212recutils manual}).
1213
1214@example
1215$ guix package --show=python | recsel -p name,version
1216name: python
1217version: 2.7.6
1218
1219name: python
1220version: 3.3.5
1221@end example
1222
1223You may also specify the full name of a package to only get details about a
1224specific version of it:
1225@example
1226$ guix package --show=python-3.3.5 | recsel -p name,version
1227name: python
1228version: 3.3.5
1229@end example
1230
1231
1232
733b4130
LC
1233@item --list-installed[=@var{regexp}]
1234@itemx -I [@var{regexp}]
bd9bde1c
LC
1235List the currently installed packages in the specified profile, with the
1236most recently installed packages shown last. When @var{regexp} is
1237specified, list only installed packages whose name matches @var{regexp}.
733b4130
LC
1238
1239For each installed package, print the following items, separated by
1240tabs: the package name, its version string, the part of the package that
1241is installed (for instance, @code{out} for the default output,
1242@code{include} for its headers, etc.), and the path of this package in
1243the store.
1244
64fc89b6
LC
1245@item --list-available[=@var{regexp}]
1246@itemx -A [@var{regexp}]
5763ad92 1247List packages currently available in the distribution for this system
a1ba8475
LC
1248(@pxref{GNU Distribution}). When @var{regexp} is specified, list only
1249installed packages whose name matches @var{regexp}.
64fc89b6
LC
1250
1251For each package, print the following items separated by tabs: its name,
6e721c4d
LC
1252its version string, the parts of the package (@pxref{Packages with
1253Multiple Outputs}), and the source location of its definition.
64fc89b6 1254
f566d765
LC
1255@item --list-generations[=@var{pattern}]
1256@itemx -l [@var{pattern}]
1257Return a list of generations along with their creation dates; for each
1258generation, show the installed packages, with the most recently
4b2bc804
NK
1259installed packages shown last. Note that the zeroth generation is never
1260shown.
f566d765
LC
1261
1262For each installed package, print the following items, separated by
1263tabs: the name of a package, its version string, the part of the package
1264that is installed (@pxref{Packages with Multiple Outputs}), and the
1265location of this package in the store.
1266
1267When @var{pattern} is used, the command returns only matching
1268generations. Valid patterns include:
1269
1270@itemize
1271@item @emph{Integers and comma-separated integers}. Both patterns denote
1272generation numbers. For instance, @code{--list-generations=1} returns
1273the first one.
1274
1275And @code{--list-generations=1,8,2} outputs three generations in the
1276specified order. Neither spaces nor trailing commas are allowed.
1277
1278@item @emph{Ranges}. @code{--list-generations=2..9} prints the
1279specified generations and everything in between. Note that the start of
1280a range must be lesser than its end.
1281
1282It is also possible to omit the endpoint. For example,
1283@code{--list-generations=2..}, returns all generations starting from the
1284second one.
1285
1286@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
1287or months by passing an integer along with the first letter of the
d7ddb257
LC
1288duration. For example, @code{--list-generations=20d} lists generations
1289that are up to 20 days old.
f566d765
LC
1290@end itemize
1291
b7884ca3
NK
1292@item --delete-generations[=@var{pattern}]
1293@itemx -d [@var{pattern}]
d7ddb257
LC
1294When @var{pattern} is omitted, delete all generations except the current
1295one.
b7884ca3
NK
1296
1297This command accepts the same patterns as @option{--list-generations}.
d7ddb257
LC
1298When @var{pattern} is specified, delete the matching generations. When
1299@var{pattern} specifies a duration, generations @emph{older} than the
1300specified duration match. For instance, @code{--delete-generations=1m}
1301deletes generations that are more than one month old.
1302
391bdd8f
LC
1303If the current generation matches, it is @emph{not} deleted. Also, the
1304zeroth generation is never deleted.
b7884ca3 1305
1bb9900a
LC
1306Note that deleting generations prevents roll-back to them.
1307Consequently, this command must be used with care.
1308
733b4130 1309@end table
eeaf4427 1310
70ee5642
LC
1311Finally, since @command{guix package} may actually start build
1312processes, it supports all the common build options that @command{guix
1313build} supports (@pxref{Invoking guix build, common build options}).
1314
457f60fa
AK
1315@include emacs.texi
1316
c4202d60
LC
1317@node Substitutes
1318@section Substitutes
1319
1320@cindex substitutes
1321@cindex pre-built binaries
1322Guix supports transparent source/binary deployment, which means that it
1323can either build things locally, or download pre-built items from a
1324server. We call these pre-built items @dfn{substitutes}---they are
1325substitutes for local build results. In many cases, downloading a
1326substitute is much faster than building things locally.
1327
1328Substitutes can be anything resulting from a derivation build
1329(@pxref{Derivations}). Of course, in the common case, they are
1330pre-built package binaries, but source tarballs, for instance, which
1331also result from derivation builds, can be available as substitutes.
1332
1333The @code{hydra.gnu.org} server is a front-end to a build farm that
1334builds packages from the GNU distribution continuously for some
9176607e
LC
1335architectures, and makes them available as substitutes. This is the
1336default source of substitutes; it can be overridden by passing
1337@command{guix-daemon} the @code{--substitute-urls} option
1338(@pxref{Invoking guix-daemon}).
c4202d60
LC
1339
1340@cindex security
1341@cindex digital signatures
1342To allow Guix to download substitutes from @code{hydra.gnu.org}, you
1343must add its public key to the access control list (ACL) of archive
1344imports, using the @command{guix archive} command (@pxref{Invoking guix
1345archive}). Doing so implies that you trust @code{hydra.gnu.org} to not
1346be compromised and to serve genuine substitutes.
1347
1348This public key is installed along with Guix, in
1349@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is
1350the installation prefix of Guix. If you installed Guix from source,
1351make sure you checked the GPG signature of
1352@file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
1353Then, you can run something like this:
1354
1355@example
1356# guix archive --authorize < hydra.gnu.org.pub
1357@end example
1358
1359Once this is in place, the output of a command like @code{guix build}
1360should change from something like:
1361
1362@example
1363$ guix build emacs --dry-run
1364The following derivations would be built:
1365 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
1366 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
1367 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
1368 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
1369@dots{}
1370@end example
1371
1372@noindent
1373to something like:
1374
1375@example
1376$ guix build emacs --dry-run
1377The following files would be downloaded:
1378 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
1379 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
1380 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
1381 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
1382@dots{}
1383@end example
1384
1385@noindent
1386This indicates that substitutes from @code{hydra.gnu.org} are usable and
1387will be downloaded, when possible, for future builds.
1388
1389Guix ignores substitutes that are not signed, or that are not signed by
ef27aa9c 1390one of the keys listed in the ACL. It also detects and raises an error
c4202d60
LC
1391when attempting to use a substitute that has been tampered with.
1392
1393The substitute mechanism can be disabled globally by running
1394@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
1395guix-daemon}). It can also be disabled temporarily by passing the
1396@code{--no-substitutes} option to @command{guix package}, @command{guix
1397build}, and other command-line tools.
1398
1399
1400Today, each individual's control over their own computing is at the
1401mercy of institutions, corporations, and groups with enough power and
1402determination to subvert the computing infrastructure and exploit its
1403weaknesses. While using @code{hydra.gnu.org} substitutes can be
1404convenient, we encourage users to also build on their own, or even run
1405their own build farm, such that @code{hydra.gnu.org} is less of an
8ce229fc
LC
1406interesting target. One way to help is by publishing the software you
1407build using @command{guix publish} so that others have one more choice
1408of server to download substitutes from (@pxref{Invoking guix publish}).
c4202d60
LC
1409
1410Guix has the foundations to maximize build reproducibility
1411(@pxref{Features}). In most cases, independent builds of a given
1412package or derivation should yield bit-identical results. Thus, through
1413a diverse set of independent package builds, we can strengthen the
1414integrity of our systems.
1415
1416In the future, we want Guix to have support to publish and retrieve
1417binaries to/from other users, in a peer-to-peer fashion. If you would
1418like to discuss this project, join us on @email{guix-devel@@gnu.org}.
1419
1420
6e721c4d
LC
1421@node Packages with Multiple Outputs
1422@section Packages with Multiple Outputs
1423
1424@cindex multiple-output packages
1425@cindex package outputs
1426
1427Often, packages defined in Guix have a single @dfn{output}---i.e., the
1428source package leads exactly one directory in the store. When running
1429@command{guix package -i glibc}, one installs the default output of the
1430GNU libc package; the default output is called @code{out}, but its name
1431can be omitted as shown in this command. In this particular case, the
1432default output of @code{glibc} contains all the C header files, shared
1433libraries, static libraries, Info documentation, and other supporting
1434files.
1435
1436Sometimes it is more appropriate to separate the various types of files
1437produced from a single source package into separate outputs. For
1438instance, the GLib C library (used by GTK+ and related packages)
1439installs more than 20 MiB of reference documentation as HTML pages.
1440To save space for users who do not need it, the documentation goes to a
1441separate output, called @code{doc}. To install the main GLib output,
1442which contains everything but the documentation, one would run:
1443
1444@example
1445guix package -i glib
1446@end example
1447
1448The command to install its documentation is:
1449
1450@example
1451guix package -i glib:doc
1452@end example
1453
1454Some packages install programs with different ``dependency footprints''.
1455For instance, the WordNet package install both command-line tools and
1456graphical user interfaces (GUIs). The former depend solely on the C
1457library, whereas the latter depend on Tcl/Tk and the underlying X
1458libraries. In this case, we leave the command-line tools in the default
1459output, whereas the GUIs are in a separate output. This allows users
1460who do not need the GUIs to save space.
1461
1462There are several such multiple-output packages in the GNU distribution.
91ef73d4
LC
1463Other conventional output names include @code{lib} for libraries and
1464possibly header files, @code{bin} for stand-alone programs, and
1465@code{debug} for debugging information (@pxref{Installing Debugging
1466Files}). The outputs of a packages are listed in the third column of
1467the output of @command{guix package --list-available} (@pxref{Invoking
1468guix package}).
6e721c4d 1469
eeaf4427 1470
e49951eb
MW
1471@node Invoking guix gc
1472@section Invoking @command{guix gc}
fe8ff028
LC
1473
1474@cindex garbage collector
1475Packages that are installed but not used may be @dfn{garbage-collected}.
e49951eb 1476The @command{guix gc} command allows users to explicitly run the garbage
c22eb992
LC
1477collector to reclaim space from the @file{/gnu/store} directory. It is
1478the @emph{only} way to remove files from @file{/gnu/store}---removing
1479files or directories manually may break it beyond repair!
fe8ff028
LC
1480
1481The garbage collector has a set of known @dfn{roots}: any file under
834129e0 1482@file{/gnu/store} reachable from a root is considered @dfn{live} and
fe8ff028
LC
1483cannot be deleted; any other file is considered @dfn{dead} and may be
1484deleted. The set of garbage collector roots includes default user
e49951eb
MW
1485profiles, and may be augmented with @command{guix build --root}, for
1486example (@pxref{Invoking guix build}).
fe8ff028 1487
1bb9900a
LC
1488Prior to running @code{guix gc --collect-garbage} to make space, it is
1489often useful to remove old generations from user profiles; that way, old
1490package builds referenced by those generations can be reclaimed. This
1491is achieved by running @code{guix package --delete-generations}
1492(@pxref{Invoking guix package}).
1493
e49951eb 1494The @command{guix gc} command has three modes of operation: it can be
fe8ff028
LC
1495used to garbage-collect any dead files (the default), to delete specific
1496files (the @code{--delete} option), or to print garbage-collector
1497information. The available options are listed below:
1498
1499@table @code
1500@item --collect-garbage[=@var{min}]
1501@itemx -C [@var{min}]
834129e0 1502Collect garbage---i.e., unreachable @file{/gnu/store} files and
fe8ff028
LC
1503sub-directories. This is the default operation when no option is
1504specified.
1505
1506When @var{min} is given, stop once @var{min} bytes have been collected.
1507@var{min} may be a number of bytes, or it may include a unit as a
4a44d7bb
LC
1508suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
1509(@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
fe8ff028
LC
1510
1511When @var{min} is omitted, collect all the garbage.
1512
1513@item --delete
1514@itemx -d
1515Attempt to delete all the store files and directories specified as
1516arguments. This fails if some of the files are not in the store, or if
1517they are still live.
1518
38d27786
LC
1519@item --optimize
1520@cindex deduplication
1521Optimize the store by hard-linking identical files---this is
1522@dfn{deduplication}.
1523
1524The daemon performs deduplication after each successful build or archive
1525import, unless it was started with @code{--disable-deduplication}
1526(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus,
1527this option is primarily useful when the daemon was running with
1528@code{--disable-deduplication}.
1529
fe8ff028
LC
1530@item --list-dead
1531Show the list of dead files and directories still present in the
1532store---i.e., files and directories no longer reachable from any root.
1533
1534@item --list-live
1535Show the list of live store files and directories.
ba8b732d
LC
1536
1537@end table
1538
1539In addition, the references among existing store files can be queried:
1540
1541@table @code
1542
1543@item --references
1544@itemx --referrers
1545List the references (respectively, the referrers) of store files given
1546as arguments.
1547
8e59fdd5
LC
1548@item --requisites
1549@itemx -R
1550List the requisites of the store files passed as arguments. Requisites
1551include the store files themselves, their references, and the references
1552of these, recursively. In other words, the returned list is the
1553@dfn{transitive closure} of the store files.
1554
fe8ff028
LC
1555@end table
1556
eeaf4427 1557
f651b477
LC
1558@node Invoking guix pull
1559@section Invoking @command{guix pull}
1560
1561Packages are installed or upgraded to the latest version available in
1562the distribution currently available on your local machine. To update
1563that distribution, along with the Guix tools, you must run @command{guix
1564pull}: the command downloads the latest Guix source code and package
1565descriptions, and deploys it.
1566
1567On completion, @command{guix package} will use packages and package
1568versions from this just-retrieved copy of Guix. Not only that, but all
1569the Guix commands and Scheme modules will also be taken from that latest
1570version. New @command{guix} sub-commands added by the update also
1571become available.
1572
1573The @command{guix pull} command is usually invoked with no arguments,
1574but it supports the following options:
1575
1576@table @code
1577@item --verbose
1578Produce verbose output, writing build logs to the standard error output.
1579
ab5d72ad
LC
1580@item --url=@var{url}
1581Download the source tarball of Guix from @var{url}.
1582
1583By default, the tarball is taken from its canonical address at
1584@code{gnu.org}, for the stable branch of Guix.
1585
f651b477
LC
1586@item --bootstrap
1587Use the bootstrap Guile to build the latest Guix. This option is only
1588useful to Guix developers.
1589@end table
1590
760c60d6
LC
1591
1592@node Invoking guix archive
1593@section Invoking @command{guix archive}
1594
1595The @command{guix archive} command allows users to @dfn{export} files
1596from the store into a single archive, and to later @dfn{import} them.
1597In particular, it allows store files to be transferred from one machine
1598to another machine's store. For example, to transfer the @code{emacs}
1599package to a machine connected over SSH, one would run:
1600
1601@example
56607088 1602guix archive --export -r emacs | ssh the-machine guix archive --import
760c60d6
LC
1603@end example
1604
87236aed 1605@noindent
56607088
LC
1606Similarly, a complete user profile may be transferred from one machine
1607to another like this:
1608
1609@example
1610guix archive --export -r $(readlink -f ~/.guix-profile) | \
1611 ssh the-machine guix-archive --import
1612@end example
1613
1614@noindent
1615However, note that, in both examples, all of @code{emacs} and the
1616profile as well as all of their dependencies are transferred (due to
1617@code{-r}), regardless of what is already available in the target
1618machine's store. The @code{--missing} option can help figure out which
1619items are missing from the target's store.
87236aed 1620
760c60d6 1621Archives are stored in the ``Nix archive'' or ``Nar'' format, which is
0dbd88db
LC
1622comparable in spirit to `tar', but with a few noteworthy differences
1623that make it more appropriate for our purposes. First, rather than
1624recording all Unix meta-data for each file, the Nar format only mentions
1625the file type (regular, directory, or symbolic link); Unix permissions
1626and owner/group are dismissed. Second, the order in which directory
1627entries are stored always follows the order of file names according to
1628the C locale collation order. This makes archive production fully
1629deterministic.
1630
1631When exporting, the daemon digitally signs the contents of the archive,
1632and that digital signature is appended. When importing, the daemon
1633verifies the signature and rejects the import in case of an invalid
1634signature or if the signing key is not authorized.
760c60d6
LC
1635@c FIXME: Add xref to daemon doc about signatures.
1636
1637The main options are:
1638
1639@table @code
1640@item --export
1641Export the specified store files or packages (see below.) Write the
1642resulting archive to the standard output.
1643
56607088
LC
1644Dependencies are @emph{not} included in the output, unless
1645@code{--recursive} is passed.
1646
1647@item -r
1648@itemx --recursive
1649When combined with @code{--export}, this instructs @command{guix
1650archive} to include dependencies of the given items in the archive.
1651Thus, the resulting archive is self-contained: it contains the closure
1652of the exported store items.
1653
760c60d6
LC
1654@item --import
1655Read an archive from the standard input, and import the files listed
1656therein into the store. Abort if the archive has an invalid digital
f82cc5fd
LC
1657signature, or if it is signed by a public key not among the authorized
1658keys (see @code{--authorize} below.)
554f26ec 1659
87236aed
LC
1660@item --missing
1661Read a list of store file names from the standard input, one per line,
1662and write on the standard output the subset of these files missing from
1663the store.
1664
554f26ec 1665@item --generate-key[=@var{parameters}]
f82cc5fd 1666@cindex signing, archives
554f26ec
LC
1667Generate a new key pair for the daemons. This is a prerequisite before
1668archives can be exported with @code{--export}. Note that this operation
1669usually takes time, because it needs to gather enough entropy to
1670generate the key pair.
1671
1672The generated key pair is typically stored under @file{/etc/guix}, in
1673@file{signing-key.pub} (public key) and @file{signing-key.sec} (private
867d8473
LC
1674key, which must be kept secret.) When @var{parameters} is omitted,
1675an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
1676versions before 1.6.0, it is a 4096-bit RSA key.
1677Alternately, @var{parameters} can specify
554f26ec
LC
1678@code{genkey} parameters suitable for Libgcrypt (@pxref{General
1679public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
1680Libgcrypt Reference Manual}).
f82cc5fd
LC
1681
1682@item --authorize
1683@cindex authorizing, archives
1684Authorize imports signed by the public key passed on standard input.
1685The public key must be in ``s-expression advanced format''---i.e., the
1686same format as the @file{signing-key.pub} file.
1687
1688The list of authorized keys is kept in the human-editable file
1689@file{/etc/guix/acl}. The file contains
1690@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
1691s-expressions''} and is structured as an access-control list in the
1692@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
1693(SPKI)}.
760c60d6
LC
1694@end table
1695
1696To export store files as an archive to the standard output, run:
1697
1698@example
1699guix archive --export @var{options} @var{specifications}...
1700@end example
1701
1702@var{specifications} may be either store file names or package
1703specifications, as for @command{guix package} (@pxref{Invoking guix
1704package}). For instance, the following command creates an archive
1705containing the @code{gui} output of the @code{git} package and the main
1706output of @code{emacs}:
1707
1708@example
834129e0 1709guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
760c60d6
LC
1710@end example
1711
1712If the specified packages are not built yet, @command{guix archive}
1713automatically builds them. The build process may be controlled with the
1714same options that can be passed to the @command{guix build} command
70ee5642 1715(@pxref{Invoking guix build, common build options}).
760c60d6
LC
1716
1717
568717fd
LC
1718@c *********************************************************************
1719@node Programming Interface
1720@chapter Programming Interface
1721
3dc1970d
LC
1722GNU Guix provides several Scheme programming interfaces (APIs) to
1723define, build, and query packages. The first interface allows users to
1724write high-level package definitions. These definitions refer to
1725familiar packaging concepts, such as the name and version of a package,
1726its build system, and its dependencies. These definitions can then be
1727turned into concrete build actions.
1728
ba55b1cb 1729Build actions are performed by the Guix daemon, on behalf of users. In a
3dc1970d 1730standard setup, the daemon has write access to the store---the
834129e0 1731@file{/gnu/store} directory---whereas users do not. The recommended
3dc1970d
LC
1732setup also has the daemon perform builds in chroots, under a specific
1733build users, to minimize interference with the rest of the system.
1734
1735@cindex derivation
1736Lower-level APIs are available to interact with the daemon and the
1737store. To instruct the daemon to perform a build action, users actually
1738provide it with a @dfn{derivation}. A derivation is a low-level
1739representation of the build actions to be taken, and the environment in
1740which they should occur---derivations are to package definitions what
49ad317a
LC
1741assembly is to C programs. The term ``derivation'' comes from the fact
1742that build results @emph{derive} from them.
3dc1970d
LC
1743
1744This chapter describes all these APIs in turn, starting from high-level
1745package definitions.
1746
568717fd 1747@menu
b860f382 1748* Defining Packages:: Defining new packages.
7458bd0a 1749* Build Systems:: Specifying how packages are built.
b860f382
LC
1750* The Store:: Manipulating the package store.
1751* Derivations:: Low-level interface to package derivations.
1752* The Store Monad:: Purely functional interface to the store.
21b679f6 1753* G-Expressions:: Manipulating build expressions.
568717fd
LC
1754@end menu
1755
1756@node Defining Packages
1757@section Defining Packages
1758
3dc1970d
LC
1759The high-level interface to package definitions is implemented in the
1760@code{(guix packages)} and @code{(guix build-system)} modules. As an
1761example, the package definition, or @dfn{recipe}, for the GNU Hello
1762package looks like this:
1763
1764@example
e7f34eb0
LC
1765(define-module (gnu packages hello)
1766 #:use-module (guix packages)
1767 #:use-module (guix download)
1768 #:use-module (guix build-system gnu)
1769 #:use-module (guix licenses))
b22a12fd 1770
79f5dd59 1771(define-public hello
3dc1970d
LC
1772 (package
1773 (name "hello")
1774 (version "2.8")
1775 (source (origin
1776 (method url-fetch)
1777 (uri (string-append "mirror://gnu/hello/hello-" version
1778 ".tar.gz"))
1779 (sha256
1780 (base32 "0wqd8sjmxfskrflaxywc7gqw7sfawrfvdxd9skxawzfgyy0pzdz6"))))
1781 (build-system gnu-build-system)
7458bd0a 1782 (arguments `(#:configure-flags '("--enable-silent-rules")))
3dc1970d 1783 (inputs `(("gawk" ,gawk)))
7458bd0a
LC
1784 (synopsis "Hello, GNU world: An example GNU package")
1785 (description "Guess what GNU Hello prints!")
3dc1970d 1786 (home-page "http://www.gnu.org/software/hello/")
b22a12fd 1787 (license gpl3+)))
3dc1970d
LC
1788@end example
1789
1790@noindent
1791Without being a Scheme expert, the reader may have guessed the meaning
e7f34eb0 1792of the various fields here. This expression binds variable @code{hello}
3dc1970d
LC
1793to a @code{<package>} object, which is essentially a record
1794(@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
1795This package object can be inspected using procedures found in the
1796@code{(guix packages)} module; for instance, @code{(package-name hello)}
1797returns---surprise!---@code{"hello"}.
1798
2f7d2d91
LC
1799With luck, you may be able to import part or all of the definition of
1800the package you are interested in from another repository, using the
1801@code{guix import} command (@pxref{Invoking guix import}).
1802
e7f34eb0
LC
1803In the example above, @var{hello} is defined into a module of its own,
1804@code{(gnu packages hello)}. Technically, this is not strictly
1805necessary, but it is convenient to do so: all the packages defined in
1806modules under @code{(gnu packages @dots{})} are automatically known to
1807the command-line tools (@pxref{Package Modules}).
1808
3dc1970d
LC
1809There are a few points worth noting in the above package definition:
1810
1811@itemize
1812@item
a2bf4907
LC
1813The @code{source} field of the package is an @code{<origin>} object
1814(@pxref{origin Reference}, for the complete reference).
3dc1970d
LC
1815Here, the @code{url-fetch} method from @code{(guix download)} is used,
1816meaning that the source is a file to be downloaded over FTP or HTTP.
1817
1818The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
1819the GNU mirrors defined in @code{(guix download)}.
1820
1821The @code{sha256} field specifies the expected SHA256 hash of the file
1822being downloaded. It is mandatory, and allows Guix to check the
1823integrity of the file. The @code{(base32 @dots{})} form introduces the
6c365eca 1824base32 representation of the hash. You can obtain this information with
210cc920
LC
1825@code{guix download} (@pxref{Invoking guix download}) and @code{guix
1826hash} (@pxref{Invoking guix hash}).
3dc1970d 1827
f9cc8971
LC
1828@cindex patches
1829When needed, the @code{origin} form can also have a @code{patches} field
1830listing patches to be applied, and a @code{snippet} field giving a
1831Scheme expression to modify the source code.
1832
3dc1970d
LC
1833@item
1834@cindex GNU Build System
7458bd0a
LC
1835The @code{build-system} field specifies the procedure to build the
1836package (@pxref{Build Systems}). Here, @var{gnu-build-system}
1837represents the familiar GNU Build System, where packages may be
1838configured, built, and installed with the usual @code{./configure &&
1839make && make check && make install} command sequence.
1840
1841@item
1842The @code{arguments} field specifies options for the build system
1843(@pxref{Build Systems}). Here it is interpreted by
1844@var{gnu-build-system} as a request run @file{configure} with the
1845@code{--enable-silent-rules} flag.
3dc1970d
LC
1846
1847@item
1848The @code{inputs} field specifies inputs to the build process---i.e.,
1849build-time or run-time dependencies of the package. Here, we define an
1850input called @code{"gawk"} whose value is that of the @var{gawk}
1851variable; @var{gawk} is itself bound to a @code{<package>} object.
1852
1853Note that GCC, Coreutils, Bash, and other essential tools do not need to
1854be specified as inputs here. Instead, @var{gnu-build-system} takes care
7458bd0a 1855of ensuring that they are present (@pxref{Build Systems}).
3dc1970d
LC
1856
1857However, any other dependencies need to be specified in the
1858@code{inputs} field. Any dependency not specified here will simply be
1859unavailable to the build process, possibly leading to a build failure.
1860@end itemize
1861
87eafdbd
TUBK
1862@xref{package Reference}, for a full description of possible fields.
1863
2f7d2d91 1864Once a package definition is in place, the
e49951eb 1865package may actually be built using the @code{guix build} command-line
7458bd0a 1866tool (@pxref{Invoking guix build}). @xref{Packaging Guidelines}, for
b4f5e0e8
CR
1867more information on how to test package definitions, and
1868@ref{Invoking guix lint}, for information on how to check a definition
1869for style conformance.
1870
7458bd0a
LC
1871Eventually, updating the package definition to a new upstream version
1872can be partly automated by the @command{guix refresh} command
1873(@pxref{Invoking guix refresh}).
3dc1970d
LC
1874
1875Behind the scenes, a derivation corresponding to the @code{<package>}
1876object is first computed by the @code{package-derivation} procedure.
834129e0 1877That derivation is stored in a @code{.drv} file under @file{/gnu/store}.
ba55b1cb 1878The build actions it prescribes may then be realized by using the
3dc1970d
LC
1879@code{build-derivations} procedure (@pxref{The Store}).
1880
1881@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
59688fc4
LC
1882Return the @code{<derivation>} object of @var{package} for @var{system}
1883(@pxref{Derivations}).
3dc1970d
LC
1884
1885@var{package} must be a valid @code{<package>} object, and @var{system}
1886must be a string denoting the target system type---e.g.,
1887@code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
1888must be a connection to the daemon, which operates on the store
1889(@pxref{The Store}).
1890@end deffn
568717fd 1891
9c1edabd
LC
1892@noindent
1893@cindex cross-compilation
1894Similarly, it is possible to compute a derivation that cross-builds a
1895package for some other system:
1896
1897@deffn {Scheme Procedure} package-cross-derivation @var{store} @
1898 @var{package} @var{target} [@var{system}]
59688fc4
LC
1899Return the @code{<derivation>} object of @var{package} cross-built from
1900@var{system} to @var{target}.
9c1edabd
LC
1901
1902@var{target} must be a valid GNU triplet denoting the target hardware
1903and operating system, such as @code{"mips64el-linux-gnu"}
1904(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
1905Configure and Build System}).
1906@end deffn
1907
87eafdbd
TUBK
1908@menu
1909* package Reference :: The package data type.
1910* origin Reference:: The origin data type.
1911@end menu
1912
1913
1914@node package Reference
1915@subsection @code{package} Reference
1916
1917This section summarizes all the options available in @code{package}
1918declarations (@pxref{Defining Packages}).
1919
1920@deftp {Data Type} package
1921This is the data type representing a package recipe.
1922
1923@table @asis
1924@item @code{name}
1925The name of the package, as a string.
1926
1927@item @code{version}
1928The version of the package, as a string.
1929
1930@item @code{source}
1931An origin object telling how the source code for the package should be
1932acquired (@pxref{origin Reference}).
1933
1934@item @code{build-system}
1935The build system that should be used to build the package (@pxref{Build
1936Systems}).
1937
1938@item @code{arguments} (default: @code{'()})
1939The arguments that should be passed to the build system. This is a
1940list, typically containing sequential keyword-value pairs.
1941
1942@item @code{inputs} (default: @code{'()})
1943Package or derivation inputs to the build. This is a list of lists,
1944where each list has the name of the input (a string) as its first
1945element, a package or derivation object as its second element, and
1946optionally the name of the output of the package or derivation that
1947should be used, which defaults to @code{"out"}.
1948
21461f27
LC
1949@item @anchor{package-propagated-inputs}@code{propagated-inputs} (default: @code{'()})
1950@cindex propagated inputs
87eafdbd 1951This field is like @code{inputs}, but the specified packages will be
21461f27
LC
1952force-installed alongside the package they belong to
1953(@pxref{package-cmd-propagated-inputs, @command{guix package}}, for
1954information on how @command{guix package} deals with propagated inputs.)
1955
1956For example this is necessary when a library needs headers of another
1957library to compile, or needs another shared library to be linked
1958alongside itself when a program wants to link to it.
87eafdbd
TUBK
1959
1960@item @code{native-inputs} (default: @code{'()})
1961This field is like @code{inputs}, but in case of a cross-compilation it
1962will be ensured that packages for the architecture of the build machine
1963are present, such that executables from them can be used during the
21461f27
LC
1964build.
1965
1966This is typically where you would list tools needed at build time but
1967not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
1968Bison. @command{guix lint} can report likely mistakes in this area
1969(@pxref{Invoking guix lint}).
87eafdbd
TUBK
1970
1971@item @code{self-native-input?} (default: @code{#f})
1972This is a Boolean field telling whether the package should use itself as
1973a native input when cross-compiling.
1974
1975@item @code{outputs} (default: @code{'("out")})
1976The list of output names of the package. @xref{Packages with Multiple
1977Outputs}, for typical uses of additional outputs.
1978
1979@item @code{native-search-paths} (default: @code{'()})
1980@itemx @code{search-paths} (default: @code{'()})
1981A list of @code{search-path-specification} objects describing
1982search-path environment variables honored by the package.
1983
1984@item @code{replacement} (default: @code{#f})
1985This must either @code{#f} or a package object that will be used as a
1986@dfn{replacement} for this package. @xref{Security Updates, grafts},
1987for details.
1988
1989@item @code{synopsis}
1990A one-line description of the package.
1991
1992@item @code{description}
1993A more elaborate description of the package.
1994
1995@item @code{license}
1996The license of the package; a value from @code{(guix licenses)}.
1997
1998@item @code{home-page}
1999The URL to the home-page of the package, as a string.
2000
2001@item @code{supported-systems} (default: @var{%supported-systems})
2002The list of systems supported by the package, as strings of the form
2003@code{architecture-kernel}, for example @code{"x86_64-linux"}.
2004
2005@item @code{maintainers} (default: @code{'()})
2006The list of maintainers of the package, as @code{maintainer} objects.
2007
2008@item @code{location} (default: source location of the @code{package} form)
2009The source location of the package. It's useful to override this when
2010inheriting from another package, in which case this field is not
2011automatically corrected.
2012@end table
2013@end deftp
2014
2015
2016@node origin Reference
2017@subsection @code{origin} Reference
2018
2019This section summarizes all the options available in @code{origin}
2020declarations (@pxref{Defining Packages}).
2021
2022@deftp {Data Type} origin
2023This is the data type representing a source code origin.
2024
2025@table @asis
2026@item @code{uri}
2027An object containing the URI of the source. The object type depends on
2028the @code{method} (see below). For example, when using the
2029@var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
2030values are: a URL represented as a string, or a list thereof.
2031
2032@item @code{method}
2033A procedure that will handle the URI.
2034
2035Examples include:
2036
2037@table @asis
2038@item @var{url-fetch} from @code{(guix download)}
2039download a file the HTTP, HTTPS, or FTP URL specified in the
2040@code{uri} field;
2041
2042@item @var{git-fetch} from @code{(guix git-download)}
2043clone the Git version control repository, and check out the revision
2044specified in the @code{uri} field as a @code{git-reference} object; a
2045@code{git-reference} looks like this:
2046
2047@example
2048(git-reference
2049 (url "git://git.debian.org/git/pkg-shadow/shadow")
2050 (commit "v4.1.5.1"))
2051@end example
2052@end table
2053
2054@item @code{sha256}
2055A bytevector containing the SHA-256 hash of the source. Typically the
2056@code{base32} form is used here to generate the bytevector from a
2057base-32 string.
2058
2059@item @code{file-name} (default: @code{#f})
2060The file name under which the source code should be saved. When this is
2061@code{#f}, a sensible default value will be used in most cases. In case
2062the source is fetched from a URL, the file name from the URL will be
2063used. For version control checkouts, it's recommended to provide the
2064file name explicitly because the default is not very descriptive.
2065
2066@item @code{patches} (default: @code{'()})
2067A list of file names containing patches to be applied to the source.
2068
2069@item @code{snippet} (default: @code{#f})
2070A quoted piece of code that will be run in the source directory to make
2071any modifications, which is sometimes more convenient than a patch.
2072
2073@item @code{patch-flags} (default: @code{'("-p1")})
2074A list of command-line flags that should be passed to the @code{patch}
2075command.
2076
2077@item @code{patch-inputs} (default: @code{#f})
2078Input packages or derivations to the patching process. When this is
2079@code{#f}, the usual set of inputs necessary for patching are provided,
2080such as GNU@tie{}Patch.
2081
2082@item @code{modules} (default: @code{'()})
2083A list of Guile modules that should be loaded during the patching
2084process and while running the code in the @code{snippet} field.
2085
2086@item @code{imported-modules} (default: @code{'()})
2087The list of Guile modules to import in the patch derivation, for use by
2088the @code{snippet}.
2089
2090@item @code{patch-guile} (default: @code{#f})
2091The Guile package that should be used in the patching process. When
2092this is @code{#f}, a sensible default is used.
2093@end table
2094@end deftp
2095
9c1edabd 2096
7458bd0a
LC
2097@node Build Systems
2098@section Build Systems
2099
2100@cindex build system
2101Each package definition specifies a @dfn{build system} and arguments for
2102that build system (@pxref{Defining Packages}). This @code{build-system}
2103field represents the build procedure of the package, as well implicit
2104dependencies of that build procedure.
2105
2106Build systems are @code{<build-system>} objects. The interface to
2107create and manipulate them is provided by the @code{(guix build-system)}
2108module, and actual build systems are exported by specific modules.
2109
f5fd4fd2 2110@cindex bag (low-level package representation)
0d5a559f
LC
2111Under the hood, build systems first compile package objects to
2112@dfn{bags}. A @dfn{bag} is like a package, but with less
2113ornamentation---in other words, a bag is a lower-level representation of
2114a package, which includes all the inputs of that package, including some
2115that were implicitly added by the build system. This intermediate
2116representation is then compiled to a derivation (@pxref{Derivations}).
2117
7458bd0a
LC
2118Build systems accept an optional list of @dfn{arguments}. In package
2119definitions, these are passed @i{via} the @code{arguments} field
2120(@pxref{Defining Packages}). They are typically keyword arguments
2121(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
2122Guile Reference Manual}). The value of these arguments is usually
2123evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
2124by the daemon (@pxref{Derivations}).
2125
2126The main build system is @var{gnu-build-system}, which implements the
2127standard build procedure for GNU packages and many other packages. It
2128is provided by the @code{(guix build-system gnu)} module.
2129
2130@defvr {Scheme Variable} gnu-build-system
2131@var{gnu-build-system} represents the GNU Build System, and variants
2132thereof (@pxref{Configuration, configuration and makefile conventions,,
2133standards, GNU Coding Standards}).
2134
2135@cindex build phases
2136In a nutshell, packages using it configured, built, and installed with
2137the usual @code{./configure && make && make check && make install}
2138command sequence. In practice, a few additional steps are often needed.
2139All these steps are split up in separate @dfn{phases},
2140notably@footnote{Please see the @code{(guix build gnu-build-system)}
2141modules for more details about the build phases.}:
2142
2143@table @code
2144@item unpack
2145Unpack the source tarball, and change the current directory to the
2146extracted source tree. If the source is actually a directory, copy it
2147to the build tree, and enter that directory.
2148
2149@item patch-source-shebangs
2150Patch shebangs encountered in source files so they refer to the right
2151store file names. For instance, this changes @code{#!/bin/sh} to
2152@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
2153
2154@item configure
2155Run the @file{configure} script with a number of default options, such
2156as @code{--prefix=/gnu/store/@dots{}}, as well as the options specified
2157by the @code{#:configure-flags} argument.
2158
2159@item build
2160Run @code{make} with the list of flags specified with
2161@code{#:make-flags}. If the @code{#:parallel-builds?} argument is true
2162(the default), build with @code{make -j}.
2163
2164@item check
2165Run @code{make check}, or some other target specified with
2166@code{#:test-target}, unless @code{#:tests? #f} is passed. If the
2167@code{#:parallel-tests?} argument is true (the default), run @code{make
2168check -j}.
2169
2170@item install
2171Run @code{make install} with the flags listed in @code{#:make-flags}.
2172
2173@item patch-shebangs
2174Patch shebangs on the installed executable files.
2175
2176@item strip
2177Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
2178is false), copying them to the @code{debug} output when available
2179(@pxref{Installing Debugging Files}).
2180@end table
2181
2182@vindex %standard-phases
2183The build-side module @code{(guix build gnu-build-system)} defines
2184@var{%standard-phases} as the default list of build phases.
2185@var{%standard-phases} is a list of symbol/procedure pairs, where the
2186procedure implements the actual phase.
2187
2188The list of phases used for a particular package can be changed with the
2189@code{#:phases} parameter. For instance, passing:
2190
2191@example
2192#:phases (alist-delete 'configure %standard-phases)
2193@end example
2194
9bf404e9 2195means that all the phases described above will be used, except the
7458bd0a
LC
2196@code{configure} phase.
2197
2198In addition, this build system ensures that the ``standard'' environment
2199for GNU packages is available. This includes tools such as GCC, libc,
2200Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
2201build-system gnu)} module for a complete list.) We call these the
2202@dfn{implicit inputs} of a package, because package definitions don't
2203have to mention them.
2204@end defvr
2205
2206Other @code{<build-system>} objects are defined to support other
2207conventions and tools used by free software packages. They inherit most
2208of @var{gnu-build-system}, and differ mainly in the set of inputs
2209implicitly added to the build process, and in the list of phases
2210executed. Some of these build systems are listed below.
2211
2212@defvr {Scheme Variable} cmake-build-system
2213This variable is exported by @code{(guix build-system cmake)}. It
2214implements the build procedure for packages using the
2215@url{http://www.cmake.org, CMake build tool}.
2216
2217It automatically adds the @code{cmake} package to the set of inputs.
2218Which package is used can be specified with the @code{#:cmake}
2219parameter.
9849cfc1
LC
2220
2221The @code{#:configure-flags} parameter is taken as a list of flags
2222passed to the @command{cmake} command. The @code{#:build-type}
2223parameter specifies in abstract terms the flags passed to the compiler;
2224it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
2225debugging information''), which roughly means that code is compiled with
2226@code{-O2 -g}, as is the case for Autoconf-based packages by default.
7458bd0a
LC
2227@end defvr
2228
3afcf52b
FB
2229@defvr {Scheme Variable} glib-or-gtk-build-system
2230This variable is exported by @code{(guix build-system glib-or-gtk)}. It
2231is intended for use with packages making use of GLib or GTK+.
2232
2233This build system adds the following two phases to the ones defined by
2234@var{gnu-build-system}:
2235
2236@table @code
2237@item glib-or-gtk-wrap
2238The phase @code{glib-or-gtk-wrap} ensures that programs found under
2239@file{bin/} are able to find GLib's ``schemas'' and
2240@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
2241modules}. This is achieved by wrapping the programs in launch scripts
2242that appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH}
2243environment variables.
2244
73aa8ddb
LC
2245It is possible to exclude specific package outputs from that wrapping
2246process by listing their names in the
2247@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
2248when an output is known not to contain any GLib or GTK+ binaries, and
2249where wrapping would gratuitously add a dependency of that output on
2250GLib and GTK+.
2251
3afcf52b
FB
2252@item glib-or-gtk-compile-schemas
2253The phase @code{glib-or-gtk-compile-schemas} makes sure that all GLib's
2254@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
2255GSettings schemas} are compiled. Compilation is performed by the
2256@command{glib-compile-schemas} program. It is provided by the package
2257@code{glib:bin} which is automatically imported by the build system.
2258The @code{glib} package providing @command{glib-compile-schemas} can be
2259specified with the @code{#:glib} parameter.
2260@end table
2261
2262Both phases are executed after the @code{install} phase.
2263@end defvr
2264
7458bd0a
LC
2265@defvr {Scheme Variable} python-build-system
2266This variable is exported by @code{(guix build-system python)}. It
2267implements the more or less standard build procedure used by Python
2268packages, which consists in running @code{python setup.py build} and
2269then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
2270
2271For packages that install stand-alone Python programs under @code{bin/},
2272it takes care of wrapping these programs so their @code{PYTHONPATH}
2273environment variable points to all the Python libraries they depend on.
2274
2275Which Python package is used can be specified with the @code{#:python}
2276parameter.
2277@end defvr
2278
2279@defvr {Scheme Variable} perl-build-system
2280This variable is exported by @code{(guix build-system perl)}. It
2d2a53fc
EB
2281implements the standard build procedure for Perl packages, which either
2282consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
2283followed by @code{Build} and @code{Build install}; or in running
2284@code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
2285@code{make} and @code{make install}; depending on which of
2286@code{Build.PL} or @code{Makefile.PL} is present in the package
2287distribution. Preference is given to the former if both @code{Build.PL}
2288and @code{Makefile.PL} exist in the package distribution. This
2289preference can be reversed by specifying @code{#t} for the
2290@code{#:make-maker?} parameter.
2291
2292The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
2293passes flags specified by the @code{#:make-maker-flags} or
2294@code{#:module-build-flags} parameter, respectively.
7458bd0a
LC
2295
2296Which Perl package is used can be specified with @code{#:perl}.
2297@end defvr
2298
c08f9818
DT
2299@defvr {Scheme Variable} ruby-build-system
2300This variable is exported by @code{(guix build-system ruby)}. It
2301implements the RubyGems build procedure used by Ruby packages, which
2302involves running @code{gem build} followed by @code{gem install}.
2303
2304Which Ruby package is used can be specified with the @code{#:ruby}
2305parameter.
2306@end defvr
7458bd0a 2307
a677c726
RW
2308@defvr {Scheme Variable} waf-build-system
2309This variable is exported by @code{(guix build-system waf)}. It
2310implements a build procedure around the @code{waf} script. The common
2311phases---@code{configure}, @code{build}, and @code{install}---are
2312implemented by passing their names as arguments to the @code{waf}
2313script.
2314
2315The @code{waf} script is executed by the Python interpreter. Which
2316Python package is used to run the script can be specified with the
2317@code{#:python} parameter.
2318@end defvr
2319
14dfdf2e
FB
2320@defvr {Scheme Variable} haskell-build-system
2321This variable is exported by @code{(guix build-system haskell)}. It
2322implements the Cabal build procedure used by Haskell packages, which
2323involves running @code{runhaskell Setup.hs configure
2324--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
2325Instead of installing the package by running @code{runhaskell Setup.hs
2326install}, to avoid trying to register libraries in the read-only
2327compiler store directory, the build system uses @code{runhaskell
2328Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
2329addition, the build system generates the package documentation by
2330running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
2331is passed. Optional Haddock parameters can be passed with the help of
2332the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
2333not found, the build system looks for @code{Setup.lhs} instead.
2334
2335Which Haskell compiler is used can be specified with the @code{#:haskell}
2336parameter which defaults to @code{ghc}.
2337@end defvr
2338
7458bd0a
LC
2339Lastly, for packages that do not need anything as sophisticated, a
2340``trivial'' build system is provided. It is trivial in the sense that
2341it provides basically no support: it does not pull any implicit inputs,
2342and does not have a notion of build phases.
2343
2344@defvr {Scheme Variable} trivial-build-system
2345This variable is exported by @code{(guix build-system trivial)}.
2346
2347This build system requires a @code{#:builder} argument. This argument
2348must be a Scheme expression that builds the package's output(s)---as
2349with @code{build-expression->derivation} (@pxref{Derivations,
2350@code{build-expression->derivation}}).
2351@end defvr
2352
568717fd
LC
2353@node The Store
2354@section The Store
2355
e531ac2a
LC
2356@cindex store
2357@cindex store paths
2358
2359Conceptually, the @dfn{store} is where derivations that have been
834129e0 2360successfully built are stored---by default, under @file{/gnu/store}.
e531ac2a
LC
2361Sub-directories in the store are referred to as @dfn{store paths}. The
2362store has an associated database that contains information such has the
2363store paths referred to by each store path, and the list of @emph{valid}
2364store paths---paths that result from a successful build.
2365
2366The store is always accessed by the daemon on behalf of its clients
2367(@pxref{Invoking guix-daemon}). To manipulate the store, clients
2368connect to the daemon over a Unix-domain socket, send it requests, and
2369read the result---these are remote procedure calls, or RPCs.
2370
2371The @code{(guix store)} module provides procedures to connect to the
2372daemon, and to perform RPCs. These are described below.
2373
2374@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t]
2375Connect to the daemon over the Unix-domain socket at @var{file}. When
2376@var{reserve-space?} is true, instruct it to reserve a little bit of
2377extra space on the file system so that the garbage collector can still
2378operate, should the disk become full. Return a server object.
2379
2380@var{file} defaults to @var{%default-socket-path}, which is the normal
2381location given the options that were passed to @command{configure}.
2382@end deffn
2383
2384@deffn {Scheme Procedure} close-connection @var{server}
2385Close the connection to @var{server}.
2386@end deffn
2387
2388@defvr {Scheme Variable} current-build-output-port
2389This variable is bound to a SRFI-39 parameter, which refers to the port
2390where build and error logs sent by the daemon should be written.
2391@end defvr
2392
2393Procedures that make RPCs all take a server object as their first
2394argument.
2395
2396@deffn {Scheme Procedure} valid-path? @var{server} @var{path}
2397Return @code{#t} when @var{path} is a valid store path.
2398@end deffn
2399
cfbf9160 2400@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
e531ac2a
LC
2401Add @var{text} under file @var{name} in the store, and return its store
2402path. @var{references} is the list of store paths referred to by the
2403resulting store path.
2404@end deffn
2405
874e6874 2406@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
59688fc4
LC
2407Build @var{derivations} (a list of @code{<derivation>} objects or
2408derivation paths), and return when the worker is done building them.
2409Return @code{#t} on success.
874e6874
LC
2410@end deffn
2411
b860f382
LC
2412Note that the @code{(guix monads)} module provides a monad as well as
2413monadic versions of the above procedures, with the goal of making it
2414more convenient to work with code that accesses the store (@pxref{The
2415Store Monad}).
2416
e531ac2a
LC
2417@c FIXME
2418@i{This section is currently incomplete.}
568717fd
LC
2419
2420@node Derivations
2421@section Derivations
2422
874e6874
LC
2423@cindex derivations
2424Low-level build actions and the environment in which they are performed
2425are represented by @dfn{derivations}. A derivation contain the
2426following pieces of information:
2427
2428@itemize
2429@item
2430The outputs of the derivation---derivations produce at least one file or
2431directory in the store, but may produce more.
2432
2433@item
2434The inputs of the derivations, which may be other derivations or plain
2435files in the store (patches, build scripts, etc.)
2436
2437@item
2438The system type targeted by the derivation---e.g., @code{x86_64-linux}.
2439
2440@item
2441The file name of a build script in the store, along with the arguments
2442to be passed.
2443
2444@item
2445A list of environment variables to be defined.
2446
2447@end itemize
2448
2449@cindex derivation path
2450Derivations allow clients of the daemon to communicate build actions to
2451the store. They exist in two forms: as an in-memory representation,
2452both on the client- and daemon-side, and as files in the store whose
2453name end in @code{.drv}---these files are referred to as @dfn{derivation
2454paths}. Derivations paths can be passed to the @code{build-derivations}
2455procedure to perform the build actions they prescribe (@pxref{The
2456Store}).
2457
2458The @code{(guix derivations)} module provides a representation of
2459derivations as Scheme objects, along with procedures to create and
2460otherwise manipulate derivations. The lowest-level primitive to create
2461a derivation is the @code{derivation} procedure:
2462
1909431c
LC
2463@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
2464 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
2096ef47 2465 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
1909431c 2466 [#:system (%current-system)] [#:references-graphs #f] @
c0468155 2467 [#:allowed-references #f] [#:leaked-env-vars #f] [#:local-build? #f]
59688fc4
LC
2468Build a derivation with the given arguments, and return the resulting
2469@code{<derivation>} object.
874e6874 2470
2096ef47 2471When @var{hash} and @var{hash-algo} are given, a
874e6874 2472@dfn{fixed-output derivation} is created---i.e., one whose result is
36bbbbd1
LC
2473known in advance, such as a file download. If, in addition,
2474@var{recursive?} is true, then that fixed output may be an executable
2475file or a directory and @var{hash} must be the hash of an archive
2476containing this output.
5b0c9d16 2477
858e9282 2478When @var{references-graphs} is true, it must be a list of file
5b0c9d16
LC
2479name/store path pairs. In that case, the reference graph of each store
2480path is exported in the build environment in the corresponding file, in
2481a simple text format.
1909431c 2482
b53be755
LC
2483When @var{allowed-references} is true, it must be a list of store items
2484or outputs that the derivation's output may refer to.
2485
c0468155
LC
2486When @var{leaked-env-vars} is true, it must be a list of strings
2487denoting environment variables that are allowed to ``leak'' from the
2488daemon's environment to the build environment. This is only applicable
2489to fixed-output derivations---i.e., when @var{hash} is true. The main
2490use is to allow variables such as @code{http_proxy} to be passed to
2491derivations that download files.
2492
1909431c
LC
2493When @var{local-build?} is true, declare that the derivation is not a
2494good candidate for offloading and should rather be built locally
2495(@pxref{Daemon Offload Setup}). This is the case for small derivations
2496where the costs of data transfers would outweigh the benefits.
874e6874
LC
2497@end deffn
2498
2499@noindent
2500Here's an example with a shell script as its builder, assuming
2501@var{store} is an open connection to the daemon, and @var{bash} points
2502to a Bash executable in the store:
2503
2504@lisp
2505(use-modules (guix utils)
2506 (guix store)
2507 (guix derivations))
2508
59688fc4
LC
2509(let ((builder ; add the Bash script to the store
2510 (add-text-to-store store "my-builder.sh"
2511 "echo hello world > $out\n" '())))
2512 (derivation store "foo"
2513 bash `("-e" ,builder)
21b679f6 2514 #:inputs `((,bash) (,builder))
59688fc4 2515 #:env-vars '(("HOME" . "/homeless"))))
834129e0 2516@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
874e6874
LC
2517@end lisp
2518
21b679f6
LC
2519As can be guessed, this primitive is cumbersome to use directly. A
2520better approach is to write build scripts in Scheme, of course! The
2521best course of action for that is to write the build code as a
2522``G-expression'', and to pass it to @code{gexp->derivation}. For more
6621cdb6 2523information, @pxref{G-Expressions}.
21b679f6
LC
2524
2525Once upon a time, @code{gexp->derivation} did not exist and constructing
2526derivations with build code written in Scheme was achieved with
2527@code{build-expression->derivation}, documented below. This procedure
2528is now deprecated in favor of the much nicer @code{gexp->derivation}.
874e6874 2529
dd1a5a15
LC
2530@deffn {Scheme Procedure} build-expression->derivation @var{store} @
2531 @var{name} @var{exp} @
2532 [#:system (%current-system)] [#:inputs '()] @
2533 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
36bbbbd1 2534 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
63a42824
LC
2535 [#:references-graphs #f] [#:allowed-references #f] @
2536 [#:local-build? #f] [#:guile-for-build #f]
874e6874
LC
2537Return a derivation that executes Scheme expression @var{exp} as a
2538builder for derivation @var{name}. @var{inputs} must be a list of
2539@code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
2540@code{"out"} is assumed. @var{modules} is a list of names of Guile
2541modules from the current search path to be copied in the store,
2542compiled, and made available in the load path during the execution of
2543@var{exp}---e.g., @code{((guix build utils) (guix build
2544gnu-build-system))}.
2545
2546@var{exp} is evaluated in an environment where @code{%outputs} is bound
2547to a list of output/path pairs, and where @code{%build-inputs} is bound
2548to a list of string/output-path pairs made from @var{inputs}.
2549Optionally, @var{env-vars} is a list of string pairs specifying the name
2550and value of environment variables visible to the builder. The builder
2551terminates by passing the result of @var{exp} to @code{exit}; thus, when
2552@var{exp} returns @code{#f}, the build is considered to have failed.
2553
2554@var{exp} is built using @var{guile-for-build} (a derivation). When
2555@var{guile-for-build} is omitted or is @code{#f}, the value of the
2556@code{%guile-for-build} fluid is used instead.
9c629a27 2557
63a42824
LC
2558See the @code{derivation} procedure for the meaning of
2559@var{references-graphs}, @var{allowed-references}, and @var{local-build?}.
874e6874
LC
2560@end deffn
2561
2562@noindent
2563Here's an example of a single-output derivation that creates a directory
2564containing one file:
2565
2566@lisp
2567(let ((builder '(let ((out (assoc-ref %outputs "out")))
834129e0 2568 (mkdir out) ; create /gnu/store/@dots{}-goo
874e6874
LC
2569 (call-with-output-file (string-append out "/test")
2570 (lambda (p)
2571 (display '(hello guix) p))))))
dd1a5a15 2572 (build-expression->derivation store "goo" builder))
874e6874 2573
834129e0 2574@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
874e6874
LC
2575@end lisp
2576
568717fd 2577
b860f382
LC
2578@node The Store Monad
2579@section The Store Monad
2580
2581@cindex monad
2582
2583The procedures that operate on the store described in the previous
2584sections all take an open connection to the build daemon as their first
2585argument. Although the underlying model is functional, they either have
2586side effects or depend on the current state of the store.
2587
2588The former is inconvenient: the connection to the build daemon has to be
2589carried around in all those functions, making it impossible to compose
2590functions that do not take that parameter with functions that do. The
2591latter can be problematic: since store operations have side effects
2592and/or depend on external state, they have to be properly sequenced.
2593
2594@cindex monadic values
2595@cindex monadic functions
2596This is where the @code{(guix monads)} module comes in. This module
2597provides a framework for working with @dfn{monads}, and a particularly
2598useful monad for our uses, the @dfn{store monad}. Monads are a
2599construct that allows two things: associating ``context'' with values
2600(in our case, the context is the store), and building sequences of
561fb6c3 2601computations (here computations include accesses to the store.) Values
b860f382
LC
2602in a monad---values that carry this additional context---are called
2603@dfn{monadic values}; procedures that return such values are called
2604@dfn{monadic procedures}.
2605
2606Consider this ``normal'' procedure:
2607
2608@example
45adbd62
LC
2609(define (sh-symlink store)
2610 ;; Return a derivation that symlinks the 'bash' executable.
2611 (let* ((drv (package-derivation store bash))
2612 (out (derivation->output-path drv))
2613 (sh (string-append out "/bin/bash")))
2614 (build-expression->derivation store "sh"
2615 `(symlink ,sh %output))))
b860f382
LC
2616@end example
2617
c6f30b81
LC
2618Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
2619as a monadic function:
b860f382
LC
2620
2621@example
45adbd62 2622(define (sh-symlink)
b860f382 2623 ;; Same, but return a monadic value.
c6f30b81
LC
2624 (mlet %store-monad ((drv (package->derivation bash)))
2625 (gexp->derivation "sh"
2626 #~(symlink (string-append #$drv "/bin/bash")
2627 #$output))))
b860f382
LC
2628@end example
2629
c6f30b81
LC
2630There several things to note in the second version: the @code{store}
2631parameter is now implicit and is ``threaded'' in the calls to the
2632@code{package->derivation} and @code{gexp->derivation} monadic
2633procedures, and the monadic value returned by @code{package->derivation}
2634is @dfn{bound} using @code{mlet} instead of plain @code{let}.
2635
2636As it turns out, the call to @code{package->derivation} can even be
2637omitted since it will take place implicitly, as we will see later
2638(@pxref{G-Expressions}):
2639
2640@example
2641(define (sh-symlink)
2642 (gexp->derivation "sh"
2643 #~(symlink (string-append #$bash "/bin/bash")
2644 #$output)))
2645@end example
b860f382 2646
8e9aa37f 2647Calling the monadic @code{sh-symlink} has no effect. To get the desired
b860f382
LC
2648effect, one must use @code{run-with-store}:
2649
2650@example
8e9aa37f
CAW
2651(run-with-store (open-connection) (sh-symlink))
2652@result{} /gnu/store/...-sh-symlink
b860f382
LC
2653@end example
2654
b9b86078
LC
2655Note that the @code{(guix monad-repl)} module extends Guile's REPL with
2656new ``meta-commands'' to make it easier to deal with monadic procedures:
2657@code{run-in-store}, and @code{enter-store-monad}. The former, is used
2658to ``run'' a single monadic value through the store:
2659
2660@example
2661scheme@@(guile-user)> ,run-in-store (package->derivation hello)
2662$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2663@end example
2664
2665The latter enters a recursive REPL, where all the return values are
2666automatically run through the store:
2667
2668@example
2669scheme@@(guile-user)> ,enter-store-monad
2670store-monad@@(guile-user) [1]> (package->derivation hello)
2671$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
2672store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
2673$3 = "/gnu/store/@dots{}-foo"
2674store-monad@@(guile-user) [1]> ,q
2675scheme@@(guile-user)>
2676@end example
2677
2678@noindent
2679Note that non-monadic values cannot be returned in the
2680@code{store-monad} REPL.
2681
e87f0591
LC
2682The main syntactic forms to deal with monads in general are provided by
2683the @code{(guix monads)} module and are described below.
b860f382
LC
2684
2685@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
2686Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
2687in @var{monad}.
2688@end deffn
2689
2690@deffn {Scheme Syntax} return @var{val}
2691Return a monadic value that encapsulates @var{val}.
2692@end deffn
2693
2694@deffn {Scheme Syntax} >>= @var{mval} @var{mproc}
2695@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
2696procedure @var{mproc}@footnote{This operation is commonly referred to as
2697``bind'', but that name denotes an unrelated procedure in Guile. Thus
2698we use this somewhat cryptic symbol inherited from the Haskell
2699language.}.
2700@end deffn
2701
2702@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
2703 @var{body} ...
2704@deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
2705 @var{body} ...
2706Bind the variables @var{var} to the monadic values @var{mval} in
2707@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the
2708``normal'' value @var{val}, as per @code{let}.
2709
2710@code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
2711(@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
2712@end deffn
2713
405a9d4e
LC
2714@deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
2715Bind @var{mexp} and the following monadic expressions in sequence,
2716returning the result of the last expression.
2717
2718This is akin to @code{mlet}, except that the return values of the
2719monadic expressions are ignored. In that sense, it is analogous to
2720@code{begin}, but applied to monadic expressions.
2721@end deffn
2722
561fb6c3
LC
2723@cindex state monad
2724The @code{(guix monads)} module provides the @dfn{state monad}, which
2725allows an additional value---the state---to be @emph{threaded} through
2726monadic procedure calls.
2727
2728@defvr {Scheme Variable} %state-monad
2729The state monad. Procedures in the state monad can access and change
2730the state that is threaded.
2731
2732Consider the example below. The @code{square} procedure returns a value
2733in the state monad. It returns the square of its argument, but also
2734increments the current state value:
2735
2736@example
2737(define (square x)
2738 (mlet %state-monad ((count (current-state)))
2739 (mbegin %state-monad
2740 (set-current-state (+ 1 count))
2741 (return (* x x)))))
2742
2743(run-with-state (sequence %state-monad (map square (iota 3))) 0)
2744@result{} (0 1 4)
2745@result{} 3
2746@end example
2747
2748When ``run'' through @var{%state-monad}, we obtain that additional state
2749value, which is the number of @code{square} calls.
2750@end defvr
2751
2752@deffn {Monadic Procedure} current-state
2753Return the current state as a monadic value.
2754@end deffn
2755
2756@deffn {Monadic Procedure} set-current-state @var{value}
2757Set the current state to @var{value} and return the previous state as a
2758monadic value.
2759@end deffn
2760
2761@deffn {Monadic Procedure} state-push @var{value}
2762Push @var{value} to the current state, which is assumed to be a list,
2763and return the previous state as a monadic value.
2764@end deffn
2765
2766@deffn {Monadic Procedure} state-pop
2767Pop a value from the current state and return it as a monadic value.
2768The state is assumed to be a list.
2769@end deffn
2770
2771@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
2772Run monadic value @var{mval} starting with @var{state} as the initial
2773state. Return two values: the resulting value, and the resulting state.
2774@end deffn
2775
e87f0591
LC
2776The main interface to the store monad, provided by the @code{(guix
2777store)} module, is as follows.
b860f382
LC
2778
2779@defvr {Scheme Variable} %store-monad
561fb6c3
LC
2780The store monad---an alias for @var{%state-monad}.
2781
2782Values in the store monad encapsulate accesses to the store. When its
2783effect is needed, a value of the store monad must be ``evaluated'' by
2784passing it to the @code{run-with-store} procedure (see below.)
b860f382
LC
2785@end defvr
2786
2787@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
2788Run @var{mval}, a monadic value in the store monad, in @var{store}, an
2789open store connection.
2790@end deffn
2791
ad372953 2792@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
b860f382 2793Return as a monadic value the absolute file name in the store of the file
ad372953
LC
2794containing @var{text}, a string. @var{references} is a list of store items that the
2795resulting text file refers to; it defaults to the empty list.
45adbd62
LC
2796@end deffn
2797
0a90af15
LC
2798@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
2799 [#:recursive? #t]
2800Return the name of @var{file} once interned in the store. Use
2801@var{name} as its store name, or the basename of @var{file} if
2802@var{name} is omitted.
2803
2804When @var{recursive?} is true, the contents of @var{file} are added
2805recursively; if @var{file} designates a flat file and @var{recursive?}
2806is true, its contents are added, and its permission bits are kept.
2807
2808The example below adds a file to the store, under two different names:
2809
2810@example
2811(run-with-store (open-connection)
2812 (mlet %store-monad ((a (interned-file "README"))
2813 (b (interned-file "README" "LEGU-MIN")))
2814 (return (list a b))))
2815
2816@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
2817@end example
2818
2819@end deffn
2820
e87f0591
LC
2821The @code{(guix packages)} module exports the following package-related
2822monadic procedures:
2823
b860f382 2824@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
4231f05b
LC
2825 [#:system (%current-system)] [#:target #f] @
2826 [#:output "out"] Return as a monadic
b860f382
LC
2827value in the absolute file name of @var{file} within the @var{output}
2828directory of @var{package}. When @var{file} is omitted, return the name
4231f05b
LC
2829of the @var{output} directory of @var{package}. When @var{target} is
2830true, use it as a cross-compilation target triplet.
b860f382
LC
2831@end deffn
2832
b860f382 2833@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
4231f05b
LC
2834@deffnx {Monadic Procedure} package->cross-derivation @var{package} @
2835 @var{target} [@var{system}]
2836Monadic version of @code{package-derivation} and
2837@code{package-cross-derivation} (@pxref{Defining Packages}).
b860f382
LC
2838@end deffn
2839
2840
21b679f6
LC
2841@node G-Expressions
2842@section G-Expressions
2843
2844@cindex G-expression
2845@cindex build code quoting
2846So we have ``derivations'', which represent a sequence of build actions
2847to be performed to produce an item in the store (@pxref{Derivations}).
2848Those build actions are performed when asking the daemon to actually
2849build the derivations; they are run by the daemon in a container
2850(@pxref{Invoking guix-daemon}).
2851
2852@cindex strata of code
2853It should come as no surprise that we like to write those build actions
2854in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
2855code@footnote{The term @dfn{stratum} in this context was coined by
ef4ab0a4
LC
2856Manuel Serrano et al.@: in the context of their work on Hop. Oleg
2857Kiselyov, who has written insightful
2858@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
2859on this topic}, refers to this kind of code generation as
2860@dfn{staging}.}: the ``host code''---code that defines packages, talks
2861to the daemon, etc.---and the ``build code''---code that actually
2862performs build actions, such as making directories, invoking
2863@command{make}, etc.
21b679f6
LC
2864
2865To describe a derivation and its build actions, one typically needs to
2866embed build code inside host code. It boils down to manipulating build
2867code as data, and Scheme's homoiconicity---code has a direct
2868representation as data---comes in handy for that. But we need more than
2869Scheme's normal @code{quasiquote} mechanism to construct build
2870expressions.
2871
2872The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
2873S-expressions adapted to build expressions. G-expressions, or
2874@dfn{gexps}, consist essentially in three syntactic forms: @code{gexp},
2875@code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
2876@code{#$}, and @code{#$@@}), which are comparable respectively to
2877@code{quasiquote}, @code{unquote}, and @code{unquote-splicing}
2878(@pxref{Expression Syntax, @code{quasiquote},, guile, GNU Guile
2879Reference Manual}). However, there are major differences:
2880
2881@itemize
2882@item
2883Gexps are meant to be written to a file and run or manipulated by other
2884processes.
2885
2886@item
b39fc6f7
LC
2887When a high-level object such as a package or derivation is unquoted
2888inside a gexp, the result is as if its output file name had been
2889introduced.
ff40e9b7 2890
21b679f6
LC
2891@item
2892Gexps carry information about the packages or derivations they refer to,
2893and these dependencies are automatically added as inputs to the build
2894processes that use them.
2895@end itemize
2896
b39fc6f7
LC
2897Actually this mechanism is not limited to package and derivation
2898objects; @dfn{compilers} able to ``lower'' other high-level objects to
2899derivations can be defined, such that these objects can also be inserted
d9ae938f
LC
2900into gexps. Another useful type of high-level object that can be
2901inserted in a gexp is @dfn{local files}, which allows files from the
2902local file system to be added to the store and referred to by
2903derivations and such (see @code{local-file} below.)
b39fc6f7 2904
21b679f6
LC
2905To illustrate the idea, here is an example of a gexp:
2906
2907@example
2908(define build-exp
2909 #~(begin
2910 (mkdir #$output)
2911 (chdir #$output)
aff8ce7c 2912 (symlink (string-append #$coreutils "/bin/ls")
21b679f6
LC
2913 "list-files")))
2914@end example
2915
2916This gexp can be passed to @code{gexp->derivation}; we obtain a
2917derivation that builds a directory containing exactly one symlink to
2918@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
2919
2920@example
2921(gexp->derivation "the-thing" build-exp)
2922@end example
2923
e20fd1bf 2924As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
21b679f6
LC
2925substituted to the reference to the @var{coreutils} package in the
2926actual build code, and @var{coreutils} is automatically made an input to
2927the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
2928output)}) is replaced by a string containing the derivation's output
667b2508
LC
2929directory name.
2930
2931@cindex cross compilation
2932In a cross-compilation context, it is useful to distinguish between
2933references to the @emph{native} build of a package---that can run on the
2934host---versus references to cross builds of a package. To that end, the
2935@code{#+} plays the same role as @code{#$}, but is a reference to a
2936native package build:
2937
2938@example
2939(gexp->derivation "vi"
2940 #~(begin
2941 (mkdir #$output)
2942 (system* (string-append #+coreutils "/bin/ln")
2943 "-s"
2944 (string-append #$emacs "/bin/emacs")
2945 (string-append #$output "/bin/vi")))
2946 #:target "mips64el-linux")
2947@end example
2948
2949@noindent
2950In the example above, the native build of @var{coreutils} is used, so
2951that @command{ln} can actually run on the host; but then the
2952cross-compiled build of @var{emacs} is referenced.
2953
2954The syntactic form to construct gexps is summarized below.
21b679f6
LC
2955
2956@deffn {Scheme Syntax} #~@var{exp}
2957@deffnx {Scheme Syntax} (gexp @var{exp})
2958Return a G-expression containing @var{exp}. @var{exp} may contain one
2959or more of the following forms:
2960
2961@table @code
2962@item #$@var{obj}
2963@itemx (ungexp @var{obj})
b39fc6f7
LC
2964Introduce a reference to @var{obj}. @var{obj} may have one of the
2965supported types, for example a package or a
21b679f6
LC
2966derivation, in which case the @code{ungexp} form is replaced by its
2967output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
2968
b39fc6f7
LC
2969If @var{obj} is a list, it is traversed and references to supported
2970objects are substituted similarly.
21b679f6
LC
2971
2972If @var{obj} is another gexp, its contents are inserted and its
2973dependencies are added to those of the containing gexp.
2974
2975If @var{obj} is another kind of object, it is inserted as is.
2976
b39fc6f7
LC
2977@item #$@var{obj}:@var{output}
2978@itemx (ungexp @var{obj} @var{output})
21b679f6 2979This is like the form above, but referring explicitly to the
b39fc6f7
LC
2980@var{output} of @var{obj}---this is useful when @var{obj} produces
2981multiple outputs (@pxref{Packages with Multiple Outputs}).
21b679f6 2982
667b2508
LC
2983@item #+@var{obj}
2984@itemx #+@var{obj}:output
2985@itemx (ungexp-native @var{obj})
2986@itemx (ungexp-native @var{obj} @var{output})
2987Same as @code{ungexp}, but produces a reference to the @emph{native}
2988build of @var{obj} when used in a cross compilation context.
2989
21b679f6
LC
2990@item #$output[:@var{output}]
2991@itemx (ungexp output [@var{output}])
2992Insert a reference to derivation output @var{output}, or to the main
2993output when @var{output} is omitted.
2994
2995This only makes sense for gexps passed to @code{gexp->derivation}.
2996
2997@item #$@@@var{lst}
2998@itemx (ungexp-splicing @var{lst})
2999Like the above, but splices the contents of @var{lst} inside the
3000containing list.
3001
667b2508
LC
3002@item #+@@@var{lst}
3003@itemx (ungexp-native-splicing @var{lst})
3004Like the above, but refers to native builds of the objects listed in
3005@var{lst}.
3006
21b679f6
LC
3007@end table
3008
3009G-expressions created by @code{gexp} or @code{#~} are run-time objects
3010of the @code{gexp?} type (see below.)
3011@end deffn
3012
3013@deffn {Scheme Procedure} gexp? @var{obj}
3014Return @code{#t} if @var{obj} is a G-expression.
3015@end deffn
3016
3017G-expressions are meant to be written to disk, either as code building
3018some derivation, or as plain files in the store. The monadic procedures
3019below allow you to do that (@pxref{The Store Monad}, for more
3020information about monads.)
3021
3022@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
ce45eb4c 3023 [#:system (%current-system)] [#:target #f] [#:graft? #t] @
21b679f6
LC
3024 [#:hash #f] [#:hash-algo #f] @
3025 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
4684f301 3026 [#:module-path @var{%load-path}] @
c8351d9a 3027 [#:references-graphs #f] [#:allowed-references #f] @
c0468155 3028 [#:leaked-env-vars #f] @
c8351d9a 3029 [#:local-build? #f] [#:guile-for-build #f]
21b679f6 3030Return a derivation @var{name} that runs @var{exp} (a gexp) with
68a61e9f
LC
3031@var{guile-for-build} (a derivation) on @var{system}. When @var{target}
3032is true, it is used as the cross-compilation target triplet for packages
3033referred to by @var{exp}.
21b679f6 3034
ce45eb4c
LC
3035Make @var{modules} available in the evaluation context of @var{exp};
3036@var{modules} is a list of names of Guile modules searched in
3037@var{module-path} to be copied in the store, compiled, and made available in
21b679f6
LC
3038the load path during the execution of @var{exp}---e.g., @code{((guix
3039build utils) (guix build gnu-build-system))}.
3040
ce45eb4c
LC
3041@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
3042applicable.
3043
b53833b2
LC
3044When @var{references-graphs} is true, it must be a list of tuples of one of the
3045following forms:
3046
3047@example
3048(@var{file-name} @var{package})
3049(@var{file-name} @var{package} @var{output})
3050(@var{file-name} @var{derivation})
3051(@var{file-name} @var{derivation} @var{output})
3052(@var{file-name} @var{store-item})
3053@end example
3054
3055The right-hand-side of each element of @var{references-graphs} is automatically made
3056an input of the build process of @var{exp}. In the build environment, each
3057@var{file-name} contains the reference graph of the corresponding item, in a simple
3058text format.
3059
c8351d9a
LC
3060@var{allowed-references} must be either @code{#f} or a list of output names and packages.
3061In the latter case, the list denotes store items that the result is allowed to
3062refer to. Any reference to another store item will lead to a build error.
3063
e20fd1bf 3064The other arguments are as for @code{derivation} (@pxref{Derivations}).
21b679f6
LC
3065@end deffn
3066
d9ae938f
LC
3067@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
3068 [#:recursive? #t]
3069Return an object representing local file @var{file} to add to the store; this
3070object can be used in a gexp. @var{file} will be added to the store under @var{name}--by
3071default the base name of @var{file}.
3072
3073When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
3074designates a flat file and @var{recursive?} is true, its contents are added, and its
3075permission bits are kept.
3076
3077This is the declarative counterpart of the @code{interned-file} monadic
3078procedure (@pxref{The Store Monad, @code{interned-file}}).
3079@end deffn
3080
21b679f6
LC
3081@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
3082Return an executable script @var{name} that runs @var{exp} using
3083@var{guile} with @var{modules} in its search path.
3084
3085The example below builds a script that simply invokes the @command{ls}
3086command:
3087
3088@example
3089(use-modules (guix gexp) (gnu packages base))
3090
3091(gexp->script "list-files"
3092 #~(execl (string-append #$coreutils "/bin/ls")
3093 "ls"))
3094@end example
3095
3096When ``running'' it through the store (@pxref{The Store Monad,
e20fd1bf 3097@code{run-with-store}}), we obtain a derivation that produces an
21b679f6
LC
3098executable file @file{/gnu/store/@dots{}-list-files} along these lines:
3099
3100@example
3101#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
3102!#
3103(execl (string-append "/gnu/store/@dots{}-coreutils-8.22"/bin/ls")
3104 "ls")
3105@end example
3106@end deffn
3107
3108@deffn {Monadic Procedure} gexp->file @var{name} @var{exp}
3109Return a derivation that builds a file @var{name} containing @var{exp}.
3110
3111The resulting file holds references to all the dependencies of @var{exp}
3112or a subset thereof.
3113@end deffn
1ed19464
LC
3114
3115@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
3116Return as a monadic value a derivation that builds a text file
3117containing all of @var{text}. @var{text} may list, in addition to
d9ae938f
LC
3118strings, objects of any type that can be used in a gexp: packages,
3119derivations, local file objects, etc. The resulting store file holds
3120references to all these.
1ed19464
LC
3121
3122This variant should be preferred over @code{text-file} anytime the file
3123to create will reference items from the store. This is typically the
3124case when building a configuration file that embeds store file names,
3125like this:
3126
3127@example
3128(define (profile.sh)
3129 ;; Return the name of a shell script in the store that
3130 ;; initializes the 'PATH' environment variable.
3131 (text-file* "profile.sh"
3132 "export PATH=" coreutils "/bin:"
3133 grep "/bin:" sed "/bin\n"))
3134@end example
3135
3136In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
3137will references @var{coreutils}, @var{grep}, and @var{sed}, thereby
3138preventing them from being garbage-collected during its lifetime.
3139@end deffn
21b679f6
LC
3140
3141Of course, in addition to gexps embedded in ``host'' code, there are
3142also modules containing build tools. To make it clear that they are
3143meant to be used in the build stratum, these modules are kept in the
3144@code{(guix build @dots{})} name space.
3145
3146
568717fd
LC
3147@c *********************************************************************
3148@node Utilities
3149@chapter Utilities
3150
210cc920
LC
3151This section describes tools primarily targeted at developers and users
3152who write new package definitions. They complement the Scheme
3153programming interface of Guix in a convenient way.
3154
568717fd 3155@menu
37166310 3156* Invoking guix build:: Building packages from the command line.
210cc920 3157* Invoking guix download:: Downloading a file and printing its hash.
37166310 3158* Invoking guix hash:: Computing the cryptographic hash of a file.
2f7d2d91 3159* Invoking guix import:: Importing package definitions.
37166310 3160* Invoking guix refresh:: Updating package definitions.
b4f5e0e8 3161* Invoking guix lint:: Finding errors in package definitions.
372c4bbc 3162* Invoking guix environment:: Setting up development environments.
aff8ce7c 3163* Invoking guix publish:: Sharing substitutes.
568717fd
LC
3164@end menu
3165
e49951eb
MW
3166@node Invoking guix build
3167@section Invoking @command{guix build}
568717fd 3168
e49951eb 3169The @command{guix build} command builds packages or derivations and
6798a8e4
LC
3170their dependencies, and prints the resulting store paths. Note that it
3171does not modify the user's profile---this is the job of the
e49951eb 3172@command{guix package} command (@pxref{Invoking guix package}). Thus,
6798a8e4
LC
3173it is mainly useful for distribution developers.
3174
3175The general syntax is:
c78bd12b
LC
3176
3177@example
e49951eb 3178guix build @var{options} @var{package-or-derivation}@dots{}
c78bd12b
LC
3179@end example
3180
3181@var{package-or-derivation} may be either the name of a package found in
5401dd75
LC
3182the software distribution such as @code{coreutils} or
3183@code{coreutils-8.20}, or a derivation such as
834129e0 3184@file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
e7f34eb0
LC
3185package with the corresponding name (and optionally version) is searched
3186for among the GNU distribution modules (@pxref{Package Modules}).
3187
3188Alternatively, the @code{--expression} option may be used to specify a
3189Scheme expression that evaluates to a package; this is useful when
3190disambiguation among several same-named packages or package variants is
3191needed.
c78bd12b
LC
3192
3193The @var{options} may be zero or more of the following:
3194
3195@table @code
3196
3197@item --expression=@var{expr}
3198@itemx -e @var{expr}
ac5de156 3199Build the package or derivation @var{expr} evaluates to.
c78bd12b 3200
5401dd75 3201For example, @var{expr} may be @code{(@@ (gnu packages guile)
c78bd12b
LC
3202guile-1.8)}, which unambiguously designates this specific variant of
3203version 1.8 of Guile.
3204
56b82106
LC
3205Alternately, @var{expr} may be a G-expression, in which case it is used
3206as a build program passed to @code{gexp->derivation}
3207(@pxref{G-Expressions}).
3208
3209Lastly, @var{expr} may refer to a zero-argument monadic procedure
ac5de156
LC
3210(@pxref{The Store Monad}). The procedure must return a derivation as a
3211monadic value, which is then passed through @code{run-with-store}.
3212
c78bd12b
LC
3213@item --source
3214@itemx -S
3215Build the packages' source derivations, rather than the packages
3216themselves.
3217
e49951eb 3218For instance, @code{guix build -S gcc} returns something like
834129e0 3219@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is GCC's source tarball.
c78bd12b 3220
f9cc8971
LC
3221The returned source tarball is the result of applying any patches and
3222code snippets specified in the package's @code{origin} (@pxref{Defining
3223Packages}).
3224
2cdfe13d
EB
3225@item --sources
3226Fetch and return the source of @var{package-or-derivation} and all their
3227dependencies, recursively. This is a handy way to obtain a local copy
3228of all the source code needed to build @var{packages}, allowing you to
3229eventually build them even without network access. It is an extension
3230of the @code{--source} option and can accept one of the following
3231optional argument values:
3232
3233@table @code
3234@item package
3235This value causes the @code{--sources} option to behave in the same way
3236as the @code{--source} option.
3237
3238@item all
3239Build all packages' source derivations, including any source that might
3240be listed as @code{inputs}. This is the default value.
3241
3242@example
3243$ guix build --sources tzdata
3244The following derivations will be built:
3245 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
3246 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3247@end example
3248
3249@item transitive
3250Build all packages' source derivations, as well as all source
3251derivations for packages' transitive inputs. This can be used e.g. to
3252prefetch package source for later offline building.
3253
3254@example
3255$ guix build --sources=transitive tzdata
3256The following derivations will be built:
3257 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
3258 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
3259 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
3260 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
3261 /gnu/store/@dots{}-make-4.1.tar.xz.drv
3262 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
3263@dots{}
3264@end example
3265
3266@end table
3267
c78bd12b
LC
3268@item --system=@var{system}
3269@itemx -s @var{system}
3270Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
3271the host's system type.
3272
3273An example use of this is on Linux-based systems, which can emulate
3274different personalities. For instance, passing
3275@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
3276to build packages in a complete 32-bit environment.
3277
e55ec43d
LC
3278@item --target=@var{triplet}
3279@cindex cross-compilation
3280Cross-build for @var{triplet}, which must be a valid GNU triplet, such
3281as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU
3282configuration triplets,, configure, GNU Configure and Build System}).
3283
7f3673f2
LC
3284@item --with-source=@var{source}
3285Use @var{source} as the source of the corresponding package.
3286@var{source} must be a file name or a URL, as for @command{guix
3287download} (@pxref{Invoking guix download}).
3288
3289The ``corresponding package'' is taken to be one specified on the
3290command line whose name matches the base of @var{source}---e.g., if
3291@var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
3292package is @code{guile}. Likewise, the version string is inferred from
3293@var{source}; in the previous example, it's @code{2.0.10}.
3294
3295This option allows users to try out versions of packages other than the
3296one provided by the distribution. The example below downloads
3297@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
3298the @code{ed} package:
3299
3300@example
3301guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
3302@end example
3303
3304As a developer, @code{--with-source} makes it easy to test release
3305candidates:
3306
3307@example
3308guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
3309@end example
3310
05962f29
LC
3311@item --no-grafts
3312Do not ``graft'' packages. In practice, this means that package updates
3313available as grafts are not applied. @xref{Security Updates}, for more
3314information on grafts.
7f3673f2 3315
c78bd12b
LC
3316@item --derivations
3317@itemx -d
3318Return the derivation paths, not the output paths, of the given
3319packages.
3320
70ee5642
LC
3321@item --root=@var{file}
3322@itemx -r @var{file}
3323Make @var{file} a symlink to the result, and register it as a garbage
3324collector root.
3325
3326@item --log-file
3327Return the build log file names for the given
3328@var{package-or-derivation}s, or raise an error if build logs are
3329missing.
3330
3331This works regardless of how packages or derivations are specified. For
3332instance, the following invocations are equivalent:
3333
3334@example
3335guix build --log-file `guix build -d guile`
3336guix build --log-file `guix build guile`
3337guix build --log-file guile
3338guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
3339@end example
3340
3341
3342@end table
3343
3344@cindex common build options
3345In addition, a number of options that control the build process are
3346common to @command{guix build} and other commands that can spawn builds,
3347such as @command{guix package} or @command{guix archive}. These are the
3348following:
3349
3350@table @code
3351
300868ba
LC
3352@item --load-path=@var{directory}
3353@itemx -L @var{directory}
3354Add @var{directory} to the front of the package module search path
3355(@pxref{Package Modules}).
3356
3357This allows users to define their own packages and make them visible to
3358the command-line tools.
3359
c78bd12b
LC
3360@item --keep-failed
3361@itemx -K
3362Keep the build tree of failed builds. Thus, if a build fail, its build
3363tree is kept under @file{/tmp}, in a directory whose name is shown at
3364the end of the build log. This is useful when debugging build issues.
3365
3366@item --dry-run
3367@itemx -n
3368Do not build the derivations.
3369
56b1f4b7
LC
3370@item --fallback
3371When substituting a pre-built binary fails, fall back to building
3372packages locally.
3373
c78bd12b 3374@item --no-substitutes
b5385b52 3375Do not use substitutes for build products. That is, always build things
c4202d60
LC
3376locally instead of allowing downloads of pre-built binaries
3377(@pxref{Substitutes}).
c78bd12b 3378
425b0bfc 3379@item --no-build-hook
4ec2e92d
LC
3380Do not attempt to offload builds @i{via} the daemon's ``build hook''
3381(@pxref{Daemon Offload Setup}). That is, always build things locally
3382instead of offloading builds to remote machines.
425b0bfc 3383
969e678e
LC
3384@item --max-silent-time=@var{seconds}
3385When the build or substitution process remains silent for more than
3386@var{seconds}, terminate it and report a build failure.
3387
002622b6
LC
3388@item --timeout=@var{seconds}
3389Likewise, when the build or substitution process lasts for more than
3390@var{seconds}, terminate it and report a build failure.
3391
3392By default there is no timeout. This behavior can be restored with
3393@code{--timeout=0}.
3394
07ab4bf1
LC
3395@item --verbosity=@var{level}
3396Use the given verbosity level. @var{level} must be an integer between 0
3397and 5; higher means more verbose output. Setting a level of 4 or more
3398may be helpful when debugging setup issues with the build daemon.
3399
70ee5642
LC
3400@item --cores=@var{n}
3401@itemx -c @var{n}
3402Allow the use of up to @var{n} CPU cores for the build. The special
3403value @code{0} means to use as many CPU cores as available.
bf421152 3404
f6526eb3
LC
3405@item --max-jobs=@var{n}
3406@itemx -M @var{n}
3407Allow at most @var{n} build jobs in parallel. @xref{Invoking
3408guix-daemon, @code{--max-jobs}}, for details about this option and the
3409equivalent @command{guix-daemon} option.
3410
c78bd12b
LC
3411@end table
3412
e49951eb 3413Behind the scenes, @command{guix build} is essentially an interface to
c78bd12b
LC
3414the @code{package-derivation} procedure of the @code{(guix packages)}
3415module, and to the @code{build-derivations} procedure of the @code{(guix
01d8ac64 3416derivations)} module.
c78bd12b 3417
16eb115e
DP
3418In addition to options explicitly passed on the command line,
3419@command{guix build} and other @command{guix} commands that support
3420building honor the @code{GUIX_BUILD_OPTIONS} environment variable.
3421
3422@defvr {Environment Variable} GUIX_BUILD_OPTIONS
3423Users can define this variable to a list of command line options that
3424will automatically be used by @command{guix build} and other
3425@command{guix} commands that can perform builds, as in the example
3426below:
3427
3428@example
3429$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
3430@end example
3431
847391fe
DP
3432These options are parsed independently, and the result is appended to
3433the parsed command-line options.
16eb115e
DP
3434@end defvr
3435
3436
210cc920
LC
3437@node Invoking guix download
3438@section Invoking @command{guix download}
3439
3440When writing a package definition, developers typically need to download
3441the package's source tarball, compute its SHA256 hash, and write that
3442hash in the package definition (@pxref{Defining Packages}). The
3443@command{guix download} tool helps with this task: it downloads a file
3444from the given URI, adds it to the store, and prints both its file name
3445in the store and its SHA256 hash.
3446
3447The fact that the downloaded file is added to the store saves bandwidth:
3448when the developer eventually tries to build the newly defined package
3449with @command{guix build}, the source tarball will not have to be
3450downloaded again because it is already in the store. It is also a
3451convenient way to temporarily stash files, which may be deleted
3452eventually (@pxref{Invoking guix gc}).
3453
3454The @command{guix download} command supports the same URIs as used in
3455package definitions. In particular, it supports @code{mirror://} URIs.
3456@code{https} URIs (HTTP over TLS) are supported @emph{provided} the
3457Guile bindings for GnuTLS are available in the user's environment; when
537c8bb3
LC
3458they are not available, an error is raised. @xref{Guile Preparations,
3459how to install the GnuTLS bindings for Guile,, gnutls-guile,
3460GnuTLS-Guile}, for more information.
210cc920
LC
3461
3462The following option is available:
3463
3464@table @code
3465@item --format=@var{fmt}
3466@itemx -f @var{fmt}
3467Write the hash in the format specified by @var{fmt}. For more
081145cf 3468information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
210cc920
LC
3469@end table
3470
6c365eca
NK
3471@node Invoking guix hash
3472@section Invoking @command{guix hash}
3473
210cc920 3474The @command{guix hash} command computes the SHA256 hash of a file.
6c365eca
NK
3475It is primarily a convenience tool for anyone contributing to the
3476distribution: it computes the cryptographic hash of a file, which can be
3477used in the definition of a package (@pxref{Defining Packages}).
3478
3479The general syntax is:
3480
3481@example
3482guix hash @var{option} @var{file}
3483@end example
3484
3485@command{guix hash} has the following option:
3486
3487@table @code
3488
3489@item --format=@var{fmt}
3490@itemx -f @var{fmt}
210cc920 3491Write the hash in the format specified by @var{fmt}.
6c365eca
NK
3492
3493Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
3494(@code{hex} and @code{hexadecimal} can be used as well).
3495
3496If the @option{--format} option is not specified, @command{guix hash}
3497will output the hash in @code{nix-base32}. This representation is used
3498in the definitions of packages.
3499
3140f2df
LC
3500@item --recursive
3501@itemx -r
3502Compute the hash on @var{file} recursively.
3503
3504In this case, the hash is computed on an archive containing @var{file},
3505including its children if it is a directory. Some of @var{file}'s
3506meta-data is part of the archive; for instance, when @var{file} is a
3507regular file, the hash is different depending on whether @var{file} is
3508executable or not. Meta-data such as time stamps has no impact on the
3509hash (@pxref{Invoking guix archive}).
3510@c FIXME: Replace xref above with xref to an ``Archive'' section when
3511@c it exists.
3512
6c365eca
NK
3513@end table
3514
2f7d2d91
LC
3515@node Invoking guix import
3516@section Invoking @command{guix import}
3517
3518@cindex importing packages
3519@cindex package import
3520@cindex package conversion
3521The @command{guix import} command is useful for people willing to add a
3522package to the distribution but who'd rather do as little work as
3523possible to get there---a legitimate demand. The command knows of a few
3524repositories from which it can ``import'' package meta-data. The result
3525is a package definition, or a template thereof, in the format we know
3526(@pxref{Defining Packages}).
3527
3528The general syntax is:
3529
3530@example
3531guix import @var{importer} @var{options}@dots{}
3532@end example
3533
3534@var{importer} specifies the source from which to import package
3535meta-data, and @var{options} specifies a package identifier and other
3536options specific to @var{importer}. Currently, the available
3537``importers'' are:
3538
3539@table @code
3540@item gnu
3541Import meta-data for the given GNU package. This provides a template
3542for the latest version of that GNU package, including the hash of its
3543source tarball, and its canonical synopsis and description.
3544
3545Additional information such as the package's dependencies and its
3546license needs to be figured out manually.
3547
3548For example, the following command returns a package definition for
3549GNU@tie{}Hello:
3550
3551@example
3552guix import gnu hello
3553@end example
3554
3555Specific command-line options are:
3556
3557@table @code
3558@item --key-download=@var{policy}
3559As for @code{guix refresh}, specify the policy to handle missing OpenPGP
3560keys when verifying the package's signature. @xref{Invoking guix
3561refresh, @code{--key-download}}.
3562@end table
3563
3564@item pypi
3565@cindex pypi
3566Import meta-data from the @uref{https://pypi.python.org/, Python Package
3567Index}@footnote{This functionality requires Guile-JSON to be installed.
3568@xref{Requirements}.}. Information is taken from the JSON-formatted
3569description available at @code{pypi.python.org} and usually includes all
3570the relevant information, including package dependencies.
3571
3572The command below imports meta-data for the @code{itsdangerous} Python
3573package:
3574
3575@example
3576guix import pypi itsdangerous
3577@end example
3578
d45dc6da
EB
3579@item cpan
3580@cindex CPAN
3581Import meta-data from @uref{https://www.metacpan.org/, MetaCPAN}.
3582Information is taken from the JSON-formatted meta-data provided through
3583@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
66392e47
EB
3584relevant information, such as module dependencies. License information
3585should be checked closely. If Perl is available in the store, then the
3586@code{corelist} utility will be used to filter core modules out of the
3587list of dependencies.
d45dc6da
EB
3588
3589The command command below imports meta-data for the @code{Acme::Boolean}
3590Perl module:
3591
3592@example
3593guix import cpan Acme::Boolean
3594@end example
3595
2f7d2d91
LC
3596@item nix
3597Import meta-data from a local copy of the source of the
3598@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
3599relies on the @command{nix-instantiate} command of
3600@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
3601typically written in a mixture of Nix-language and Bash code. This
3602command only imports the high-level package structure that is written in
3603the Nix language. It normally includes all the basic fields of a
3604package definition.
3605
3606When importing a GNU package, the synopsis and descriptions are replaced
3607by their canonical upstream variant.
3608
3609As an example, the command below imports the package definition of
3610LibreOffice (more precisely, it imports the definition of the package
3611bound to the @code{libreoffice} top-level attribute):
3612
3613@example
3614guix import nix ~/path/to/nixpkgs libreoffice
3615@end example
863af4e1
FB
3616
3617@item hackage
3618@cindex hackage
3619Import meta-data from Haskell community's central package archive
3620@uref{https://hackage.haskell.org/, Hackage}. Information is taken from
3621Cabal files and includes all the relevant information, including package
3622dependencies.
3623
3624Specific command-line options are:
3625
3626@table @code
3627@item --no-test-dependencies
3628@itemx -t
3629Do not include dependencies only required to run the test suite.
3630@end table
3631
3632The command below imports meta-data for the latest version of the
3633@code{HTTP} Haskell package without including test dependencies:
3634
3635@example
3636guix import hackage -t HTTP
3637@end example
3638
3639A specific package version may optionally be specified by following the
3640package name by a hyphen and a version number as in the following example:
3641
3642@example
3643guix import hackage mtl-2.1.3.1
3644@end example
3645
3646Currently only indentation structured Cabal files are supported.
2f7d2d91
LC
3647@end table
3648
3649The structure of the @command{guix import} code is modular. It would be
3650useful to have more importers for other package formats, and your help
3651is welcome here (@pxref{Contributing}).
3652
37166310
LC
3653@node Invoking guix refresh
3654@section Invoking @command{guix refresh}
3655
3656The primary audience of the @command{guix refresh} command is developers
3657of the GNU software distribution. By default, it reports any packages
3658provided by the distribution that are outdated compared to the latest
3659upstream version, like this:
3660
3661@example
3662$ guix refresh
3663gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
3664gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
3665@end example
3666
3667It does so by browsing each package's FTP directory and determining the
3668highest version number of the source tarballs
3669therein@footnote{Currently, this only works for GNU packages.}.
3670
3671When passed @code{--update}, it modifies distribution source files to
3672update the version numbers and source tarball hashes of those packages'
3673recipes (@pxref{Defining Packages}). This is achieved by downloading
3674each package's latest source tarball and its associated OpenPGP
3675signature, authenticating the downloaded tarball against its signature
3676using @command{gpg}, and finally computing its hash. When the public
3677key used to sign the tarball is missing from the user's keyring, an
3678attempt is made to automatically retrieve it from a public key server;
3679when it's successful, the key is added to the user's keyring; otherwise,
3680@command{guix refresh} reports an error.
3681
3682The following options are supported:
3683
3684@table @code
3685
3686@item --update
3687@itemx -u
3688Update distribution source files (package recipes) in place.
081145cf 3689@xref{Defining Packages}, for more information on package definitions.
37166310
LC
3690
3691@item --select=[@var{subset}]
3692@itemx -s @var{subset}
3693Select all the packages in @var{subset}, one of @code{core} or
3694@code{non-core}.
3695
3696The @code{core} subset refers to all the packages at the core of the
3697distribution---i.e., packages that are used to build ``everything
3698else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
3699changing one of these packages in the distribution entails a rebuild of
3700all the others. Thus, such updates are an inconvenience to users in
3701terms of build time or bandwidth used to achieve the upgrade.
3702
3703The @code{non-core} subset refers to the remaining packages. It is
3704typically useful in cases where an update of the core packages would be
3705inconvenient.
3706
3707@end table
3708
3709In addition, @command{guix refresh} can be passed one or more package
3710names, as in this example:
3711
3712@example
4b9b3cbb 3713guix refresh -u emacs idutils gcc-4.8.4
37166310
LC
3714@end example
3715
3716@noindent
3717The command above specifically updates the @code{emacs} and
3718@code{idutils} packages. The @code{--select} option would have no
3719effect in this case.
3720
7d193ec3
EB
3721When considering whether to upgrade a package, it is sometimes
3722convenient to know which packages would be affected by the upgrade and
3723should be checked for compatibility. For this the following option may
3724be used when passing @command{guix refresh} one or more package names:
3725
3726@table @code
3727
3728@item --list-dependent
3729@itemx -l
3730List top-level dependent packages that would need to be rebuilt as a
3731result of upgrading one or more packages.
3732
3733@end table
3734
3735Be aware that the @code{--list-dependent} option only
3736@emph{approximates} the rebuilds that would be required as a result of
3737an upgrade. More rebuilds might be required under some circumstances.
3738
3739@example
7779ab61
LC
3740$ guix refresh --list-dependent flex
3741Building the following 120 packages would ensure 213 dependent packages are rebuilt:
3742hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{}
7d193ec3
EB
3743@end example
3744
3745The command above lists a set of packages that could be built to check
3746for compatibility with an upgraded @code{flex} package.
3747
f9230085
LC
3748The following options can be used to customize GnuPG operation:
3749
3750@table @code
3751
f9230085
LC
3752@item --gpg=@var{command}
3753Use @var{command} as the GnuPG 2.x command. @var{command} is searched
3754for in @code{$PATH}.
3755
2bc53ba9
LC
3756@item --key-download=@var{policy}
3757Handle missing OpenPGP keys according to @var{policy}, which may be one
3758of:
3759
3760@table @code
3761@item always
3762Always download missing OpenPGP keys from the key server, and add them
3763to the user's GnuPG keyring.
3764
3765@item never
3766Never try to download missing OpenPGP keys. Instead just bail out.
3767
3768@item interactive
3769When a package signed with an unknown OpenPGP key is encountered, ask
3770the user whether to download it or not. This is the default behavior.
3771@end table
3772
3773@item --key-server=@var{host}
3774Use @var{host} as the OpenPGP key server when importing a public key.
3775
f9230085
LC
3776@end table
3777
b4f5e0e8
CR
3778@node Invoking guix lint
3779@section Invoking @command{guix lint}
3780The @command{guix lint} is meant to help package developers avoid common
873c4085
LC
3781errors and use a consistent style. It runs a number of checks on a
3782given set of packages in order to find common mistakes in their
3783definitions. Available @dfn{checkers} include (see
3784@code{--list-checkers} for a complete list):
3785
3786@table @code
3787@item synopsis
3788@itemx description
3789Validate certain typographical and stylistic rules about package
3790descriptions and synopses.
3791
3792@item inputs-should-be-native
3793Identify inputs that should most likely be native inputs.
3794
3795@item source
3796@itemx home-page
3797Probe @code{home-page} and @code{source} URLs and report those that are
3798invalid.
3799@end table
b4f5e0e8
CR
3800
3801The general syntax is:
3802
3803@example
3804guix lint @var{options} @var{package}@dots{}
3805@end example
3806
3807If no package is given on the command line, then all packages are checked.
3808The @var{options} may be zero or more of the following:
3809
3810@table @code
3811
dd7c013d
CR
3812@item --checkers
3813@itemx -c
3814Only enable the checkers specified in a comma-separated list using the
3815names returned by @code{--list-checkers}.
3816
b4f5e0e8
CR
3817@item --list-checkers
3818@itemx -l
3819List and describe all the available checkers that will be run on packages
3820and exit.
3821
3822@end table
37166310 3823
372c4bbc
DT
3824@node Invoking guix environment
3825@section Invoking @command{guix environment}
3826
f5fd4fd2 3827@cindex reproducible build environments
372c4bbc
DT
3828The purpose of @command{guix environment} is to assist hackers in
3829creating reproducible development environments without polluting their
3830package profile. The @command{guix environment} tool takes one or more
3831packages, builds all of the necessary inputs, and creates a shell
3832environment to use them.
3833
3834The general syntax is:
3835
3836@example
3837guix environment @var{options} @var{package}@dots{}
3838@end example
3839
3840The following examples spawns a new shell that is capable of building
3841the GNU Guile source code:
3842
3843@example
3844guix environment guile
3845@end example
3846
3847If the specified packages are not built yet, @command{guix environment}
3848automatically builds them. The new shell's environment is an augmented
3849version of the environment that @command{guix environment} was run in.
3850It contains the necessary search paths for building the given package
3851added to the existing environment variables. To create a ``pure''
3852environment in which the original environment variables have been unset,
3853use the @code{--pure} option.
3854
3855Additionally, more than one package may be specified, in which case the
3856union of the inputs for the given packages are used. For example, the
3857command below spawns a shell where all of the dependencies of both Guile
3858and Emacs are available:
3859
3860@example
3861guix environment guile emacs
3862@end example
3863
3864Sometimes an interactive shell session is not desired. The
3865@code{--exec} option can be used to specify the command to run instead.
3866
3867@example
3868guix environment guile --exec=make
3869@end example
3870
3871The following options are available:
3872
3873@table @code
3874@item --expression=@var{expr}
3875@itemx -e @var{expr}
3876Create an environment for the package that @var{expr} evaluates to.
3877
3878@item --load=@var{file}
3879@itemx -l @var{file}
3880Create an environment for the package that the code within @var{file}
3881evaluates to.
3882
3883@item --exec=@var{command}
3884@item -E @var{command}
3885Execute @var{command} in the new environment.
3886
3887@item --pure
3888Unset existing environment variables when building the new environment.
3889This has the effect of creating an environment in which search paths
3890only contain package inputs.
3891
3892@item --search-paths
3893Display the environment variable definitions that make up the
3894environment.
3895@end table
3896
3897It also supports all of the common build options that @command{guix
3898build} supports (@pxref{Invoking guix build, common build options}).
3899
aff8ce7c
DT
3900@node Invoking guix publish
3901@section Invoking @command{guix publish}
3902
3903The purpose of @command{guix publish} is to enable users to easily share
8ce229fc
LC
3904their store with others, which can then use it as a substitute server
3905(@pxref{Substitutes}).
3906
3907When @command{guix publish} runs, it spawns an HTTP server which allows
3908anyone with network access to obtain substitutes from it. This means
3909that any machine running Guix can also act as if it were a build farm,
3910since the HTTP interface is compatible with Hydra, the software behind
3911the @code{hydra.gnu.org} build farm.
aff8ce7c
DT
3912
3913For security, each substitute is signed, allowing recipients to check
3914their authenticity and integrity (@pxref{Substitutes}). Because
3915@command{guix publish} uses the system's signing key, which is only
5463fe51
LC
3916readable by the system administrator, it must be started as root; the
3917@code{--user} option makes it drop root privileges early on.
aff8ce7c
DT
3918
3919The general syntax is:
3920
3921@example
3922guix publish @var{options}@dots{}
3923@end example
3924
3925Running @command{guix publish} without any additional arguments will
3926spawn an HTTP server on port 8080:
3927
3928@example
3929guix publish
3930@end example
3931
3932Once a publishing server has been authorized (@pxref{Invoking guix
3933archive}), the daemon may download substitutes from it:
3934
3935@example
3936guix-daemon --substitute-urls=http://example.org:8080
3937@end example
3938
3939The following options are available:
3940
3941@table @code
3942@item --port=@var{port}
3943@itemx -p @var{port}
3944Listen for HTTP requests on @var{port}.
3945
9e2292ef
LC
3946@item --listen=@var{host}
3947Listen on the network interface for @var{host}. The default is to
3948accept connections from any interface.
3949
5463fe51
LC
3950@item --user=@var{user}
3951@itemx -u @var{user}
3952Change privileges to @var{user} as soon as possible---i.e., once the
3953server socket is open and the signing key has been read.
3954
aff8ce7c
DT
3955@item --repl[=@var{port}]
3956@itemx -r [@var{port}]
3957Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
8ce229fc
LC
3958Reference Manual}) on @var{port} (37146 by default). This is used
3959primarily for debugging a running @command{guix publish} server.
aff8ce7c
DT
3960@end table
3961
a1ba8475
LC
3962@c *********************************************************************
3963@node GNU Distribution
3964@chapter GNU Distribution
3965
3ca2731c 3966@cindex Guix System Distribution
4705641f 3967@cindex GuixSD
3ca2731c
LC
3968Guix comes with a distribution of the GNU system consisting entirely of
3969free software@footnote{The term ``free'' here refers to the
a1ba8475 3970@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
3ca2731c 3971users of that software}.}. The
35ed9306
LC
3972distribution can be installed on its own (@pxref{System Installation}),
3973but it is also possible to install Guix as a package manager on top of
3974an installed GNU/Linux system (@pxref{Installation}). To distinguish
3ca2731c 3975between the two, we refer to the standalone distribution as the Guix
4705641f 3976System Distribution, or GuixSD.
35ed9306
LC
3977
3978The distribution provides core GNU packages such as GNU libc, GCC, and
3979Binutils, as well as many GNU and non-GNU applications. The complete
3980list of available packages can be browsed
d03bb653
LC
3981@url{http://www.gnu.org/software/guix/package-list.html,on-line} or by
3982running @command{guix package} (@pxref{Invoking guix package}):
a1ba8475
LC
3983
3984@example
e49951eb 3985guix package --list-available
a1ba8475
LC
3986@end example
3987
35ed9306 3988Our goal has been to provide a practical 100% free software distribution of
401c53c4
LC
3989Linux-based and other variants of GNU, with a focus on the promotion and
3990tight integration of GNU components, and an emphasis on programs and
3991tools that help users exert that freedom.
3992
3ca2731c 3993Packages are currently available on the following platforms:
c320011d
LC
3994
3995@table @code
3996
3997@item x86_64-linux
3998Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
3999
4000@item i686-linux
4001Intel 32-bit architecture (IA32), Linux-Libre kernel;
4002
aa1e1947
MW
4003@item armhf-linux
4004ARMv7-A architecture with hard float, Thumb-2 and VFP3D16 coprocessor,
4005using the EABI hard-float ABI, and Linux-Libre kernel.
4006
c320011d
LC
4007@item mips64el-linux
4008little-endian 64-bit MIPS processors, specifically the Loongson series,
4009n32 application binary interface (ABI), and Linux-Libre kernel.
4010
4011@end table
4012
4705641f 4013GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
3ca2731c 4014
c320011d
LC
4015@noindent
4016For information on porting to other architectures or kernels,
4017@xref{Porting}.
4018
401c53c4 4019@menu
5af6de3e 4020* System Installation:: Installing the whole operating system.
35ed9306 4021* System Configuration:: Configuring the operating system.
91ef73d4 4022* Installing Debugging Files:: Feeding the debugger.
05962f29 4023* Security Updates:: Deploying security fixes quickly.
401c53c4 4024* Package Modules:: Packages from the programmer's viewpoint.
da7cabd4 4025* Packaging Guidelines:: Growing the distribution.
401c53c4 4026* Bootstrapping:: GNU/Linux built from scratch.
8b315a6d 4027* Porting:: Targeting another platform or kernel.
401c53c4
LC
4028@end menu
4029
4030Building this distribution is a cooperative effort, and you are invited
081145cf 4031to join! @xref{Contributing}, for information about how you can help.
401c53c4 4032
5af6de3e
LC
4033@node System Installation
4034@section System Installation
4035
3ca2731c
LC
4036@cindex Guix System Distribution
4037This section explains how to install the Guix System Distribution
4038on a machine. The Guix package manager can
35ed9306
LC
4039also be installed on top of a running GNU/Linux system,
4040@pxref{Installation}.
5af6de3e
LC
4041
4042@ifinfo
4043@c This paragraph is for people reading this from tty2 of the
4044@c installation image.
4045You're reading this documentation with an Info reader. For details on
4046how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
6621cdb6 4047link that follows: @pxref{Help,,, info, Info: An Introduction}. Hit
5af6de3e
LC
4048@kbd{l} afterwards to come back here.
4049@end ifinfo
4050
8aaaae38
LC
4051@subsection Limitations
4052
4705641f 4053As of version @value{VERSION}, the Guix System Distribution (GuixSD) is
3ca2731c 4054not production-ready. It may contain bugs and lack important
8aaaae38
LC
4055features. Thus, if you are looking for a stable production system that
4056respects your freedom as a computer user, a good solution at this point
4057is to consider @url{http://www.gnu.org/distros/free-distros.html, one of
4058more established GNU/Linux distributions}. We hope you can soon switch
4705641f 4059to the GuixSD without fear, of course. In the meantime, you can
8aaaae38
LC
4060also keep using your distribution and try out the package manager on top
4061of it (@pxref{Installation}).
4062
4063Before you proceed with the installation, be aware of the following
4064noteworthy limitations applicable to version @value{VERSION}:
4065
4066@itemize
4067@item
4068The installation process does not include a graphical user interface and
4069requires familiarity with GNU/Linux (see the following subsections to
4070get a feel of what that means.)
4071
4072@item
b1e95eca
LC
4073The system does not yet provide GNOME and KDE; it provides Xfce, though,
4074if graphical desktop environments are your thing.
8aaaae38
LC
4075
4076@item
dbcb0ab1 4077Support for the Logical Volume Manager (LVM) is missing.
8aaaae38
LC
4078
4079@item
4080Few system services are currently supported out-of-the-box
4081(@pxref{Services}).
4082
4083@item
49607566 4084On the order of 1,900 packages are available, which means that you may
8aaaae38
LC
4085occasionally find that a useful package is missing.
4086@end itemize
4087
4088You've been warned. But more than a disclaimer, this is an invitation
4089to report issues (and success stories!), and join us in improving it.
4090@xref{Contributing}, for more info.
5af6de3e
LC
4091
4092@subsection USB Stick Installation
4093
4094An installation image for USB sticks can be downloaded from
4705641f 4095@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
5af6de3e
LC
4096where @var{system} is one of:
4097
4098@table @code
4099@item x86_64-linux
4100for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
4101
4102@item i686-linux
4103for a 32-bit GNU/Linux system on Intel-compatible CPUs.
4104@end table
4105
4106This image contains a single partition with the tools necessary for an
4107installation. It is meant to be copied @emph{as is} to a large-enough
4108USB stick.
4109
4110To copy the image to a USB stick, follow these steps:
4111
4112@enumerate
4113@item
4114Decompress the image using the @command{xz} command:
4115
4116@example
4705641f 4117xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
5af6de3e
LC
4118@end example
4119
4120@item
4121Insert a USB stick of 1@tie{}GiB or more in your machine, and determine
4122its device name. Assuming that USB stick is known as @file{/dev/sdX},
4123copy the image with:
4124
4125@example
4705641f 4126dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
5af6de3e
LC
4127@end example
4128
4129Access to @file{/dev/sdX} usually requires root privileges.
4130@end enumerate
4131
4132Once this is done, you should be able to reboot the system and boot from
4133the USB stick. The latter usually requires you to get in the BIOS' boot
4134menu, where you can choose to boot from the USB stick.
4135
4136@subsection Preparing for Installation
4137
4138Once you have successfully booted the image on the USB stick, you should
4139end up with a root prompt. Several console TTYs are configured and can
4140be used to run commands as root. TTY2 shows this documentation,
4141browsable using the Info reader commands (@pxref{Help,,, info, Info: An
4142Introduction}).
4143
4144To install the system, you would:
4145
4146@enumerate
4147
4148@item
152dd61c
LC
4149Configure the network, by running @command{ifconfig eno1 up && dhclient
4150eno1} (to get an automatically assigned IP address from the wired
4151network interface controller@footnote{
95c559c1
LC
4152@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
4153The name @code{eno1} is for the first on-board Ethernet controller. The
4154interface name for an Ethernet controller that is in the first slot of
4155the first PCI bus, for instance, would be @code{enp1s0}. Use
4156@command{ifconfig -a} to list all the available network interfaces.}),
4157or using the @command{ifconfig} command.
5af6de3e
LC
4158
4159The system automatically loads drivers for your network interface
4160controllers.
4161
4162Setting up network access is almost always a requirement because the
4163image does not contain all the software and tools that may be needed.
4164
4165@item
4166Unless this has already been done, you must partition and format the
4167target partitions.
4168
7ab44369
LC
4169Preferably, assign partitions a label so that you can easily and
4170reliably refer to them in @code{file-system} declarations (@pxref{File
4171Systems}). This is typically done using the @code{-L} option of
4172@command{mkfs.ext4} and related commands.
4173
5af6de3e 4174The installation image includes Parted (@pxref{Overview,,, parted, GNU
b419c7f5
LC
4175Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
4176encryption, and e2fsprogs, the suite of tools to manipulate
4177ext2/ext3/ext4 file systems.
5af6de3e 4178
83a17b62
LC
4179@item
4180Once that is done, mount the target root partition under @file{/mnt}.
4181
4182@item
4183Lastly, run @code{deco start cow-store /mnt}.
4184
4185This will make @file{/gnu/store} copy-on-write, such that packages added
4186to it during the installation phase will be written to the target disk
4187rather than kept in memory.
4188
5af6de3e
LC
4189@end enumerate
4190
5af6de3e
LC
4191
4192@subsection Proceeding with the Installation
4193
4194With the target partitions ready, you now have to edit a file and
4195provide the declaration of the operating system to be installed. To
4196that end, the installation system comes with two text editors: GNU nano
4197(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
4198It is better to store that file on the target root file system, say, as
4199@file{/mnt/etc/config.scm}.
4200
dd51caac
LC
4201@xref{Using the Configuration System}, for examples of operating system
4202configurations. These examples are available under
4203@file{/etc/configuration} in the installation image, so you can copy
4204them and use them as a starting point for your own configuration.
5af6de3e 4205
dd51caac
LC
4206Once you are done preparing the configuration file, the new system must
4207be initialized (remember that the target root file system is mounted
4208under @file{/mnt}):
5af6de3e
LC
4209
4210@example
4211guix system init /mnt/etc/config.scm /mnt
4212@end example
4213
4214@noindent
4215This will copy all the necessary files, and install GRUB on
4216@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For
6621cdb6 4217more information, @pxref{Invoking guix system}. This command may trigger
5af6de3e
LC
4218downloads or builds of missing packages, which can take some time.
4219
4220Once that command has completed---and hopefully succeeded!---you can
ad14d9e7 4221run @command{reboot} and boot into the new system. Cross fingers, and
5af6de3e
LC
4222join us on @code{#guix} on the Freenode IRC network or on
4223@file{guix-devel@@gnu.org} to share your experience---good or not so
4224good.
4225
4226@subsection Building the Installation Image
4227
4228The installation image described above was built using the @command{guix
4229system} command, specifically:
4230
4231@example
8a225c66 4232guix system disk-image --image-size=850MiB gnu/system/install.scm
5af6de3e
LC
4233@end example
4234
4235@xref{Invoking guix system}, for more information. See
4236@file{gnu/system/install.scm} in the source tree for more information
4237about the installation image.
4238
cf4a9129
LC
4239@node System Configuration
4240@section System Configuration
b208a005 4241
cf4a9129 4242@cindex system configuration
3ca2731c 4243The Guix System Distribution supports a consistent whole-system configuration
cf4a9129
LC
4244mechanism. By that we mean that all aspects of the global system
4245configuration---such as the available system services, timezone and
4246locale settings, user accounts---are declared in a single place. Such
4247a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
91ef73d4 4248
cf4a9129
LC
4249One of the advantages of putting all the system configuration under the
4250control of Guix is that it supports transactional system upgrades, and
4251makes it possible to roll-back to a previous system instantiation,
4252should something go wrong with the new one (@pxref{Features}). Another
4253one is that it makes it easy to replicate the exact same configuration
4254across different machines, or at different points in time, without
4255having to resort to additional administration tools layered on top of
4256the system's own tools.
4257@c Yes, we're talking of Puppet, Chef, & co. here. ↑
91ef73d4 4258
cf4a9129
LC
4259This section describes this mechanism. First we focus on the system
4260administrator's viewpoint---explaining how the system is configured and
4261instantiated. Then we show how this mechanism can be extended, for
4262instance to support new system services.
91ef73d4 4263
cf4a9129
LC
4264@menu
4265* Using the Configuration System:: Customizing your GNU system.
7313a52e 4266* operating-system Reference:: Detail of operating-system declarations.
cf4a9129 4267* File Systems:: Configuring file system mounts.
510f9d86 4268* Mapped Devices:: Block device extra processing.
cf4a9129 4269* User Accounts:: Specifying user accounts.
598e19dc 4270* Locales:: Language and cultural convention settings.
cf4a9129 4271* Services:: Specifying system services.
0ae8c15a 4272* Setuid Programs:: Programs running with root privileges.
efb5e833 4273* X.509 Certificates:: Authenticating HTTPS servers.
996ed739 4274* Name Service Switch:: Configuring libc's name service switch.
fd1b1fa2 4275* Initial RAM Disk:: Linux-Libre bootstrapping.
88faf933 4276* GRUB Configuration:: Configuring the boot loader.
cf4a9129
LC
4277* Invoking guix system:: Instantiating a system configuration.
4278* Defining Services:: Adding new service definitions.
4279@end menu
91ef73d4 4280
cf4a9129
LC
4281@node Using the Configuration System
4282@subsection Using the Configuration System
64d76fa6 4283
cf4a9129
LC
4284The operating system is configured by providing an
4285@code{operating-system} declaration in a file that can then be passed to
4286the @command{guix system} command (@pxref{Invoking guix system}). A
4287simple setup, with the default system services, the default Linux-Libre
4288kernel, initial RAM disk, and boot loader looks like this:
91ef73d4 4289
cf4a9129
LC
4290@findex operating-system
4291@lisp
dd51caac 4292@include os-config-bare-bones.texi
cf4a9129 4293@end lisp
401c53c4 4294
cf4a9129
LC
4295This example should be self-describing. Some of the fields defined
4296above, such as @code{host-name} and @code{bootloader}, are mandatory.
4297Others, such as @code{packages} and @code{services}, can be omitted, in
4298which case they get a default value.
e7f34eb0 4299
cf4a9129
LC
4300@vindex %base-packages
4301The @code{packages} field lists
4302packages that will be globally visible on the system, for all user
4303accounts---i.e., in every user's @code{PATH} environment variable---in
4304addition to the per-user profiles (@pxref{Invoking guix package}). The
4305@var{%base-packages} variable provides all the tools one would expect
4306for basic user and administrator tasks---including the GNU Core
4307Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
4308editor, @command{find}, @command{grep}, etc. The example above adds
4309Emacs to those, taken from the @code{(gnu packages emacs)} module
4310(@pxref{Package Modules}).
e7f34eb0 4311
cf4a9129
LC
4312@vindex %base-services
4313The @code{services} field lists @dfn{system services} to be made
4314available when the system starts (@pxref{Services}).
4315The @code{operating-system} declaration above specifies that, in
4316addition to the basic services, we want the @command{lshd} secure shell
4317daemon listening on port 2222, and allowing remote @code{root} logins
4318(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood,
4319@code{lsh-service} arranges so that @code{lshd} is started with the
4320right command-line options, possibly with supporting configuration files
7313a52e
LC
4321generated as needed (@pxref{Defining Services}). @xref{operating-system
4322Reference}, for details about the available @code{operating-system}
4323fields.
a1ba8475 4324
dd51caac
LC
4325The configuration for a typical ``desktop'' usage, with the X11 display
4326server, a desktop environment, network management, an SSH server, and
4327more, would look like this:
4328
4329@lisp
4330@include os-config-desktop.texi
4331@end lisp
4332
4333@xref{Desktop Services}, for the exact list of services provided by
efb5e833
LC
4334@var{%desktop-services}. @xref{X.509 Certificates}, for background
4335information about the @code{nss-certs} package that is used here.
dd51caac 4336
cf4a9129
LC
4337Assuming the above snippet is stored in the @file{my-system-config.scm}
4338file, the @command{guix system reconfigure my-system-config.scm} command
4339instantiates that configuration, and makes it the default GRUB boot
4340entry (@pxref{Invoking guix system}). The normal way to change the
4341system's configuration is by updating this file and re-running the
4342@command{guix system} command.
b81e1947 4343
cf4a9129
LC
4344At the Scheme level, the bulk of an @code{operating-system} declaration
4345is instantiated with the following monadic procedure (@pxref{The Store
4346Monad}):
b81e1947 4347
cf4a9129
LC
4348@deffn {Monadic Procedure} operating-system-derivation os
4349Return a derivation that builds @var{os}, an @code{operating-system}
4350object (@pxref{Derivations}).
b81e1947 4351
cf4a9129
LC
4352The output of the derivation is a single directory that refers to all
4353the packages, configuration files, and other supporting files needed to
4354instantiate @var{os}.
4355@end deffn
b81e1947 4356
7313a52e
LC
4357@node operating-system Reference
4358@subsection @code{operating-system} Reference
4359
4360This section summarizes all the options available in
4361@code{operating-system} declarations (@pxref{Using the Configuration
4362System}).
4363
4364@deftp {Data Type} operating-system
4365This is the data type representing an operating system configuration.
4366By that, we mean all the global system configuration, not per-user
4367configuration (@pxref{Using the Configuration System}).
4368
4369@table @asis
4370@item @code{kernel} (default: @var{linux-libre})
4371The package object of the operating system to use@footnote{Currently
4372only the Linux-libre kernel is supported. In the future, it will be
4373possible to use the GNU@tie{}Hurd.}.
4374
4375@item @code{bootloader}
88faf933 4376The system bootloader configuration object. @xref{GRUB Configuration}.
7313a52e
LC
4377
4378@item @code{initrd} (default: @code{base-initrd})
4379A two-argument monadic procedure that returns an initial RAM disk for
4380the Linux kernel. @xref{Initial RAM Disk}.
4381
f34c56be
LC
4382@item @code{firmware} (default: @var{%base-firmware})
4383@cindex firmware
4384List of firmware packages loadable by the operating system kernel.
4385
4386The default includes firmware needed for Atheros-based WiFi devices
4387(Linux-libre module @code{ath9k}.)
4388
7313a52e
LC
4389@item @code{host-name}
4390The host name.
4391
4392@item @code{hosts-file}
4393@cindex hosts file
4394A zero-argument monadic procedure that returns a text file for use as
4395@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
4396Reference Manual}). The default is to produce a file with entries for
4397@code{localhost} and @var{host-name}.
4398
4399@item @code{mapped-devices} (default: @code{'()})
4400A list of mapped devices. @xref{Mapped Devices}.
4401
4402@item @code{file-systems}
4403A list of file systems. @xref{File Systems}.
4404
4405@item @code{swap-devices} (default: @code{'()})
4406@cindex swap devices
4407A list of strings identifying devices to be used for ``swap space''
4408(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}).
4409For example, @code{'("/dev/sda3")}.
4410
4411@item @code{users} (default: @code{'()})
4412@itemx @code{groups} (default: @var{%base-groups})
4413List of user accounts and groups. @xref{User Accounts}.
4414
4415@item @code{skeletons} (default: @code{(default-skeletons)})
4416A monadic list of pairs of target file name and files. These are the
4417files that will be used as skeletons as new accounts are created.
4418
4419For instance, a valid value may look like this:
4420
4421@example
4422(mlet %store-monad ((bashrc (text-file "bashrc" "\
4423 export PATH=$HOME/.guix-profile/bin")))
4424 (return `((".bashrc" ,bashrc))))
4425@end example
4426
4427@item @code{issue} (default: @var{%default-issue})
4428A string denoting the contents of the @file{/etc/issue} file, which is
4429what displayed when users log in on a text console.
4430
4431@item @code{packages} (default: @var{%base-packages})
4432The set of packages installed in the global profile, which is accessible
4433at @file{/run/current-system/profile}.
4434
4435The default set includes core utilities, but it is good practice to
4436install non-core utilities in user profiles (@pxref{Invoking guix
4437package}).
4438
4439@item @code{timezone}
4440A timezone identifying string---e.g., @code{"Europe/Paris"}.
4441
598e19dc
LC
4442@item @code{locale} (default: @code{"en_US.utf8"})
4443The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
4444Library Reference Manual}). @xref{Locales}, for more information.
4445
4446@item @code{locale-definitions} (default: @var{%default-locale-definitions})
4447The list of locale definitions to be compiled and that may be used at
4448run time. @xref{Locales}.
7313a52e 4449
996ed739
LC
4450@item @code{name-service-switch} (default: @var{%default-nss})
4451Configuration of libc's name service switch (NSS)---a
4452@code{<name-service-switch>} object. @xref{Name Service Switch}, for
4453details.
4454
7313a52e
LC
4455@item @code{services} (default: @var{%base-services})
4456A list of monadic values denoting system services. @xref{Services}.
4457
4458@item @code{pam-services} (default: @code{(base-pam-services)})
4459@cindex PAM
4460@cindex pluggable authentication modules
4461Linux @dfn{pluggable authentication module} (PAM) services.
4462@c FIXME: Add xref to PAM services section.
4463
4464@item @code{setuid-programs} (default: @var{%setuid-programs})
4465List of string-valued G-expressions denoting setuid programs.
4466@xref{Setuid Programs}.
4467
4468@item @code{sudoers} (default: @var{%sudoers-specification})
4469@cindex sudoers
4470The contents of the @file{/etc/sudoers} file as a string.
4471
4472This file specifies which users can use the @command{sudo} command, what
4473they are allowed to do, and what privileges they may gain. The default
4474is that only @code{root} and members of the @code{wheel} group may use
4475@code{sudo}.
4476
4477@end table
4478@end deftp
4479
cf4a9129
LC
4480@node File Systems
4481@subsection File Systems
b81e1947 4482
cf4a9129
LC
4483The list of file systems to be mounted is specified in the
4484@code{file-systems} field of the operating system's declaration
4485(@pxref{Using the Configuration System}). Each file system is declared
4486using the @code{file-system} form, like this:
b81e1947
LC
4487
4488@example
cf4a9129
LC
4489(file-system
4490 (mount-point "/home")
4491 (device "/dev/sda3")
4492 (type "ext4"))
b81e1947
LC
4493@end example
4494
cf4a9129
LC
4495As usual, some of the fields are mandatory---those shown in the example
4496above---while others can be omitted. These are described below.
b81e1947 4497
cf4a9129
LC
4498@deftp {Data Type} file-system
4499Objects of this type represent file systems to be mounted. They
4500contain the following members:
5ff3c4b8 4501
cf4a9129
LC
4502@table @asis
4503@item @code{type}
4504This is a string specifying the type of the file system---e.g.,
4505@code{"ext4"}.
5ff3c4b8 4506
cf4a9129
LC
4507@item @code{mount-point}
4508This designates the place where the file system is to be mounted.
b81e1947 4509
cf4a9129
LC
4510@item @code{device}
4511This names the ``source'' of the file system. By default it is the name
4512of a node under @file{/dev}, but its meaning depends on the @code{title}
4513field described below.
401c53c4 4514
cf4a9129
LC
4515@item @code{title} (default: @code{'device})
4516This is a symbol that specifies how the @code{device} field is to be
4517interpreted.
401c53c4 4518
cf4a9129
LC
4519When it is the symbol @code{device}, then the @code{device} field is
4520interpreted as a file name; when it is @code{label}, then @code{device}
4521is interpreted as a partition label name; when it is @code{uuid},
4522@code{device} is interpreted as a partition unique identifier (UUID).
da7cabd4 4523
cf4a9129
LC
4524The @code{label} and @code{uuid} options offer a way to refer to disk
4525partitions without having to hard-code their actual device name.
da7cabd4 4526
5f86a66e
LC
4527However, when a file system's source is a mapped device (@pxref{Mapped
4528Devices}), its @code{device} field @emph{must} refer to the mapped
4529device name---e.g., @file{/dev/mapper/root-partition}---and consequently
4530@code{title} must be set to @code{'device}. This is required so that
4531the system knows that mounting the file system depends on having the
4532corresponding device mapping established.
4533
cf4a9129
LC
4534@item @code{flags} (default: @code{'()})
4535This is a list of symbols denoting mount flags. Recognized flags
2c071ce9
LC
4536include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
4537access to special files), @code{no-suid} (ignore setuid and setgid
4538bits), and @code{no-exec} (disallow program execution.)
da7cabd4 4539
cf4a9129
LC
4540@item @code{options} (default: @code{#f})
4541This is either @code{#f}, or a string denoting mount options.
da7cabd4 4542
cf4a9129
LC
4543@item @code{needed-for-boot?} (default: @code{#f})
4544This Boolean value indicates whether the file system is needed when
4545booting. If that is true, then the file system is mounted when the
4546initial RAM disk (initrd) is loaded. This is always the case, for
4547instance, for the root file system.
da7cabd4 4548
cf4a9129
LC
4549@item @code{check?} (default: @code{#t})
4550This Boolean indicates whether the file system needs to be checked for
4551errors before being mounted.
f9cc8971 4552
4e469051
LC
4553@item @code{create-mount-point?} (default: @code{#f})
4554When true, the mount point is created if it does not exist yet.
4555
cf4a9129
LC
4556@end table
4557@end deftp
da7cabd4 4558
a69576ea
LC
4559The @code{(gnu system file-systems)} exports the following useful
4560variables.
4561
4562@defvr {Scheme Variable} %base-file-systems
4563These are essential file systems that are required on normal systems,
3392ce5d
LC
4564such as @var{%devtmpfs-file-system} and @var{%immutable-store} (see
4565below.) Operating system declarations should always contain at least
4566these.
a69576ea
LC
4567@end defvr
4568
4569@defvr {Scheme Variable} %devtmpfs-file-system
4570The @code{devtmpfs} file system to be mounted on @file{/dev}. This is a
4571requirement for udev (@pxref{Base Services, @code{udev-service}}).
4572@end defvr
4573
7f239fd3
LC
4574@defvr {Scheme Variable} %pseudo-terminal-file-system
4575This is the file system to be mounted as @file{/dev/pts}. It supports
4576@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
4577functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
4578Manual}). Pseudo-terminals are used by terminal emulators such as
4579@command{xterm}.
4580@end defvr
4581
db17ae5c
LC
4582@defvr {Scheme Variable} %shared-memory-file-system
4583This file system is mounted as @file{/dev/shm} and is used to support
4584memory sharing across processes (@pxref{Memory-mapped I/O,
4585@code{shm_open},, libc, The GNU C Library Reference Manual}).
4586@end defvr
4587
3392ce5d
LC
4588@defvr {Scheme Variable} %immutable-store
4589This file system performs a read-only ``bind mount'' of
4590@file{/gnu/store}, making it read-only for all the users including
4591@code{root}. This prevents against accidental modification by software
4592running as @code{root} or by system administrators.
4593
4594The daemon itself is still able to write to the store: it remounts it
4595read-write in its own ``name space.''
4596@end defvr
4597
a69576ea
LC
4598@defvr {Scheme Variable} %binary-format-file-system
4599The @code{binfmt_misc} file system, which allows handling of arbitrary
4600executable file types to be delegated to user space. This requires the
4601@code{binfmt.ko} kernel module to be loaded.
4602@end defvr
4603
4604@defvr {Scheme Variable} %fuse-control-file-system
4605The @code{fusectl} file system, which allows unprivileged users to mount
4606and unmount user-space FUSE file systems. This requires the
4607@code{fuse.ko} kernel module to be loaded.
4608@end defvr
4609
510f9d86
LC
4610@node Mapped Devices
4611@subsection Mapped Devices
4612
4613@cindex device mapping
4614@cindex mapped devices
4615The Linux kernel has a notion of @dfn{device mapping}: a block device,
4616such as a hard disk partition, can be @dfn{mapped} into another device,
4617with additional processing over the data that flows through
4618it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
4619concept of a ``mapped device'' and that of a file system: both boil down
4620to @emph{translating} input/output operations made on a file to
4621operations on its backing store. Thus, the Hurd implements mapped
4622devices, like file systems, using the generic @dfn{translator} mechanism
4623(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
4624typical example is encryption device mapping: all writes to the mapped
4625device are encrypted, and all reads are deciphered, transparently.
4626
4627Mapped devices are declared using the @code{mapped-device} form:
4628
4629@example
4630(mapped-device
4631 (source "/dev/sda3")
4632 (target "home")
4633 (type luks-device-mapping))
4634@end example
4635
4636@noindent
4637@cindex disk encryption
4638@cindex LUKS
4639This example specifies a mapping from @file{/dev/sda3} to
4640@file{/dev/mapper/home} using LUKS---the
4641@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a
4642standard mechanism for disk encryption. The @file{/dev/mapper/home}
4643device can then be used as the @code{device} of a @code{file-system}
4644declaration (@pxref{File Systems}). The @code{mapped-device} form is
4645detailed below.
4646
4647@deftp {Data Type} mapped-device
4648Objects of this type represent device mappings that will be made when
4649the system boots up.
4650
9cb426b8
LC
4651@table @code
4652@item source
510f9d86
LC
4653This string specifies the name of the block device to be mapped, such as
4654@code{"/dev/sda3"}.
4655
9cb426b8 4656@item target
510f9d86
LC
4657This string specifies the name of the mapping to be established. For
4658example, specifying @code{"my-partition"} will lead to the creation of
4659the @code{"/dev/mapper/my-partition"} device.
4660
9cb426b8 4661@item type
510f9d86
LC
4662This must be a @code{mapped-device-kind} object, which specifies how
4663@var{source} is mapped to @var{target}.
4664@end table
4665@end deftp
4666
4667@defvr {Scheme Variable} luks-device-mapping
4668This defines LUKS block device encryption using the @command{cryptsetup}
4669command, from the same-named package. This relies on the
4670@code{dm-crypt} Linux kernel module.
4671@end defvr
4672
cf4a9129
LC
4673@node User Accounts
4674@subsection User Accounts
ee85f3db 4675
9bea87a5
LC
4676User accounts and groups are entirely managed through the
4677@code{operating-system} declaration. They are specified with the
4678@code{user-account} and @code{user-group} forms:
ee85f3db 4679
cf4a9129
LC
4680@example
4681(user-account
4682 (name "alice")
4683 (group "users")
24e752c0
LC
4684 (supplementary-groups '("wheel" ;allow use of sudo, etc.
4685 "audio" ;sound card
4686 "video" ;video devices such as webcams
4687 "cdrom")) ;the good ol' CD-ROM
cf4a9129
LC
4688 (comment "Bob's sister")
4689 (home-directory "/home/alice"))
4690@end example
25083588 4691
9bea87a5
LC
4692When booting or upon completion of @command{guix system reconfigure},
4693the system ensures that only the user accounts and groups specified in
4694the @code{operating-system} declaration exist, and with the specified
4695properties. Thus, account or group creations or modifications made by
4696directly invoking commands such as @command{useradd} are lost upon
4697reconfiguration or reboot. This ensures that the system remains exactly
4698as declared.
4699
cf4a9129
LC
4700@deftp {Data Type} user-account
4701Objects of this type represent user accounts. The following members may
4702be specified:
ee85f3db 4703
cf4a9129
LC
4704@table @asis
4705@item @code{name}
4706The name of the user account.
ee85f3db 4707
cf4a9129
LC
4708@item @code{group}
4709This is the name (a string) or identifier (a number) of the user group
4710this account belongs to.
ee85f3db 4711
cf4a9129
LC
4712@item @code{supplementary-groups} (default: @code{'()})
4713Optionally, this can be defined as a list of group names that this
4714account belongs to.
ee85f3db 4715
cf4a9129
LC
4716@item @code{uid} (default: @code{#f})
4717This is the user ID for this account (a number), or @code{#f}. In the
4718latter case, a number is automatically chosen by the system when the
4719account is created.
ee85f3db 4720
cf4a9129
LC
4721@item @code{comment} (default: @code{""})
4722A comment about the account, such as the account's owner full name.
c8c871d1 4723
cf4a9129
LC
4724@item @code{home-directory}
4725This is the name of the home directory for the account.
ee85f3db 4726
cf4a9129
LC
4727@item @code{shell} (default: Bash)
4728This is a G-expression denoting the file name of a program to be used as
4729the shell (@pxref{G-Expressions}).
ee85f3db 4730
cf4a9129
LC
4731@item @code{system?} (default: @code{#f})
4732This Boolean value indicates whether the account is a ``system''
4733account. System accounts are sometimes treated specially; for instance,
4734graphical login managers do not list them.
ee85f3db 4735
cf4a9129 4736@item @code{password} (default: @code{#f})
eb59595c
LC
4737You would normally leave this field to @code{#f}, initialize user
4738passwords as @code{root} with the @command{passwd} command, and then let
9bea87a5
LC
4739users change it with @command{passwd}. Passwords set with
4740@command{passwd} are of course preserved across reboot and
4741reconfiguration.
eb59595c
LC
4742
4743If you @emph{do} want to have a preset password for an account, then
4744this field must contain the encrypted password, as a string.
5d1f1177
LC
4745@xref{crypt,,, libc, The GNU C Library Reference Manual}, for more information
4746on password encryption, and @ref{Encryption,,, guile, GNU Guile Reference
eb59595c 4747Manual}, for information on Guile's @code{crypt} procedure.
c8c871d1 4748
cf4a9129
LC
4749@end table
4750@end deftp
ee85f3db 4751
cf4a9129 4752User group declarations are even simpler:
ee85f3db 4753
cf4a9129
LC
4754@example
4755(user-group (name "students"))
4756@end example
ee85f3db 4757
cf4a9129
LC
4758@deftp {Data Type} user-group
4759This type is for, well, user groups. There are just a few fields:
af8a56b8 4760
cf4a9129
LC
4761@table @asis
4762@item @code{name}
4763The group's name.
ee85f3db 4764
cf4a9129
LC
4765@item @code{id} (default: @code{#f})
4766The group identifier (a number). If @code{#f}, a new number is
4767automatically allocated when the group is created.
ee85f3db 4768
c8fa3426
LC
4769@item @code{system?} (default: @code{#f})
4770This Boolean value indicates whether the group is a ``system'' group.
4771System groups have low numerical IDs.
4772
cf4a9129
LC
4773@item @code{password} (default: @code{#f})
4774What, user groups can have a password? Well, apparently yes. Unless
4775@code{#f}, this field specifies the group's password.
ee85f3db 4776
cf4a9129
LC
4777@end table
4778@end deftp
401c53c4 4779
cf4a9129
LC
4780For convenience, a variable lists all the basic user groups one may
4781expect:
401c53c4 4782
cf4a9129
LC
4783@defvr {Scheme Variable} %base-groups
4784This is the list of basic user groups that users and/or packages expect
4785to be present on the system. This includes groups such as ``root'',
4786``wheel'', and ``users'', as well as groups used to control access to
4787specific devices such as ``audio'', ``disk'', and ``cdrom''.
4788@end defvr
401c53c4 4789
598e19dc
LC
4790@node Locales
4791@subsection Locales
4792
4793@cindex locale
4794A @dfn{locale} defines cultural conventions for a particular language
4795and region of the world (@pxref{Locales,,, libc, The GNU C Library
4796Reference Manual}). Each locale has a name that typically has the form
4797@code{@var{language}_@var{territory}.@var{charset}}---e.g.,
4798@code{fr_LU.utf8} designates the locale for the French language, with
4799cultural conventions from Luxembourg, and using the UTF-8 encoding.
4800
4801@cindex locale definition
4802Usually, you will want to specify the default locale for the machine
4803using the @code{locale} field of the @code{operating-system} declaration
4804(@pxref{operating-system Reference, @code{locale}}).
4805
4806That locale must be among the @dfn{locale definitions} that are known to
4807the system---and these are specified in the @code{locale-definitions}
4808slot of @code{operating-system}. The default value includes locale
4809definition for some widely used locales, but not for all the available
4810locales, in order to save space.
4811
4812If the locale specified in the @code{locale} field is not among the
4813definitions listed in @code{locale-definitions}, @command{guix system}
4814raises an error. In that case, you should add the locale definition to
4815the @code{locale-definitions} field. For instance, to add the North
4816Frisian locale for Germany, the value of that field may be:
4817
4818@example
4819(cons (locale-definition
4820 (name "fy_DE.utf8") (source "fy_DE"))
4821 %default-locale-definitions)
4822@end example
4823
4824Likewise, to save space, one might want @code{locale-definitions} to
4825list only the locales that are actually used, as in:
4826
4827@example
4828(list (locale-definition
4829 (name "ja_JP.eucjp") (source "ja_JP")
4830 (charset "EUC-JP")))
4831@end example
4832
4833The @code{locale-definition} form is provided by the @code{(gnu system
4834locale)} module. Details are given below.
4835
4836@deftp {Data Type} locale-definition
4837This is the data type of a locale definition.
4838
4839@table @asis
4840
4841@item @code{name}
4842The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
4843Reference Manual}, for more information on locale names.
4844
4845@item @code{source}
4846The name of the source for that locale. This is typically the
4847@code{@var{language}_@var{territory}} part of the locale name.
4848
4849@item @code{charset} (default: @code{"UTF-8"})
4850The ``character set'' or ``code set'' for that locale,
4851@uref{http://www.iana.org/assignments/character-sets, as defined by
4852IANA}.
4853
4854@end table
4855@end deftp
4856
4857@defvr {Scheme Variable} %default-locale-definitions
4858An arbitrary list of commonly used locales, used as the default value of
4859the @code{locale-definitions} field of @code{operating-system}
4860declarations.
4861@end defvr
401c53c4 4862
cf4a9129
LC
4863@node Services
4864@subsection Services
401c53c4 4865
cf4a9129
LC
4866@cindex system services
4867An important part of preparing an @code{operating-system} declaration is
4868listing @dfn{system services} and their configuration (@pxref{Using the
4869Configuration System}). System services are typically daemons launched
4870when the system boots, or other actions needed at that time---e.g.,
d8b94dbd
LC
4871configuring network access.
4872
4873Services are managed by GNU@tie{}dmd (@pxref{Introduction,,, dmd, GNU
4874dmd Manual}). On a running system, the @command{deco} command allows
4875you to list the available services, show their status, start and stop
4876them, or do other specific operations (@pxref{Jump Start,,, dmd, GNU dmd
4877Manual}). For example:
4878
4879@example
4880# deco status dmd
4881@end example
4882
4883The above command, run as @code{root}, lists the currently defined
4884services. The @command{deco doc} command shows a synopsis of the given
4885service:
4886
4887@example
4888# deco doc nscd
4889Run libc's name service cache daemon (nscd).
4890@end example
4891
4892The @command{start}, @command{stop}, and @command{restart} sub-commands
4893have the effect you would expect. For instance, the commands below stop
4894the nscd service and restart the Xorg display server:
4895
4896@example
4897# deco stop nscd
4898Service nscd has been stopped.
4899# deco restart xorg-server
4900Service xorg-server has been stopped.
4901Service xorg-server has been started.
4902@end example
401c53c4 4903
cf4a9129 4904The following sections document the available services, starting with
d8b94dbd
LC
4905the core services, that may be used in an @code{operating-system}
4906declaration.
401c53c4 4907
cf4a9129
LC
4908@menu
4909* Base Services:: Essential system services.
4910* Networking Services:: Network setup, SSH daemon, etc.
4911* X Window:: Graphical display.
fe1a39d3 4912* Desktop Services:: D-Bus and desktop services.
105369a4 4913* Database Services:: SQL databases.
aa4ed923 4914* Various Services:: Other services.
cf4a9129 4915@end menu
401c53c4 4916
cf4a9129
LC
4917@node Base Services
4918@subsubsection Base Services
a1ba8475 4919
cf4a9129
LC
4920The @code{(gnu services base)} module provides definitions for the basic
4921services that one expects from the system. The services exported by
4922this module are listed below.
401c53c4 4923
cf4a9129
LC
4924@defvr {Scheme Variable} %base-services
4925This variable contains a list of basic services@footnote{Technically,
4926this is a list of monadic services. @xref{The Store Monad}.} one would
4927expect from the system: a login service (mingetty) on each tty, syslogd,
4928libc's name service cache daemon (nscd), the udev device manager, and
4929more.
401c53c4 4930
cf4a9129
LC
4931This is the default value of the @code{services} field of
4932@code{operating-system} declarations. Usually, when customizing a
4933system, you will want to append services to @var{%base-services}, like
4934this:
401c53c4 4935
cf4a9129 4936@example
fa1e31b8 4937(cons* (avahi-service) (lsh-service) %base-services)
cf4a9129
LC
4938@end example
4939@end defvr
401c53c4 4940
cf4a9129
LC
4941@deffn {Monadic Procedure} host-name-service @var{name}
4942Return a service that sets the host name to @var{name}.
4943@end deffn
401c53c4 4944
cf4a9129
LC
4945@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @
4946 [#:auto-login #f] [#:login-program] [#:login-pause? #f] @
4947 [#:allow-empty-passwords? #f]
4948Return a service to run mingetty on @var{tty}.
401c53c4 4949
cf4a9129
LC
4950When @var{allow-empty-passwords?} is true, allow empty log-in password. When
4951@var{auto-login} is true, it must be a user name under which to log-in
4952automatically. @var{login-pause?} can be set to @code{#t} in conjunction with
4953@var{auto-login}, in which case the user will have to press a key before the
4954login shell is launched.
401c53c4 4955
cf4a9129
LC
4956When true, @var{login-program} is a gexp or a monadic gexp denoting the name
4957of the log-in program (the default is the @code{login} program from the Shadow
4958tool suite.)
401c53c4 4959
cf4a9129
LC
4960@var{motd} is a monadic value containing a text file to use as
4961the ``message of the day''.
4962@end deffn
401c53c4 4963
6454b333
LC
4964@cindex name service cache daemon
4965@cindex nscd
4aee6e60
LC
4966@deffn {Monadic Procedure} nscd-service [@var{config}] [#:glibc glibc] @
4967 [#:name-services '()]
4968Return a service that runs libc's name service cache daemon (nscd) with
4969the given @var{config}---an @code{<nscd-configuration>} object.
4970Optionally, @code{#:name-services} is a list of packages that provide
4c9050c6
LC
4971name service switch (NSS) modules needed by nscd. @xref{Name Service
4972Switch}, for an example.
cf4a9129 4973@end deffn
401c53c4 4974
6454b333
LC
4975@defvr {Scheme Variable} %nscd-default-configuration
4976This is the default @code{<nscd-configuration>} value (see below) used
4977by @code{nscd-service}. This uses the caches defined by
4978@var{%nscd-default-caches}; see below.
4979@end defvr
4980
4981@deftp {Data Type} nscd-configuration
4982This is the type representing the name service cache daemon (nscd)
4983configuration.
4984
4985@table @asis
4986
4987@item @code{log-file} (default: @code{"/var/log/nscd.log"})
4988Name of nscd's log file. This is where debugging output goes when
4989@code{debug-level} is strictly positive.
4990
4991@item @code{debug-level} (default: @code{0})
4992Integer denoting the debugging levels. Higher numbers mean more
4993debugging output is logged.
4994
4995@item @code{caches} (default: @var{%nscd-default-caches})
4996List of @code{<nscd-cache>} objects denoting things to be cached; see
4997below.
4998
4999@end table
5000@end deftp
5001
5002@deftp {Data Type} nscd-cache
5003Data type representing a cache database of nscd and its parameters.
5004
5005@table @asis
5006
5007@item @code{database}
5008This is a symbol representing the name of the database to be cached.
5009Valid values are @code{passwd}, @code{group}, @code{hosts}, and
5010@code{services}, which designate the corresponding NSS database
5011(@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
5012
5013@item @code{positive-time-to-live}
5014@itemx @code{negative-time-to-live} (default: @code{20})
5015A number representing the number of seconds during which a positive or
5016negative lookup result remains in cache.
5017
5018@item @code{check-files?} (default: @code{#t})
5019Whether to check for updates of the files corresponding to
5020@var{database}.
5021
5022For instance, when @var{database} is @code{hosts}, setting this flag
5023instructs nscd to check for updates in @file{/etc/hosts} and to take
5024them into account.
5025
5026@item @code{persistent?} (default: @code{#t})
5027Whether the cache should be stored persistently on disk.
5028
5029@item @code{shared?} (default: @code{#t})
5030Whether the cache should be shared among users.
5031
5032@item @code{max-database-size} (default: 32@tie{}MiB)
5033Maximum size in bytes of the database cache.
5034
5035@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
5036@c settings, so leave them out.
5037
5038@end table
5039@end deftp
5040
5041@defvr {Scheme Variable} %nscd-default-caches
5042List of @code{<nscd-cache>} objects used by default by
5043@code{nscd-configuration} (see above.)
5044
5045It enables persistent and aggressive caching of service and host name
5046lookups. The latter provides better host name lookup performance,
5047resilience in the face of unreliable name servers, and also better
5048privacy---often the result of host name lookups is in local cache, so
5049external name servers do not even need to be queried.
5050@end defvr
5051
5052
1bb76f75
AK
5053@deffn {Monadic Procedure} syslog-service [#:config-file #f]
5054Return a service that runs @code{syslogd}. If configuration file name
5055@var{config-file} is not specified, use some reasonable default
cf4a9129
LC
5056settings.
5057@end deffn
401c53c4 5058
cf4a9129
LC
5059@deffn {Monadic Procedure} guix-service [#:guix guix] @
5060 [#:builder-group "guixbuild"] [#:build-accounts 10] @
02bb6b45 5061 [#:authorize-hydra-key? #t] [#:use-substitutes? #t] @
cf4a9129
LC
5062 [#:extra-options '()]
5063Return a service that runs the build daemon from @var{guix}, and has
5064@var{build-accounts} user accounts available under @var{builder-group}.
401c53c4 5065
cf4a9129
LC
5066When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key
5067provided by @var{guix} is authorized upon activation, meaning that substitutes
5068from @code{hydra.gnu.org} are used by default.
401c53c4 5069
cf4a9129
LC
5070If @var{use-substitutes?} is false, the daemon is run with
5071@option{--no-substitutes} (@pxref{Invoking guix-daemon,
5072@option{--no-substitutes}}).
401c53c4 5073
cf4a9129
LC
5074Finally, @var{extra-options} is a list of additional command-line options
5075passed to @command{guix-daemon}.
5076@end deffn
a1ba8475 5077
cf4a9129
LC
5078@deffn {Monadic Procedure} udev-service [#:udev udev]
5079Run @var{udev}, which populates the @file{/dev} directory dynamically.
5080@end deffn
401c53c4 5081
5eca9459
AK
5082@deffn {Monadic Procedure} console-keymap-service @var{file}
5083Return a service to load console keymap from @var{file} using
5084@command{loadkeys} command.
5085@end deffn
5086
a69576ea 5087
cf4a9129
LC
5088@node Networking Services
5089@subsubsection Networking Services
401c53c4 5090
fa1e31b8 5091The @code{(gnu services networking)} module provides services to configure
cf4a9129 5092the network interface.
a1ba8475 5093
a023cca8
LC
5094@cindex DHCP, networking service
5095@deffn {Monadic Procedure} dhcp-client-service [#:dhcp @var{isc-dhcp}]
5096Return a service that runs @var{dhcp}, a Dynamic Host Configuration
5097Protocol (DHCP) client, on all the non-loopback network interfaces.
5098@end deffn
5099
cf4a9129
LC
5100@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @
5101 [#:gateway #f] [#:name-services @code{'()}]
5102Return a service that starts @var{interface} with address @var{ip}. If
5103@var{gateway} is true, it must be a string specifying the default network
5104gateway.
5105@end deffn
8b315a6d 5106
b7d0c494
MW
5107@cindex wicd
5108@deffn {Monadic Procedure} wicd-service [#:wicd @var{wicd}]
5109Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a
5110network manager that aims to simplify wired and wireless networking.
5111@end deffn
5112
63854bcb
LC
5113@deffn {Monadic Procedure} ntp-service [#:ntp @var{ntp}] @
5114 [#:name-service @var{%ntp-servers}]
5115Return a service that runs the daemon from @var{ntp}, the
5116@uref{http://www.ntp.org, Network Time Protocol package}. The daemon will
5117keep the system clock synchronized with that of @var{servers}.
5118@end deffn
5119
5120@defvr {Scheme Variable} %ntp-servers
5121List of host names used as the default NTP servers.
5122@end defvr
5123
cf4a9129
LC
5124@deffn {Monadic Procedure} tor-service [#:tor tor]
5125Return a service to run the @uref{https://torproject.org,Tor} daemon.
8b315a6d 5126
cf4a9129
LC
5127The daemon runs with the default settings (in particular the default exit
5128policy) as the @code{tor} unprivileged user.
5129@end deffn
8b315a6d 5130
4627a464
LC
5131@deffn {Monadic Procedure} bitlbee-service [#:bitlbee bitlbee] @
5132 [#:interface "127.0.0.1"] [#:port 6667] @
5133 [#:extra-settings ""]
5134Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
5135acts as a gateway between IRC and chat networks.
5136
5137The daemon will listen to the interface corresponding to the IP address
5138specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
5139local clients can connect, whereas @code{0.0.0.0} means that connections can
5140come from any networking interface.
5141
5142In addition, @var{extra-settings} specifies a string to append to the
5143configuration file.
5144@end deffn
5145
f4391bec 5146Furthermore, @code{(gnu services ssh)} provides the following service.
8b315a6d 5147
cf4a9129 5148@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
5833bf33 5149 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
cf4a9129
LC
5150 [#:allow-empty-passwords? #f] [#:root-login? #f] @
5151 [#:syslog-output? #t] [#:x11-forwarding? #t] @
5152 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
21cc905a 5153 [#:public-key-authentication? #t] [#:initialize? #t]
cf4a9129
LC
5154Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
5155@var{host-key} must designate a file containing the host key, and readable
5156only by root.
72e25e35 5157
5833bf33
DP
5158When @var{daemonic?} is true, @command{lshd} will detach from the
5159controlling terminal and log its output to syslogd, unless one sets
5160@var{syslog-output?} to false. Obviously, it also makes lsh-service
5161depend on existence of syslogd service. When @var{pid-file?} is true,
5162@command{lshd} writes its PID to the file called @var{pid-file}.
5163
cf4a9129
LC
5164When @var{initialize?} is true, automatically create the seed and host key
5165upon service activation if they do not exist yet. This may take long and
5166require interaction.
8b315a6d 5167
20dd519c
LC
5168When @var{initialize?} is false, it is up to the user to initialize the
5169randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
5170a key pair with the private key stored in file @var{host-key} (@pxref{lshd
5171basics,,, lsh, LSH Manual}).
5172
cf4a9129
LC
5173When @var{interfaces} is empty, lshd listens for connections on all the
5174network interfaces; otherwise, @var{interfaces} must be a list of host names
5175or addresses.
9bf3c1a7 5176
20dd519c
LC
5177@var{allow-empty-passwords?} specifies whether to accept log-ins with empty
5178passwords, and @var{root-login?} specifies whether to accept log-ins as
cf4a9129 5179root.
4af2447e 5180
cf4a9129
LC
5181The other options should be self-descriptive.
5182@end deffn
4af2447e 5183
fa0c1d61
LC
5184@defvr {Scheme Variable} %facebook-host-aliases
5185This variable contains a string for use in @file{/etc/hosts}
5186(@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
5187line contains a entry that maps a known server name of the Facebook
5188on-line service---e.g., @code{www.facebook.com}---to the local
5189host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
5190
5191This variable is typically used in the @code{hosts-file} field of an
7313a52e
LC
5192@code{operating-system} declaration (@pxref{operating-system Reference,
5193@file{/etc/hosts}}):
fa0c1d61
LC
5194
5195@example
5196(use-modules (gnu) (guix))
5197
5198(operating-system
5199 (host-name "mymachine")
5200 ;; ...
5201 (hosts-file
5202 ;; Create a /etc/hosts file with aliases for "localhost"
5203 ;; and "mymachine", as well as for Facebook servers.
5204 (text-file "hosts"
5205 (string-append (local-host-aliases host-name)
5206 %facebook-host-aliases))))
5207@end example
5208
5209This mechanism can prevent programs running locally, such as Web
5210browsers, from accessing Facebook.
5211@end defvr
5212
965a7332
LC
5213The @code{(gnu services avahi)} provides the following definition.
5214
5215@deffn {Monadic Procedure} avahi-service [#:avahi @var{avahi}] @
5216 [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @
5217 [#:ipv6? #t] [#:wide-area? #f] @
5218 [#:domains-to-browse '()]
5219Return a service that runs @command{avahi-daemon}, a system-wide
5220mDNS/DNS-SD responder that allows for service discovery and
5221"zero-configuration" host name lookups (see @uref{http://avahi.org/}).
5222
5223If @var{host-name} is different from @code{#f}, use that as the host name to
5224publish for this machine; otherwise, use the machine's actual host name.
5225
5226When @var{publish?} is true, publishing of host names and services is allowed;
5227in particular, avahi-daemon will publish the machine's host name and IP
5228address via mDNS on the local network.
5229
5230When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
5231
5232Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6
5233sockets.
5234@end deffn
5235
5236
cf4a9129
LC
5237@node X Window
5238@subsubsection X Window
68ad877c 5239
cf4a9129
LC
5240Support for the X Window graphical display system---specifically
5241Xorg---is provided by the @code{(gnu services xorg)} module. Note that
5242there is no @code{xorg-service} procedure. Instead, the X server is
5243started by the @dfn{login manager}, currently SLiM.
4af2447e 5244
cf4a9129 5245@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @
0ecc3bf3
LC
5246 [#:auto-login? #f] [#:default-user ""] [#:startx] @
5247 [#:theme @var{%default-slim-theme}] @
4bd43bbe 5248 [#:theme-name @var{%default-slim-theme-name}]
cf4a9129
LC
5249Return a service that spawns the SLiM graphical login manager, which in
5250turn starts the X display server with @var{startx}, a command as returned by
5251@code{xorg-start-command}.
4af2447e 5252
04e4e6ab
LC
5253@cindex X session
5254
5255SLiM automatically looks for session types described by the @file{.desktop}
5256files in @file{/run/current-system/profile/share/xsessions} and allows users
5257to choose a session from the log-in screen using @kbd{F1}. Packages such as
5258@var{xfce}, @var{sawfish}, and @var{ratpoison} provide @file{.desktop} files;
5259adding them to the system-wide set of packages automatically makes them
5260available at the log-in screen.
5261
5262In addition, @file{~/.xsession} files are honored. When available,
5263@file{~/.xsession} must be an executable that starts a window manager
5264and/or other X clients.
5265
cf4a9129
LC
5266When @var{allow-empty-passwords?} is true, allow logins with an empty
5267password. When @var{auto-login?} is true, log in automatically as
5268@var{default-user}.
0ecc3bf3
LC
5269
5270If @var{theme} is @code{#f}, the use the default log-in theme; otherwise
5271@var{theme} must be a gexp denoting the name of a directory containing the
5272theme to use. In that case, @var{theme-name} specifies the name of the
5273theme.
cf4a9129 5274@end deffn
4af2447e 5275
0ecc3bf3
LC
5276@defvr {Scheme Variable} %default-theme
5277@defvrx {Scheme Variable} %default-theme-name
5278The G-Expression denoting the default SLiM theme and its name.
5279@end defvr
5280
f703413e 5281@deffn {Monadic Procedure} xorg-start-command [#:guile] @
d1cdd7ba 5282 [#:configuration-file #f] [#:xorg-server @var{xorg-server}]
f703413e 5283Return a derivation that builds a @var{guile} script to start the X server
d1cdd7ba
LC
5284from @var{xorg-server}. @var{configuration-file} is the server configuration
5285file or a derivation that builds it; when omitted, the result of
5286@code{xorg-configuration-file} is used.
5287
5288Usually the X server is started by a login manager.
5289@end deffn
5290
5291@deffn {Monadic Procedure} xorg-configuration-file @
12422c9d 5292 [#:drivers '()] [#:resolutions '()] [#:extra-config '()]
d1cdd7ba
LC
5293Return a configuration file for the Xorg server containing search paths for
5294all the common drivers.
f703413e
LC
5295
5296@var{drivers} must be either the empty list, in which case Xorg chooses a
5297graphics driver automatically, or a list of driver names that will be tried in
d1cdd7ba 5298this order---e.g., @code{(\"modesetting\" \"vesa\")}.
d2e59637
LC
5299
5300Likewise, when @var{resolutions} is the empty list, Xorg chooses an
5301appropriate screen resolution; otherwise, it must be a list of
5302resolutions---e.g., @code{((1024 768) (640 480))}.
12422c9d
LC
5303
5304Last, @var{extra-config} is a list of strings or objects appended to the
5305@code{text-file*} argument list. It is used to pass extra text to be added
5306verbatim to the configuration file.
f703413e 5307@end deffn
4af2447e 5308
fe1a39d3
LC
5309@node Desktop Services
5310@subsubsection Desktop Services
aa4ed923 5311
fe1a39d3
LC
5312The @code{(gnu services desktop)} module provides services that are
5313usually useful in the context of a ``desktop'' setup---that is, on a
5314machine running a graphical display server, possibly with graphical user
5315interfaces, etc.
aa4ed923 5316
4467be21
LC
5317To simplify things, the module defines a variable containing the set of
5318services that users typically expect on a machine with a graphical
5319environment and networking:
5320
5321@defvr {Scheme Variable} %desktop-services
5322This is a list of services that builds upon @var{%base-services} and
5323adds or adjust services for a typical ``desktop'' setup.
5324
5325In particular, it adds a graphical login manager (@pxref{X Window,
5326@code{slim-service}}), a network management tool (@pxref{Networking
5327Services, @code{wicd-service}}), energy and color management services,
5328an NTP client and an SSH server (@pxref{Networking Services}), the Avahi
5329daemon, and has the name service switch service configured to be able to
5330use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
5331@end defvr
5332
5333The @var{%desktop-services} variable can be used as the @code{services}
5334field of an @code{operating-system} declaration (@pxref{operating-system
5335Reference, @code{services}}).
5336
5337The actual service definitions provided by @code{(gnu services desktop)}
5338are described below.
5339
fe1a39d3
LC
5340@deffn {Monadic Procedure} dbus-service @var{services} @
5341 [#:dbus @var{dbus}]
5342Return a service that runs the ``system bus'', using @var{dbus}, with
5343support for @var{services}.
aa4ed923 5344
fe1a39d3
LC
5345@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
5346facility. Its system bus is used to allow system services to communicate
5347and be notified of system-wide events.
aa4ed923 5348
fe1a39d3
LC
5349@var{services} must be a list of packages that provide an
5350@file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
5351and policy files. For example, to allow avahi-daemon to use the system bus,
5352@var{services} must be equal to @code{(list avahi)}.
aa4ed923
AK
5353@end deffn
5354
be234128
AW
5355@deffn {Monadic Procedure} upower-service [#:upower @var{upower}] @
5356 [#:watts-up-pro? #f] @
5357 [#:poll-batteries? #t] @
5358 [#:ignore-lid? #f] @
5359 [#:use-percentage-for-policy? #f] @
5360 [#:percentage-low 10] @
5361 [#:percentage-critical 3] @
5362 [#:percentage-action 2] @
5363 [#:time-low 1200] @
5364 [#:time-critical 300] @
5365 [#:time-action 120] @
5366 [#:critical-power-action 'hybrid-sleep]
5367Return a service that runs @uref{http://upower.freedesktop.org/,
5368@command{upowerd}}, a system-wide monitor for power consumption and battery
5369levels, with the given configuration settings. It implements the
5370@code{org.freedesktop.UPower} D-Bus interface, and is notably used by
5371GNOME.
5372@end deffn
5373
7ce597ff
AW
5374@deffn {Monadic Procedure} colord-service [#:colord @var{colord}]
5375Return a service that runs @command{colord}, a system service with a D-Bus
5376interface to manage the color profiles of input and output devices such as
5377screens and scanners. It is notably used by the GNOME Color Manager graphical
5378tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
5379site} for more information.
5380@end deffn
5381
105369a4
DT
5382@node Database Services
5383@subsubsection Database Services
5384
5385The @code{(gnu services databases)} module provides the following service.
5386
5387@deffn {Monadic Procedure} postgresql-service [#:postgresql postgresql] @
5388 [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']
5389Return a service that runs @var{postgresql}, the PostgreSQL database
5390server.
5391
5392The PostgreSQL daemon loads its runtime configuration from
5393@var{config-file} and stores the database cluster in
5394@var{data-directory}.
5395@end deffn
fe1a39d3
LC
5396
5397@node Various Services
5398@subsubsection Various Services
5399
5400The @code{(gnu services lirc)} module provides the following service.
5401
5402@deffn {Monadic Procedure} lirc-service [#:lirc lirc] @
5403 [#:device #f] [#:driver #f] [#:config-file #f] @
5404 [#:extra-options '()]
5405Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
5406decodes infrared signals from remote controls.
5407
5408Optionally, @var{device}, @var{driver} and @var{config-file}
5409(configuration file name) may be specified. See @command{lircd} manual
5410for details.
5411
5412Finally, @var{extra-options} is a list of additional command-line options
5413passed to @command{lircd}.
5414@end deffn
5415
5416
0ae8c15a
LC
5417@node Setuid Programs
5418@subsection Setuid Programs
5419
5420@cindex setuid programs
5421Some programs need to run with ``root'' privileges, even when they are
5422launched by unprivileged users. A notorious example is the
5423@command{passwd} programs, which can users can run to change their
5424password, and which requires write access to the @file{/etc/passwd} and
5425@file{/etc/shadow} files---something normally restricted to root, for
5426obvious security reasons. To address that, these executables are
5427@dfn{setuid-root}, meaning that they always run with root privileges
5428(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
5429for more info about the setuid mechanisms.)
5430
5431The store itself @emph{cannot} contain setuid programs: that would be a
5432security issue since any user on the system can write derivations that
5433populate the store (@pxref{The Store}). Thus, a different mechanism is
5434used: instead of changing the setuid bit directly on files that are in
5435the store, we let the system administrator @emph{declare} which programs
5436should be setuid root.
5437
5438The @code{setuid-programs} field of an @code{operating-system}
5439declaration contains a list of G-expressions denoting the names of
5440programs to be setuid-root (@pxref{Using the Configuration System}).
5441For instance, the @command{passwd} program, which is part of the Shadow
5442package, can be designated by this G-expression (@pxref{G-Expressions}):
5443
5444@example
5445#~(string-append #$shadow "/bin/passwd")
5446@end example
5447
5448A default set of setuid programs is defined by the
5449@code{%setuid-programs} variable of the @code{(gnu system)} module.
5450
5451@defvr {Scheme Variable} %setuid-programs
5452A list of G-expressions denoting common programs that are setuid-root.
5453
5454The list includes commands such as @command{passwd}, @command{ping},
5455@command{su}, and @command{sudo}.
5456@end defvr
5457
5458Under the hood, the actual setuid programs are created in the
5459@file{/run/setuid-programs} directory at system activation time. The
5460files in this directory refer to the ``real'' binaries, which are in the
5461store.
5462
efb5e833
LC
5463@node X.509 Certificates
5464@subsection X.509 Certificates
5465
5466@cindex HTTPS, certificates
5467@cindex X.509 certificates
5468@cindex TLS
5469Web servers available over HTTPS (that is, HTTP over the transport-layer
5470security mechanism, TLS) send client programs an @dfn{X.509 certificate}
5471that the client can then use to @emph{authenticate} the server. To do
5472that, clients verify that the server's certificate is signed by a
5473so-called @dfn{certificate authority} (CA). But to verify the CA's
5474signature, clients must have first acquired the CA's certificate.
5475
5476Web browsers such as GNU@tie{}IceCat include their own set of CA
5477certificates, such that they are able to verify CA signatures
5478out-of-the-box.
5479
5480However, most other programs that can talk HTTPS---@command{wget},
5481@command{git}, @command{w3m}, etc.---need to be told where CA
5482certificates can be found.
5483
5484@cindex @code{nss-certs}
5485In GuixSD, this is done by adding a package that provides certificates
5486to the @code{packages} field of the @code{operating-system} declaration
5487(@pxref{operating-system Reference}). GuixSD includes one such package,
5488@code{nss-certs}, which is a set of CA certificates provided as part of
5489Mozilla's Network Security Services.
5490
5491Note that it is @emph{not} part of @var{%base-packages}, so you need to
5492explicitly add it. The @file{/etc/ssl/certs} directory, which is where
5493most applications and libraries look for certificates by default, points
5494to the certificates installed globally.
5495
5496Unprivileged users can also install their own certificate package in
5497their profile. A number of environment variables need to be defined so
5498that applications and libraries know where to find them. Namely, the
5499OpenSSL library honors the @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE}
5500variables. Some applications add their own environment variables; for
5501instance, the Git version control system honors the certificate bundle
5502pointed to by the @code{GIT_SSL_CAINFO} environment variable.
5503
5504
996ed739
LC
5505@node Name Service Switch
5506@subsection Name Service Switch
5507
5508@cindex name service switch
5509@cindex NSS
5510The @code{(gnu system nss)} module provides bindings to the
5511configuration file of libc's @dfn{name service switch} or @dfn{NSS}
5512(@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
5513Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
5514extended with new ``name'' lookup methods for system databases, which
5515includes host names, service names, user accounts, and more (@pxref{Name
5516Service Switch, System Databases and Name Service Switch,, libc, The GNU
5517C Library Reference Manual}).
5518
5519The NSS configuration specifies, for each system database, which lookup
5520method is to be used, and how the various methods are chained
5521together---for instance, under which circumstances NSS should try the
5522next method in the list. The NSS configuration is given in the
5523@code{name-service-switch} field of @code{operating-system} declarations
5524(@pxref{operating-system Reference, @code{name-service-switch}}).
5525
4c9050c6
LC
5526@cindex nss-mdns
5527@cindex .local, host name lookup
996ed739 5528As an example, the declaration below configures the NSS to use the
4c9050c6
LC
5529@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
5530back-end}, which supports host name lookups over multicast DNS (mDNS)
5531for host names ending in @code{.local}:
996ed739
LC
5532
5533@example
5534(name-service-switch
5535 (hosts (list %files ;first, check /etc/hosts
5536
5537 ;; If the above did not succeed, try
5538 ;; with 'mdns_minimal'.
5539 (name-service
5540 (name "mdns_minimal")
5541
5542 ;; 'mdns_minimal' is authoritative for
5543 ;; '.local'. When it returns "not found",
5544 ;; no need to try the next methods.
5545 (reaction (lookup-specification
5546 (not-found => return))))
5547
5548 ;; Then fall back to DNS.
5549 (name-service
5550 (name "dns"))
5551
5552 ;; Finally, try with the "full" 'mdns'.
5553 (name-service
5554 (name "mdns")))))
5555@end example
5556
15137a29
LC
5557Don't worry: the @code{%mdns-host-lookup-nss} variable (see below)
5558contains this configuration, so you won't have to type it if all you
5559want is to have @code{.local} host lookup working.
5560
4c9050c6
LC
5561Note that, in this case, in addition to setting the
5562@code{name-service-switch} of the @code{operating-system} declaration,
5563@code{nscd-service} must be told where to find the @code{nss-mdns}
5564shared library (@pxref{Base Services, @code{nscd-service}}). Since the
5565@code{nscd} service is part of @var{%base-services}, you may want to
5566customize it by adding this snippet in the operating system
5567configuration file:
5568
5569@example
5570(use-modules (guix) (gnu))
5571
5572(define %my-base-services
5573 ;; Replace the default nscd service with one that knows
5574 ;; about nss-mdns.
5575 (map (lambda (mservice)
5576 ;; "Bind" the MSERVICE monadic value to inspect it.
5577 (mlet %store-monad ((service mservice))
5578 (if (member 'nscd (service-provision service))
5579 (nscd-service (nscd-configuration)
5580 #:name-services (list nss-mdns))
5581 mservice)))
5582 %base-services))
5583@end example
5584
5585@noindent
5586@dots{} and then refer to @var{%my-base-services} instead of
5587@var{%base-services} in the @code{operating-system} declaration.
15137a29 5588Lastly, this relies on the availability of the Avahi service
965a7332 5589(@pxref{Networking Services, @code{avahi-service}}).
15137a29
LC
5590
5591For convenience, the following variables provide typical NSS
5592configurations.
5593
5594@defvr {Scheme Variable} %default-nss
5595This is the default name service switch configuration, a
5596@code{name-service-switch} object.
5597@end defvr
5598
5599@defvr {Scheme Variable} %mdns-host-lookup-nss
5600This is the name service switch configuration with support for host name
5601lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
5602@end defvr
4c9050c6 5603
996ed739
LC
5604The reference for name service switch configuration is given below. It
5605is a direct mapping of the C library's configuration file format, so
5606please refer to the C library manual for more information (@pxref{NSS
5607Configuration File,,, libc, The GNU C Library Reference Manual}).
5608Compared to libc's NSS configuration file format, it has the advantage
5609not only of adding this warm parenthetic feel that we like, but also
5610static checks: you'll know about syntax errors and typos as soon as you
5611run @command{guix system}.
5612
996ed739
LC
5613@deftp {Data Type} name-service-switch
5614
5615This is the data type representation the configuration of libc's name
5616service switch (NSS). Each field below represents one of the supported
5617system databases.
5618
5619@table @code
5620@item aliases
5621@itemx ethers
5622@itemx group
5623@itemx gshadow
5624@itemx hosts
5625@itemx initgroups
5626@itemx netgroup
5627@itemx networks
5628@itemx password
5629@itemx public-key
5630@itemx rpc
5631@itemx services
5632@itemx shadow
5633The system databases handled by the NSS. Each of these fields must be a
5634list of @code{<name-service>} objects (see below.)
5635@end table
5636@end deftp
5637
5638@deftp {Data Type} name-service
5639
5640This is the data type representing an actual name service and the
5641associated lookup action.
5642
5643@table @code
5644@item name
5645A string denoting the name service (@pxref{Services in the NSS
5646configuration,,, libc, The GNU C Library Reference Manual}).
5647
4aee6e60
LC
5648Note that name services listed here must be visible to nscd. This is
5649achieved by passing the @code{#:name-services} argument to
5650@code{nscd-service} the list of packages providing the needed name
5651services (@pxref{Base Services, @code{nscd-service}}).
5652
996ed739
LC
5653@item reaction
5654An action specified using the @code{lookup-specification} macro
5655(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
5656Reference Manual}). For example:
5657
5658@example
5659(lookup-specification (unavailable => continue)
5660 (success => return))
5661@end example
5662@end table
5663@end deftp
0ae8c15a 5664
fd1b1fa2
LC
5665@node Initial RAM Disk
5666@subsection Initial RAM Disk
5667
5668@cindex initial RAM disk (initrd)
5669@cindex initrd (initial RAM disk)
5670For bootstrapping purposes, the Linux-Libre kernel is passed an
5671@dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
5672root file system, as well as an initialization script. The latter is
5673responsible for mounting the real root file system, and for loading any
5674kernel modules that may be needed to achieve that.
5675
5676The @code{initrd} field of an @code{operating-system} declaration allows
5677you to specify which initrd you would like to use. The @code{(gnu
5678system linux-initrd)} module provides two ways to build an initrd: the
5679high-level @code{base-initrd} procedure, and the low-level
5680@code{expression->initrd} procedure.
5681
5682The @code{base-initrd} procedure is intended to cover most common uses.
5683For example, if you want to add a bunch of kernel modules to be loaded
5684at boot time, you can define the @code{initrd} field of the operating
5685system declaration like this:
5686
5687@example
52ac153e 5688(initrd (lambda (file-systems . rest)
027981d6
LC
5689 ;; Create a standard initrd that has modules "foo.ko"
5690 ;; and "bar.ko", as well as their dependencies, in
5691 ;; addition to the modules available by default.
52ac153e 5692 (apply base-initrd file-systems
027981d6 5693 #:extra-modules '("foo" "bar")
52ac153e 5694 rest)))
fd1b1fa2
LC
5695@end example
5696
52ac153e
LC
5697The @code{base-initrd} procedure also handles common use cases that
5698involves using the system as a QEMU guest, or as a ``live'' system whose
5699root file system is volatile.
fd1b1fa2
LC
5700
5701@deffn {Monadic Procedure} base-initrd @var{file-systems} @
5702 [#:qemu-networking? #f] [#:virtio? #f] [#:volatile-root? #f] @
52ac153e 5703 [#:extra-modules '()] [#:mapped-devices '()]
fd1b1fa2
LC
5704Return a monadic derivation that builds a generic initrd. @var{file-systems} is
5705a list of file-systems to be mounted by the initrd, possibly in addition to
5706the root file system specified on the kernel command line via @code{--root}.
52ac153e
LC
5707@var{mapped-devices} is a list of device mappings to realize before
5708@var{file-systems} are mounted (@pxref{Mapped Devices}).
fd1b1fa2
LC
5709
5710When @var{qemu-networking?} is true, set up networking with the standard QEMU
5711parameters. When @var{virtio?} is true, load additional modules so the initrd can
5712be used as a QEMU guest with para-virtualized I/O drivers.
5713
5714When @var{volatile-root?} is true, the root file system is writable but any changes
5715to it are lost.
5716
5717The initrd is automatically populated with all the kernel modules necessary
5718for @var{file-systems} and for the given options. However, additional kernel
5719modules can be listed in @var{extra-modules}. They will be added to the initrd, and
5720loaded at boot time in the order in which they appear.
5721@end deffn
5722
5723Needless to say, the initrds we produce and use embed a
5724statically-linked Guile, and the initialization program is a Guile
5725program. That gives a lot of flexibility. The
5726@code{expression->initrd} procedure builds such an initrd, given the
5727program to run in that initrd.
5728
5729@deffn {Monadic Procedure} expression->initrd @var{exp} @
5730 [#:guile %guile-static-stripped] [#:name "guile-initrd"] @
42d10464 5731 [#:modules '()]
fd1b1fa2
LC
5732Return a derivation that builds a Linux initrd (a gzipped cpio archive)
5733containing @var{guile} and that evaluates @var{exp}, a G-expression,
df650fa8
LC
5734upon booting. All the derivations referenced by @var{exp} are
5735automatically copied to the initrd.
fd1b1fa2 5736
42d10464
LC
5737@var{modules} is a list of Guile module names to be embedded in the
5738initrd.
fd1b1fa2
LC
5739@end deffn
5740
88faf933
LC
5741@node GRUB Configuration
5742@subsection GRUB Configuration
5743
5744@cindex GRUB
5745@cindex boot loader
5746
5747The operating system uses GNU@tie{}GRUB as its boot loader
5748(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
5749configured using @code{grub-configuration} declarations. This data type
5750is exported by the @code{(gnu system grub)} module, and described below.
5751
5752@deftp {Data Type} grub-configuration
5753The type of a GRUB configuration declaration.
5754
5755@table @asis
5756
5757@item @code{device}
5758This is a string denoting the boot device. It must be a device name
5759understood by the @command{grub-install} command, such as
5760@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
5761GNU GRUB Manual}).
5762
5763@item @code{menu-entries} (default: @code{()})
5764A possibly empty list of @code{menu-entry} objects (see below), denoting
5765entries to appear in the GRUB boot menu, in addition to the current
5766system entry and the entry pointing to previous system generations.
5767
5768@item @code{default-entry} (default: @code{0})
5769The index of the default boot menu entry. Index 0 is for the current
5770system's entry.
5771
5772@item @code{timeout} (default: @code{5})
5773The number of seconds to wait for keyboard input before booting. Set to
57740 to boot immediately, and to -1 to wait indefinitely.
5775
5776@item @code{theme} (default: @var{%default-theme})
5777The @code{grub-theme} object describing the theme to use.
5778@end table
5779
5780@end deftp
5781
5782Should you want to list additional boot menu entries @i{via} the
5783@code{menu-entries} field above, you will need to create them with the
5784@code{menu-entry} form:
5785
5786@deftp {Data Type} menu-entry
5787The type of an entry in the GRUB boot menu.
5788
5789@table @asis
5790
5791@item @code{label}
35ed9306 5792The label to show in the menu---e.g., @code{"GNU"}.
88faf933
LC
5793
5794@item @code{linux}
5795The Linux kernel to boot.
5796
5797@item @code{linux-arguments} (default: @code{()})
5798The list of extra Linux kernel command-line arguments---e.g.,
5799@code{("console=ttyS0")}.
5800
5801@item @code{initrd}
5802A G-Expression or string denoting the file name of the initial RAM disk
5803to use (@pxref{G-Expressions}).
5804
5805@end table
5806@end deftp
5807
5808@c FIXME: Write documentation once it's stable.
5809Themes are created using the @code{grub-theme} form, which is not
5810documented yet.
5811
5812@defvr {Scheme Variable} %default-theme
5813This is the default GRUB theme used by the operating system, with a
5814fancy background image displaying the GNU and Guix logos.
5815@end defvr
5816
5817
cf4a9129
LC
5818@node Invoking guix system
5819@subsection Invoking @code{guix system}
0918e64a 5820
cf4a9129
LC
5821Once you have written an operating system declaration, as seen in the
5822previous section, it can be @dfn{instantiated} using the @command{guix
5823system} command. The synopsis is:
4af2447e 5824
cf4a9129
LC
5825@example
5826guix system @var{options}@dots{} @var{action} @var{file}
5827@end example
4af2447e 5828
cf4a9129
LC
5829@var{file} must be the name of a file containing an
5830@code{operating-system} declaration. @var{action} specifies how the
5831operating system is instantiate. Currently the following values are
5832supported:
4af2447e 5833
cf4a9129
LC
5834@table @code
5835@item reconfigure
5836Build the operating system described in @var{file}, activate it, and
5837switch to it@footnote{This action is usable only on systems already
5838running GNU.}.
4af2447e 5839
cf4a9129
LC
5840This effects all the configuration specified in @var{file}: user
5841accounts, system services, global package list, setuid programs, etc.
4af2447e 5842
cf4a9129
LC
5843It also adds a GRUB menu entry for the new OS configuration, and moves
5844entries for older configurations to a submenu---unless
5845@option{--no-grub} is passed.
4af2447e 5846
bf2479c7
LC
5847@c The paragraph below refers to the problem discussed at
5848@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
5849It is highly recommended to run @command{guix pull} once before you run
5850@command{guix system reconfigure} for the first time (@pxref{Invoking
5851guix pull}). Failing to do that you would see an older version of Guix
5852once @command{reconfigure} has completed.
5853
cf4a9129
LC
5854@item build
5855Build the operating system's derivation, which includes all the
5856configuration files and programs needed to boot and run the system.
5857This action does not actually install anything.
113daf62 5858
cf4a9129
LC
5859@item init
5860Populate the given directory with all the files necessary to run the
5861operating system specified in @var{file}. This is useful for first-time
4705641f 5862installations of GuixSD. For instance:
113daf62
LC
5863
5864@example
cf4a9129 5865guix system init my-os-config.scm /mnt
113daf62
LC
5866@end example
5867
cf4a9129
LC
5868copies to @file{/mnt} all the store items required by the configuration
5869specified in @file{my-os-config.scm}. This includes configuration
5870files, packages, and so on. It also creates other essential files
5871needed for the system to operate correctly---e.g., the @file{/etc},
5872@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
113daf62 5873
cf4a9129
LC
5874This command also installs GRUB on the device specified in
5875@file{my-os-config}, unless the @option{--no-grub} option was passed.
113daf62 5876
cf4a9129
LC
5877@item vm
5878@cindex virtual machine
0276f697 5879@cindex VM
cf4a9129
LC
5880Build a virtual machine that contain the operating system declared in
5881@var{file}, and return a script to run that virtual machine (VM).
810568b3 5882Arguments given to the script are passed as is to QEMU.
113daf62 5883
cf4a9129 5884The VM shares its store with the host system.
113daf62 5885
0276f697
LC
5886Additional file systems can be shared between the host and the VM using
5887the @code{--share} and @code{--expose} command-line options: the former
5888specifies a directory to be shared with write access, while the latter
5889provides read-only access to the shared directory.
5890
5891The example below creates a VM in which the user's home directory is
5892accessible read-only, and where the @file{/exchange} directory is a
5893read-write mapping of the host's @file{$HOME/tmp}:
5894
5895@example
5896guix system vm my-config.scm \
5897 --expose=$HOME --share=$HOME/tmp=/exchange
5898@end example
5899
6aa260af
LC
5900On GNU/Linux, the default is to boot directly to the kernel; this has
5901the advantage of requiring only a very tiny root disk image since the
5902host's store can then be mounted.
5903
5904The @code{--full-boot} option forces a complete boot sequence, starting
5905with the bootloader. This requires more disk space since a root image
5906containing at least the kernel, initrd, and bootloader data files must
5907be created. The @code{--image-size} option can be used to specify the
5908image's size.
ab11f0be 5909
cf4a9129
LC
5910@item vm-image
5911@itemx disk-image
5912Return a virtual machine or disk image of the operating system declared
5913in @var{file} that stands alone. Use the @option{--image-size} option
5914to specify the size of the image.
113daf62 5915
cf4a9129
LC
5916When using @code{vm-image}, the returned image is in qcow2 format, which
5917the QEMU emulator can efficiently use.
113daf62 5918
cf4a9129
LC
5919When using @code{disk-image}, a raw disk image is produced; it can be
5920copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is
5921the device corresponding to a USB stick, one can copy the image on it
5922using the following command:
113daf62 5923
cf4a9129
LC
5924@example
5925# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
5926@end example
113daf62 5927
cf4a9129 5928@end table
113daf62 5929
cf4a9129
LC
5930@var{options} can contain any of the common build options provided by
5931@command{guix build} (@pxref{Invoking guix build}). In addition,
5932@var{options} can contain one of the following:
113daf62 5933
cf4a9129
LC
5934@table @option
5935@item --system=@var{system}
5936@itemx -s @var{system}
5937Attempt to build for @var{system} instead of the host's system type.
5938This works as per @command{guix build} (@pxref{Invoking guix build}).
113daf62 5939
cf4a9129
LC
5940@item --image-size=@var{size}
5941For the @code{vm-image} and @code{disk-image} actions, create an image
5942of the given @var{size}. @var{size} may be a number of bytes, or it may
4a44d7bb
LC
5943include a unit as a suffix (@pxref{Block size, size specifications,,
5944coreutils, GNU Coreutils}).
113daf62 5945@end table
113daf62 5946
cf4a9129
LC
5947Note that all the actions above, except @code{build} and @code{init},
5948rely on KVM support in the Linux-Libre kernel. Specifically, the
5949machine should have hardware virtualization support, the corresponding
5950KVM kernel module should be loaded, and the @file{/dev/kvm} device node
5951must exist and be readable and writable by the user and by the daemon's
5952build users.
8451a568 5953
cf4a9129
LC
5954@node Defining Services
5955@subsection Defining Services
8451a568 5956
cf4a9129
LC
5957The @code{(gnu services @dots{})} modules define several procedures that allow
5958users to declare the operating system's services (@pxref{Using the
5959Configuration System}). These procedures are @emph{monadic
5960procedures}---i.e., procedures that return a monadic value in the store
5961monad (@pxref{The Store Monad}). For examples of such procedures,
5962@xref{Services}.
8451a568 5963
cf4a9129
LC
5964@cindex service definition
5965The monadic value returned by those procedures is a @dfn{service
5966definition}---a structure as returned by the @code{service} form.
5967Service definitions specifies the inputs the service depends on, and an
5968expression to start and stop the service. Behind the scenes, service
5969definitions are ``translated'' into the form suitable for the
5970configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU
5971dmd Manual}).
8451a568 5972
cf4a9129
LC
5973As an example, here is what the @code{nscd-service} procedure looks
5974like:
8451a568 5975
cf4a9129
LC
5976@lisp
5977(define (nscd-service)
5978 (with-monad %store-monad
5979 (return (service
5980 (documentation "Run libc's name service cache daemon.")
5981 (provision '(nscd))
5982 (activate #~(begin
5983 (use-modules (guix build utils))
5984 (mkdir-p "/var/run/nscd")))
5985 (start #~(make-forkexec-constructor
5986 (string-append #$glibc "/sbin/nscd")
5987 "-f" "/dev/null" "--foreground"))
5988 (stop #~(make-kill-destructor))
5989 (respawn? #f)))))
5990@end lisp
8451a568 5991
cf4a9129
LC
5992@noindent
5993The @code{activate}, @code{start}, and @code{stop} fields are G-expressions
5994(@pxref{G-Expressions}). The @code{activate} field contains a script to
5995run at ``activation'' time; it makes sure that the @file{/var/run/nscd}
5996directory exists before @command{nscd} is started.
8451a568 5997
cf4a9129
LC
5998The @code{start} and @code{stop} fields refer to dmd's facilities to
5999start and stop processes (@pxref{Service De- and Constructors,,, dmd,
6000GNU dmd Manual}). The @code{provision} field specifies the name under
6001which this service is known to dmd, and @code{documentation} specifies
6002on-line documentation. Thus, the commands @command{deco start ncsd},
6003@command{deco stop nscd}, and @command{deco doc nscd} will do what you
6004would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
8451a568 6005
8451a568 6006
cf4a9129
LC
6007@node Installing Debugging Files
6008@section Installing Debugging Files
8451a568 6009
cf4a9129
LC
6010@cindex debugging files
6011Program binaries, as produced by the GCC compilers for instance, are
6012typically written in the ELF format, with a section containing
6013@dfn{debugging information}. Debugging information is what allows the
6014debugger, GDB, to map binary code to source code; it is required to
6015debug a compiled program in good conditions.
8451a568 6016
cf4a9129
LC
6017The problem with debugging information is that is takes up a fair amount
6018of disk space. For example, debugging information for the GNU C Library
6019weighs in at more than 60 MiB. Thus, as a user, keeping all the
6020debugging info of all the installed programs is usually not an option.
6021Yet, space savings should not come at the cost of an impediment to
6022debugging---especially in the GNU system, which should make it easier
6023for users to exert their computing freedom (@pxref{GNU Distribution}).
8451a568 6024
cf4a9129
LC
6025Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
6026mechanism that allows users to get the best of both worlds: debugging
6027information can be stripped from the binaries and stored in separate
6028files. GDB is then able to load debugging information from those files,
6029when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
6030with GDB}).
8451a568 6031
cf4a9129
LC
6032The GNU distribution takes advantage of this by storing debugging
6033information in the @code{lib/debug} sub-directory of a separate package
6034output unimaginatively called @code{debug} (@pxref{Packages with
6035Multiple Outputs}). Users can choose to install the @code{debug} output
6036of a package when they need it. For instance, the following command
6037installs the debugging information for the GNU C Library and for GNU
6038Guile:
8451a568
LC
6039
6040@example
cf4a9129 6041guix package -i glibc:debug guile:debug
8451a568
LC
6042@end example
6043
cf4a9129
LC
6044GDB must then be told to look for debug files in the user's profile, by
6045setting the @code{debug-file-directory} variable (consider setting it
6046from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
6047GDB}):
8451a568 6048
cf4a9129
LC
6049@example
6050(gdb) set debug-file-directory ~/.guix-profile/lib/debug
6051@end example
8451a568 6052
cf4a9129
LC
6053From there on, GDB will pick up debugging information from the
6054@code{.debug} files under @file{~/.guix-profile/lib/debug}.
8451a568 6055
cf4a9129
LC
6056In addition, you will most likely want GDB to be able to show the source
6057code being debugged. To do that, you will have to unpack the source
6058code of the package of interest (obtained with @code{guix build
6059--source}, @pxref{Invoking guix build}), and to point GDB to that source
6060directory using the @code{directory} command (@pxref{Source Path,
6061@code{directory},, gdb, Debugging with GDB}).
8451a568 6062
cf4a9129
LC
6063@c XXX: keep me up-to-date
6064The @code{debug} output mechanism in Guix is implemented by the
6065@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
6066opt-in---debugging information is available only for those packages
6067whose definition explicitly declares a @code{debug} output. This may be
6068changed to opt-out in the future, if our build farm servers can handle
6069the load. To check whether a package has a @code{debug} output, use
6070@command{guix package --list-available} (@pxref{Invoking guix package}).
8451a568 6071
8451a568 6072
05962f29
LC
6073@node Security Updates
6074@section Security Updates
6075
843858b8
LC
6076@quotation Note
6077As of version @value{VERSION}, the feature described in this section is
6078experimental.
6079@end quotation
05962f29
LC
6080
6081@cindex security updates
6082Occasionally, important security vulnerabilities are discovered in core
6083software packages and must be patched. Guix follows a functional
6084package management discipline (@pxref{Introduction}), which implies
6085that, when a package is changed, @emph{every package that depends on it}
6086must be rebuilt. This can significantly slow down the deployment of
6087fixes in core packages such as libc or Bash, since basically the whole
6088distribution would need to be rebuilt. Using pre-built binaries helps
6089(@pxref{Substitutes}), but deployment may still take more time than
6090desired.
6091
6092@cindex grafts
6093To address that, Guix implements @dfn{grafts}, a mechanism that allows
6094for fast deployment of critical updates without the costs associated
6095with a whole-distribution rebuild. The idea is to rebuild only the
6096package that needs to be patched, and then to ``graft'' it onto packages
6097explicitly installed by the user and that were previously referring to
6098the original package. The cost of grafting is typically very low, and
6099order of magnitudes lower than a full rebuild of the dependency chain.
6100
6101@cindex replacements of packages, for grafts
6102For instance, suppose a security update needs to be applied to Bash.
6103Guix developers will provide a package definition for the ``fixed''
6104Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
6105Packages}). Then, the original package definition is augmented with a
6106@code{replacement} field pointing to the package containing the bug fix:
6107
6108@example
6109(define bash
6110 (package
6111 (name "bash")
6112 ;; @dots{}
6113 (replacement bash-fixed)))
6114@end example
6115
6116From there on, any package depending directly or indirectly on Bash that
6117is installed will automatically be ``rewritten'' to refer to
6118@var{bash-fixed} instead of @var{bash}. This grafting process takes
6119time proportional to the size of the package, but expect less than a
6120minute for an ``average'' package on a recent machine.
6121
6122Currently, the graft and the package it replaces (@var{bash-fixed} and
6123@var{bash} in the example above) must have the exact same @code{name}
6124and @code{version} fields. This restriction mostly comes from the fact
6125that grafting works by patching files, including binary files, directly.
6126Other restrictions may apply: for instance, when adding a graft to a
6127package providing a shared library, the original shared library and its
6128replacement must have the same @code{SONAME} and be binary-compatible.
6129
6130
cf4a9129
LC
6131@node Package Modules
6132@section Package Modules
8451a568 6133
cf4a9129
LC
6134From a programming viewpoint, the package definitions of the
6135GNU distribution are provided by Guile modules in the @code{(gnu packages
6136@dots{})} name space@footnote{Note that packages under the @code{(gnu
6137packages @dots{})} module name space are not necessarily ``GNU
6138packages''. This module naming scheme follows the usual Guile module
6139naming convention: @code{gnu} means that these modules are distributed
6140as part of the GNU system, and @code{packages} identifies modules that
6141define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
6142Reference Manual}). For instance, the @code{(gnu packages emacs)}
6143module exports a variable named @code{emacs}, which is bound to a
6144@code{<package>} object (@pxref{Defining Packages}).
113daf62 6145
300868ba 6146The @code{(gnu packages @dots{})} module name space is
cf4a9129
LC
6147automatically scanned for packages by the command-line tools. For
6148instance, when running @code{guix package -i emacs}, all the @code{(gnu
6149packages @dots{})} modules are scanned until one that exports a package
6150object whose name is @code{emacs} is found. This package search
6151facility is implemented in the @code{(gnu packages)} module.
113daf62 6152
300868ba 6153@cindex customization, of packages
8689901f 6154@cindex package module search path
cf4a9129 6155Users can store package definitions in modules with different
60142854
LC
6156names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
6157name and module name must match. @xref{Modules and the File System,,,
6158guile, GNU Guile Reference Manual}, for details.} These package definitions
300868ba
LC
6159will not be visible by default. Thus, users can invoke commands such as
6160@command{guix package} and @command{guix build} have to be used with the
6161@code{-e} option so that they know where to find the package, or use the
6162@code{-L} option of these commands to make those modules visible
8689901f
LC
6163(@pxref{Invoking guix build, @code{--load-path}}), or define the
6164@code{GUIX_PACKAGE_PATH} environment variable. This environment
6165variable makes it easy to extend or customize the distribution and is
6166honored by all the user interfaces.
6167
6168@defvr {Environment Variable} GUIX_PACKAGE_PATH
6169This is a colon-separated list of directories to search for package
6170modules. Directories listed in this variable take precedence over the
6171distribution's own modules.
6172@end defvr
ef5dd60a 6173
cf4a9129
LC
6174The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
6175each package is built based solely on other packages in the
6176distribution. The root of this dependency graph is a small set of
6177@dfn{bootstrap binaries}, provided by the @code{(gnu packages
6178bootstrap)} module. For more information on bootstrapping,
081145cf 6179@pxref{Bootstrapping}.
ef5dd60a 6180
cf4a9129
LC
6181@node Packaging Guidelines
6182@section Packaging Guidelines
ef5dd60a 6183
cf4a9129
LC
6184The GNU distribution is nascent and may well lack some of your favorite
6185packages. This section describes how you can help make the distribution
6186grow. @xref{Contributing}, for additional information on how you can
6187help.
ef5dd60a 6188
cf4a9129
LC
6189Free software packages are usually distributed in the form of
6190@dfn{source code tarballs}---typically @file{tar.gz} files that contain
6191all the source files. Adding a package to the distribution means
6192essentially two things: adding a @dfn{recipe} that describes how to
6193build the package, including a list of other packages required to build
6194it, and adding @dfn{package meta-data} along with that recipe, such as a
6195description and licensing information.
ef5dd60a 6196
cf4a9129
LC
6197In Guix all this information is embodied in @dfn{package definitions}.
6198Package definitions provide a high-level view of the package. They are
6199written using the syntax of the Scheme programming language; in fact,
6200for each package we define a variable bound to the package definition,
6201and export that variable from a module (@pxref{Package Modules}).
6202However, in-depth Scheme knowledge is @emph{not} a prerequisite for
6203creating packages. For more information on package definitions,
081145cf 6204@pxref{Defining Packages}.
ef5dd60a 6205
cf4a9129
LC
6206Once a package definition is in place, stored in a file in the Guix
6207source tree, it can be tested using the @command{guix build} command
6208(@pxref{Invoking guix build}). For example, assuming the new package is
6209called @code{gnew}, you may run this command from the Guix build tree:
ef5dd60a
LC
6210
6211@example
cf4a9129 6212./pre-inst-env guix build gnew --keep-failed
ef5dd60a 6213@end example
ef5dd60a 6214
cf4a9129
LC
6215Using @code{--keep-failed} makes it easier to debug build failures since
6216it provides access to the failed build tree. Another useful
6217command-line option when debugging is @code{--log-file}, to access the
6218build log.
ef5dd60a 6219
cf4a9129
LC
6220If the package is unknown to the @command{guix} command, it may be that
6221the source file contains a syntax error, or lacks a @code{define-public}
6222clause to export the package variable. To figure it out, you may load
6223the module from Guile to get more information about the actual error:
ef5dd60a 6224
cf4a9129
LC
6225@example
6226./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
6227@end example
ef5dd60a 6228
cf4a9129
LC
6229Once your package builds correctly, please send us a patch
6230(@pxref{Contributing}). Well, if you need help, we will be happy to
6231help you too. Once the patch is committed in the Guix repository, the
6232new package automatically gets built on the supported platforms by
2b1cee21 6233@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
cf4a9129 6234system}.
ef5dd60a 6235
cf4a9129
LC
6236@cindex substituter
6237Users can obtain the new package definition simply by running
6238@command{guix pull} (@pxref{Invoking guix pull}). When
6239@code{hydra.gnu.org} is done building the package, installing the
6240package automatically downloads binaries from there
6241(@pxref{Substitutes}). The only place where human intervention is
6242needed is to review and apply the patch.
ef5dd60a 6243
ef5dd60a 6244
cf4a9129 6245@menu
ec0339cd
LC
6246* Software Freedom:: What may go into the distribution.
6247* Package Naming:: What's in a name?
6248* Version Numbers:: When the name is not enough.
6249* Python Modules:: Taming the snake.
6250* Perl Modules:: Little pearls.
6251* Fonts:: Fond of fonts.
cf4a9129 6252@end menu
ef5dd60a 6253
cf4a9129
LC
6254@node Software Freedom
6255@subsection Software Freedom
ef5dd60a 6256
cf4a9129 6257@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
c11a6eb1 6258
cf4a9129
LC
6259The GNU operating system has been developed so that users can have
6260freedom in their computing. GNU is @dfn{free software}, meaning that
6261users have the @url{http://www.gnu.org/philosophy/free-sw.html,four
6262essential freedoms}: to run the program, to study and change the program
6263in source code form, to redistribute exact copies, and to distribute
6264modified versions. Packages found in the GNU distribution provide only
6265software that conveys these four freedoms.
c11a6eb1 6266
cf4a9129
LC
6267In addition, the GNU distribution follow the
6268@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
6269software distribution guidelines}. Among other things, these guidelines
6270reject non-free firmware, recommendations of non-free software, and
6271discuss ways to deal with trademarks and patents.
ef5dd60a 6272
cf4a9129
LC
6273Some packages contain a small and optional subset that violates the
6274above guidelines, for instance because this subset is itself non-free
6275code. When that happens, the offending items are removed with
6276appropriate patches or code snippets in the package definition's
6277@code{origin} form (@pxref{Defining Packages}). That way, @code{guix
6278build --source} returns the ``freed'' source rather than the unmodified
6279upstream source.
ef5dd60a 6280
ef5dd60a 6281
cf4a9129
LC
6282@node Package Naming
6283@subsection Package Naming
ef5dd60a 6284
cf4a9129
LC
6285A package has actually two names associated with it:
6286First, there is the name of the @emph{Scheme variable}, the one following
6287@code{define-public}. By this name, the package can be made known in the
6288Scheme code, for instance as input to another package. Second, there is
6289the string in the @code{name} field of a package definition. This name
6290is used by package management commands such as
6291@command{guix package} and @command{guix build}.
ef5dd60a 6292
cf4a9129
LC
6293Both are usually the same and correspond to the lowercase conversion of
6294the project name chosen upstream, with underscores replaced with
6295hyphens. For instance, GNUnet is available as @code{gnunet}, and
6296SDL_net as @code{sdl-net}.
927097ef 6297
cf4a9129 6298We do not add @code{lib} prefixes for library packages, unless these are
081145cf 6299already part of the official project name. But @pxref{Python
cf4a9129
LC
6300Modules} and @ref{Perl Modules} for special rules concerning modules for
6301the Python and Perl languages.
927097ef 6302
1b366ee4 6303Font package names are handled differently, @pxref{Fonts}.
7fec52b7 6304
ef5dd60a 6305
cf4a9129
LC
6306@node Version Numbers
6307@subsection Version Numbers
ef5dd60a 6308
cf4a9129
LC
6309We usually package only the latest version of a given free software
6310project. But sometimes, for instance for incompatible library versions,
6311two (or more) versions of the same package are needed. These require
6312different Scheme variable names. We use the name as defined
6313in @ref{Package Naming}
6314for the most recent version; previous versions use the same name, suffixed
6315by @code{-} and the smallest prefix of the version number that may
6316distinguish the two versions.
ef5dd60a 6317
cf4a9129
LC
6318The name inside the package definition is the same for all versions of a
6319package and does not contain any version number.
ef5dd60a 6320
cf4a9129 6321For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows:
ef5dd60a 6322
cf4a9129
LC
6323@example
6324(define-public gtk+
6325 (package
6326 (name "gtk+")
6327 (version "3.9.12")
6328 ...))
6329(define-public gtk+-2
6330 (package
6331 (name "gtk+")
6332 (version "2.24.20")
6333 ...))
6334@end example
6335If we also wanted GTK+ 3.8.2, this would be packaged as
6336@example
6337(define-public gtk+-3.8
6338 (package
6339 (name "gtk+")
6340 (version "3.8.2")
6341 ...))
6342@end example
ef5dd60a 6343
ef5dd60a 6344
cf4a9129
LC
6345@node Python Modules
6346@subsection Python Modules
ef5dd60a 6347
cf4a9129
LC
6348We currently package Python 2 and Python 3, under the Scheme variable names
6349@code{python-2} and @code{python} as explained in @ref{Version Numbers}.
6350To avoid confusion and naming clashes with other programming languages, it
6351seems desirable that the name of a package for a Python module contains
6352the word @code{python}.
ef5dd60a 6353
cf4a9129
LC
6354Some modules are compatible with only one version of Python, others with both.
6355If the package Foo compiles only with Python 3, we name it
6356@code{python-foo}; if it compiles only with Python 2, we name it
6357@code{python2-foo}. If it is compatible with both versions, we create two
6358packages with the corresponding names.
ef5dd60a 6359
cf4a9129
LC
6360If a project already contains the word @code{python}, we drop this;
6361for instance, the module python-dateutil is packaged under the names
6362@code{python-dateutil} and @code{python2-dateutil}.
113daf62 6363
523e4896 6364
cf4a9129
LC
6365@node Perl Modules
6366@subsection Perl Modules
523e4896 6367
cf4a9129
LC
6368Perl programs standing for themselves are named as any other package,
6369using the lowercase upstream name.
6370For Perl packages containing a single class, we use the lowercase class name,
6371replace all occurrences of @code{::} by dashes and prepend the prefix
6372@code{perl-}.
6373So the class @code{XML::Parser} becomes @code{perl-xml-parser}.
6374Modules containing several classes keep their lowercase upstream name and
6375are also prepended by @code{perl-}. Such modules tend to have the word
6376@code{perl} somewhere in their name, which gets dropped in favor of the
6377prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}.
523e4896 6378
523e4896 6379
7fec52b7
AE
6380@node Fonts
6381@subsection Fonts
6382
6383For fonts that are in general not installed by a user for typesetting
6384purposes, or that are distributed as part of a larger software package,
6385we rely on the general packaging rules for software; for instance, this
6386applies to the fonts delivered as part of the X.Org system or fonts that
6387are part of TeX Live.
6388
6389To make it easier for a user to search for fonts, names for other packages
6390containing only fonts are constructed as follows, independently of the
6391upstream package name.
6392
6393The name of a package containing only one font family starts with
6394@code{font-}; it is followed by the foundry name and a dash @code{-}
6395if the foundry is known, and the font family name, in which spaces are
6396replaced by dashes (and as usual, all upper case letters are transformed
6397to lower case).
6398For example, the Gentium font family by SIL is packaged under the name
6399@code{font-sil-gentium}.
6400
6401For a package containing several font families, the name of the collection
6402is used in the place of the font family name.
6403For instance, the Liberation fonts consist of three families,
6404Liberation Sans, Liberation Serif and Liberation Mono.
6405These could be packaged separately under the names
6406@code{font-liberation-sans} and so on; but as they are distributed together
6407under a common name, we prefer to package them together as
6408@code{font-liberation}.
6409
6410In the case where several formats of the same font family or font collection
6411are packaged separately, a short form of the format, prepended by a dash,
6412is added to the package name. We use @code{-ttf} for TrueType fonts,
1b366ee4 6413@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
7fec52b7
AE
6414fonts.
6415
6416
b25937e3 6417
cf4a9129
LC
6418@node Bootstrapping
6419@section Bootstrapping
b25937e3 6420
cf4a9129 6421@c Adapted from the ELS 2013 paper.
b25937e3 6422
cf4a9129 6423@cindex bootstrapping
7889394e 6424
cf4a9129
LC
6425Bootstrapping in our context refers to how the distribution gets built
6426``from nothing''. Remember that the build environment of a derivation
6427contains nothing but its declared inputs (@pxref{Introduction}). So
6428there's an obvious chicken-and-egg problem: how does the first package
6429get built? How does the first compiler get compiled? Note that this is
6430a question of interest only to the curious hacker, not to the regular
6431user, so you can shamelessly skip this section if you consider yourself
6432a ``regular user''.
72b9d60d 6433
cf4a9129
LC
6434@cindex bootstrap binaries
6435The GNU system is primarily made of C code, with libc at its core. The
6436GNU build system itself assumes the availability of a Bourne shell and
6437command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
6438`grep'. Furthermore, build programs---programs that run
6439@code{./configure}, @code{make}, etc.---are written in Guile Scheme
6440(@pxref{Derivations}). Consequently, to be able to build anything at
6441all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
6442Binutils, libc, and the other packages mentioned above---the
6443@dfn{bootstrap binaries}.
72b9d60d 6444
cf4a9129
LC
6445These bootstrap binaries are ``taken for granted'', though we can also
6446re-create them if needed (more on that later).
72b9d60d 6447
cf4a9129 6448@unnumberedsubsec Preparing to Use the Bootstrap Binaries
c79d54fe 6449
cf4a9129
LC
6450@c As of Emacs 24.3, Info-mode displays the image, but since it's a
6451@c large image, it's hard to scroll. Oh well.
6452@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
523e4896 6453
cf4a9129
LC
6454The figure above shows the very beginning of the dependency graph of the
6455distribution, corresponding to the package definitions of the @code{(gnu
6456packages bootstrap)} module. At this level of detail, things are
6457slightly complex. First, Guile itself consists of an ELF executable,
6458along with many source and compiled Scheme files that are dynamically
6459loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
6460tarball shown in this graph. This tarball is part of Guix's ``source''
6461distribution, and gets inserted into the store with @code{add-to-store}
6462(@pxref{The Store}).
2e7b5cea 6463
cf4a9129
LC
6464But how do we write a derivation that unpacks this tarball and adds it
6465to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
6466derivation---the first one that gets built---uses @code{bash} as its
6467builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
6468@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
6469@file{xz}, and @file{mkdir} are statically-linked binaries, also part of
6470the Guix source distribution, whose sole purpose is to allow the Guile
6471tarball to be unpacked.
fb729425 6472
cf4a9129
LC
6473Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
6474Guile that can be used to run subsequent build programs. Its first task
6475is to download tarballs containing the other pre-built binaries---this
6476is what the @code{.tar.xz.drv} derivations do. Guix modules such as
6477@code{ftp-client.scm} are used for this purpose. The
6478@code{module-import.drv} derivations import those modules in a directory
6479in the store, using the original layout. The
6480@code{module-import-compiled.drv} derivations compile those modules, and
6481write them in an output directory with the right layout. This
6482corresponds to the @code{#:modules} argument of
6483@code{build-expression->derivation} (@pxref{Derivations}).
fb729425 6484
cf4a9129
LC
6485Finally, the various tarballs are unpacked by the
6486derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
6487etc., at which point we have a working C tool chain.
fb729425 6488
fb729425 6489
cf4a9129 6490@unnumberedsubsec Building the Build Tools
523e4896 6491
cf4a9129
LC
6492@c TODO: Add a package-level dependency graph generated from (gnu
6493@c packages base).
df2ce343 6494
cf4a9129
LC
6495Bootstrapping is complete when we have a full tool chain that does not
6496depend on the pre-built bootstrap tools discussed above. This
6497no-dependency requirement is verified by checking whether the files of
6498the final tool chain contain references to the @file{/gnu/store}
6499directories of the bootstrap inputs. The process that leads to this
6500``final'' tool chain is described by the package definitions found in
1f6f57df 6501the @code{(gnu packages commencement)} module.
df2ce343 6502
cf4a9129
LC
6503@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
6504The first tool that gets built with the bootstrap binaries is
6505GNU Make, which is a prerequisite for all the following packages.
6506From there Findutils and Diffutils get built.
523e4896 6507
cf4a9129
LC
6508Then come the first-stage Binutils and GCC, built as pseudo cross
6509tools---i.e., with @code{--target} equal to @code{--host}. They are
6510used to build libc. Thanks to this cross-build trick, this libc is
6511guaranteed not to hold any reference to the initial tool chain.
4af2447e 6512
cf4a9129
LC
6513From there the final Binutils and GCC are built. GCC uses @code{ld}
6514from the final Binutils, and links programs against the just-built libc.
6515This tool chain is used to build the other packages used by Guix and by
6516the GNU Build System: Guile, Bash, Coreutils, etc.
4af2447e 6517
cf4a9129
LC
6518And voilà! At this point we have the complete set of build tools that
6519the GNU Build System expects. These are in the @code{%final-inputs}
dd164244
MW
6520variable of the @code{(gnu packages commencement)} module, and are
6521implicitly used by any package that uses @code{gnu-build-system}
1f6f57df 6522(@pxref{Build Systems, @code{gnu-build-system}}).
4af2447e 6523
4af2447e 6524
cf4a9129 6525@unnumberedsubsec Building the Bootstrap Binaries
4af2447e 6526
cf4a9129
LC
6527Because the final tool chain does not depend on the bootstrap binaries,
6528those rarely need to be updated. Nevertheless, it is useful to have an
6529automated way to produce them, should an update occur, and this is what
6530the @code{(gnu packages make-bootstrap)} module provides.
4af2447e 6531
cf4a9129
LC
6532The following command builds the tarballs containing the bootstrap
6533binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
6534of Coreutils and other basic command-line tools):
4b2615e1 6535
cf4a9129
LC
6536@example
6537guix build bootstrap-tarballs
6538@end example
6539
6540The generated tarballs are those that should be referred to in the
6541@code{(gnu packages bootstrap)} module mentioned at the beginning of
6542this section.
6543
6544Still here? Then perhaps by now you've started to wonder: when do we
6545reach a fixed point? That is an interesting question! The answer is
6546unknown, but if you would like to investigate further (and have
6547significant computational and storage resources to do so), then let us
6548know.
6549
6550@node Porting
6551@section Porting to a New Platform
6552
6553As discussed above, the GNU distribution is self-contained, and
6554self-containment is achieved by relying on pre-built ``bootstrap
6555binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
6556operating system kernel, CPU architecture, and application binary
6557interface (ABI). Thus, to port the distribution to a platform that is
6558not yet supported, one must build those bootstrap binaries, and update
6559the @code{(gnu packages bootstrap)} module to use them on that platform.
6560
6561Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
6562When everything goes well, and assuming the GNU tool chain supports the
6563target platform, this can be as simple as running a command like this
6564one:
6565
6566@example
6567guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
6568@end example
6569
1c0c417d
LC
6570For this to work, the @code{glibc-dynamic-linker} procedure in
6571@code{(gnu packages bootstrap)} must be augmented to return the right
6572file name for libc's dynamic linker on that platform; likewise,
6573@code{system->linux-architecture} in @code{(gnu packages linux)} must be
6574taught about the new platform.
6575
cf4a9129 6576Once these are built, the @code{(gnu packages bootstrap)} module needs
1c0c417d
LC
6577to be updated to refer to these binaries on the target platform. That
6578is, the hashes and URLs of the bootstrap tarballs for the new platform
6579must be added alongside those of the currently supported platforms. The
6580bootstrap Guile tarball is treated specially: it is expected to be
6581available locally, and @file{gnu-system.am} has rules do download it for
6582the supported architectures; a rule for the new platform must be added
6583as well.
cf4a9129
LC
6584
6585In practice, there may be some complications. First, it may be that the
6586extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
6587above) is not recognized by all the GNU tools. Typically, glibc
6588recognizes some of these, whereas GCC uses an extra @code{--with-abi}
6589configure flag (see @code{gcc.scm} for examples of how to handle this).
6590Second, some of the required packages could fail to build for that
6591platform. Lastly, the generated binaries could be broken for some
6592reason.
4af2447e
LC
6593
6594
9bf3c1a7
LC
6595@c *********************************************************************
6596@node Contributing
6597@chapter Contributing
6598
6599This project is a cooperative effort, and we need your help to make it
5ff3c4b8
PAR
6600grow! Please get in touch with us on @email{guix-devel@@gnu.org} and
6601@code{#guix} on the Freenode IRC network. We welcome ideas, bug
6602reports, patches, and anything that may be helpful to the project. We
6603particularly welcome help on packaging (@pxref{Packaging Guidelines}).
a1ba8475 6604
9bf3c1a7
LC
6605Please see the
6606@url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING,
6607@file{HACKING} file} that comes with the Guix source code for practical
6608details about contributions.
6609
c78bd12b 6610
568717fd
LC
6611@c *********************************************************************
6612@node Acknowledgments
6613@chapter Acknowledgments
6614
6615Guix is based on the Nix package manager, which was designed and
4c7ac9aa
LC
6616implemented by Eelco Dolstra, with contributions from other people (see
6617the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
568717fd
LC
6618management, and promoted unprecedented features, such as transactional
6619package upgrades and rollbacks, per-user profiles, and referentially
6620transparent build processes. Without this work, Guix would not exist.
6621
6622The Nix-based software distributions, Nixpkgs and NixOS, have also been
6623an inspiration for Guix.
6624
4c7ac9aa
LC
6625GNU@tie{}Guix itself is a collective work with contributions from a
6626number of people. See the @file{AUTHORS} file in Guix for more
6627information on these fine people. The @file{THANKS} file lists people
6628who have helped by reporting bugs, taking care of the infrastructure,
6629providing artwork and themes, making suggestions, and more---thank you!
6630
6631
568717fd
LC
6632@c *********************************************************************
6633@node GNU Free Documentation License
6634@appendix GNU Free Documentation License
6635
6636@include fdl-1.3.texi
6637
6638@c *********************************************************************
6639@node Concept Index
6640@unnumbered Concept Index
6641@printindex cp
6642
a85b83d2
LC
6643@node Programming Index
6644@unnumbered Programming Index
6645@syncodeindex tp fn
6646@syncodeindex vr fn
568717fd
LC
6647@printindex fn
6648
6649@bye
6650
6651@c Local Variables:
6652@c ispell-local-dictionary: "american";
6653@c End: