5 @setfilename guix-cookbook.info
6 @documentencoding UTF-8
7 @settitle GNU Guix Cookbook
11 Copyright @copyright{} 2019 Ricardo Wurmus@*
12 Copyright @copyright{} 2019 Efraim Flashner@*
13 Copyright @copyright{} 2019 Pierre Neidhardt@*
14 Copyright @copyright{} 2020 Oleg Pykhalov@*
15 Copyright @copyright{} 2020 Matthew Brooks@*
16 Copyright @copyright{} 2020 Marcin Karpezo@*
17 Copyright @copyright{} 2020 Brice Waegeneire@*
18 Copyright @copyright{} 2020 André Batista@*
19 Copyright @copyright{} 2020 Christopher Lemmer Webber
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.3 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
25 copy of the license is included in the section entitled ``GNU Free
26 Documentation License''.
29 @dircategory System administration
31 * Guix cookbook: (guix-cookbook). Tutorials and examples for GNU Guix.
35 @title GNU Guix Cookbook
36 @subtitle Tutorials and examples for using the GNU Guix Functional Package Manager
37 @author The GNU Guix Developers
40 @vskip 0pt plus 1filll
47 @c *********************************************************************
49 @top GNU Guix Cookbook
51 This document presents tutorials and detailed examples for GNU@tie{}Guix, a
52 functional package management tool written for the GNU system. Please
53 @pxref{Top,,, guix, GNU Guix reference manual} for details about the system,
54 its API, and related concepts.
56 @c TRANSLATORS: You can replace the following paragraph with information on
57 @c how to join your own translation team and how to report issues with the
59 If you would like to translate this document in your native language, consider
61 @uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook,
65 * Scheme tutorials:: Meet your new favorite language!
66 * Packaging:: Packaging tutorials
67 * System Configuration:: Customizing the GNU System
68 * Advanced package management:: Power to the users!
69 * Environment management:: Control environment
71 * Acknowledgments:: Thanks!
72 * GNU Free Documentation License:: The license of this document.
73 * Concept Index:: Concepts.
76 --- The Detailed Node Listing ---
80 * A Scheme Crash Course:: Learn the basics of Scheme
84 * Packaging Tutorial:: Let's add a package to Guix!
88 * Customizing the Kernel:: Creating and using a custom Linux kernel
94 @c *********************************************************************
95 @node Scheme tutorials
96 @chapter Scheme tutorials
98 GNU@tie{}Guix is written in the general purpose programming language Scheme,
99 and many of its features can be accessed and manipulated programmatically.
100 You can use Scheme to generate package definitions, to modify them, to build
101 them, to deploy whole operating systems, etc.
103 Knowing the basics of how to program in Scheme will unlock many of the
104 advanced features Guix provides --- and you don't even need to be an
105 experienced programmer to use them!
109 @node A Scheme Crash Course
110 @section A Scheme Crash Course
112 @cindex Scheme, crash course
114 Guix uses the Guile implementation of Scheme. To start playing with the
115 language, install it with @code{guix install guile} and start a
116 @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop,
117 @dfn{read-eval-print loop}}---by running @code{guile} from the command line.
119 Alternatively you can also run @code{guix environment --ad-hoc guile -- guile}
120 if you'd rather not have Guile installed in your user profile.
122 In the following examples, lines show what you would type at the REPL;
123 lines starting with ``@result{}'' show evaluation results, while lines
124 starting with ``@print{}'' show things that get printed. @xref{Using Guile
125 Interactively,,, guile, GNU Guile Reference Manual}, for more details on the
130 Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in
131 Lisp lingo). An expression can be a literal such as numbers and strings, or a
132 compound which is a parenthesized list of compounds and literals. @code{#true}
133 and @code{#false} (abbreviated @code{#t} and @code{#f}) stand for the
134 Booleans ``true'' and ``false'', respectively.
136 Examples of valid expressions:
140 @result{} "Hello World!"
145 (display (string-append "Hello " "Guix" "\n"))
147 @result{} #<unspecified>
151 This last example is a function call nested in another function call. When a
152 parenthesized expression is evaluated, the first term is the function and the
153 rest are the arguments passed to the function. Every function returns the
154 last evaluated expression as its return value.
157 Anonymous functions are declared with the @code{lambda} term:
161 @result{} #<procedure 120e348 at <unknown port>:24:0 (x)>
164 The above procedure returns the square of its argument. Since everything is
165 an expression, the @code{lambda} expression returns an anonymous procedure,
166 which can in turn be applied to an argument:
169 ((lambda (x) (* x x)) 3)
174 Anything can be assigned a global name with @code{define}:
178 (define square (lambda (x) (* x x)))
184 Procedures can be defined more concisely with the following syntax:
187 (define (square x) (* x x))
191 A list structure can be created with the @code{list} procedure:
199 The @dfn{quote} disables evaluation of a parenthesized expression: the
200 first term is not called over the other terms (@pxref{Expression Syntax,
201 quote,, guile, GNU Guile Reference Manual}). Thus it effectively
202 returns a list of terms.
205 '(display (string-append "Hello " "Guix" "\n"))
206 @result{} (display (string-append "Hello " "Guix" "\n"))
213 The @dfn{quasiquote} disables evaluation of a parenthesized expression
214 until @dfn{unquote} (a comma) re-enables it. Thus it provides us with
215 fine-grained control over what is evaluated and what is not.
218 `(2 a 5 7 (2 ,a 5 ,(+ a 4)))
219 @result{} (2 a 5 7 (2 3 5 7))
222 Note that the above result is a list of mixed elements: numbers, symbols (here
223 @code{a}) and the last element is a list itself.
226 Multiple variables can be named locally with @code{let} (@pxref{Local
227 Bindings,,, guile, GNU Guile Reference Manual}):
240 @error{} In procedure module-lookup: Unbound variable: y
243 Use @code{let*} to allow later variable declarations to refer to earlier
254 @dfn{Keywords} are typically used to identify the named parameters of a
255 procedure. They are prefixed by @code{#:} (hash, colon) followed by
256 alphanumeric characters: @code{#:like-this}.
257 @xref{Keywords,,, guile, GNU Guile Reference Manual}.
260 The percentage @code{%} is typically used for read-only global variables in
261 the build stage. Note that it is merely a convention, like @code{_} in C.
262 Scheme treats @code{%} exactly the same as any other letter.
265 Modules are created with @code{define-module} (@pxref{Creating Guile
266 Modules,,, guile, GNU Guile Reference Manual}). For instance
269 (define-module (guix build-system ruby)
270 #:use-module (guix store)
275 defines the module @code{guix build-system ruby} which must be located in
276 @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It
277 depends on the @code{(guix store)} module and it exports two variables,
278 @code{ruby-build} and @code{ruby-build-system}.
281 For a more detailed introduction, check out
282 @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme
283 at a Glance}, by Steve Litt.
285 One of the reference Scheme books is the seminal ``Structure and
286 Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay
287 Sussman, with Julie Sussman. You'll find a
288 @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy
289 online}, together with
290 @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/,
291 videos of the lectures by the authors}. The book is available in Texinfo
292 format as the @code{sicp} Guix package. Go ahead, run @code{guix install
293 sicp} and start reading with @code{info sicp} (@pxref{,,, sicp, Structure and Interpretation of Computer Programs}).
294 An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also
297 You'll find more books, tutorials and other resources at
298 @url{https://schemers.org/}.
301 @c *********************************************************************
307 This chapter is dedicated to teaching you how to add packages to the
308 collection of packages that come with GNU Guix. This involves writing package
309 definitions in Guile Scheme, organizing them in package modules, and building
313 * Packaging Tutorial:: A tutorial on how to add packages to Guix.
316 @node Packaging Tutorial
317 @section Packaging Tutorial
319 GNU Guix stands out as the @emph{hackable} package manager, mostly because it
320 uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful
321 high-level programming language, one of the
322 @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme}
324 @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}.
326 Package definitions are also written in Scheme, which empowers Guix in some
327 very unique ways, unlike most other package managers that use shell scripts or
332 Use functions, structures, macros and all of Scheme expressiveness for your
336 Inheritance makes it easy to customize a package by inheriting from it and
337 modifying only what is needed.
340 Batch processing: the whole package collection can be parsed, filtered and
341 processed. Building a headless server with all graphical interfaces stripped
342 out? It's possible. Want to rebuild everything from source using specific
343 compiler optimization flags? Pass the @code{#:make-flags "..."} argument to
344 the list of packages. It wouldn't be a stretch to think
345 @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this
346 goes even further: the changes don't have to be thought out beforehand by the
347 packager, they can be @emph{programmed} by the user!
350 The following tutorial covers all the basics around package creation with Guix.
351 It does not assume much knowledge of the Guix system nor of the Lisp language.
352 The reader is only expected to be familiar with the command line and to have some
353 basic programming knowledge.
355 @node A ``Hello World'' package
356 @subsection A ``Hello World'' package
358 The ``Defining Packages'' section of the manual introduces the basics of Guix
359 packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In
360 the following section, we will partly go over those basics again.
362 GNU@tie{}Hello is a dummy project that serves as an idiomatic example for
363 packaging. It uses the GNU build system (@code{./configure && make && make
364 install}). Guix already provides a package definition which is a perfect
365 example to start with. You can look up its declaration with @code{guix edit
366 hello} from the command line. Let's see how it looks:
375 (uri (string-append "mirror://gnu/hello/hello-" version
379 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
380 (build-system gnu-build-system)
381 (synopsis "Hello, GNU world: An example GNU package")
383 "GNU Hello prints the message \"Hello, world!\" and then exits. It
384 serves as an example of standard GNU coding practices. As such, it supports
385 command-line arguments, multiple languages, and so on.")
386 (home-page "https://www.gnu.org/software/hello/")
390 As you can see, most of it is rather straightforward. But let's review the
395 The project name. Using Scheme conventions, we prefer to keep it
396 lower case, without underscore and using dash-separated words.
399 This field contains a description of the source code origin. The
400 @code{origin} record contains these fields:
403 @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods
404 exist, such as @code{git-fetch} for Git repositories.
405 @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here
406 the special `mirror://gnu` refers to a set of well known locations, all of
407 which can be used by Guix to fetch the source, should some of them fail.
408 @item The @code{sha256} checksum of the requested file. This is essential to ensure
409 the source is not corrupted. Note that Guix works with base32 strings,
410 hence the call to the @code{base32} function.
415 This is where the power of abstraction provided by the Scheme language really
416 shines: in this case, the @code{gnu-build-system} abstracts away the famous
417 @code{./configure && make && make install} shell invocations. Other build
418 systems include the @code{trivial-build-system} which does not do anything and
419 requires from the packager to program all the build steps, the
420 @code{python-build-system}, the @code{emacs-build-system}, and many more
421 (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}).
424 It should be a concise summary of what the package does. For many packages a
425 tagline from the project's home page can be used as the synopsis.
428 Same as for the synopsis, it's fine to re-use the project description from the
429 homepage. Note that Guix uses Texinfo syntax.
432 Use HTTPS if available.
435 See @code{guix/licenses.scm} in the project source for a full list of
439 Time to build our first package! Nothing fancy here for now: we will stick to a
440 dummy @code{my-hello}, a copy of the above declaration.
442 As with the ritualistic ``Hello World'' taught with most programming languages,
443 this will possibly be the most ``manual'' approach. We will work out an ideal
444 setup later; for now we will go the simplest route.
446 Save the following to a file @file{my-hello.scm}.
449 (use-modules (guix packages)
451 (guix build-system gnu)
459 (uri (string-append "mirror://gnu/hello/hello-" version
463 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
464 (build-system gnu-build-system)
465 (synopsis "Hello, Guix world: An example custom Guix package")
467 "GNU Hello prints the message \"Hello, world!\" and then exits. It
468 serves as an example of standard GNU coding practices. As such, it supports
469 command-line arguments, multiple languages, and so on.")
470 (home-page "https://www.gnu.org/software/hello/")
474 We will explain the extra code in a moment.
476 Feel free to play with the different values of the various fields. If you
477 change the source, you'll need to update the checksum. Indeed, Guix refuses to
478 build anything if the given checksum does not match the computed checksum of the
479 source code. To obtain the correct checksum of the package declaration, we
480 need to download the source, compute the sha256 checksum and convert it to
483 Thankfully, Guix can automate this task for us; all we need is to provide the
486 @c TRANSLATORS: This is example shell output.
488 $ guix download mirror://gnu/hello/hello-2.10.tar.gz
490 Starting download of /tmp/guix-file.JLYgL7
491 From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...
492 following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...
493 …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0%
494 /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
495 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
498 In this specific case the output tells us which mirror was chosen.
499 If the result of the above command is not the same as in the above snippet,
500 update your @code{my-hello} declaration accordingly.
502 Note that GNU package tarballs come with an OpenPGP signature, so you
503 should definitely check the signature of this tarball with `gpg` to
504 authenticate it before going further:
506 @c TRANSLATORS: This is example shell output.
508 $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig
510 Starting download of /tmp/guix-file.03tFfb
511 From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...
512 following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...
513 ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0%
514 /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig
515 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf
516 $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
517 gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET
518 gpg: using RSA key A9553245FDE9B739
519 gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown]
520 gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown]
521 gpg: WARNING: This key is not certified with a trusted signature!
522 gpg: There is no indication that the signature belongs to the owner.
523 Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739
526 You can then happily run
528 @c TRANSLATORS: Do not translate this command
530 $ guix package --install-from-file=my-hello.scm
533 You should now have @code{my-hello} in your profile!
535 @c TRANSLATORS: Do not translate this command
537 $ guix package --list-installed=my-hello
539 /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10
542 We've gone as far as we could without any knowledge of Scheme. Before moving
543 on to more complex packages, now is the right time to brush up on your Scheme
544 knowledge. @pxref{A Scheme Crash Course} to get up to speed.
549 In the rest of this chapter we will rely on some basic Scheme
550 programming knowledge. Now let's detail the different possible setups
551 for working on Guix packages.
553 There are several ways to set up a Guix packaging environment.
555 We recommend you work directly on the Guix source checkout since it makes it
556 easier for everyone to contribute to the project.
558 But first, let's look at other possibilities.
561 @subsubsection Local file
563 This is what we previously did with @samp{my-hello}. With the Scheme basics we've
564 covered, we are now able to explain the leading chunks. As stated in @code{guix
568 -f, --install-from-file=FILE
569 install the package that the code within FILE
573 Thus the last expression @emph{must} return a package, which is the case in our
576 The @code{use-modules} expression tells which of the modules we need in the file.
577 Modules are a collection of values and procedures. They are commonly called
578 ``libraries'' or ``packages'' in other programming languages.
580 @node @samp{GUIX_PACKAGE_PATH}
581 @subsubsection @samp{GUIX_PACKAGE_PATH}
583 @emph{Note: Starting from Guix 0.16, the more flexible Guix @dfn{channels} are the
584 preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section.}
586 It can be tedious to specify the file from the command line instead of simply
587 calling @code{guix package --install my-hello} as you would do with the official
590 Guix makes it possible to streamline the process by adding as many ``package
591 declaration directories'' as you want.
593 Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
594 environment variable:
597 $ mkdir ~/guix-packages
598 $ export GUIX_PACKAGE_PATH=~/guix-packages
601 To add several directories, separate them with a colon (@code{:}).
603 Our previous @samp{my-hello} needs some adjustments though:
606 (define-module (my-hello)
607 #:use-module (guix licenses)
608 #:use-module (guix packages)
609 #:use-module (guix build-system gnu)
610 #:use-module (guix download))
612 (define-public my-hello
618 (uri (string-append "mirror://gnu/hello/hello-" version
622 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
623 (build-system gnu-build-system)
624 (synopsis "Hello, Guix world: An example custom Guix package")
626 "GNU Hello prints the message \"Hello, world!\" and then exits. It
627 serves as an example of standard GNU coding practices. As such, it supports
628 command-line arguments, multiple languages, and so on.")
629 (home-page "https://www.gnu.org/software/hello/")
633 Note that we have assigned the package value to an exported variable name with
634 @code{define-public}. This is effectively assigning the package to the @code{my-hello}
635 variable so that it can be referenced, among other as dependency of other
638 If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it
639 will fail because the last expression, @code{define-public}, does not return a
640 package. If you want to use @code{define-public} in this use-case nonetheless, make
641 sure the file ends with an evaluation of @code{my-hello}:
645 (define-public my-hello
652 This last example is not very typical.
654 Now @samp{my-hello} should be part of the package collection like all other official
655 packages. You can verify this with:
658 $ guix package --show=my-hello
662 @subsubsection Guix channels
664 Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but
665 provides better integration and provenance tracking. Channels are not
666 necessarily local, they can be maintained as a public Git repository for
667 instance. Of course, several channels can be used at the same time.
669 @xref{Channels,,, guix, GNU Guix Reference Manual} for setup details.
671 @node Direct checkout hacking
672 @subsubsection Direct checkout hacking
674 Working directly on the Guix project is recommended: it reduces the friction
675 when the time comes to submit your changes upstream to let the community benefit
678 Unlike most software distributions, the Guix repository holds in one place both
679 the tooling (including the package manager) and the package definitions. This
680 choice was made so that it would give developers the flexibility to modify the
681 API without breakage by updating all packages at the same time. This reduces
684 Check out the official @uref{https://git-scm.com/, Git} repository:
687 $ git clone https://git.savannah.gnu.org/git/guix.git
690 In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of
694 Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix
695 Reference Manual}) to set up the repository environment.
697 Once ready, you should be able to use the package definitions from the
698 repository environment.
700 Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}.
702 The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package
703 collection of the repository (@pxref{Running Guix Before It Is
704 Installed,,, guix, GNU Guix Reference Manual}).
708 Search packages, such as Ruby:
712 $ ./pre-inst-env guix package --list-available=ruby
713 ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2
714 ruby 2.1.6 out gnu/packages/ruby.scm:91:2
715 ruby 2.2.2 out gnu/packages/ruby.scm:39:2
719 Build a package, here Ruby version 2.1:
722 $ ./pre-inst-env guix build --keep-failed ruby@@2.1
723 /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6
727 Install it to your user profile:
730 $ ./pre-inst-env guix package --install ruby@@2.1
734 Check for common mistakes:
737 $ ./pre-inst-env guix lint ruby@@2.1
741 Guix strives at maintaining a high packaging standard; when contributing to the
742 Guix project, remember to
746 follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}),
748 and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual}).
751 Once you are happy with the result, you are welcome to send your contribution to
752 make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual})
755 It's a community effort so the more join in, the better Guix becomes!
757 @node Extended example
758 @subsection Extended example
760 The above ``Hello World'' example is as simple as it goes. Packages can be more
761 complex than that and Guix can handle more advanced scenarios. Let's look at
762 another, more sophisticated package (slightly modified from the source):
765 (define-module (gnu packages version-control)
766 #:use-module ((guix licenses) #:prefix license:)
767 #:use-module (guix utils)
768 #:use-module (guix packages)
769 #:use-module (guix git-download)
770 #:use-module (guix build-system cmake)
771 #:use-module (gnu packages ssh)
772 #:use-module (gnu packages web)
773 #:use-module (gnu packages pkg-config)
774 #:use-module (gnu packages python)
775 #:use-module (gnu packages compression)
776 #:use-module (gnu packages tls))
778 (define-public my-libgit2
779 (let ((commit "e98d0a37c93574d2c6107bf7f31140b548c6a7bf")
783 (version (git-version "0.26.6" revision commit))
787 (url "https://github.com/libgit2/libgit2/")
789 (file-name (git-file-name name version))
792 "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3"))
793 (patches (search-patches "libgit2-mtime-0.patch"))
794 (modules '((guix build utils)))
796 ;; Remove bundled software.
797 (delete-file-recursively "deps")
799 (build-system cmake-build-system)
800 (outputs '("out" "debug"))
802 `(#:tests? #true ; Run the test suite (this is the default)
803 #:configure-flags '("-DUSE_SHA1DC=ON") ; SHA-1 collision detection
805 (modify-phases %standard-phases
806 (add-after 'unpack 'fix-hardcoded-paths
808 (substitute* "tests/repo/init.c"
809 (("#!/bin/sh") (string-append "#!" (which "sh"))))
810 (substitute* "tests/clar/fs.h"
811 (("/bin/cp") (which "cp"))
812 (("/bin/rm") (which "rm")))
814 ;; Run checks more verbosely.
816 (lambda _ (invoke "./libgit2_clar" "-v" "-Q")))
817 (add-after 'unpack 'make-files-writable-for-tests
818 (lambda _ (for-each make-file-writable (find-files "." ".*")))))))
820 `(("libssh2" ,libssh2)
821 ("http-parser" ,http-parser)
822 ("python" ,python-wrapper)))
824 `(("pkg-config" ,pkg-config)))
826 ;; These two libraries are in 'Requires.private' in libgit2.pc.
827 `(("openssl" ,openssl)
829 (home-page "https://libgit2.github.com/")
830 (synopsis "Library providing Git core methods")
832 "Libgit2 is a portable, pure C implementation of the Git core methods
833 provided as a re-entrant linkable library with a solid API, allowing you to
834 write native speed custom Git applications in any language with bindings.")
835 ;; GPLv2 with linking exception
836 (license license:gpl2))))
839 (In those cases were you only want to tweak a few fields from a package
840 definition, you should rely on inheritance instead of copy-pasting everything.
843 Let's discuss those fields in depth.
845 @subsubsection @code{git-fetch} method
847 Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes
848 a Git repository and a commit. The commit can be any Git reference such as
849 tags, so if the @code{version} is tagged, then it can be used directly. Sometimes
850 the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append
853 To ensure that the source code from the Git repository is stored in a
854 directory with a descriptive name, we use @code{(file-name (git-file-name name
857 The @code{git-version} procedure can be used to derive the
858 version when packaging programs for a specific commit, following the
859 Guix contributor guidelines (@pxref{Version Numbers,,, guix, GNU Guix
862 How does one obtain the @code{sha256} hash that's in there, you ask? By
863 invoking @command{guix hash} on a checkout of the desired commit, along
867 git clone https://github.com/libgit2/libgit2/
873 @command{guix hash -rx} computes a SHA256 hash over the whole directory,
874 excluding the @file{.git} sub-directory (@pxref{Invoking guix hash,,,
875 guix, GNU Guix Reference Manual}).
877 In the future, @command{guix download} will hopefully be able to do
878 these steps for you, just like it does for regular downloads.
880 @subsubsection Snippets
882 Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching
883 the source. They are a Guix-y alternative to the traditional @file{.patch} files.
884 Because of the quote, the code in only evaluated when passed to the Guix daemon
885 for building. There can be as many snippets as needed.
887 Snippets might need additional Guile modules which can be imported from the
888 @code{modules} field.
890 @subsubsection Inputs
892 First, a syntactic comment: See the quasi-quote / comma syntax?
896 `(("pkg-config" ,pkg-config)))
903 (list (list "pkg-config" pkg-config)))
906 You'll mostly see the former because it's shorter.
908 There are 3 different input types. In short:
912 Required for building but not runtime -- installing a package
913 through a substitute won't install these inputs.
915 Installed in the store but not in the profile, as well as being
916 present at build time.
917 @item propagated-inputs
918 Installed in the store and in the profile, as well as
919 being present at build time.
922 @xref{Package Reference,,, guix, GNU Guix Reference Manual} for more details.
924 The distinction between the various inputs is important: if a dependency can be
925 handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or
926 else it ``pollutes'' the user profile for no good reason.
928 For instance, a user installing a graphical program that depends on a
929 command line tool might only be interested in the graphical part, so there is no
930 need to force the command line tool into the user profile. The dependency is a
931 concern to the package, not to the user. @emph{Inputs} make it possible to handle
932 dependencies without bugging the user by adding undesired executable files (or
933 libraries) to their profile.
935 Same goes for @emph{native-inputs}: once the program is installed, build-time
936 dependencies can be safely garbage-collected.
937 It also matters when a substitute is available, in which case only the @emph{inputs}
938 and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to
939 install a package from a substitute.
941 @subsubsection Outputs
943 Just like how a package can have multiple inputs, it can also produce multiple
946 Each output corresponds to a separate directory in the store.
948 The user can choose which output to install; this is useful to save space or
949 to avoid polluting the user profile with unwanted executables or libraries.
951 Output separation is optional. When the @code{outputs} field is left out, the
952 default and only output (the complete package) is referred to as @code{"out"}.
954 Typical separate output names include @code{debug} and @code{doc}.
956 It's advised to separate outputs only when you've shown it's worth it: if the
957 output size is significant (compare with @code{guix size}) or in case the package is
960 @subsubsection Build system arguments
962 The @code{arguments} is a keyword-value list used to configure the build process.
964 The simplest argument @code{#:tests?} can be used to disable the test suite when
965 building the package. This is mostly useful when the package does not feature
966 any test suite. It's strongly recommended to keep the test suite on if there is
969 Another common argument is @code{:make-flags}, which specifies a list of flags to
970 append when running make, as you would from the command line. For instance, the
974 #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out"))
981 $ make CC=gcc prefix=/gnu/store/...-<out>
984 This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation
985 directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage
986 global variable pointing to the destination directory in the store (something like
987 @file{/gnu/store/...-my-libgit2-20180408}).
989 Similarly, it's possible to set the configure flags:
992 #:configure-flags '("-DUSE_SHA1DC=ON")
995 The @code{%build-inputs} variable is also generated in scope. It's an association
996 table that maps the input names to their store directories.
998 The @code{phases} keyword lists the sequential steps of the build system. Typically
999 phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know
1000 more about those phases, you need to work out the appropriate build system
1001 definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}:
1004 (define %standard-phases
1005 ;; Standard build phases, as a list of symbol/procedure pairs.
1006 (let-syntax ((phases (syntax-rules ()
1007 ((_ p ...) `((p . ,p) ...)))))
1008 (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack
1011 patch-source-shebangs configure patch-generated-file-shebangs
1013 patch-shebangs strip
1015 validate-documentation-location
1016 delete-info-dir-file
1017 patch-dot-desktop-files
1018 install-license-files
1019 reset-gzip-timestamps
1020 compress-documentation)))
1026 (add-to-load-path "/path/to/guix/checkout")
1027 ,use (guix build gnu-build-system)
1028 (map first %standard-phases)
1029 @result{} (set-SOURCE-DATE-EPOCH set-paths install-locale unpack bootstrap patch-usr-bin-file patch-source-shebangs configure patch-generated-file-shebangs build check install patch-shebangs strip validate-runpath validate-documentation-location delete-info-dir-file patch-dot-desktop-files install-license-files reset-gzip-timestamps compress-documentation)
1032 If you want to know more about what happens during those phases, consult the
1033 associated procedures.
1035 For instance, as of this writing the definition of @code{unpack} for the GNU build
1039 (define* (unpack #:key source #:allow-other-keys)
1040 "Unpack SOURCE in the working directory, and change directory within the
1041 source. When SOURCE is a directory, copy it in a sub-directory of the current
1043 (if (file-is-directory? source)
1048 ;; Preserve timestamps (set to the Epoch) on the copied tree so that
1049 ;; things work deterministically.
1050 (copy-recursively source "."
1051 #:keep-mtime? #true))
1053 (if (string-suffix? ".zip" source)
1054 (invoke "unzip" source)
1055 (invoke "tar" "xvf" source))
1056 (chdir (first-subdirectory "."))))
1060 Note the @code{chdir} call: it changes the working directory to where the source was
1062 Thus every phase following the @code{unpack} will use the source as a working
1063 directory, which is why we can directly work on the source files.
1064 That is to say, unless a later phase changes the working directory to something
1067 We modify the list of @code{%standard-phases} of the build system with the
1068 @code{modify-phases} macro as per the list of specified modifications, which may have
1069 the following forms:
1073 @code{(add-before @var{phase} @var{new-phase} @var{procedure})}: Run @var{procedure} named @var{new-phase} before @var{phase}.
1075 @code{(add-after @var{phase} @var{new-phase} @var{procedure})}: Same, but afterwards.
1077 @code{(replace @var{phase} @var{procedure})}.
1079 @code{(delete @var{phase})}.
1082 The @var{procedure} supports the keyword arguments @code{inputs} and @code{outputs}. Each
1083 input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced
1084 by their name in those variables. Thus @code{(assoc-ref outputs "out")} is the store
1085 directory of the main output of the package. A phase procedure may look like
1089 (lambda* (#:key inputs outputs #:allow-other-keys)
1090 (let ((bash-directory (assoc-ref inputs "bash"))
1091 (output-directory (assoc-ref outputs "out"))
1092 (doc-directory (assoc-ref outputs "doc")))
1097 The procedure must return @code{#true} on success. It's brittle to rely on the return
1098 value of the last expression used to tweak the phase because there is no
1099 guarantee it would be a @code{#true}. Hence the trailing @code{#true} to ensure the right value
1100 is returned on success.
1102 @subsubsection Code staging
1104 The astute reader may have noticed the quasi-quote and comma syntax in the
1105 argument field. Indeed, the build code in the package declaration should not be
1106 evaluated on the client side, but only when passed to the Guix daemon. This
1107 mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}.
1109 @subsubsection Utility functions
1111 When customizing @code{phases}, we often need to write code that mimics the
1112 equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during
1113 regular ``Unix-style'' installations.
1115 Some like @code{chmod} are native to Guile.
1116 @xref{,,, guile, Guile reference manual} for a complete list.
1118 Guix provides additional helper functions which prove especially handy in the
1119 context of package management.
1121 Some of those functions can be found in
1122 @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour
1123 of the traditional Unix system commands:
1127 Like the @samp{which} system command.
1129 Akin to the @samp{find} system command.
1131 Like @samp{mkdir -p}, which creates all parents as needed.
1133 Similar to @samp{install} when installing a file to a (possibly
1134 non-existing) directory. Guile has @code{copy-file} which works
1136 @item copy-recursively
1138 @item delete-file-recursively
1141 Run an executable. This should be used instead of @code{system*}.
1142 @item with-directory-excursion
1143 Run the body in a different working directory,
1144 then restore the previous working directory.
1146 A ``@command{sed}-like'' function.
1149 @xref{Build Utilities,,, guix, GNU Guix Reference Manual}, for more
1150 information on these utilities.
1152 @subsubsection Module prefix
1154 The license in our last example needs a prefix: this is because of how the
1155 @code{license} module was imported in the package, as @code{#:use-module ((guix licenses)
1156 #:prefix license:)}. The Guile module import mechanism
1157 (@pxref{Using Guile Modules,,, guile, Guile reference manual})
1158 gives the user full control over namespacing: this is needed to avoid
1159 clashes between, say, the
1160 @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable
1161 from @samp{compression.scm} (a @emph{package} value).
1163 @node Other build systems
1164 @subsection Other build systems
1166 What we've seen so far covers the majority of packages using a build system
1167 other than the @code{trivial-build-system}. The latter does not automate anything
1168 and leaves you to build everything manually. This can be more demanding and we
1169 won't cover it here for now, but thankfully it is rarely necessary to fall back
1172 For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the
1173 process is very similar to the GNU build system except for a few specialized
1176 @xref{Build Systems,,, guix, GNU Guix Reference Manual}, for more
1177 information on build systems, or check the source code in the
1178 @samp{$GUIX_CHECKOUT/guix/build} and
1179 @samp{$GUIX_CHECKOUT/guix/build-system} directories.
1181 @node Programmable and automated package definition
1182 @subsection Programmable and automated package definition
1184 We can't repeat it enough: having a full-fledged programming language at hand
1185 empowers us in ways that reach far beyond traditional package management.
1187 Let's illustrate this with some awesome features of Guix!
1189 @node Recursive importers
1190 @subsubsection Recursive importers
1192 You might find some build systems good enough that there is little to do at all
1193 to write a package, to the point that it becomes repetitive and tedious after a
1194 while. A @emph{raison d'être} of computers is to replace human beings at those
1195 boring tasks. So let's tell Guix to do this for us and create the package
1196 definition of an R package from CRAN (the output is trimmed for conciseness):
1199 $ guix import cran --recursive walrus
1201 (define-public r-mc2d
1205 (define-public r-jmvcore
1209 (define-public r-wrs2
1213 (define-public r-walrus
1220 (uri (cran-uri "walrus" version))
1223 "1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj"))))
1224 (build-system r-build-system)
1226 `(("r-ggplot2" ,r-ggplot2)
1227 ("r-jmvcore" ,r-jmvcore)
1229 ("r-wrs2" ,r-wrs2)))
1230 (home-page "https://github.com/jamovi/walrus")
1231 (synopsis "Robust Statistical Methods")
1233 "This package provides a toolbox of common robust statistical
1234 tests, including robust descriptives, robust t-tests, and robust ANOVA.
1235 It is also available as a module for 'jamovi' (see
1236 <https://www.jamovi.org> for more information). Walrus is based on the
1237 WRS2 package by Patrick Mair, which is in turn based on the scripts and
1238 work of Rand Wilcox. These analyses are described in depth in the book
1239 'Introduction to Robust Estimation & Hypothesis Testing'.")
1243 The recursive importer won't import packages for which Guix already has package
1244 definitions, except for the very first.
1246 Not all applications can be packaged this way, only those relying on a select
1247 number of supported systems. Read about the full list of importers in
1248 the guix import section of the manual
1249 (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual}).
1251 @node Automatic update
1252 @subsubsection Automatic update
1254 Guix can be smart enough to check for updates on systems it knows. It can
1255 report outdated package definitions with
1258 $ guix refresh hello
1261 In most cases, updating a package to a newer version requires little more than
1262 changing the version number and the checksum. Guix can do that automatically as
1266 $ guix refresh hello --update
1270 @subsubsection Inheritance
1272 If you've started browsing the existing package definitions, you might have
1273 noticed that a significant number of them have a @code{inherit} field:
1276 (define-public adwaita-icon-theme
1277 (package (inherit gnome-icon-theme)
1278 (name "adwaita-icon-theme")
1282 (uri (string-append "mirror://gnome/sources/" name "/"
1283 (version-major+minor version) "/"
1284 name "-" version ".tar.xz"))
1287 "17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8"))))
1289 `(("gtk-encode-symbolic-svg" ,gtk+ "bin")))))
1292 All unspecified fields are inherited from the parent package. This is very
1293 convenient to create alternative packages, for instance with different source,
1294 version or compilation options.
1297 @subsection Getting help
1299 Sadly, some applications can be tough to package. Sometimes they need a patch to
1300 work with the non-standard file system hierarchy enforced by the store.
1301 Sometimes the tests won't run properly. (They can be skipped but this is not
1302 recommended.) Other times the resulting package won't be reproducible.
1304 Should you be stuck, unable to figure out how to fix any sort of packaging
1305 issue, don't hesitate to ask the community for help.
1307 See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc.
1310 @subsection Conclusion
1312 This tutorial was a showcase of the sophisticated package management that Guix
1313 boasts. At this point we have mostly restricted this introduction to the
1314 @code{gnu-build-system} which is a core abstraction layer on which more advanced
1315 abstractions are based.
1317 Where do we go from here? Next we ought to dissect the innards of the build
1318 system by removing all abstractions, using the @code{trivial-build-system}: this
1319 should give us a thorough understanding of the process before investigating some
1320 more advanced packaging techniques and edge cases.
1322 Other features worth exploring are the interactive editing and debugging
1323 capabilities of Guix provided by the Guile REPL@.
1325 Those fancy features are completely optional and can wait; now is a good time
1326 to take a well-deserved break. With what we've introduced here you should be
1327 well armed to package lots of programs. You can get started right away and
1328 hopefully we will see your contributions soon!
1331 @subsection References
1335 The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual}
1338 @uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix}
1341 @uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, ``GNU Guix: Package without a scheme!''}, by Andreas Enge
1344 @c *********************************************************************
1345 @node System Configuration
1346 @chapter System Configuration
1348 Guix offers a flexible language for declaratively configuring your Guix
1349 System. This flexibility can at times be overwhelming. The purpose of this
1350 chapter is to demonstrate some advanced configuration concepts.
1352 @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete
1356 * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
1357 * Guix System Image API:: Customizing images to target specific platforms.
1358 * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN.
1359 * Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
1360 * Running Guix on a Linode Server:: Running Guix on a Linode Server
1361 * Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
1362 * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor.
1363 * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules.
1366 @node Customizing the Kernel
1367 @section Customizing the Kernel
1369 Guix is, at its core, a source based distribution with substitutes
1370 (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building
1371 packages from their source code is an expected part of regular package
1372 installations and upgrades. Given this starting point, it makes sense that
1373 efforts are made to reduce the amount of time spent compiling packages, and
1374 recent changes and upgrades to the building and distribution of substitutes
1375 continues to be a topic of discussion within Guix.
1377 The kernel, while not requiring an overabundance of RAM to build, does take a
1378 rather long time on an average machine. The official kernel configuration, as
1379 is the case with many GNU/Linux distributions, errs on the side of
1380 inclusiveness, and this is really what causes the build to take such a long
1381 time when the kernel is built from source.
1383 The Linux kernel, however, can also just be described as a regular old
1384 package, and as such can be customized just like any other package. The
1385 procedure is a little bit different, although this is primarily due to the
1386 nature of how the package definition is written.
1388 The @code{linux-libre} kernel package definition is actually a procedure which
1392 (define* (make-linux-libre version hash supported-systems
1394 ;; A function that takes an arch and a variant.
1395 ;; See kernel-config for an example.
1396 (extra-version #false)
1397 (configuration-file #false)
1398 (defconfig "defconfig")
1399 (extra-options %default-extra-linux-options)
1400 (patches (list %boot-logo-patch)))
1404 The current @code{linux-libre} package is for the 5.1.x series, and is
1408 (define-public linux-libre
1409 (make-linux-libre %linux-libre-version
1411 '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux")
1412 #:patches %linux-libre-5.1-patches
1413 #:configuration-file kernel-config))
1416 Any keys which are not assigned values inherit their default value from the
1417 @code{make-linux-libre} definition. When comparing the two snippets above,
1418 you may notice that the code comment in the first doesn't actually refer to
1419 the @code{#:extra-version} keyword; it is actually for
1420 @code{#:configuration-file}. Because of this, it is not actually easy to
1421 include a custom kernel configuration from the definition, but don't worry,
1422 there are other ways to work with what we do have.
1424 There are two ways to create a kernel with a custom kernel configuration. The
1425 first is to provide a standard @file{.config} file during the build process by
1426 including an actual @file{.config} file as a native input to our custom
1427 kernel. The following is a snippet from the custom @code{'configure} phase of
1428 the @code{make-linux-libre} package definition:
1431 (let ((build (assoc-ref %standard-phases 'build))
1432 (config (assoc-ref (or native-inputs inputs) "kconfig")))
1434 ;; Use a custom kernel configuration file or a default
1435 ;; configuration file.
1438 (copy-file config ".config")
1439 (chmod ".config" #o666))
1440 (invoke "make" ,defconfig)))
1443 Below is a sample kernel package. The @code{linux-libre} package is nothing
1444 special and can be inherited from and have its fields overridden like any
1448 (define-public linux-libre/E2140
1450 (inherit linux-libre)
1452 `(("kconfig" ,(local-file "E2140.config"))
1453 ,@@(alist-delete "kconfig"
1454 (package-native-inputs linux-libre))))))
1457 In the same directory as the file defining @code{linux-libre-E2140} is a file
1458 named @file{E2140.config}, which is an actual kernel configuration file. The
1459 @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the
1460 only kernel configuration in the package is the one which was included in the
1461 @code{native-inputs} field.
1463 The second way to create a custom kernel is to pass a new value to the
1464 @code{extra-options} keyword of the @code{make-linux-libre} procedure. The
1465 @code{extra-options} keyword works with another function defined right below
1469 (define %default-extra-linux-options
1470 `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
1471 ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #true)
1472 ;; Modules required for initrd:
1473 ("CONFIG_NET_9P" . m)
1474 ("CONFIG_NET_9P_VIRTIO" . m)
1475 ("CONFIG_VIRTIO_BLK" . m)
1476 ("CONFIG_VIRTIO_NET" . m)
1477 ("CONFIG_VIRTIO_PCI" . m)
1478 ("CONFIG_VIRTIO_BALLOON" . m)
1479 ("CONFIG_VIRTIO_MMIO" . m)
1480 ("CONFIG_FUSE_FS" . m)
1482 ("CONFIG_9P_FS" . m)))
1484 (define (config->string options)
1485 (string-join (map (match-lambda
1487 (string-append option "=m"))
1489 (string-append option "=y"))
1491 (string-append option "=n")))
1496 And in the custom configure script from the `make-linux-libre` package:
1499 ;; Appending works even when the option wasn't in the
1500 ;; file. The last one prevails if duplicated.
1501 (let ((port (open-file ".config" "a"))
1502 (extra-configuration ,(config->string extra-options)))
1503 (display extra-configuration port)
1506 (invoke "make" "oldconfig")
1509 So by not providing a configuration-file the @file{.config} starts blank, and
1510 then we write into it the collection of flags that we want. Here's another
1514 (define %macbook41-full-config
1515 (append %macbook41-config-options
1519 (@@@@ (gnu packages linux) %default-extra-linux-options)))
1521 (define-public linux-libre-macbook41
1522 ;; XXX: Access the internal 'make-linux-libre' procedure, which is
1523 ;; private and unexported, and is liable to change in the future.
1524 ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux) %linux-libre-version)
1525 (@@@@ (gnu packages linux) %linux-libre-hash)
1527 #:extra-version "macbook41"
1528 #:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches)
1529 #:extra-options %macbook41-config-options))
1532 In the above example @code{%file-systems} is a collection of flags enabling
1533 different file system support, @code{%efi-support} enables EFI support and
1534 @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also.
1535 @code{%default-extra-linux-options} are the ones quoted above, which had to be
1536 added in since they were replaced in the @code{extra-options} keyword.
1538 This all sounds like it should be doable, but how does one even know which
1539 modules are required for a particular system? Two places that can be helpful
1540 in trying to answer this question is the
1541 @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo
1543 @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig,
1544 documentation from the kernel itself}. From the kernel documentation, it
1545 seems that @code{make localmodconfig} is the command we want.
1547 In order to actually run @code{make localmodconfig} we first need to get and
1548 unpack the kernel source code:
1551 tar xf $(guix build linux-libre --source)
1554 Once inside the directory containing the source code run @code{touch .config}
1555 to create an initial, empty @file{.config} to start with. @code{make
1556 localmodconfig} works by seeing what you already have in @file{.config} and
1557 letting you know what you're missing. If the file is blank then you're
1558 missing everything. The next step is to run:
1561 guix environment linux-libre -- make localmodconfig
1564 and note the output. Do note that the @file{.config} file is still empty.
1565 The output generally contains two types of warnings. The first start with
1566 "WARNING" and can actually be ignored in our case. The second read:
1569 module pcspkr did not have configs CONFIG_INPUT_PCSPKR
1572 For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the
1573 @file{.config} in the directory, and append @code{=m}, so in the end it looks
1577 CONFIG_INPUT_PCSPKR=m
1581 After copying all the configuration options, run @code{make localmodconfig}
1582 again to make sure that you don't have any output starting with ``module''.
1583 After all of these machine specific modules there are a couple more left that
1584 are also needed. @code{CONFIG_MODULES} is necessary so that you can build and
1585 load modules separately and not have everything built into the kernel.
1586 @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is
1587 possible that there are other modules which you will need.
1589 This post does not aim to be a guide to configuring your own kernel however,
1590 so if you do decide to build a custom kernel you'll have to seek out other
1591 guides to create a kernel which is just right for your needs.
1593 The second way to setup the kernel configuration makes more use of Guix's
1594 features and allows you to share configuration segments between different
1595 kernels. For example, all machines using EFI to boot have a number of EFI
1596 configuration flags that they need. It is likely that all the kernels will
1597 share a list of file systems to support. By using variables it is easier to
1598 see at a glance what features are enabled and to make sure you don't have
1599 features in one kernel but missing in another.
1601 Left undiscussed however, is Guix's initrd and its customization. It is
1602 likely that you'll need to modify the initrd on a machine using a custom
1603 kernel, since certain modules which are expected to be built may not be
1604 available for inclusion into the initrd.
1606 @node Guix System Image API
1607 @section Guix System Image API
1609 Historically, Guix System is centered around an @code{operating-system}
1610 structure. This structure contains various fields ranging from the
1611 bootloader and kernel declaration to the services to install.
1613 Depending on the target machine, that can go from a standard
1614 @code{x86_64} machine to a small ARM single board computer such as the
1615 Pine64, the image constraints can vary a lot. The hardware
1616 manufacturers will impose different image formats with various partition
1619 To create images suitable for all those machines, a new abstraction is
1620 necessary: that's the goal of the @code{image} record. This record
1621 contains all the required information to be transformed into a
1622 standalone image, that can be directly booted on any target machine.
1625 (define-record-type* <image>
1628 (name image-name ;symbol
1630 (format image-format) ;symbol
1631 (target image-target
1633 (size image-size ;size in bytes as integer
1635 (operating-system image-operating-system ;<operating-system>
1637 (partitions image-partitions ;list of <partition>
1639 (compression? image-compression? ;boolean
1641 (volatile-root? image-volatile-root? ;boolean
1643 (substitutable? image-substitutable? ;boolean
1647 This record contains the operating-system to instantiate. The
1648 @code{format} field defines the image type and can be @code{efi-raw},
1649 @code{qcow2} or @code{iso9660} for instance. In the future, it could be
1650 extended to @code{docker} or other image types.
1652 A new directory in the Guix sources is dedicated to images definition. For now
1653 there are four files:
1656 @item @file{gnu/system/images/hurd.scm}
1657 @item @file{gnu/system/images/pine64.scm}
1658 @item @file{gnu/system/images/novena.scm}
1659 @item @file{gnu/system/images/pinebook-pro.scm}
1662 Let's have a look to @file{pine64.scm}. It contains the
1663 @code{pine64-barebones-os} variable which is a minimal definition of an
1664 operating-system dedicated to the @b{Pine A64 LTS} board.
1667 (define pine64-barebones-os
1669 (host-name "vignemale")
1670 (timezone "Europe/Paris")
1671 (locale "en_US.utf8")
1672 (bootloader (bootloader-configuration
1673 (bootloader u-boot-pine64-lts-bootloader)
1674 (target "/dev/vda")))
1675 (initrd-modules '())
1676 (kernel linux-libre-arm64-generic)
1677 (file-systems (cons (file-system
1678 (device (file-system-label "my-root"))
1681 %base-file-systems))
1682 (services (cons (service agetty-service-type
1683 (agetty-configuration
1684 (extra-options '("-L")) ; no carrier detect
1685 (baud-rate "115200")
1691 The @code{kernel} and @code{bootloader} fields are pointing to packages
1692 dedicated to this board.
1694 Right below, the @code{pine64-image-type} variable is also defined.
1697 (define pine64-image-type
1700 (constructor (cut image-with-os arm64-disk-image <>))))
1703 It's using a record we haven't talked about yet, the @code{image-type} record,
1707 (define-record-type* <image-type>
1708 image-type make-image-type
1710 (name image-type-name) ;symbol
1711 (constructor image-type-constructor)) ;<operating-system> -> <image>
1714 The main purpose of this record is to associate a name to a procedure
1715 transforming an @code{operating-system} to an image. To understand why
1716 it is necessary, let's have a look to the command producing an image
1717 from an @code{operating-system} configuration file:
1720 guix system image my-os.scm
1723 This command expects an @code{operating-system} configuration but how
1724 should we indicate that we want an image targeting a Pine64 board? We
1725 need to provide an extra information, the @code{image-type}, by passing
1726 the @code{--image-type} or @code{-t} flag, this way:
1729 guix system image --image-type=pine64-raw my-os.scm
1732 This @code{image-type} parameter points to the @code{pine64-image-type}
1733 defined above. Hence, the @code{operating-system} declared in
1734 @code{my-os.scm} will be applied the @code{(cut image-with-os
1735 arm64-disk-image <>)} procedure to turn it into an image.
1737 The resulting image looks like:
1741 (format 'disk-image)
1742 (target "aarch64-linux-gnu")
1743 (operating-system my-os)
1746 (inherit root-partition)
1747 (offset root-offset)))))
1750 which is the aggregation of the @code{operating-system} defined in
1751 @code{my-os.scm} to the @code{arm64-disk-image} record.
1753 But enough Scheme madness. What does this image API bring to the Guix user?
1758 mathieu@@cervin:~$ guix system --list-image-types
1759 The available image types are:
1767 - uncompressed-iso9660
1774 and by writing an @code{operating-system} file based on
1775 @code{pine64-barebones-os}, you can customize your image to your
1776 preferences in a file (@file{my-pine-os.scm}) like this:
1779 (use-modules (gnu services linux)
1780 (gnu system images pine64))
1782 (let ((base-os pine64-barebones-os))
1785 (timezone "America/Indiana/Indianapolis")
1788 (service earlyoom-service-type
1789 (earlyoom-configuration
1790 (prefer-regexp "icecat|chromium")))
1791 (operating-system-user-services base-os)))))
1797 guix system image --image-type=pine64-raw my-pine-os.scm
1803 guix system image --image-type=hurd-raw my-hurd-os.scm
1806 to get an image that can be written directly to a hard drive and booted
1809 Without changing anything to @code{my-hurd-os.scm}, calling:
1812 guix system image --image-type=hurd-qcow2 my-hurd-os.scm
1815 will instead produce a Hurd QEMU image.
1817 @node Connecting to Wireguard VPN
1818 @section Connecting to Wireguard VPN
1820 To connect to a Wireguard VPN server you need the kernel module to be
1821 loaded in memory and a package providing networking tools that support
1822 it (e.g. @code{wireguard-tools} or @code{network-manager}).
1824 Here is a configuration example for Linux-Libre < 5.6, where the module
1825 is out of tree and need to be loaded manually---following revisions of
1826 the kernel have it built-in and so don't need such configuration:
1830 (use-service-modules desktop)
1831 (use-package-modules vpn)
1835 (services (cons (simple-service 'wireguard-module
1836 kernel-module-loader-service-type
1839 (packages (cons wireguard-tools %base-packages))
1840 (kernel-loadable-modules (list wireguard-linux-compat)))
1843 After reconfiguring and restarting your system you can either use
1844 Wireguard tools or NetworkManager to connect to a VPN server.
1846 @subsection Using Wireguard tools
1848 To test your Wireguard setup it is convenient to use @command{wg-quick}.
1849 Just give it a configuration file @command{wg-quick up ./wg0.conf}; or
1850 put that file in @file{/etc/wireguard} and run @command{wg-quick up wg0}
1854 Be warned that the author described this command as a: “[…] very quick
1855 and dirty bash script […]”.
1858 @subsection Using NetworkManager
1860 Thanks to NetworkManager support for Wireguard we can connect to our VPN
1861 using @command{nmcli} command. Up to this point this guide assumes that
1862 you're using Network Manager service provided by
1863 @code{%desktop-services}. Ortherwise you need to adjust your services
1864 list to load @code{network-manager-service-type} and reconfigure your
1867 To import your VPN configuration execute nmcli import command:
1870 # nmcli connection import type wireguard file wg0.conf
1871 Connection 'wg0' (edbee261-aa5a-42db-b032-6c7757c60fde) successfully added
1874 This will create a configuration file in
1875 @file{/etc/NetworkManager/wg0.nmconnection}. Next connect to the
1879 $ nmcli connection up wg0
1880 Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/6)
1883 By default NetworkManager will connect automatically on system boot. To
1884 change that behaviour you need to edit your config:
1887 # nmcli connection modify wg0 connection.autoconnect no
1890 For more specific information about NetworkManager and wireguard
1891 @uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see
1892 this post by thaller}.
1894 @node Customizing a Window Manager
1895 @section Customizing a Window Manager
1902 You could install StumpWM with a Guix system by adding
1903 @code{stumpwm} and optionally @code{`(,stumpwm "lib")}
1904 packages to a system configuration file, e.g.@: @file{/etc/config.scm}.
1906 An example configuration can look like this:
1910 (use-package-modules wm)
1914 (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
1918 @cindex stumpwm fonts
1919 By default StumpWM uses X11 fonts, which could be small or pixelated on
1920 your system. You could fix this by installing StumpWM contrib Lisp
1921 module @code{sbcl-ttf-fonts}, adding it to Guix system packages:
1925 (use-package-modules fonts wm)
1929 (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
1930 sbcl-ttf-fonts font-dejavu %base-packages)))
1933 Then you need to add the following code to a StumpWM configuration file
1934 @file{~/.stumpwm.d/init.lisp}:
1937 (require :ttf-fonts)
1938 (setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/"))
1939 (setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp"))
1941 (set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
1945 @subsection Session lock
1948 Depending on your environment, locking the screen of your session might come built in
1949 or it might be something you have to set up yourself. If you use a desktop environment
1950 like GNOME or KDE, it's usually built in. If you use a plain window manager like
1951 StumpWM or EXWM, you might have to set it up yourself.
1956 If you use Xorg, you can use the utility
1957 @uref{https://www.mankier.com/1/xss-lock, xss-lock} to lock the screen of your session.
1958 xss-lock is triggered by DPMS which since Xorg 1.8 is auto-detected and enabled if
1959 ACPI is also enabled at kernel runtime.
1961 To use xss-lock, you can simple execute it and put it into the background before
1962 you start your window manager from e.g. your @file{~/.xsession}:
1969 In this example, xss-lock uses @code{slock} to do the actual locking of the screen when
1970 it determines it's appropriate, like when you suspend your device.
1972 For slock to be allowed to be a screen locker for the graphical session, it needs to
1973 be made setuid-root so it can authenticate users, and it needs a PAM service. This
1974 can be achieved by adding the following service to your @file{config.scm}:
1977 (screen-locker-service slock)
1980 If you manually lock your screen, e.g. by directly calling slock when you want to lock
1981 your screen but not suspend it, it's a good idea to notify xss-lock about this so no
1982 confusion occurs. This can be done by executing @code{xset s activate} immediately
1983 before you execute slock.
1985 @node Running Guix on a Linode Server
1986 @section Running Guix on a Linode Server
1987 @cindex linode, Linode
1989 To run Guix on a server hosted by @uref{https://www.linode.com, Linode},
1990 start with a recommended Debian server. We recommend using the default
1991 distro as a way to bootstrap Guix. Create your SSH keys.
1997 Be sure to add your SSH key for easy login to the remote server.
1998 This is trivially done via Linode's graphical interface for adding
1999 SSH keys. Go to your profile and click add SSH Key.
2000 Copy into it the output of:
2003 cat ~/.ssh/<username>_rsa.pub
2006 Power the Linode down. In the Linode's Disks/Configurations tab, resize
2007 the Debian disk to be smaller. 30 GB is recommended.
2009 In the Linode settings, "Add a disk", with the following:
2018 Set it to the remaining size
2021 On the "configuration" field that comes with the default image, press
2022 "..." and select "Edit", then on that menu add to @file{/dev/sdc} the "Guix"
2025 Now "Add a Configuration", with the following:
2031 Kernel:GRUB 2 (it's at the bottom! This step is @b{IMPORTANT!})
2034 Block device assignment:
2037 @file{/dev/sda}: Guix
2040 @file{/dev/sdb}: swap
2043 Root device: @file{/dev/sda}
2046 Turn off all the filesystem/boot helpers
2049 Now power it back up, picking the Debian configuration. Once it's
2050 booted up, ssh in your server via @code{ssh
2051 root@@@var{<your-server-IP-here>}}. (You can find your server IP address in
2052 your Linode Summary section.) Now you can run the "install guix from
2053 @pxref{Binary Installation,,, guix, GNU Guix}" steps:
2056 sudo apt-get install gpg
2057 wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import -
2058 wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
2059 chmod +x guix-install.sh
2064 Now it's time to write out a config for the server. The key information
2065 is below. Save the resulting file as @file{guix-config.scm}.
2070 (use-service-modules networking
2072 (use-package-modules admin
2079 (host-name "my-server")
2080 (timezone "America/New_York")
2081 (locale "en_US.UTF-8")
2082 ;; This goofy code will generate the grub.cfg
2083 ;; without installing the grub bootloader on disk.
2084 (bootloader (bootloader-configuration
2087 (inherit grub-bootloader)
2088 (installer #~(const #true))))))
2089 (file-systems (cons (file-system
2093 %base-file-systems))
2096 (swap-devices (list "/dev/sdb"))
2099 (initrd-modules (cons "virtio_scsi" ; Needed to find the disk
2100 %base-initrd-modules))
2102 (users (cons (user-account
2105 ;; Adding the account to the "wheel" group
2106 ;; makes it a sudoer.
2107 (supplementary-groups '("wheel"))
2108 (home-directory "/home/janedoe"))
2109 %base-user-accounts))
2111 (packages (cons* nss-certs ;for HTTPS access
2116 (service dhcp-client-service-type)
2117 (service openssh-service-type
2118 (openssh-configuration
2119 (openssh openssh-sans-x)
2120 (password-authentication? #false)
2122 `(("janedoe" ,(local-file "janedoe_rsa.pub"))
2123 ("root" ,(local-file "janedoe_rsa.pub"))))))
2127 Replace the following fields in the above configuration:
2129 (host-name "my-server") ; replace with your server name
2130 ; if you chose a linode server outside the U.S., then
2131 ; use tzselect to find a correct timezone string
2132 (timezone "America/New_York") ; if needed replace timezone
2133 (name "janedoe") ; replace with your username
2134 ("janedoe" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
2135 ("root" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key
2138 The last line in the above example lets you log into the server as root
2139 and set the initial root password. After you have done this, you may
2140 delete that line from your configuration and reconfigure to prevent root
2143 Save your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as
2144 @file{@var{<your-username-here>}_rsa.pub} and your
2145 @file{guix-config.scm} in the same directory. In a new terminal run
2149 sftp root@@<remote server ip address>
2150 put /home/<username>/ssh/id_rsa.pub .
2151 put /path/to/linode/guix-config.scm .
2154 In your first terminal, mount the guix drive:
2158 mount /dev/sdc /mnt/guix
2161 Due to the way we set things up above, we do not install GRUB
2162 completely. Instead we install only our grub configuration file. So we
2163 need to copy over some of the other GRUB stuff that is already there:
2166 mkdir -p /mnt/guix/boot/grub
2167 cp -r /boot/grub/* /mnt/guix/boot/grub/
2170 Now initialize the Guix installation:
2173 guix system init guix-config.scm /mnt/guix
2177 Now from the Linode console, select boot and select "Guix".
2179 Once it boots, you should be able to log in via SSH! (The server config
2180 will have changed though.) You may encounter an error like:
2183 $ ssh root@@<server ip address>
2184 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
2185 @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @
2186 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
2187 IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY!
2188 Someone could be eavesdropping on you right now (man-in-the-middle attack)!
2189 It is also possible that a host key has just been changed.
2190 The fingerprint for the ECDSA key sent by the remote host is
2191 SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4.
2192 Please contact your system administrator.
2193 Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message.
2194 Offending ECDSA key in /home/joshua/.ssh/known_hosts:3
2195 ECDSA host key for 198.58.98.76 has changed and you have requested strict checking.
2196 Host key verification failed.
2199 Either delete @file{~/.ssh/known_hosts} file, or delete the offending line
2200 starting with your server IP address.
2202 Be sure to set your password and root's password.
2205 ssh root@@<remote ip address>
2206 passwd ; for the root password
2207 passwd <username> ; for the user password
2210 You may not be able to run the above commands at this point. If you
2211 have issues remotely logging into your linode box via SSH, then you may
2212 still need to set your root and user password initially by clicking on
2213 the ``Launch Console'' option in your linode. Choose the ``Glish''
2214 instead of ``Weblish''. Now you should be able to ssh into the machine.
2216 Horray! At this point you can shut down the server, delete the
2217 Debian disk, and resize the Guix to the rest of the size.
2220 By the way, if you save it as a disk image right at this point, you'll
2221 have an easy time spinning up new Guix images! You may need to
2222 down-size the Guix image to 6144MB, to save it as an image. Then you
2223 can resize it again to the max size.
2225 @node Setting up a bind mount
2226 @section Setting up a bind mount
2228 To bind mount a file system, one must first set up some definitions
2229 before the @code{operating-system} section of the system definition. In
2230 this example we will bind mount a folder from a spinning disk drive to
2231 @file{/tmp}, to save wear and tear on the primary SSD, without
2232 dedicating an entire partition to be mounted as @file{/tmp}.
2234 First, the source drive that hosts the folder we wish to bind mount
2235 should be defined, so that the bind mount can depend on it.
2238 (define source-drive ;; "source-drive" can be named anything you want.
2240 (device (uuid "UUID goes here"))
2241 (mount-point "/path-to-spinning-disk-goes-here")
2242 (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive.
2245 The source folder must also be defined, so that guix will know it's not
2246 a regular block device, but a folder.
2248 (define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name.
2251 Finally, inside the @code{file-systems} definition, we must add the
2255 (file-systems (cons*
2257 ...<other drives omitted for clarity>...
2259 source-drive ;; Must match the name you gave the source drive in the earlier definition.
2262 (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition.
2263 (mount-point "/tmp")
2264 (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none"
2265 (flags '(bind-mount))
2266 (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive.
2269 ...<other drives omitted for clarity>...
2274 @node Getting substitutes from Tor
2275 @section Getting substitutes from Tor
2277 Guix daemon can use a HTTP proxy to get substitutes, here we are
2278 configuring it to get them via Tor.
2281 @emph{Not all} Guix daemon's traffic will go through Tor! Only
2282 HTTP/HTTPS will get proxied; FTP, Git protocol, SSH, etc connections
2283 will still go through the clearnet. Again, this configuration isn't
2284 foolproof some of your traffic won't get routed by Tor at all. Use it
2287 Also note that the procedure described here applies only to package
2288 substitution. When you update your guix distribution with
2289 @command{guix pull}, you still need to use @command{torsocks} if
2290 you want to route the connection to guix's git repository servers
2294 Guix's substitute server is available as a Onion service, if you want
2295 to use it to get your substitutes through Tor configure your system as
2300 (use-service-module base networking)
2306 (service tor-service-type
2308 (config-file (plain-file "tor-config"
2309 "HTTPTunnelPort 127.0.0.1:9250"))))
2310 (modify-services %base-services
2312 config => (guix-configuration
2314 ;; ci.guix.gnu.org's Onion service
2315 (substitute-urls "https://bp7o7ckwlewr4slm.onion")
2316 (http-proxy "http://localhost:9250")))))))
2319 This will keep a tor process running that provides a HTTP CONNECT tunnel
2320 which will be used by @command{guix-daemon}. The daemon can use other
2321 protocols than HTTP(S) to get remote resources, request using those
2322 protocols won't go through Tor since we are only setting a HTTP tunnel
2323 here. Note that @code{substitutes-urls} is using HTTPS and not HTTP or
2324 it won't work, that's a limitation of Tor's tunnel; you may want to use
2325 @command{privoxy} instead to avoid such limitations.
2327 If you don't want to always get substitutes through Tor but using it just
2328 some of the times, then skip the @code{guix-configuration}. When you
2329 want to get a substitute from the Tor tunnel run:
2332 sudo herd set-http-proxy guix-daemon http://localhost:9250
2333 guix build --substitute-urls=https://bp7o7ckwlewr4slm.onion …
2336 @node Setting up NGINX with Lua
2337 @section Setting up NGINX with Lua
2338 @cindex nginx, lua, openresty, resty
2340 NGINX could be extended with Lua scripts.
2342 Guix provides NGINX service with ability to load Lua module and specific
2343 Lua packages, and reply to requests by evaluating Lua scripts.
2345 The following example demonstrates system definition with configuration
2346 to evaluate @file{index.lua} Lua script on HTTP request to
2347 @uref{http://localhost/hello} endpoint:
2350 local shell = require "resty.shell"
2353 local timeout = 1000 -- ms
2354 local max_size = 4096 -- byte
2356 local ok, stdout, stderr, reason, status =
2357 shell.run([[/run/current-system/profile/bin/ls /tmp]], stdin, timeout, max_size)
2364 (use-service-modules #;… web)
2365 (use-package-modules #;… lua)
2370 (service nginx-service-type
2371 (nginx-configuration
2374 (file-append nginx-lua-module "/etc/nginx/modules/ngx_http_lua_module.so")))
2375 (lua-package-path (list lua-resty-core
2380 (lua-package-cpath (list lua-resty-signal))
2382 (list (nginx-server-configuration
2383 (server-name '("localhost"))
2387 (nginx-location-configuration
2389 (body (list #~(format #f "content_by_lua_file ~s;"
2390 #$(local-file "index.lua"))))))))))))))
2393 @c *********************************************************************
2394 @node Advanced package management
2395 @chapter Advanced package management
2397 Guix is a functional package manager that offers many features beyond
2398 what more traditional package managers can do. To the uninitiated,
2399 those features might not have obvious use cases at first. The purpose
2400 of this chapter is to demonstrate some advanced package management
2403 @pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete
2407 * Guix Profiles in Practice:: Strategies for multiple profiles and manifests.
2410 @node Guix Profiles in Practice
2411 @section Guix Profiles in Practice
2413 Guix provides a very useful feature that may be quite foreign to newcomers:
2414 @emph{profiles}. They are a way to group package installations together and all users
2415 on the same system are free to use as many profiles as they want.
2417 Whether you're a developer or not, you may find that multiple profiles bring you
2418 great power and flexibility. While they shift the paradigm somewhat compared to
2419 @emph{traditional package managers}, they are very convenient to use once you've
2420 understood how to set them up.
2422 If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
2423 kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
2424 just Python software. Furthermore, profiles are self-sufficient: they capture
2425 all the runtime dependencies which guarantees that all programs within a profile
2426 will always work at any point in time.
2428 Multiple profiles have many benefits:
2432 Clean semantic separation of the various packages a user needs for different contexts.
2435 Multiple profiles can be made available into the environment either on login
2436 or within a dedicated shell.
2439 Profiles can be loaded on demand. For instance, the user can use multiple
2440 shells, each of them running different profiles.
2443 Isolation: Programs from one profile will not use programs from the other, and
2444 the user can even install different versions of the same programs to the two
2445 profiles without conflict.
2448 Deduplication: Profiles share dependencies that happens to be the exact same.
2449 This makes multiple profiles storage-efficient.
2452 Reproducible: when used with declarative manifests, a profile can be fully
2453 specified by the Guix commit that was active when it was set up. This means
2454 that the exact same profile can be
2455 @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/,
2456 set up anywhere and anytime}, with just the commit information. See the
2457 section on @ref{Reproducible profiles}.
2460 Easier upgrades and maintenance: Multiple profiles make it easy to keep
2461 package listings at hand and make upgrades completely frictionless.
2464 Concretely, here follows some typical profiles:
2468 The dependencies of a project you are working on.
2471 Your favourite programming language libraries.
2474 Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop.
2477 @TeX{}live (this one can be really useful when you need to install just one
2478 package for this one document you've just received over email).
2484 Let's dive in the set up!
2486 @node Basic setup with manifests
2487 @subsection Basic setup with manifests
2489 A Guix profile can be set up @emph{via} a so-called @emph{manifest specification} that looks like
2493 (specifications->manifest
2495 ;; Version 1.3 of package-2.
2497 ;; The "lib" output of package-3.
2503 @pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for
2506 We can create a manifest specification per profile and install them this way:
2509 GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
2510 mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet
2511 guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
2514 Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory
2515 where we will store our profiles in the rest of this article.
2517 Placing all your profiles in a single directory, with each profile getting its
2518 own sub-directory, is somewhat cleaner. This way, each sub-directory will
2519 contain all the symlinks for precisely one profile. Besides, ``looping over
2520 profiles'' becomes obvious from any programming language (e.g.@: a shell script) by
2521 simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}.
2523 Note that it's also possible to loop over the output of
2526 guix package --list-profiles
2529 although you'll probably have to filter out @file{~/.config/guix/current}.
2531 To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar):
2534 for i in $GUIX_EXTRA_PROFILES/*; do
2535 profile=$i/$(basename "$i")
2536 if [ -f "$profile"/etc/profile ]; then
2537 GUIX_PROFILE="$profile"
2538 . "$GUIX_PROFILE"/etc/profile
2544 Note to Guix System users: the above reflects how your default profile
2545 @file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by
2546 @file{~/.bashrc} by default.
2548 You can obviously choose to only enable a subset of them:
2551 for i in "$GUIX_EXTRA_PROFILES"/my-project-1 "$GUIX_EXTRA_PROFILES"/my-project-2; do
2552 profile=$i/$(basename "$i")
2553 if [ -f "$profile"/etc/profile ]; then
2554 GUIX_PROFILE="$profile"
2555 . "$GUIX_PROFILE"/etc/profile
2561 When a profile is off, it's straightforward to enable it for an individual shell
2562 without "polluting" the rest of the user session:
2565 GUIX_PROFILE="path/to/my-project" ; . "$GUIX_PROFILE"/etc/profile
2568 The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file
2569 contains shell code that exports the right environment variables necessary to
2570 activate the software contained in the profile. It is built automatically by
2571 Guix and meant to be sourced.
2572 It contains the same variables you would get if you ran:
2575 guix package --search-paths=prefix --profile=$my_profile"
2578 Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual})
2579 for the command line options.
2581 To upgrade a profile, simply install the manifest again:
2584 guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project
2587 To upgrade all profiles, it's easy enough to loop over them. For instance,
2588 assuming your manifest specifications are stored in
2589 @file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name
2590 of the profile (e.g.@: "project1"), you could do the following in Bourne shell:
2593 for profile in "$GUIX_EXTRA_PROFILES"/*; do
2594 guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm"
2598 Each profile has its own generations:
2601 guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --list-generations
2604 You can roll-back to any generation of a given profile:
2607 guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --switch-generations=17
2610 Finally, if you want to switch to a profile without inheriting from the
2611 current environment, you can activate it from an empty shell:
2614 env -i $(which bash) --login --noprofile --norc
2615 . my-project/etc/profile
2618 @node Required packages
2619 @subsection Required packages
2621 Activating a profile essentially boils down to exporting a bunch of
2622 environmental variables. This is the role of the @samp{etc/profile} within the
2625 @emph{Note: Only the environmental variables of the packages that consume them will
2628 For instance, @samp{MANPATH} won't be set if there is no consumer application for man
2629 pages within the profile. So if you need to transparently access man pages once
2630 the profile is loaded, you've got two options:
2634 Either export the variable manually, e.g.
2636 export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH
2640 Or include @samp{man-db} to the profile manifest.
2643 The same is true for @samp{INFOPATH} (you can install @samp{info-reader}),
2644 @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc.
2646 @node Default profile
2647 @subsection Default profile
2649 What about the default profile that Guix keeps in @file{~/.guix-profile}?
2651 You can assign it the role you want. Typically you would install the manifest
2652 of the packages you want to use all the time.
2654 Alternatively, you could keep it ``manifest-less'' for throw-away packages
2655 that you would just use for a couple of days.
2656 This way makes it convenient to run
2659 guix install package-foo
2660 guix upgrade package-bar
2663 without having to specify the path to a profile.
2665 @node The benefits of manifests
2666 @subsection The benefits of manifests
2668 Manifests are a convenient way to keep your package lists around and, say,
2669 to synchronize them across multiple machines using a version control system.
2671 A common complaint about manifests is that they can be slow to install when they
2672 contain large number of packages. This is especially cumbersome when you just
2673 want get an upgrade for one package within a big manifest.
2675 This is one more reason to use multiple profiles, which happen to be just
2676 perfect to break down manifests into multiple sets of semantically connected
2677 packages. Using multiple, small profiles provides more flexibility and
2680 Manifests come with multiple benefits. In particular, they ease maintenance:
2684 When a profile is set up from a manifest, the manifest itself is
2685 self-sufficient to keep a ``package listing'' around and reinstall the profile
2686 later or on a different system. For ad-hoc profiles, we would need to
2687 generate a manifest specification manually and maintain the package versions
2688 for the packages that don't use the default version.
2691 @code{guix package --upgrade} always tries to update the packages that have
2692 propagated inputs, even if there is nothing to do. Guix manifests remove this
2696 When partially upgrading a profile, conflicts may arise (due to diverging
2697 dependencies between the updated and the non-updated packages) and they can be
2698 annoying to resolve manually. Manifests remove this problem altogether since
2699 all packages are always upgraded at once.
2702 As mentioned above, manifests allow for reproducible profiles, while the
2703 imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce
2704 different profiles every time even when they hold the same packages. See
2705 @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}.
2708 Manifest specifications are usable by other @samp{guix} commands. For example, you
2709 can run @code{guix weather -m manifest.scm} to see how many substitutes are
2710 available, which can help you decide whether you want to try upgrading today
2711 or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to
2712 create a pack containing all the packages in the manifest (and their
2713 transitive references).
2716 Finally, manifests have a Scheme representation, the @samp{<manifest>} record type.
2717 They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}.
2720 It's important to understand that while manifests can be used to declare
2721 profiles, they are not strictly equivalent: profiles have the side effect that
2722 they ``pin'' packages in the store, which prevents them from being
2723 garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
2724 and ensures that they will still be available at any point in
2727 Let's take an example:
2731 We have an environment for hacking on a project for which there isn't a Guix
2732 package yet. We build the environment using a manifest, and then run @code{guix
2733 environment -m manifest.scm}. So far so good.
2736 Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
2737 Maybe a dependency from our manifest has been updated; or we may have run
2738 @code{guix gc} and some packages needed by our manifest have been
2742 Eventually, we set to work on that project again, so we run @code{guix environment
2743 -m manifest.scm}. But now we have to wait for Guix to build and install
2747 Ideally, we could spare the rebuild time. And indeed we can, all we need is to
2748 install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
2749 . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
2750 hacking environment will be available at all times.
2752 @emph{Security warning:} While keeping old profiles around can be convenient, keep in
2753 mind that outdated packages may not have received the latest security fixes.
2755 @node Reproducible profiles
2756 @subsection Reproducible profiles
2758 To reproduce a profile bit-for-bit, we need two pieces of information:
2764 a Guix channel specification.
2767 Indeed, manifests alone might not be enough: different Guix versions (or
2768 different channels) can produce different outputs for a given manifest.
2770 You can output the Guix channel specification with @samp{guix describe
2772 Save this to a file, say @samp{channel-specs.scm}.
2774 On another computer, you can use the channel specification file and the manifest
2775 to reproduce the exact same profile:
2778 GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
2779 GUIX_EXTRA=$HOME/.guix-extra
2781 mkdir "$GUIX_EXTRA"/my-project
2782 guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix"
2784 mkdir -p "$GUIX_EXTRA_PROFILES/my-project"
2785 "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
2788 It's safe to delete the Guix channel profile you've just installed with the
2789 channel specification, the project profile does not depend on it.
2791 @c *********************************************************************
2792 @node Environment management
2793 @chapter Environment management
2795 Guix provides multiple tools to manage environment. This chapter
2796 demonstrate such utilities.
2799 * Guix environment via direnv:: Setup Guix environment with direnv
2802 @node Guix environment via direnv
2803 @section Guix environment via direnv
2805 Guix provides a @samp{direnv} package, which could extend shell after
2806 directory change. This tool could be used to prepare a pure Guix
2809 The following example provides a shell function for @file{~/.direnvrc}
2810 file, which could be used from Guix Git repository in
2811 @file{~/src/guix/.envrc} file to setup a build environment similar to
2812 described in @pxref{Building from Git,,, guix, GNU Guix Reference
2815 Create a @file{~/.direnvrc} with a Bash code:
2818 # Thanks <https://github.com/direnv/direnv/issues/73#issuecomment-152284914>
2822 local alias_dir=$PWD/.direnv/aliases
2823 mkdir -p "$alias_dir"
2824 PATH_add "$alias_dir"
2825 local target="$alias_dir/$name"
2826 if declare -f "$name" >/dev/null; then
2827 echo "#!$SHELL" > "$target"
2828 declare -f "$name" >> "$target" 2>/dev/null
2829 # Notice that we add shell variables to the function trigger.
2830 echo "$name \$*" >> "$target"
2838 export GUIX_GITHUB_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
2840 # Unset 'GUIX_PACKAGE_PATH'.
2841 export GUIX_PACKAGE_PATH=""
2843 # Recreate a garbage collector root.
2844 gcroots="$HOME/.config/guix/gcroots"
2846 gcroot="$gcroots/guix"
2852 # Miscellaneous packages.
2853 PACKAGES_MAINTENANCE=(
2867 # Environment packages.
2868 PACKAGES=(help2man guile-sqlite3 guile-gcrypt)
2870 # Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html>
2871 eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")"
2873 # Predefine configure flags.
2876 ./configure --localstatedir=/var --prefix=
2878 export_function configure
2880 # Run make and optionally build something.
2886 ./pre-inst-env guix build "$@@"
2889 export_function build
2891 # Predefine push Git command.
2894 git push --set-upstream origin
2896 export_function push
2898 clear # Clean up the screen.
2899 git-cal --author='Your Name' # Show contributions calendar.
2901 # Show commands help.
2903 build build a package or just a project if no argument provided
2904 configure run ./configure with predefined parameters
2905 push push to upstream Git repository
2910 Every project containing @file{.envrc} with a string @code{use guix}
2911 will have predefined environment variables and procedures.
2913 Run @command{direnv allow} to setup the environment for the first time.
2915 @c *********************************************************************
2916 @node Acknowledgments
2917 @chapter Acknowledgments
2919 Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
2920 which was designed and
2921 implemented by Eelco Dolstra, with contributions from other people (see
2922 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
2923 management, and promoted unprecedented features, such as transactional
2924 package upgrades and rollbacks, per-user profiles, and referentially
2925 transparent build processes. Without this work, Guix would not exist.
2927 The Nix-based software distributions, Nixpkgs and NixOS, have also been
2928 an inspiration for Guix.
2930 GNU@tie{}Guix itself is a collective work with contributions from a
2931 number of people. See the @file{AUTHORS} file in Guix for more
2932 information on these fine people. The @file{THANKS} file lists people
2933 who have helped by reporting bugs, taking care of the infrastructure,
2934 providing artwork and themes, making suggestions, and more---thank you!
2936 This document includes adapted sections from articles that have previously
2937 been published on the Guix blog at @uref{https://guix.gnu.org/blog}.
2940 @c *********************************************************************
2941 @node GNU Free Documentation License
2942 @appendix GNU Free Documentation License
2943 @cindex license, GNU Free Documentation License
2944 @include fdl-1.3.texi
2946 @c *********************************************************************
2948 @unnumbered Concept Index
2954 @c ispell-local-dictionary: "american";