/
guix.texi
11271 lines (9036 loc) · 429 KB
/
guix.texi
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
\input texinfo
@c -*-texinfo-*-
@c %**start of header
@setfilename guix.info
@documentencoding UTF-8
@settitle GNU Guix Reference Manual
@c %**end of header
@include version.texi
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016 Leo Famulari@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
copy of the license is included in the section entitled ``GNU Free
Documentation License''.
@end copying
@dircategory System administration
@direntry
* Guix: (guix). Manage installed software and system configuration.
* guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
* guix build: (guix)Invoking guix build. Building packages.
* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull. Update the list of available packages.
* guix system: (guix)Invoking guix system. Manage the operating system configuration.
@end direntry
@dircategory Software development
@direntry
* guix environment: (guix)Invoking guix environment. Building development environments with Guix.
@end direntry
@dircategory Emacs
@direntry
* Guix user interface: (guix)Emacs Interface. Package management from the comfort of Emacs.
@end direntry
@titlepage
@title GNU Guix Reference Manual
@subtitle Using the GNU Guix Functional Package Manager
@author The GNU Guix Developers
@page
@vskip 0pt plus 1filll
Edition @value{EDITION} @*
@value{UPDATED} @*
@insertcopying
@end titlepage
@contents
@c *********************************************************************
@node Top
@top GNU Guix
This document describes GNU Guix version @value{VERSION}, a functional
package management tool written for the GNU system.
@menu
* Introduction:: What is Guix about?
* Installation:: Installing Guix.
* Package Management:: Package installation, upgrade, etc.
* Emacs Interface:: Using Guix from Emacs.
* Programming Interface:: Using Guix in Scheme.
* Utilities:: Package management commands.
* GNU Distribution:: Software for your friendly GNU system.
* Contributing:: Your help needed!
* Acknowledgments:: Thanks!
* GNU Free Documentation License:: The license of this manual.
* Concept Index:: Concepts.
* Programming Index:: Data types, functions, and variables.
@detailmenu
--- The Detailed Node Listing ---
Installation
* Binary Installation:: Getting Guix running in no time!
* Requirements:: Software needed to build and run Guix.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
Setting Up the Daemon
* Build Environment Setup:: Preparing the isolated build environment.
* Daemon Offload Setup:: Offloading builds to remote machines.
Package Management
* Features:: How Guix will make your life brighter.
* Invoking guix package:: Package installation, removal, etc.
* Substitutes:: Downloading pre-built binaries.
* Packages with Multiple Outputs:: Single source package, multiple outputs.
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Invoking guix archive:: Exporting and importing store files.
Emacs Interface
* Initial Setup: Emacs Initial Setup. Preparing @file{~/.emacs}.
* Package Management: Emacs Package Management. Managing packages and generations.
* Licenses: Emacs Licenses. Interface for licenses of Guix packages.
* Popup Interface: Emacs Popup Interface. Magit-like interface for guix commands.
* Prettify Mode: Emacs Prettify. Abbreviating @file{/gnu/store/@dots{}} file names.
* Build Log Mode: Emacs Build Log. Highlighting Guix build logs.
* Completions: Emacs Completions. Completing @command{guix} shell command.
* Development: Emacs Development. Tools for Guix developers.
* Hydra: Emacs Hydra. Interface for Guix build farm.
Programming Interface
* Defining Packages:: Defining new packages.
* Build Systems:: Specifying how packages are built.
* The Store:: Manipulating the package store.
* Derivations:: Low-level interface to package derivations.
* The Store Monad:: Purely functional interface to the store.
* G-Expressions:: Manipulating build expressions.
Defining Packages
* package Reference:: The package data type.
* origin Reference:: The origin data type.
Utilities
* Invoking guix build:: Building packages from the command line.
* Invoking guix edit:: Editing package definitions.
* Invoking guix download:: Downloading a file and printing its hash.
* Invoking guix hash:: Computing the cryptographic hash of a file.
* Invoking guix import:: Importing package definitions.
* Invoking guix refresh:: Updating package definitions.
* Invoking guix lint:: Finding errors in package definitions.
* Invoking guix size:: Profiling disk usage.
* Invoking guix graph:: Visualizing the graph of packages.
* Invoking guix environment:: Setting up development environments.
* Invoking guix publish:: Sharing substitutes.
* Invoking guix challenge:: Challenging substitute servers.
* Invoking guix container:: Process isolation.
Invoking @command{guix build}
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
GNU Distribution
* System Installation:: Installing the whole operating system.
* System Configuration:: Configuring the operating system.
* Installing Debugging Files:: Feeding the debugger.
* Security Updates:: Deploying security fixes quickly.
* Package Modules:: Packages from the programmer's viewpoint.
* Packaging Guidelines:: Growing the distribution.
* Bootstrapping:: GNU/Linux built from scratch.
* Porting:: Targeting another platform or kernel.
System Installation
* Limitations:: What you can expect.
* Hardware Considerations:: Supported hardware.
* USB Stick Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
* Building the Installation Image:: How this comes to be.
System Configuration
* Using the Configuration System:: Customizing your GNU system.
* operating-system Reference:: Detail of operating-system declarations.
* File Systems:: Configuring file system mounts.
* Mapped Devices:: Block device extra processing.
* User Accounts:: Specifying user accounts.
* Locales:: Language and cultural convention settings.
* Services:: Specifying system services.
* Setuid Programs:: Programs running with root privileges.
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* GRUB Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions.
Services
* Base Services:: Essential system services.
* Networking Services:: Network setup, SSH daemon, etc.
* X Window:: Graphical display.
* Desktop Services:: D-Bus and desktop services.
* Database Services:: SQL databases.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Web Services:: Web servers.
* Various Services:: Other services.
Defining Services
* Service Composition:: The model for composing services.
* Service Types and Services:: Types and services.
* Service Reference:: API reference.
* Shepherd Services:: A particular type of service.
Packaging Guidelines
* Software Freedom:: What may go into the distribution.
* Package Naming:: What's in a name?
* Version Numbers:: When the name is not enough.
* Synopses and Descriptions:: Helping users find the right package.
* Python Modules:: Taming the snake.
* Perl Modules:: Little pearls.
* Fonts:: Fond of fonts.
Contributing
* Building from Git:: The latest and greatest.
* Running Guix Before It Is Installed:: Hacker tricks.
* The Perfect Setup:: The right tools.
* Coding Style:: Hygiene of the contributor.
* Submitting Patches:: Share your work.
Coding Style
* Programming Paradigm:: How to compose your elements.
* Modules:: Where to store your code?
* Data Types and Pattern Matching:: Implementing data structures.
* Formatting Code:: Writing conventions.
@end detailmenu
@end menu
@c *********************************************************************
@node Introduction
@chapter Introduction
@cindex purpose
GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
using the international phonetic alphabet (IPA).} is a package
management tool for the GNU system. Guix makes it easy for unprivileged
users to install, upgrade, or remove packages, to roll back to a
previous package set, to build packages from source, and generally
assists with the creation and maintenance of software environments.
@cindex user interfaces
Guix provides a command-line package management interface
(@pxref{Invoking guix package}), a set of command-line utilities
(@pxref{Utilities}), a visual user interface in Emacs (@pxref{Emacs
Interface}), as well as Scheme programming interfaces
(@pxref{Programming Interface}).
@cindex build daemon
Its @dfn{build daemon} is responsible for building packages on behalf of
users (@pxref{Setting Up the Daemon}) and for downloading pre-built
binaries from authorized sources (@pxref{Substitutes}).
@cindex extensibility of the distribution
@cindex customization of packages
Guix includes package definitions for many GNU and non-GNU packages, all
of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
user's computing freedom}. It is @emph{extensible}: users can write
their own package definitions (@pxref{Defining Packages}) and make them
available as independent package modules (@pxref{Package Modules}). It
is also @emph{customizable}: users can @emph{derive} specialized package
definitions from existing ones, including from the command line
(@pxref{Package Transformation Options}).
@cindex Guix System Distribution
@cindex GuixSD
You can install GNU@tie{}Guix on top of an existing GNU/Linux system
where it complements the available tools without interference
(@pxref{Installation}), or you can use it as part of the standalone
@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}).
With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating
system configuration and Guix takes care of instantiating the
configuration in a transactional, reproducible, and stateless fashion
(@pxref{System Configuration}).
@cindex functional package management
Under the hood, Guix implements the @dfn{functional package management}
discipline pioneered by Nix (@pxref{Acknowledgments}).
In Guix, the package build and installation process is seen
as a @emph{function}, in the mathematical sense. That function takes inputs,
such as build scripts, a compiler, and libraries, and
returns an installed package. As a pure function, its result depends
solely on its inputs---for instance, it cannot refer to software or
scripts that were not explicitly passed as inputs. A build function
always produces the same result when passed a given set of inputs. It
cannot alter the environment of the running system in
any way; for instance, it cannot create, modify, or delete files outside
of its build and installation directories. This is achieved by running
build processes in isolated environments (or @dfn{containers}), where only their
explicit inputs are visible.
@cindex store
The result of package build functions is @dfn{cached} in the file
system, in a special directory called @dfn{the store} (@pxref{The
Store}). Each package is installed in a directory of its own in the
store---by default under @file{/gnu/store}. The directory name contains
a hash of all the inputs used to build that package; thus, changing an
input yields a different directory name.
This approach is the foundation for the salient features of Guix: support
for transactional package upgrade and rollback, per-user installation, and
garbage collection of packages (@pxref{Features}).
@c *********************************************************************
@node Installation
@chapter Installation
GNU Guix is available for download from its website at
@url{http://www.gnu.org/software/guix/}. This section describes the
software requirements of Guix, as well as how to install it and get
ready to use it.
Note that this section is concerned with the installation of the package
manager, which can be done on top of a running GNU/Linux system. If,
instead, you want to install the complete GNU operating system,
@pxref{System Installation}.
@menu
* Binary Installation:: Getting Guix running in no time!
* Requirements:: Software needed to build and run Guix.
* Running the Test Suite:: Testing Guix.
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
@end menu
@node Binary Installation
@section Binary Installation
This section describes how to install Guix on an arbitrary system from a
self-contained tarball providing binaries for Guix and for all its
dependencies. This is often quicker than installing from source, which
is described in the next sections. The only requirement is to have
GNU@tie{}tar and Xz.
Installing goes along these lines:
@enumerate
@item
Download the binary tarball from
@indicateurl{ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the tarball against it, along these lines:
@example
$ wget ftp://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
@end example
If that command fails because you do not have the required public key,
then run this command to import it:
@example
$ gpg --keyserver keys.gnupg.net --recv-keys 3D9AEBB5
@end example
@noindent
and rerun the @code{gpg --verify} command.
@item
As @code{root}, run:
@example
# cd /tmp
# tar --warning=no-timestamp -xf \
guix-binary-@value{VERSION}.@var{system}.tar.xz
# mv var/guix /var/ && mv gnu /
@end example
This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
The latter contains a ready-to-use profile for @code{root} (see next
step.)
Do @emph{not} unpack the tarball on a working Guix system since that
would overwrite its own essential files.
The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does
not emit warnings about ``implausibly old time stamps'' (such
warnings were triggered by GNU@tie{}tar 1.26 and older; recent
versions are fine.)
They stem from the fact that all the
files in the archive have their modification time set to zero (which
means January 1st, 1970.) This is done on purpose to make sure the
archive content is independent of its creation time, thus making it
reproducible.
@item
Make @code{root}'s profile available under @file{~/.guix-profile}:
@example
# ln -sf /var/guix/profiles/per-user/root/guix-profile \
~root/.guix-profile
@end example
@item
Create the group and user accounts for build users as explained below
(@pxref{Build Environment Setup}).
@item
Run the daemon, and set it to automatically start on boot.
If your host distro uses the systemd init system, this can be achieved
with these commands:
@example
# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
# systemctl start guix-daemon && systemctl enable guix-daemon
@end example
If your host distro uses the Upstart init system:
@example
# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
# start guix-daemon
@end example
Otherwise, you can still start the daemon manually with:
@example
# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild
@end example
@item
Make the @command{guix} command available to other users on the machine,
for instance with:
@example
# mkdir -p /usr/local/bin
# cd /usr/local/bin
# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix
@end example
It is also a good idea to make the Info version of this manual available
there:
@example
# mkdir -p /usr/local/share/info
# cd /usr/local/share/info
# for i in /var/guix/profiles/per-user/root/guix-profile/share/info/* ;
do ln -s $i ; done
@end example
That way, assuming @file{/usr/local/share/info} is in the search path,
running @command{info guix} will open this manual (@pxref{Other Info
Directories,,, texinfo, GNU Texinfo}, for more details on changing the
Info search path.)
@item
To use substitutes from @code{hydra.gnu.org} or one of its mirrors
(@pxref{Substitutes}), authorize them:
@example
# guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub
@end example
@end enumerate
This completes root-level install of Guix. Each user will need to
perform additional steps to make their Guix envionment ready for use,
@pxref{Application Setup}.
You can confirm that Guix is working by installing a sample package into
the root profile:
@example
# guix package -i hello
@end example
The @code{guix} package must remain available in @code{root}'s profile,
or it would become subject to garbage collection---in which case you
would find yourself badly handicapped by the lack of the @command{guix}
command. In other words, do not remove @code{guix} by running
@code{guix package -r guix}.
The binary installation tarball can be (re)produced and verified simply
by running the following command in the Guix source tree:
@example
make guix-binary.@var{system}.tar.xz
@end example
@node Requirements
@section Requirements
This section lists requirements when building Guix from source. The
build procedure for Guix is the same as for other GNU software, and is
not covered here. Please see the files @file{README} and @file{INSTALL}
in the Guix source tree for additional details.
GNU Guix depends on the following packages:
@itemize
@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later;
@item @url{http://gnupg.org/, GNU libgcrypt};
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
@itemize
@item
Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to
access @code{https} URLs for substitutes, which is highly recommended
(@pxref{Substitutes}). It also allows you to access HTTPS URLs with the
@command{guix download} command (@pxref{Invoking guix download}), the
@command{guix import pypi} command, and the @command{guix import cpan}
command. @xref{Guile Preparations, how to install the GnuTLS bindings
for Guile,, gnutls-guile, GnuTLS-Guile}.
@item
Installing
@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will
allow you to use the @command{guix import pypi} command (@pxref{Invoking
guix import}). It is of
interest primarily for developers and not for casual users.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
following packages are also needed:
@itemize
@item @url{http://sqlite.org, SQLite 3};
@item @url{http://www.bzip.org, libbz2};
@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
When configuring Guix on a system that already has a Guix installation,
be sure to specify the same state directory as the existing installation
using the @code{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
GNU Coding Standards}). The @command{configure} script protects against
unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).
When a working installation of @url{http://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nix replaces the three dependencies above.
Guix is compatible with Nix, so it is possible to share the same store
between both. To do so, you must pass @command{configure} not only the
same @code{--with-store-dir} value, but also the same
@code{--localstatedir} value. The latter is essential because it
specifies where the database that stores metadata about the store is
located, among other things. The default values for Nix are
@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
Note that @code{--disable-daemon} is not required if
your goal is to share the store with Nix.
@node Running the Test Suite
@section Running the Test Suite
After a successful @command{configure} and @code{make} run, it is a good
idea to run the test suite. It can help catch issues with the setup or
environment, or bugs in Guix itself---and really, reporting test
failures is a good way to help improve the software. To run the test
suite, type:
@example
make check
@end example
Test cases can run in parallel: you can use the @code{-j} option of
GNU@tie{}make to speed things up. The first run may take a few minutes
on a recent machine; subsequent runs will be faster because the store
that is created for test purposes will already have various things in
cache.
It is also possible to run a subset of the tests by defining the
@code{TESTS} makefile variable as in this example:
@example
make check TESTS="tests/store.scm tests/cpio.scm"
@end example
By default, tests results are displayed at a file level. In order to
see the details of every individual test cases, it is possible to define
the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
@example
make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
@end example
Upon failure, please email @email{bug-guix@@gnu.org} and attach the
@file{test-suite.log} file. Please specify the Guix version being used
as well as version numbers of the dependencies (@pxref{Requirements}) in
your message.
@node Setting Up the Daemon
@section Setting Up the Daemon
@cindex daemon
Operations such as building a package or running the garbage collector
are all performed by a specialized process, the @dfn{build daemon}, on
behalf of clients. Only the daemon may access the store and its
associated database. Thus, any operation that manipulates the store
goes through the daemon. For instance, command-line tools such as
@command{guix package} and @command{guix build} communicate with the
daemon (@i{via} remote procedure calls) to instruct it what to do.
The following sections explain how to prepare the build daemon's
environment. See also @ref{Substitutes}, for information on how to allow
the daemon to download pre-built binaries.
@menu
* Build Environment Setup:: Preparing the isolated build environment.
* Daemon Offload Setup:: Offloading builds to remote machines.
@end menu
@node Build Environment Setup
@subsection Build Environment Setup
In a standard multi-user setup, Guix and its daemon---the
@command{guix-daemon} program---are installed by the system
administrator; @file{/gnu/store} is owned by @code{root} and
@command{guix-daemon} runs as @code{root}. Unprivileged users may use
Guix tools to build packages or otherwise access the store, and the
daemon will do it on their behalf, ensuring that the store is kept in a
consistent state, and allowing built packages to be shared among users.
@cindex build users
When @command{guix-daemon} runs as @code{root}, you may not want package
build processes themselves to run as @code{root} too, for obvious
security reasons. To avoid that, a special pool of @dfn{build users}
should be created for use by build processes started by the daemon.
These build users need not have a shell and a home directory: they will
just be used when the daemon drops @code{root} privileges in build
processes. Having several such users allows the daemon to launch
distinct build processes under separate UIDs, which guarantees that they
do not interfere with each other---an essential feature since builds are
regarded as pure functions (@pxref{Introduction}).
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
# for i in `seq -w 1 10`;
do
useradd -g guixbuild -G guixbuild \
-d /var/empty -s `which nologin` \
-c "Guix build user $i" --system \
guixbuilder$i;
done
@end example
@noindent
The number of build users determines how many build jobs may run in
parallel, as specified by the @option{--max-jobs} option
(@pxref{Invoking guix-daemon, @option{--max-jobs}}). The
@code{guix-daemon} program may then be run as @code{root} with the
following command@footnote{If your machine uses the systemd init system,
dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
file in @file{/etc/systemd/system} will ensure that
@command{guix-daemon} is automatically started. Similarly, if your
machine uses the Upstart init system, drop the
@file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
file in @file{/etc/init}.}:
@example
# guix-daemon --build-users-group=guixbuild
@end example
@cindex chroot
@noindent
This way, the daemon starts build processes in a chroot, under one of
the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
environment contains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------
@itemize
@item
a minimal @code{/dev} directory, created mostly independently from the
host @code{/dev}@footnote{``Mostly'', because while the set of files
that appear in the chroot's @code{/dev} is fixed, most of these files
can only be created if the host has them.};
@item
the @code{/proc} directory; it only shows the processes of the container
since a separate PID name space is used;
@item
@file{/etc/passwd} with an entry for the current user and an entry for
user @file{nobody};
@item
@file{/etc/group} with an entry for the user's group;
@item
@file{/etc/hosts} with an entry that maps @code{localhost} to
@code{127.0.0.1};
@item
a writable @file{/tmp} directory.
@end itemize
You can influence the directory where the daemon stores build trees
@i{via} the @code{TMPDIR} environment variable. However, the build tree
within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
This way, the value of @code{TMPDIR} does not leak inside build
environments, which avoids discrepancies in cases where build processes
capture the name of their build tree.
@vindex http_proxy
The daemon also honors the @code{http_proxy} environment variable for
HTTP downloads it performs, be it for fixed-output derivations
(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}).
If you are installing Guix as an unprivileged user, it is still possible
to run @command{guix-daemon} provided you pass @code{--disable-chroot}.
However, build processes will not be isolated from one another, and not
from the rest of the system. Thus, build processes may interfere with
each other, and may access programs, libraries, and other files
available on the system---making it much harder to view them as
@emph{pure} functions.
@node Daemon Offload Setup
@subsection Using the Offload Facility
@cindex offloading
@cindex build hook
When desired, the build daemon can @dfn{offload}
derivation builds to other machines
running Guix, using the @code{offload} @dfn{build hook}. When that
feature is enabled, a list of user-specified build machines is read from
@file{/etc/guix/machines.scm}; every time a build is requested, for
instance via @code{guix build}, the daemon attempts to offload it to one
of the machines that satisfy the constraints of the derivation, in
particular its system type---e.g., @file{x86_64-linux}. Missing
prerequisites for the build are copied over SSH to the target machine,
which then proceeds with the build; upon success the output(s) of the
build are copied back to the initial machine.
The @file{/etc/guix/machines.scm} file typically looks like this:
@example
(list (build-machine
(name "eightysix.example.org")
(system "x86_64-linux")
(user "bob")
(speed 2.)) ; incredibly fast!
(build-machine
(name "meeps.example.org")
(system "mips64el-linux")
(user "alice")
(private-key
(string-append (getenv "HOME")
"/.lsh/identity-for-guix"))))
@end example
@noindent
In the example above we specify a list of two build machines, one for
the @code{x86_64} architecture and one for the @code{mips64el}
architecture.
In fact, this file is---not surprisingly!---a Scheme file that is
evaluated when the @code{offload} hook is started. Its return value
must be a list of @code{build-machine} objects. While this example
shows a fixed list of build machines, one could imagine, say, using
DNS-SD to return a list of potential build machines discovered in the
local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
detailed below.
@deftp {Data Type} build-machine
This data type represents build machines to which the daemon may offload
builds. The important fields are:
@table @code
@item name
The host name of the remote machine.
@item system
The system type of the remote machine---e.g., @code{"x86_64-linux"}.
@item user
The user account to use when connecting to the remote machine over SSH.
Note that the SSH key pair must @emph{not} be passphrase-protected, to
allow non-interactive logins.
@end table
A number of optional fields may be specified:
@table @code
@item port
Port number of SSH server on the machine (default: 22).
@item private-key
The SSH private key file to use when connecting to the machine.
Currently offloading uses GNU@tie{}lsh as its SSH client
(@pxref{Invoking lsh,,, GNU lsh Manual}). Thus, the key file here must
be an lsh key file. This may change in the future, though.
@item parallel-builds
The number of builds that may run in parallel on the machine (1 by
default.)
@item speed
A ``relative speed factor''. The offload scheduler will tend to prefer
machines with a higher speed factor.
@item features
A list of strings denoting specific features supported by the machine.
An example is @code{"kvm"} for machines that have the KVM Linux modules
and corresponding hardware support. Derivations can request features by
name, and they will be scheduled on matching build machines.
@end table
@end deftp
The @code{guix} command must be in the search path on the build
machines, since offloading works by invoking the @code{guix archive} and
@code{guix build} commands. In addition, the Guix modules must be in
@code{$GUILE_LOAD_PATH} on the build machine---you can check whether
this is the case by running:
@example
lsh build-machine guile -c "'(use-modules (guix config))'"
@end example
There is one last thing to do once @file{machines.scm} is in place. As
explained above, when offloading, files are transferred back and forth
between the machine stores. For this to work, you first need to
generate a key pair on each machine to allow the daemon to export signed
archives of files from the store (@pxref{Invoking guix archive}):
@example
# guix archive --generate-key
@end example
@noindent
Each build machine must authorize the key of the master machine so that
it accepts store items it receives from the master:
@example
# guix archive --authorize < master-public-key.txt
@end example
@noindent
Likewise, the master machine must authorize the key of each build machine.
All the fuss with keys is here to express pairwise mutual trust
relations between the master and the build machines. Concretely, when
the master receives files from a build machine (and @i{vice versa}), its
build daemon can make sure they are genuine, have not been tampered
with, and that they are signed by an authorized key.
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
The @command{guix-daemon} program implements all the functionality to
access the store. This includes launching build processes, running the
garbage collector, querying the availability of a build result, etc. It
is normally run as @code{root} like this:
@example
# guix-daemon --build-users-group=guixbuild
@end example
@noindent
For details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot
@cindex container, build environment
@cindex build environment
@cindex reproducible builds
By default, @command{guix-daemon} launches build processes under
different UIDs, taken from the build group specified with
@code{--build-users-group}. In addition, each build process is run in a
chroot environment that only contains the subset of the store that the
build process depends on, as specified by its derivation
(@pxref{Programming Interface, derivation}), plus a set of specific
system directories. By default, the latter contains @file{/dev} and
@file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
@dfn{container}: in addition to having its own file system tree, it has
a separate mount name space, its own PID name space, network name space,
etc. This helps achieve reproducible builds (@pxref{Features}).
When the daemon performs a build on behalf of the user, it creates a
build directory under @file{/tmp} or under the directory specified by
its @code{TMPDIR} environment variable; this directory is shared with
the container for the duration of the build. Be aware that using a
directory other than @file{/tmp} can affect build results---for example,
with a longer directory name, a build process that uses Unix-domain
sockets might hit the name length limitation for @code{sun_path}, which
it would otherwise not hit.
The build directory is automatically deleted upon completion, unless the
build failed and the client specified @option{--keep-failed}
(@pxref{Invoking guix build, @option{--keep-failed}}).
The following command-line options are supported:
@table @code
@item --build-users-group=@var{group}
Take users from @var{group} to run build processes (@pxref{Setting Up
the Daemon, build users}).
@item --no-substitutes
@cindex substitutes
Do not use substitutes for build products. That is, always build things
locally instead of allowing downloads of pre-built binaries
(@pxref{Substitutes}).
By default substitutes are used, unless the client---such as the
@command{guix package} command---is explicitly invoked with
@code{--no-substitutes}.
When the daemon runs with @code{--no-substitutes}, clients can still
explicitly enable substitution @i{via} the @code{set-build-options}
remote procedure call (@pxref{The Store}).
@item --substitute-urls=@var{urls}
@anchor{daemon-substitute-urls}
Consider @var{urls} the default whitespace-separated list of substitute
source URLs. When this option is omitted,
@indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used
(@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}).
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
@cindex build hook
@item --no-build-hook
Do not use the @dfn{build hook}.
The build hook is a helper program that the daemon can start and to
which it submits build requests. This mechanism is used to offload
builds to other machines (@pxref{Daemon Offload Setup}).
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
When this option is used, @command{guix gc --list-failures} can be used
to query the set of store items marked as failed; @command{guix gc
--clear-failures} removes store items from the set of cached failures.
@xref{Invoking guix gc}.
@item --cores=@var{n}
@itemx -c @var{n}
Use @var{n} CPU cores to build each derivation; @code{0} means as many
as available.
The default value is @code{0}, but it may be overridden by clients, such
as the @code{--cores} option of @command{guix build} (@pxref{Invoking
guix build}).
The effect is to define the @code{NIX_BUILD_CORES} environment variable
in the build process, which can then use it to exploit internal
parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
@item --max-jobs=@var{n}
@itemx -M @var{n}
Allow at most @var{n} build jobs in parallel. The default value is
@code{1}. Setting it to @code{0} means that no builds will be performed
locally; instead, the daemon will offload builds (@pxref{Daemon Offload
Setup}), or simply fail.
@item --rounds=@var{N}
Build each derivation @var{n} times in a row, and raise an error if
consecutive build results are not bit-for-bit identical. Note that this
setting can be overridden by clients such as @command{guix build}
(@pxref{Invoking guix build}).
@item --debug
Produce debugging output.