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@*
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.3 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
22 copy of the license is included in the section entitled ``GNU Free
23 Documentation License''.
26 @dircategory System administration
28 * Guix cookbook: (guix-cookbook). Tutorials and examples for GNU Guix.
32 @title GNU Guix Cookbook
33 @subtitle Tutorials and examples for using the GNU Guix Functional Package Manager
34 @author The GNU Guix Developers
37 @vskip 0pt plus 1filll
44 @c *********************************************************************
46 @top GNU Guix Cookbook
48 This document presents tutorials and detailed examples for GNU@tie{}Guix, a
49 functional package management tool written for the GNU system. Please
50 @pxref{Top,,, guix, GNU Guix reference manual} for details about the system,
51 its API, and related concepts.
53 @c TRANSLATORS: You can replace the following paragraph with information on
54 @c how to join your own translation team and how to report issues with the
56 If you would like to translate this document in your native language, consider
57 joining the @uref{https://translationproject.org/domain/guix-cookbook.html,
61 * Scheme tutorials:: Meet your new favorite language!
62 * Packaging:: Packaging tutorials
63 * System Configuration:: Customizing the GNU System
64 * Advanced package management:: Power to the users!
66 * Acknowledgments:: Thanks!
67 * GNU Free Documentation License:: The license of this document.
68 * Concept Index:: Concepts.
71 --- The Detailed Node Listing ---
75 * A Scheme Crash Course:: Learn the basics of Scheme
79 * Packaging Tutorial:: Let's add a package to Guix!
83 * Customizing the Kernel:: Creating and using a custom Linux kernel
89 @c *********************************************************************
90 @node Scheme tutorials
91 @chapter Scheme tutorials
93 GNU@tie{}Guix is written in the general purpose programming language Scheme,
94 and many of its features can be accessed and manipulated programmatically.
95 You can use Scheme to generate package definitions, to modify them, to build
96 them, to deploy whole operating systems, etc.
98 Knowing the basics of how to program in Scheme will unlock many of the
99 advanced features Guix provides --- and you don't even need to be an
100 experienced programmer to use them!
104 @node A Scheme Crash Course
105 @section A Scheme Crash Course
107 @cindex Scheme, crash course
109 Guix uses the Guile implementation of Scheme. To start playing with the
110 language, install it with @code{guix install guile} and start a
111 @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop,
112 REPL} by running @code{guile} from the command line.
114 Alternatively you can also run @code{guix environment --ad-hoc guile -- guile}
115 if you'd rather not have Guile installed in your user profile.
117 In the following examples, lines show what you would type at the REPL;
118 lines starting with ``@result{}'' show evaluation results, while lines
119 starting with ``@print{}'' show things that get printed. @xref{Using Guile
120 Interactively,,, guile, GNU Guile Reference Manual}), for more details on the
125 Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in
126 Lisp lingo). An expression can be a literal such as numbers and strings, or a
127 compound which is a parenthesized list of compounds and literals. @code{#t}
128 and @code{#f} stand for the Booleans ``true'' and ``false'', respectively.
130 Examples of valid expressions:
134 @result{} "Hello World!"
139 (display (string-append "Hello " "Guix" "\n"))
141 @result{} #<unspecified>
145 This last example is a function call nested in another function call. When a
146 parenthesized expression is evaluated, the first term is the function and the
147 rest are the arguments passed to the function. Every function returns the
148 last evaluated expression as its return value.
151 Anonymous functions are declared with the @code{lambda} term:
155 @result{} #<procedure 120e348 at <unknown port>:24:0 (x)>
158 The above procedure returns the square of its argument. Since everything is
159 an expression, the @code{lambda} expression returns an anonymous procedure,
160 which can in turn be applied to an argument:
163 ((lambda (x) (* x x)) 3)
168 Anything can be assigned a global name with @code{define}:
172 (define square (lambda (x) (* x x)))
178 Procedures can be defined more concisely with the following syntax:
181 (define (square x) (* x x))
185 A list structure can be created with the @code{list} procedure:
193 The @dfn{quote} disables evaluation of a parenthesized expression: the
194 first term is not called over the other terms (@pxref{Expression Syntax,
195 quote,, guile, GNU Guile Reference Manual}). Thus it effectively
196 returns a list of terms.
199 '(display (string-append "Hello " "Guix" "\n"))
200 @result{} (display (string-append "Hello " "Guix" "\n"))
207 The @dfn{quasiquote} disables evaluation of a parenthesized expression
208 until @dfn{unquote} (a comma) re-enables it. Thus it provides us with
209 fine-grained control over what is evaluated and what is not.
212 `(2 a 5 7 (2 ,a 5 ,(+ a 4)))
213 @result{} (2 a 5 7 (2 3 5 7))
216 Note that the above result is a list of mixed elements: numbers, symbols (here
217 @code{a}) and the last element is a list itself.
220 Multiple variables can be named locally with @code{let} (@pxref{Local
221 Bindings,,, guile, GNU Guile Reference Manual}):
234 @error{} In procedure module-lookup: Unbound variable: y
237 Use @code{let*} to allow later variable declarations to refer to earlier
248 The keyword syntax is @code{#:}; it is used to create unique identifiers.
249 @pxref{Keywords,,, guile, GNU Guile Reference Manual}.
252 The percentage @code{%} is typically used for read-only global variables in
253 the build stage. Note that it is merely a convention, like @code{_} in C.
254 Scheme treats @code{%} exactly the same as any other letter.
257 Modules are created with @code{define-module} (@pxref{Creating Guile
258 Modules,,, guile, GNU Guile Reference Manual}). For instance
261 (define-module (guix build-system ruby)
262 #:use-module (guix store)
267 defines the module @code{guix build-system ruby} which must be located in
268 @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It
269 depends on the @code{(guix store)} module and it exports two variables,
270 @code{ruby-build} and @code{ruby-build-system}.
273 For a more detailed introduction, check out
274 @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme
275 at a Glance}, by Steve Litt.
277 One of the reference Scheme books is the seminal ``Structure and
278 Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay
279 Sussman, with Julie Sussman. You'll find a
280 @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy
281 online}, together with
282 @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/,
283 videos of the lectures by the authors}. The book is available in Texinfo
284 format as the @code{sicp} Guix package. Go ahead, run @code{guix install
285 sicp} and start reading with @code{info sicp} (@pxref{,,, sicp, Structure and Interpretation of Computer Programs}).
286 An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also
289 You'll find more books, tutorials and other resources at
290 @url{https://schemers.org/}.
293 @c *********************************************************************
299 This chapter is dedicated to teaching you how to add packages to the
300 collection of packages that come with GNU Guix. This involves writing package
301 definitions in Guile Scheme, organizing them in package modules, and building
305 * Packaging Tutorial:: A tutorial on how to add packages to Guix.
308 @node Packaging Tutorial
309 @section Packaging Tutorial
311 GNU Guix stands out as the @emph{hackable} package manager, mostly because it
312 uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful
313 high-level programming language, one of the
314 @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme}
316 @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}.
318 Package definitions are also written in Scheme, which empowers Guix in some
319 very unique ways, unlike most other package managers that use shell scripts or
324 Use functions, structures, macros and all of Scheme expressiveness for your
328 Inheritance makes it easy to customize a package by inheriting from it and
329 modifying only what is needed.
332 Batch processing: the whole package collection can be parsed, filtered and
333 processed. Building a headless server with all graphical interfaces stripped
334 out? It's possible. Want to rebuild everything from source using specific
335 compiler optimization flags? Pass the @code{#:make-flags "..."} argument to
336 the list of packages. It wouldn't be a stretch to think
337 @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this
338 goes even further: the changes don't have to be thought out beforehand by the
339 packager, they can be @emph{programmed} by the user!
342 The following tutorial covers all the basics around package creation with Guix.
343 It does not assume much knowledge of the Guix system nor of the Lisp language.
344 The reader is only expected to be familiar with the command line and to have some
345 basic programming knowledge.
347 @node A ``Hello World'' package
348 @subsection A ``Hello World'' package
350 The ``Defining Packages'' section of the manual introduces the basics of Guix
351 packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In
352 the following section, we will partly go over those basics again.
354 GNU@tie{}Hello is a dummy project that serves as an idiomatic example for
355 packaging. It uses the GNU build system (@code{./configure && make && make
356 install}). Guix already provides a package definition which is a perfect
357 example to start with. You can look up its declaration with @code{guix edit
358 hello} from the command line. Let's see how it looks:
367 (uri (string-append "mirror://gnu/hello/hello-" version
371 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
372 (build-system gnu-build-system)
373 (synopsis "Hello, GNU world: An example GNU package")
375 "GNU Hello prints the message \"Hello, world!\" and then exits. It
376 serves as an example of standard GNU coding practices. As such, it supports
377 command-line arguments, multiple languages, and so on.")
378 (home-page "https://www.gnu.org/software/hello/")
382 As you can see, most of it is rather straightforward. But let's review the
387 The project name. Using Scheme conventions, we prefer to keep it
388 lower case, without underscore and using dash-separated words.
391 This field contains a description of the source code origin. The
392 @code{origin} record contains these fields:
395 @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods
396 exist, such as @code{git-fetch} for Git repositories.
397 @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here
398 the special `mirror://gnu` refers to a set of well known locations, all of
399 which can be used by Guix to fetch the source, should some of them fail.
400 @item The @code{sha256} checksum of the requested file. This is essential to ensure
401 the source is not corrupted. Note that Guix works with base32 strings,
402 hence the call to the @code{base32} function.
407 This is where the power of abstraction provided by the Scheme language really
408 shines: in this case, the @code{gnu-build-system} abstracts away the famous
409 @code{./configure && make && make install} shell invocations. Other build
410 systems include the @code{trivial-build-system} which does not do anything and
411 requires from the packager to program all the build steps, the
412 @code{python-build-system}, the @code{emacs-build-system}, and many more
413 (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}).
416 It should be a concise summary of what the package does. For many packages a
417 tagline from the project's home page can be used as the synopsis.
420 Same as for the synopsis, it's fine to re-use the project description from the
421 homepage. Note that Guix uses Texinfo syntax.
424 Use HTTPS if available.
427 See @code{guix/licenses.scm} in the project source for a full list of
431 Time to build our first package! Nothing fancy here for now: we will stick to a
432 dummy @code{my-hello}, a copy of the above declaration.
434 As with the ritualistic ``Hello World'' taught with most programming languages,
435 this will possibly be the most ``manual'' approach. We will work out an ideal
436 setup later; for now we will go the simplest route.
438 Save the following to a file @file{my-hello.scm}.
441 (use-modules (guix packages)
443 (guix build-system gnu)
451 (uri (string-append "mirror://gnu/hello/hello-" version
455 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
456 (build-system gnu-build-system)
457 (synopsis "Hello, Guix world: An example custom Guix package")
459 "GNU Hello prints the message \"Hello, world!\" and then exits. It
460 serves as an example of standard GNU coding practices. As such, it supports
461 command-line arguments, multiple languages, and so on.")
462 (home-page "https://www.gnu.org/software/hello/")
466 We will explain the extra code in a moment.
468 Feel free to play with the different values of the various fields. If you
469 change the source, you'll need to update the checksum. Indeed, Guix refuses to
470 build anything if the given checksum does not match the computed checksum of the
471 source code. To obtain the correct checksum of the package declaration, we
472 need to download the source, compute the sha256 checksum and convert it to
475 Thankfully, Guix can automate this task for us; all we need is to provide the
478 @c TRANSLATORS: This is example shell output.
480 $ guix download mirror://gnu/hello/hello-2.10.tar.gz
482 Starting download of /tmp/guix-file.JLYgL7
483 From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...
484 following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...
485 …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0%
486 /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
487 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
490 In this specific case the output tells us which mirror was chosen.
491 If the result of the above command is not the same as in the above snippet,
492 update your @code{my-hello} declaration accordingly.
494 Note that GNU package tarballs come with an OpenPGP signature, so you
495 should definitely check the signature of this tarball with `gpg` to
496 authenticate it before going further:
498 @c TRANSLATORS: This is example shell output.
500 $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig
502 Starting download of /tmp/guix-file.03tFfb
503 From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...
504 following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...
505 ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0%
506 /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig
507 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf
508 $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
509 gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET
510 gpg: using RSA key A9553245FDE9B739
511 gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown]
512 gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown]
513 gpg: WARNING: This key is not certified with a trusted signature!
514 gpg: There is no indication that the signature belongs to the owner.
515 Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739
518 You can then happily run
520 @c TRANSLATORS: Do not translate this command
522 $ guix package --install-from-file=my-hello.scm
525 You should now have @code{my-hello} in your profile!
527 @c TRANSLATORS: Do not translate this command
529 $ guix package --list-installed=my-hello
531 /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10
534 We've gone as far as we could without any knowledge of Scheme. Before moving
535 on to more complex packages, now is the right time to brush up on your Scheme
536 knowledge. @pxref{A Scheme Crash Course} to get up to speed.
541 In the rest of this chapter we will rely on some basic Scheme
542 programming knowledge. Now let's detail the different possible setups
543 for working on Guix packages.
545 There are several ways to set up a Guix packaging environment.
547 We recommend you work directly on the Guix source checkout since it makes it
548 easier for everyone to contribute to the project.
550 But first, let's look at other possibilities.
553 @subsubsection Local file
555 This is what we previously did with @samp{my-hello}. With the Scheme basics we've
556 covered, we are now able to explain the leading chunks. As stated in @code{guix
560 -f, --install-from-file=FILE
561 install the package that the code within FILE
565 Thus the last expression @emph{must} return a package, which is the case in our
568 The @code{use-modules} expression tells which of the modules we need in the file.
569 Modules are a collection of values and procedures. They are commonly called
570 ``libraries'' or ``packages'' in other programming languages.
572 @node @samp{GUIX_PACKAGE_PATH}
573 @subsubsection @samp{GUIX_PACKAGE_PATH}
575 @emph{Note: Starting from Guix 0.16, the more flexible Guix @dfn{channels} are the
576 preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section.}
578 It can be tedious to specify the file from the command line instead of simply
579 calling @code{guix package --install my-hello} as you would do with the official
582 Guix makes it possible to streamline the process by adding as many ``package
583 declaration directories'' as you want.
585 Create a directory, say @file{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH}
586 environment variable:
589 $ mkdir ~/guix-packages
590 $ export GUIX_PACKAGE_PATH=~/guix-packages
593 To add several directories, separate them with a colon (@code{:}).
595 Our previous @samp{my-hello} needs some adjustments though:
598 (define-module (my-hello)
599 #:use-module (guix licenses)
600 #:use-module (guix packages)
601 #:use-module (guix build-system gnu)
602 #:use-module (guix download))
604 (define-public my-hello
610 (uri (string-append "mirror://gnu/hello/hello-" version
614 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
615 (build-system gnu-build-system)
616 (synopsis "Hello, Guix world: An example custom Guix package")
618 "GNU Hello prints the message \"Hello, world!\" and then exits. It
619 serves as an example of standard GNU coding practices. As such, it supports
620 command-line arguments, multiple languages, and so on.")
621 (home-page "https://www.gnu.org/software/hello/")
625 Note that we have assigned the package value to an exported variable name with
626 @code{define-public}. This is effectively assigning the package to the @code{my-hello}
627 variable so that it can be referenced, among other as dependency of other
630 If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it
631 will fail because the last expression, @code{define-public}, does not return a
632 package. If you want to use @code{define-public} in this use-case nonetheless, make
633 sure the file ends with an evaluation of @code{my-hello}:
637 (define-public my-hello
644 This last example is not very typical.
646 Now @samp{my-hello} should be part of the package collection like all other official
647 packages. You can verify this with:
650 $ guix package --show=my-hello
654 @subsubsection Guix channels
656 Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but
657 provides better integration and provenance tracking. Channels are not
658 necessarily local, they can be maintained as a public Git repository for
659 instance. Of course, several channels can be used at the same time.
661 @xref{Channels,,, guix, GNU Guix Reference Manual} for setup details.
663 @node Direct checkout hacking
664 @subsubsection Direct checkout hacking
666 Working directly on the Guix project is recommended: it reduces the friction
667 when the time comes to submit your changes upstream to let the community benefit
670 Unlike most software distributions, the Guix repository holds in one place both
671 the tooling (including the package manager) and the package definitions. This
672 choice was made so that it would give developers the flexibility to modify the
673 API without breakage by updating all packages at the same time. This reduces
676 Check out the official @uref{https://git-scm.com/, Git} repository:
679 $ git clone https://git.savannah.gnu.org/git/guix.git
682 In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of
686 Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix
687 Reference Manual}) to set up the repository environment.
689 Once ready, you should be able to use the package definitions from the
690 repository environment.
692 Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}.
694 The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package
695 collection of the repository (@pxref{Running Guix Before It Is
696 Installed,,, guix, GNU Guix Reference Manual}).
700 Search packages, such as Ruby:
704 $ ./pre-inst-env guix package --list-available=ruby
705 ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2
706 ruby 2.1.6 out gnu/packages/ruby.scm:91:2
707 ruby 2.2.2 out gnu/packages/ruby.scm:39:2
711 Build a package, here Ruby version 2.1:
714 $ ./pre-inst-env guix build --keep-failed ruby@@2.1
715 /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6
719 Install it to your user profile:
722 $ ./pre-inst-env guix package --install ruby@@2.1
726 Check for common mistakes:
729 $ ./pre-inst-env guix lint ruby@@2.1
733 Guix strives at maintaining a high packaging standard; when contributing to the
734 Guix project, remember to
738 follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}),
740 and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual}).
743 Once you are happy with the result, you are welcome to send your contribution to
744 make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual})
747 It's a community effort so the more join in, the better Guix becomes!
749 @node Extended example
750 @subsection Extended example
752 The above ``Hello World'' example is as simple as it goes. Packages can be more
753 complex than that and Guix can handle more advanced scenarios. Let's look at
754 another, more sophisticated package (slightly modified from the source):
757 (define-module (gnu packages version-control)
758 #:use-module ((guix licenses) #:prefix license:)
759 #:use-module (guix utils)
760 #:use-module (guix packages)
761 #:use-module (guix git-download)
762 #:use-module (guix build-system cmake)
763 #:use-module (gnu packages ssh)
764 #:use-module (gnu packages web)
765 #:use-module (gnu packages pkg-config)
766 #:use-module (gnu packages python)
767 #:use-module (gnu packages compression)
768 #:use-module (gnu packages tls))
770 (define-public my-libgit2
771 (let ((commit "e98d0a37c93574d2c6107bf7f31140b548c6a7bf")
775 (version (git-version "0.26.6" revision commit))
779 (url "https://github.com/libgit2/libgit2/")
781 (file-name (git-file-name name version))
784 "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3"))
785 (patches (search-patches "libgit2-mtime-0.patch"))
786 (modules '((guix build utils)))
788 ;; Remove bundled software.
789 (delete-file-recursively "deps")
791 (build-system cmake-build-system)
792 (outputs '("out" "debug"))
794 `(#:tests? #t ; Run the test suite (this is the default)
795 #:configure-flags '("-DUSE_SHA1DC=ON") ; SHA-1 collision detection
797 (modify-phases %standard-phases
798 (add-after 'unpack 'fix-hardcoded-paths
800 (substitute* "tests/repo/init.c"
801 (("#!/bin/sh") (string-append "#!" (which "sh"))))
802 (substitute* "tests/clar/fs.h"
803 (("/bin/cp") (which "cp"))
804 (("/bin/rm") (which "rm")))
806 ;; Run checks more verbosely.
808 (lambda _ (invoke "./libgit2_clar" "-v" "-Q")))
809 (add-after 'unpack 'make-files-writable-for-tests
810 (lambda _ (for-each make-file-writable (find-files "." ".*")))))))
812 `(("libssh2" ,libssh2)
813 ("http-parser" ,http-parser)
814 ("python" ,python-wrapper)))
816 `(("pkg-config" ,pkg-config)))
818 ;; These two libraries are in 'Requires.private' in libgit2.pc.
819 `(("openssl" ,openssl)
821 (home-page "https://libgit2.github.com/")
822 (synopsis "Library providing Git core methods")
824 "Libgit2 is a portable, pure C implementation of the Git core methods
825 provided as a re-entrant linkable library with a solid API, allowing you to
826 write native speed custom Git applications in any language with bindings.")
827 ;; GPLv2 with linking exception
828 (license license:gpl2))))
831 (In those cases were you only want to tweak a few fields from a package
832 definition, you should rely on inheritance instead of copy-pasting everything.
835 Let's discuss those fields in depth.
837 @subsubsection @code{git-fetch} method
839 Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes
840 a Git repository and a commit. The commit can be any Git reference such as
841 tags, so if the @code{version} is tagged, then it can be used directly. Sometimes
842 the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append
845 To ensure that the source code from the Git repository is stored in a unique
846 directory with a readable name we use @code{(file-name (git-file-name name
849 Note that there is also a @code{git-version} procedure that can be used to derive the
850 version when packaging programs for a specific commit.
852 @subsubsection Snippets
854 Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching
855 the source. They are a Guix-y alternative to the traditional @file{.patch} files.
856 Because of the quote, the code in only evaluated when passed to the Guix daemon
857 for building. There can be as many snippets as needed.
859 Snippets might need additional Guile modules which can be imported from the
860 @code{modules} field.
862 @subsubsection Inputs
864 First, a syntactic comment: See the quasi-quote / comma syntax?
868 `(("pkg-config" ,pkg-config)))
875 (list (list "pkg-config" pkg-config)))
878 You'll mostly see the former because it's shorter.
880 There are 3 different input types. In short:
884 Required for building but not runtime -- installing a package
885 through a substitute won't install these inputs.
887 Installed in the store but not in the profile, as well as being
888 present at build time.
889 @item propagated-inputs
890 Installed in the store and in the profile, as well as
891 being present at build time.
894 @xref{Package Reference,,, guix, GNU Guix Reference Manual} for more details.
896 The distinction between the various inputs is important: if a dependency can be
897 handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or
898 else it ``pollutes'' the user profile for no good reason.
900 For instance, a user installing a graphical program that depends on a
901 command line tool might only be interested in the graphical part, so there is no
902 need to force the command line tool into the user profile. The dependency is a
903 concern to the package, not to the user. @emph{Inputs} make it possible to handle
904 dependencies without bugging the user by adding undesired executable files (or
905 libraries) to their profile.
907 Same goes for @emph{native-inputs}: once the program is installed, build-time
908 dependencies can be safely garbage-collected.
909 It also matters when a substitute is available, in which case only the @emph{inputs}
910 and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to
911 install a package from a substitute.
913 @subsubsection Outputs
915 Just like how a package can have multiple inputs, it can also produce multiple
918 Each output corresponds to a separate directory in the store.
920 The user can choose which output to install; this is useful to save space or
921 to avoid polluting the user profile with unwanted executables or libraries.
923 Output separation is optional. When the @code{outputs} field is left out, the
924 default and only output (the complete package) is referred to as @code{"out"}.
926 Typical separate output names include @code{debug} and @code{doc}.
928 It's advised to separate outputs only when you've shown it's worth it: if the
929 output size is significant (compare with @code{guix size}) or in case the package is
932 @subsubsection Build system arguments
934 The @code{arguments} is a keyword-value list used to configure the build process.
936 The simplest argument @code{#:tests?} can be used to disable the test suite when
937 building the package. This is mostly useful when the package does not feature
938 any test suite. It's strongly recommended to keep the test suite on if there is
941 Another common argument is @code{:make-flags}, which specifies a list of flags to
942 append when running make, as you would from the command line. For instance, the
946 #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out"))
953 $ make CC=gcc prefix=/gnu/store/...-<out>
956 This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation
957 directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage
958 global variable pointing to the destination directory in the store (something like
959 @file{/gnu/store/...-my-libgit2-20180408}).
961 Similarly, it's possible to set the configure flags:
964 #:configure-flags '("-DUSE_SHA1DC=ON")
967 The @code{%build-inputs} variable is also generated in scope. It's an association
968 table that maps the input names to their store directories.
970 The @code{phases} keyword lists the sequential steps of the build system. Typically
971 phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know
972 more about those phases, you need to work out the appropriate build system
973 definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}:
976 (define %standard-phases
977 ;; Standard build phases, as a list of symbol/procedure pairs.
978 (let-syntax ((phases (syntax-rules ()
979 ((_ p ...) `((p . ,p) ...)))))
980 (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack
983 patch-source-shebangs configure patch-generated-file-shebangs
987 validate-documentation-location
989 patch-dot-desktop-files
990 install-license-files
991 reset-gzip-timestamps
992 compress-documentation)))
998 (add-to-load-path "/path/to/guix/checkout")
999 ,use (guix build gnu-build-system)
1000 (map first %standard-phases)
1001 @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)
1004 If you want to know more about what happens during those phases, consult the
1005 associated procedures.
1007 For instance, as of this writing the definition of @code{unpack} for the GNU build
1011 (define* (unpack #:key source #:allow-other-keys)
1012 "Unpack SOURCE in the working directory, and change directory within the
1013 source. When SOURCE is a directory, copy it in a sub-directory of the current
1015 (if (file-is-directory? source)
1020 ;; Preserve timestamps (set to the Epoch) on the copied tree so that
1021 ;; things work deterministically.
1022 (copy-recursively source "."
1025 (if (string-suffix? ".zip" source)
1026 (invoke "unzip" source)
1027 (invoke "tar" "xvf" source))
1028 (chdir (first-subdirectory "."))))
1032 Note the @code{chdir} call: it changes the working directory to where the source was
1034 Thus every phase following the @code{unpack} will use the source as a working
1035 directory, which is why we can directly work on the source files.
1036 That is to say, unless a later phase changes the working directory to something
1039 We modify the list of @code{%standard-phases} of the build system with the
1040 @code{modify-phases} macro as per the list of specified modifications, which may have
1041 the following forms:
1045 @code{(add-before PHASE NEW-PHASE PROCEDURE)}: Run @code{PROCEDURE} named @code{NEW-PHASE} before @code{PHASE}.
1047 @code{(add-after PHASE NEW-PHASE PROCEDURE)}: Same, but afterwards.
1049 @code{(replace PHASE PROCEDURE)}.
1051 @code{(delete PHASE)}.
1054 The @code{PROCEDURE} supports the keyword arguments @code{inputs} and @code{outputs}. Each
1055 input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced
1056 by their name in those variables. Thus @code{(assoc-ref outputs "out")} is the store
1057 directory of the main output of the package. A phase procedure may look like
1061 (lambda* (#:key inputs outputs #:allow-other-keys)
1062 (let (((bash-directory (assoc-ref inputs "bash"))
1063 (output-directory (assoc-ref outputs "out"))
1064 (doc-directory (assoc-ref outputs "doc"))
1069 The procedure must return @code{#t} on success. It's brittle to rely on the return
1070 value of the last expression used to tweak the phase because there is no
1071 guarantee it would be a @code{#t}. Hence the trailing @code{#t} to ensure the right value
1072 is returned on success.
1074 @subsubsection Code staging
1076 The astute reader may have noticed the quasi-quote and comma syntax in the
1077 argument field. Indeed, the build code in the package declaration should not be
1078 evaluated on the client side, but only when passed to the Guix daemon. This
1079 mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}.
1081 @subsubsection Utility functions
1083 When customizing @code{phases}, we often need to write code that mimics the
1084 equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during
1085 regular ``Unix-style'' installations.
1087 Some like @code{chmod} are native to Guile.
1088 @xref{,,, guile, Guile reference manual} for a complete list.
1090 Guix provides additional helper functions which prove especially handy in the
1091 context of package management.
1093 Some of those functions can be found in
1094 @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour
1095 of the traditional Unix system commands:
1099 Like the @samp{which} system command.
1101 Akin to the @samp{find} system command.
1103 Like @samp{mkdir -p}, which creates all parents as needed.
1105 Similar to @samp{install} when installing a file to a (possibly
1106 non-existing) directory. Guile has @code{copy-file} which works
1108 @item copy-recursively
1110 @item delete-file-recursively
1113 Run an executable. This should be used instead of @code{system*}.
1114 @item with-directory-excursion
1115 Run the body in a different working directory,
1116 then restore the previous working directory.
1118 A ``@command{sed}-like'' function.
1121 @subsubsection Module prefix
1123 The license in our last example needs a prefix: this is because of how the
1124 @code{license} module was imported in the package, as @code{#:use-module ((guix licenses)
1125 #:prefix license:)}. The Guile module import mechanism
1126 (@pxref{Using Guile Modules,,, guile, Guile reference manual})
1127 gives the user full control over namespacing: this is needed to avoid
1128 clashes between, say, the
1129 @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable
1130 from @samp{compression.scm} (a @emph{package} value).
1132 @node Other build systems
1133 @subsection Other build systems
1135 What we've seen so far covers the majority of packages using a build system
1136 other than the @code{trivial-build-system}. The latter does not automate anything
1137 and leaves you to build everything manually. This can be more demanding and we
1138 won't cover it here for now, but thankfully it is rarely necessary to fall back
1141 For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the
1142 process is very similar to the GNU build system except for a few specialized
1145 @xref{Build Systems,,, guix, GNU Guix Reference Manual}, for more
1146 information on build systems, or check the source code in the
1147 @samp{$GUIX_CHECKOUT/guix/build} and
1148 @samp{$GUIX_CHECKOUT/guix/build-system} directories.
1150 @node Programmable and automated package definition
1151 @subsection Programmable and automated package definition
1153 We can't repeat it enough: having a full-fledged programming language at hand
1154 empowers us in ways that reach far beyond traditional package management.
1156 Let's illustrate this with some awesome features of Guix!
1158 @node Recursive importers
1159 @subsubsection Recursive importers
1161 You might find some build systems good enough that there is little to do at all
1162 to write a package, to the point that it becomes repetitive and tedious after a
1163 while. A @emph{raison d'être} of computers is to replace human beings at those
1164 boring tasks. So let's tell Guix to do this for us and create the package
1165 definition of an R package from CRAN (the output is trimmed for conciseness):
1168 $ guix import cran --recursive walrus
1170 (define-public r-mc2d
1174 (define-public r-jmvcore
1178 (define-public r-wrs2
1182 (define-public r-walrus
1189 (uri (cran-uri "walrus" version))
1192 "1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj"))))
1193 (build-system r-build-system)
1195 `(("r-ggplot2" ,r-ggplot2)
1196 ("r-jmvcore" ,r-jmvcore)
1198 ("r-wrs2" ,r-wrs2)))
1199 (home-page "https://github.com/jamovi/walrus")
1200 (synopsis "Robust Statistical Methods")
1202 "This package provides a toolbox of common robust statistical
1203 tests, including robust descriptives, robust t-tests, and robust ANOVA.
1204 It is also available as a module for 'jamovi' (see
1205 <https://www.jamovi.org> for more information). Walrus is based on the
1206 WRS2 package by Patrick Mair, which is in turn based on the scripts and
1207 work of Rand Wilcox. These analyses are described in depth in the book
1208 'Introduction to Robust Estimation & Hypothesis Testing'.")
1212 The recursive importer won't import packages for which Guix already has package
1213 definitions, except for the very first.
1215 Not all applications can be packaged this way, only those relying on a select
1216 number of supported systems. Read about the full list of importers in
1217 the guix import section of the manual
1218 (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual}).
1220 @node Automatic update
1221 @subsubsection Automatic update
1223 Guix can be smart enough to check for updates on systems it knows. It can
1224 report outdated package definitions with
1227 $ guix refresh hello
1230 In most cases, updating a package to a newer version requires little more than
1231 changing the version number and the checksum. Guix can do that automatically as
1235 $ guix refresh hello --update
1239 @subsubsection Inheritance
1241 If you've started browsing the existing package definitions, you might have
1242 noticed that a significant number of them have a @code{inherit} field:
1245 (define-public adwaita-icon-theme
1246 (package (inherit gnome-icon-theme)
1247 (name "adwaita-icon-theme")
1251 (uri (string-append "mirror://gnome/sources/" name "/"
1252 (version-major+minor version) "/"
1253 name "-" version ".tar.xz"))
1256 "17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8"))))
1258 `(("gtk-encode-symbolic-svg" ,gtk+ "bin")))))
1261 All unspecified fields are inherited from the parent package. This is very
1262 convenient to create alternative packages, for instance with different source,
1263 version or compilation options.
1266 @subsection Getting help
1268 Sadly, some applications can be tough to package. Sometimes they need a patch to
1269 work with the non-standard filesystem hierarchy enforced by the store.
1270 Sometimes the tests won't run properly. (They can be skipped but this is not
1271 recommended.) Other times the resulting package won't be reproducible.
1273 Should you be stuck, unable to figure out how to fix any sort of packaging
1274 issue, don't hesitate to ask the community for help.
1276 See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc.
1279 @subsection Conclusion
1281 This tutorial was a showcase of the sophisticated package management that Guix
1282 boasts. At this point we have mostly restricted this introduction to the
1283 @code{gnu-build-system} which is a core abstraction layer on which more advanced
1284 abstractions are based.
1286 Where do we go from here? Next we ought to dissect the innards of the build
1287 system by removing all abstractions, using the @code{trivial-build-system}: this
1288 should give us a thorough understanding of the process before investigating some
1289 more advanced packaging techniques and edge cases.
1291 Other features worth exploring are the interactive editing and debugging
1292 capabilities of Guix provided by the Guile REPL@.
1294 Those fancy features are completely optional and can wait; now is a good time
1295 to take a well-deserved break. With what we've introduced here you should be
1296 well armed to package lots of programs. You can get started right away and
1297 hopefully we will see your contributions soon!
1300 @subsection References
1304 The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual}
1307 @uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix}
1310 @uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, ``GNU Guix: Package without a scheme!''}, by Andreas Enge
1313 @c *********************************************************************
1314 @node System Configuration
1315 @chapter System Configuration
1317 Guix offers a flexible language for declaratively configuring your Guix
1318 System. This flexibility can at times be overwhelming. The purpose of this
1319 chapter is to demonstrate some advanced configuration concepts.
1321 @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete
1325 * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
1326 * Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
1327 * Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
1330 @node Customizing the Kernel
1331 @section Customizing the Kernel
1333 Guix is, at its core, a source based distribution with substitutes
1334 (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building
1335 packages from their source code is an expected part of regular package
1336 installations and upgrades. Given this starting point, it makes sense that
1337 efforts are made to reduce the amount of time spent compiling packages, and
1338 recent changes and upgrades to the building and distribution of substitutes
1339 continues to be a topic of discussion within Guix.
1341 The kernel, while not requiring an overabundance of RAM to build, does take a
1342 rather long time on an average machine. The official kernel configuration, as
1343 is the case with many GNU/Linux distributions, errs on the side of
1344 inclusiveness, and this is really what causes the build to take such a long
1345 time when the kernel is built from source.
1347 The Linux kernel, however, can also just be described as a regular old
1348 package, and as such can be customized just like any other package. The
1349 procedure is a little bit different, although this is primarily due to the
1350 nature of how the package definition is written.
1352 The @code{linux-libre} kernel package definition is actually a procedure which
1356 (define* (make-linux-libre version hash supported-systems
1358 ;; A function that takes an arch and a variant.
1359 ;; See kernel-config for an example.
1361 (configuration-file #f)
1362 (defconfig "defconfig")
1363 (extra-options %default-extra-linux-options)
1364 (patches (list %boot-logo-patch)))
1368 The current @code{linux-libre} package is for the 5.1.x series, and is
1372 (define-public linux-libre
1373 (make-linux-libre %linux-libre-version
1375 '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux")
1376 #:patches %linux-libre-5.1-patches
1377 #:configuration-file kernel-config))
1380 Any keys which are not assigned values inherit their default value from the
1381 @code{make-linux-libre} definition. When comparing the two snippets above,
1382 you may notice that the code comment in the first doesn't actually refer to
1383 the @code{#:extra-version} keyword; it is actually for
1384 @code{#:configuration-file}. Because of this, it is not actually easy to
1385 include a custom kernel configuration from the definition, but don't worry,
1386 there are other ways to work with what we do have.
1388 There are two ways to create a kernel with a custom kernel configuration. The
1389 first is to provide a standard @file{.config} file during the build process by
1390 including an actual @file{.config} file as a native input to our custom
1391 kernel. The following is a snippet from the custom @code{'configure} phase of
1392 the @code{make-linux-libre} package definition:
1395 (let ((build (assoc-ref %standard-phases 'build))
1396 (config (assoc-ref (or native-inputs inputs) "kconfig")))
1398 ;; Use a custom kernel configuration file or a default
1399 ;; configuration file.
1402 (copy-file config ".config")
1403 (chmod ".config" #o666))
1404 (invoke "make" ,defconfig))
1407 Below is a sample kernel package. The @code{linux-libre} package is nothing
1408 special and can be inherited from and have its fields overridden like any
1412 (define-public linux-libre/E2140
1414 (inherit linux-libre)
1416 `(("kconfig" ,(local-file "E2140.config"))
1417 ,@@(alist-delete "kconfig"
1418 (package-native-inputs linux-libre))))))
1421 In the same directory as the file defining @code{linux-libre-E2140} is a file
1422 named @file{E2140.config}, which is an actual kernel configuration file. The
1423 @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the
1424 only kernel configuration in the package is the one which was included in the
1425 @code{native-inputs} field.
1427 The second way to create a custom kernel is to pass a new value to the
1428 @code{extra-options} keyword of the @code{make-linux-libre} procedure. The
1429 @code{extra-options} keyword works with another function defined right below
1433 (define %default-extra-linux-options
1434 `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
1435 ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t)
1436 ;; Modules required for initrd:
1437 ("CONFIG_NET_9P" . m)
1438 ("CONFIG_NET_9P_VIRTIO" . m)
1439 ("CONFIG_VIRTIO_BLK" . m)
1440 ("CONFIG_VIRTIO_NET" . m)
1441 ("CONFIG_VIRTIO_PCI" . m)
1442 ("CONFIG_VIRTIO_BALLOON" . m)
1443 ("CONFIG_VIRTIO_MMIO" . m)
1444 ("CONFIG_FUSE_FS" . m)
1446 ("CONFIG_9P_FS" . m)))
1448 (define (config->string options)
1449 (string-join (map (match-lambda
1451 (string-append option "=m"))
1453 (string-append option "=y"))
1455 (string-append option "=n")))
1460 And in the custom configure script from the `make-linux-libre` package:
1463 ;; Appending works even when the option wasn't in the
1464 ;; file. The last one prevails if duplicated.
1465 (let ((port (open-file ".config" "a"))
1466 (extra-configuration ,(config->string extra-options)))
1467 (display extra-configuration port)
1470 (invoke "make" "oldconfig"))))
1473 So by not providing a configuration-file the @file{.config} starts blank, and
1474 then we write into it the collection of flags that we want. Here's another
1478 (define %macbook41-full-config
1479 (append %macbook41-config-options
1483 (@@@@ (gnu packages linux) %default-extra-linux-options)))
1485 (define-public linux-libre-macbook41
1486 ;; XXX: Access the internal 'make-linux-libre' procedure, which is
1487 ;; private and unexported, and is liable to change in the future.
1488 ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux) %linux-libre-version)
1489 (@@@@ (gnu packages linux) %linux-libre-hash)
1491 #:extra-version "macbook41"
1492 #:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches)
1493 #:extra-options %macbook41-config-options))
1496 In the above example @code{%filesystems} is a collection of flags enabling
1497 different filesystem support, @code{%efi-support} enables EFI support and
1498 @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also.
1499 @code{%default-extra-linux-options} are the ones quoted above, which had to be
1500 added in since they were replaced in the @code{extra-options} keyword.
1502 This all sounds like it should be doable, but how does one even know which
1503 modules are required for a particular system? Two places that can be helpful
1504 in trying to answer this question is the
1505 @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo
1507 @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig,
1508 documentation from the kernel itself}. From the kernel documentation, it
1509 seems that @code{make localmodconfig} is the command we want.
1511 In order to actually run @code{make localmodconfig} we first need to get and
1512 unpack the kernel source code:
1515 tar xf $(guix build linux-libre --source)
1518 Once inside the directory containing the source code run @code{touch .config}
1519 to create an initial, empty @file{.config} to start with. @code{make
1520 localmodconfig} works by seeing what you already have in @file{.config} and
1521 letting you know what you're missing. If the file is blank then you're
1522 missing everything. The next step is to run:
1525 guix environment linux-libre -- make localmodconfig
1528 and note the output. Do note that the @file{.config} file is still empty.
1529 The output generally contains two types of warnings. The first start with
1530 "WARNING" and can actually be ignored in our case. The second read:
1533 module pcspkr did not have configs CONFIG_INPUT_PCSPKR
1536 For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the
1537 @file{.config} in the directory, and append @code{=m}, so in the end it looks
1541 CONFIG_INPUT_PCSPKR=m
1545 After copying all the configuration options, run @code{make localmodconfig}
1546 again to make sure that you don't have any output starting with ``module''.
1547 After all of these machine specific modules there are a couple more left that
1548 are also needed. @code{CONFIG_MODULES} is necessary so that you can build and
1549 load modules separately and not have everything built into the kernel.
1550 @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is
1551 possible that there are other modules which you will need.
1553 This post does not aim to be a guide to configuring your own kernel however,
1554 so if you do decide to build a custom kernel you'll have to seek out other
1555 guides to create a kernel which is just right for your needs.
1557 The second way to setup the kernel configuration makes more use of Guix's
1558 features and allows you to share configuration segments between different
1559 kernels. For example, all machines using EFI to boot have a number of EFI
1560 configuration flags that they need. It is likely that all the kernels will
1561 share a list of filesystems to support. By using variables it is easier to
1562 see at a glance what features are enabled and to make sure you don't have
1563 features in one kernel but missing in another.
1565 Left undiscussed however, is Guix's initrd and its customization. It is
1566 likely that you'll need to modify the initrd on a machine using a custom
1567 kernel, since certain modules which are expected to be built may not be
1568 available for inclusion into the initrd.
1570 @node Customizing a Window Manager
1571 @section Customizing a Window Manager
1578 You could install StumpWM with a Guix system by adding
1579 @code{stumpwm} and optionally @code{`(,stumpwm "lib")}
1580 packages to a system configuration file, e.g.@: @file{/etc/config.scm}.
1582 An example configuration can look like this:
1586 (use-package-modules wm)
1590 (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
1594 @cindex stumpwm fonts
1595 By default StumpWM uses X11 fonts, which could be small or pixelated on
1596 your system. You could fix this by installing StumpWM contrib Lisp
1597 module @code{sbcl-ttf-fonts}, adding it to Guix system packages:
1601 (use-package-modules fonts wm)
1605 (packages (append (list sbcl stumpwm `(,stumpwm "lib"))
1606 sbcl-ttf-fonts font-dejavu %base-packages)))
1609 Then you need to add the following code to a StumpWM configuration file
1610 @file{~/.stumpwm.d/init.lisp}:
1613 (require :ttf-fonts)
1614 (setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/"))
1615 (setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp"))
1617 (set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11))
1620 @node Setting up a bind mount
1621 @section Setting up a bind mount
1623 To bind mount a file system, one must first set up some definitions
1624 before the @code{operating-system} section of the system definition. In
1625 this example we will bind mount a folder from a spinning disk drive to
1626 @file{/tmp}, to save wear and tear on the primary SSD, without
1627 dedicating an entire partition to be mounted as @file{/tmp}.
1629 First, the source drive that hosts the folder we wish to bind mount
1630 should be defined, so that the bind mount can depend on it.
1633 (define source-drive ;; "source-drive" can be named anything you want.
1635 (device (uuid "UUID goes here"))
1636 (mount-point "/path-to-spinning-disk-goes-here")
1637 (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive.
1640 The source folder must also be defined, so that guix will know it's not
1641 a regular block device, but a folder.
1643 (define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name.
1646 Finally, inside the @code{file-systems} definition, we must add the
1650 (file-systems (cons*
1652 ...<other drives omitted for clarity>...
1654 source-drive ;; Must match the name you gave the source drive in the earlier definition.
1657 (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition.
1658 (mount-point "/tmp")
1659 (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none"
1660 (flags '(bind-mount))
1661 (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive.
1664 ...<other drives omitted for clarity>...
1669 @c *********************************************************************
1670 @node Advanced package management
1671 @chapter Advanced package management
1673 Guix is a functional package manager that offers many features beyond
1674 what more traditional package managers can do. To the uninitiated,
1675 those features might not have obvious use cases at first. The purpose
1676 of this chapter is to demonstrate some advanced package management
1679 @pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete
1683 * Guix Profiles in Practice:: Strategies for multiple profiles and manifests.
1686 @node Guix Profiles in Practice
1687 @section Guix Profiles in Practice
1689 Guix provides a very useful feature that may be quite foreign to newcomers:
1690 @emph{profiles}. They are a way to group package installations together and all users
1691 on the same system are free to use as many profiles as they want.
1693 Whether you're a developer or not, you may find that multiple profiles bring you
1694 great power and flexibility. While they shift the paradigm somewhat compared to
1695 @emph{traditional package managers}, they are very convenient to use once you've
1696 understood how to set them up.
1698 If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a
1699 kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not
1700 just Python software. Furthermore, profiles are self-sufficient: they capture
1701 all the runtime dependencies which guarantees that all programs within a profile
1702 will always work at any point in time.
1704 Multiple profiles have many benefits:
1708 Clean semantic separation of the various packages a user needs for different contexts.
1711 Multiple profiles can be made available into the environment either on login
1712 or within a dedicated shell.
1715 Profiles can be loaded on demand. For instance, the user can use multiple
1716 shells, each of them running different profiles.
1719 Isolation: Programs from one profile will not use programs from the other, and
1720 the user can even install different versions of the same programs to the two
1721 profiles without conflict.
1724 Deduplication: Profiles share dependencies that happens to be the exact same.
1725 This makes multiple profiles storage-efficient.
1728 Reproducible: when used with declarative manifests, a profile can be fully
1729 specified by the Guix commit that was active when it was set up. This means
1730 that the exact same profile can be
1731 @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/,
1732 set up anywhere and anytime}, with just the commit information. See the
1733 section on @ref{Reproducible profiles}.
1736 Easier upgrades and maintenance: Multiple profiles make it easy to keep
1737 package listings at hand and make upgrades completely friction-less.
1740 Concretely, here follows some typical profiles:
1744 The dependencies of a project you are working on.
1747 Your favourite programming language libraries.
1750 Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop.
1753 @TeX{}live (this one can be really useful when you need to install just one
1754 package for this one document you've just received over email).
1760 Let's dive in the set up!
1762 @node Basic setup with manifests
1763 @subsection Basic setup with manifests
1765 A Guix profile can be set up @emph{via} a so-called @emph{manifest specification} that looks like
1769 (specifications->manifest
1771 ;; Version 1.3 of package-2.
1773 ;; The "lib" output of package-3.
1779 @pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for
1782 We can create a manifest specification per profile and install them this way:
1785 GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
1786 mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet
1787 guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
1790 Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory
1791 where we will store our profiles in the rest of this article.
1793 Placing all your profiles in a single directory, with each profile getting its
1794 own sub-directory, is somewhat cleaner. This way, each sub-directory will
1795 contain all the symlinks for precisely one profile. Besides, ``looping over
1796 profiles'' becomes obvious from any programming language (e.g.@: a shell script) by
1797 simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}.
1799 Note that it's also possible to loop over the output of
1802 guix package --list-profiles
1805 although you'll probably have to filter out @file{~/.config/guix/current}.
1807 To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar):
1810 for i in $GUIX_EXTRA_PROFILES/*; do
1811 profile=$i/$(basename "$i")
1812 if [ -f "$profile"/etc/profile ]; then
1813 GUIX_PROFILE="$profile"
1814 . "$GUIX_PROFILE"/etc/profile
1820 Note to Guix System users: the above reflects how your default profile
1821 @file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by
1822 @file{~/.bashrc} by default.
1824 You can obviously choose to only enable a subset of them:
1827 for i in "$GUIX_EXTRA_PROFILES"/my-project-1 "$GUIX_EXTRA_PROFILES"/my-project-2; do
1828 profile=$i/$(basename "$i")
1829 if [ -f "$profile"/etc/profile ]; then
1830 GUIX_PROFILE="$profile"
1831 . "$GUIX_PROFILE"/etc/profile
1837 When a profile is off, it's straightforward to enable it for an individual shell
1838 without "polluting" the rest of the user session:
1841 GUIX_PROFILE="path/to/my-project" ; . "$GUIX_PROFILE"/etc/profile
1844 The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file
1845 contains shell code that exports the right environment variables necessary to
1846 activate the software contained in the profile. It is built automatically by
1847 Guix and meant to be sourced.
1848 It contains the same variables you would get if you ran:
1851 guix package --search-paths=prefix --profile=$my_profile"
1854 Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual})
1855 for the command line options.
1857 To upgrade a profile, simply install the manifest again:
1860 guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project
1863 To upgrade all profiles, it's easy enough to loop over them. For instance,
1864 assuming your manifest specifications are stored in
1865 @file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name
1866 of the profile (e.g.@: "project1"), you could do the following in Bourne shell:
1869 for profile in "$GUIX_EXTRA_PROFILES"/*; do
1870 guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm"
1874 Each profile has its own generations:
1877 guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --list-generations
1880 You can roll-back to any generation of a given profile:
1883 guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --switch-generations=17
1886 Finally, if you want to switch to a profile without inheriting from the
1887 current environment, you can activate it from an empty shell:
1890 env -i $(which bash) --login --noprofile --norc
1891 . my-project/etc/profile
1894 @node Required packages
1895 @subsection Required packages
1897 Activating a profile essentially boils down to exporting a bunch of
1898 environmental variables. This is the role of the @samp{etc/profile} within the
1901 @emph{Note: Only the environmental variables of the packages that consume them will
1904 For instance, @samp{MANPATH} won't be set if there is no consumer application for man
1905 pages within the profile. So if you need to transparently access man pages once
1906 the profile is loaded, you've got two options:
1910 Either export the variable manually, e.g.
1912 export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH
1916 Or include @samp{man-db} to the profile manifest.
1919 The same is true for @samp{INFOPATH} (you can install @samp{info-reader}),
1920 @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc.
1922 @node Default profile
1923 @subsection Default profile
1925 What about the default profile that Guix keeps in @file{~/.guix-profile}?
1927 You can assign it the role you want. Typically you would install the manifest
1928 of the packages you want to use all the time.
1930 Alternatively, you could keep it ``manifest-less'' for throw-away packages
1931 that you would just use for a couple of days.
1932 This way makes it convenient to run
1935 guix install package-foo
1936 guix upgrade package-bar
1939 without having to specify the path to a profile.
1941 @node The benefits of manifests
1942 @subsection The benefits of manifests
1944 Manifests are a convenient way to keep your package lists around and, say,
1945 to synchronize them across multiple machines using a version control system.
1947 A common complaint about manifests is that they can be slow to install when they
1948 contain large number of packages. This is especially cumbersome when you just
1949 want get an upgrade for one package within a big manifest.
1951 This is one more reason to use multiple profiles, which happen to be just
1952 perfect to break down manifests into multiple sets of semantically connected
1953 packages. Using multiple, small profiles provides more flexibility and
1956 Manifests come with multiple benefits. In particular, they ease maintenance:
1960 When a profile is set up from a manifest, the manifest itself is
1961 self-sufficient to keep a ``package listing'' around and reinstall the profile
1962 later or on a different system. For ad-hoc profiles, we would need to
1963 generate a manifest specification manually and maintain the package versions
1964 for the packages that don't use the default version.
1967 @code{guix package --upgrade} always tries to update the packages that have
1968 propagated inputs, even if there is nothing to do. Guix manifests remove this
1972 When partially upgrading a profile, conflicts may arise (due to diverging
1973 dependencies between the updated and the non-updated packages) and they can be
1974 annoying to resolve manually. Manifests remove this problem altogether since
1975 all packages are always upgraded at once.
1978 As mentioned above, manifests allow for reproducible profiles, while the
1979 imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce
1980 different profiles every time even when they hold the same packages. See
1981 @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}.
1984 Manifest specifications are usable by other @samp{guix} commands. For example, you
1985 can run @code{guix weather -m manifest.scm} to see how many substitutes are
1986 available, which can help you decide whether you want to try upgrading today
1987 or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to
1988 create a pack containing all the packages in the manifest (and their
1989 transitive references).
1992 Finally, manifests have a Scheme representation, the @samp{<manifest>} record type.
1993 They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}.
1996 It's important to understand that while manifests can be used to declare
1997 profiles, they are not strictly equivalent: profiles have the side effect that
1998 they ``pin'' packages in the store, which prevents them from being
1999 garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual})
2000 and ensures that they will still be available at any point in
2003 Let's take an example:
2007 We have an environment for hacking on a project for which there isn't a Guix
2008 package yet. We build the environment using a manifest, and then run @code{guix
2009 environment -m manifest.scm}. So far so good.
2012 Many weeks pass and we have run a couple of @code{guix pull} in the mean time.
2013 Maybe a dependency from our manifest has been updated; or we may have run
2014 @code{guix gc} and some packages needed by our manifest have been
2018 Eventually, we set to work on that project again, so we run @code{guix environment
2019 -m manifest.scm}. But now we have to wait for Guix to build and install
2023 Ideally, we could spare the rebuild time. And indeed we can, all we need is to
2024 install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile;
2025 . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our
2026 hacking environment will be available at all times.
2028 @emph{Security warning:} While keeping old profiles around can be convenient, keep in
2029 mind that outdated packages may not have received the latest security fixes.
2031 @node Reproducible profiles
2032 @subsection Reproducible profiles
2034 To reproduce a profile bit-for-bit, we need two pieces of information:
2040 a Guix channel specification.
2043 Indeed, manifests alone might not be enough: different Guix versions (or
2044 different channels) can produce different outputs for a given manifest.
2046 You can output the Guix channel specification with @samp{guix describe
2048 Save this to a file, say @samp{channel-specs.scm}.
2050 On another computer, you can use the channel specification file and the manifest
2051 to reproduce the exact same profile:
2054 GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles
2055 GUIX_EXTRA=$HOME/.guix-extra
2057 mkdir "$GUIX_EXTRA"/my-project
2058 guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix"
2060 mkdir -p "$GUIX_EXTRA_PROFILES/my-project"
2061 "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project
2064 It's safe to delete the Guix channel profile you've just installed with the
2065 channel specification, the project profile does not depend on it.
2067 @c *********************************************************************
2068 @node Acknowledgments
2069 @chapter Acknowledgments
2071 Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
2072 which was designed and
2073 implemented by Eelco Dolstra, with contributions from other people (see
2074 the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
2075 management, and promoted unprecedented features, such as transactional
2076 package upgrades and rollbacks, per-user profiles, and referentially
2077 transparent build processes. Without this work, Guix would not exist.
2079 The Nix-based software distributions, Nixpkgs and NixOS, have also been
2080 an inspiration for Guix.
2082 GNU@tie{}Guix itself is a collective work with contributions from a
2083 number of people. See the @file{AUTHORS} file in Guix for more
2084 information on these fine people. The @file{THANKS} file lists people
2085 who have helped by reporting bugs, taking care of the infrastructure,
2086 providing artwork and themes, making suggestions, and more---thank you!
2088 This document includes adapted sections from articles that have previously
2089 been published on the Guix blog at @uref{https://guix.gnu.org/blog}.
2092 @c *********************************************************************
2093 @node GNU Free Documentation License
2094 @appendix GNU Free Documentation License
2095 @cindex license, GNU Free Documentation License
2096 @include fdl-1.3.texi
2098 @c *********************************************************************
2100 @unnumbered Concept Index
2106 @c ispell-local-dictionary: "american";