Commit | Line | Data |
---|---|---|
7bc46ecc RW |
1 | \input texinfo |
2 | @c -*-texinfo-*- | |
3 | ||
4 | @c %**start of header | |
5 | @setfilename guix-cookbook.info | |
6 | @documentencoding UTF-8 | |
7 | @settitle GNU Guix Cookbook | |
8 | @c %**end of header | |
9 | ||
10 | @copying | |
11 | Copyright @copyright{} 2019 Ricardo Wurmus@* | |
12 | Copyright @copyright{} 2019 Efraim Flashner@* | |
13 | Copyright @copyright{} 2019 Pierre Neidhardt@* | |
14 | ||
15 | Permission is granted to copy, distribute and/or modify this document | |
16 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
17 | any later version published by the Free Software Foundation; with no | |
18 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A | |
19 | copy of the license is included in the section entitled ``GNU Free | |
20 | Documentation License''. | |
21 | @end copying | |
22 | ||
23 | @dircategory System administration | |
24 | @direntry | |
25 | * Guix cookbook: (guix-cookbook). Tutorials and examples for GNU Guix. | |
26 | @end direntry | |
27 | ||
28 | @titlepage | |
29 | @title GNU Guix Cookbook | |
30 | @subtitle Tutorials and examples for using the GNU Guix Functional Package Manager | |
31 | @author The GNU Guix Developers | |
32 | ||
33 | @page | |
34 | @vskip 0pt plus 1filll | |
35 | ||
36 | @insertcopying | |
37 | @end titlepage | |
38 | ||
39 | @contents | |
40 | ||
41 | @c ********************************************************************* | |
42 | @node Top | |
43 | @top GNU Guix Cookbook | |
44 | ||
45 | This document presents tutorials and detailed examples for GNU@tie{}Guix, a | |
46 | functional package management tool written for the GNU system. Please | |
47 | @pxref{Top,,, guix, GNU Guix reference manual} for details about the system, | |
48 | its API, and related concepts. | |
49 | ||
50 | @c TRANSLATORS: You can replace the following paragraph with information on | |
51 | @c how to join your own translation team and how to report issues with the | |
52 | @c translation. | |
53 | If you would like to translate this document in your native language, consider | |
54 | joining the @uref{https://translationproject.org/domain/guix-cookbook.html, | |
55 | Translation Project}. | |
56 | ||
57 | @menu | |
58 | * Scheme tutorials:: Meet your new favorite language! | |
59 | * Packaging:: Packaging tutorials | |
60 | * System Configuration:: Customizing the GNU System | |
4c463569 | 61 | * Advanced package management:: Power to the users! |
7bc46ecc RW |
62 | |
63 | * Acknowledgments:: Thanks! | |
64 | * GNU Free Documentation License:: The license of this document. | |
65 | * Concept Index:: Concepts. | |
66 | ||
67 | @detailmenu | |
68 | --- The Detailed Node Listing --- | |
69 | ||
70 | Scheme tutorials | |
71 | ||
72 | * A Scheme Crash Course:: Learn the basics of Scheme | |
73 | ||
74 | Packaging | |
75 | ||
76 | * Packaging Tutorial:: Let's add a package to Guix! | |
77 | ||
78 | System Configuration | |
79 | ||
80 | * Customizing the Kernel:: Creating and using a custom Linux kernel | |
81 | ||
82 | ||
83 | @end detailmenu | |
84 | @end menu | |
85 | ||
86 | @c ********************************************************************* | |
87 | @node Scheme tutorials | |
88 | @chapter Scheme tutorials | |
89 | ||
90 | GNU@tie{}Guix is written in the general purpose programming language Scheme, | |
91 | and many of its features can be accessed and manipulated programmatically. | |
92 | You can use Scheme to generate package definitions, to modify them, to build | |
93 | them, to deploy whole operating systems, etc. | |
94 | ||
95 | Knowing the basics of how to program in Scheme will unlock many of the | |
96 | advanced features Guix provides --- and you don't even need to be an | |
97 | experienced programmer to use them! | |
98 | ||
99 | Let's get started! | |
100 | ||
101 | @node A Scheme Crash Course | |
102 | @section A Scheme Crash Course | |
103 | ||
104 | @cindex Scheme, crash course | |
105 | ||
106 | Guix uses the Guile implementation of Scheme. To start playing with the | |
107 | language, install it with @code{guix install guile} and start a | |
108 | @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop, | |
109 | REPL} by running @code{guile} from the command line. | |
110 | ||
111 | Alternatively you can also run @code{guix environment --ad-hoc guile -- guile} | |
112 | if you'd rather not have Guile installed in your user profile. | |
113 | ||
114 | In the following examples we use the @code{>} symbol to denote the REPL | |
115 | prompt, that is, the line reserved for user input. @xref{Using Guile | |
116 | Interactively,,, guile, GNU Guile Reference Manual}) for more details on the | |
117 | REPL. | |
118 | ||
119 | @itemize | |
120 | @item | |
121 | Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in | |
122 | Lisp lingo). An expression can be a literal such as numbers and strings, or a | |
123 | compound which is a parenthesized list of compounds and literals. @code{#t} | |
124 | and @code{#f} stand for the booleans "true" and "false", respectively. | |
125 | ||
126 | Examples of valid expressions: | |
127 | ||
b1eecb5c | 128 | @lisp |
7bc46ecc RW |
129 | > "Hello World!" |
130 | "Hello World!" | |
131 | > 17 | |
132 | 17 | |
133 | > (display (string-append "Hello " "Guix" "\n")) | |
134 | "Hello Guix!" | |
b1eecb5c | 135 | @end lisp |
7bc46ecc RW |
136 | |
137 | @item | |
138 | This last example is a function call nested in another function call. When a | |
139 | parenthesized expression is evaluated, the first term is the function and the | |
140 | rest are the arguments passed to the function. Every function returns the | |
141 | last evaluated expression as its return value. | |
142 | ||
143 | @item | |
144 | Anonymous functions are declared with the @code{lambda} term: | |
145 | ||
b1eecb5c | 146 | @lisp |
7bc46ecc RW |
147 | > (lambda (x) (* x x)) |
148 | #<procedure 120e348 at <unknown port>:24:0 (x)> | |
b1eecb5c | 149 | @end lisp |
7bc46ecc RW |
150 | |
151 | The above procedure returns the square of its argument. Since everything is | |
152 | an expression, the @code{lambda} expression returns an anonymous procedure, | |
153 | which can in turn be applied to an argument: | |
154 | ||
b1eecb5c | 155 | @lisp |
7bc46ecc RW |
156 | > ((lambda (x) (* x x)) 3) |
157 | 9 | |
b1eecb5c | 158 | @end lisp |
7bc46ecc RW |
159 | |
160 | @item | |
161 | Anything can be assigned a global name with @code{define}: | |
162 | ||
b1eecb5c | 163 | @lisp |
7bc46ecc RW |
164 | > (define a 3) |
165 | > (define square (lambda (x) (* x x))) | |
166 | > (square a) | |
167 | 9 | |
b1eecb5c | 168 | @end lisp |
7bc46ecc RW |
169 | |
170 | @item | |
171 | Procedures can be defined more concisely with the following syntax: | |
172 | ||
b1eecb5c | 173 | @lisp |
7bc46ecc | 174 | (define (square x) (* x x)) |
b1eecb5c | 175 | @end lisp |
7bc46ecc RW |
176 | |
177 | @item | |
178 | A list structure can be created with the @code{list} procedure: | |
179 | ||
b1eecb5c | 180 | @lisp |
7bc46ecc RW |
181 | > (list 2 a 5 7) |
182 | (2 3 5 7) | |
b1eecb5c | 183 | @end lisp |
7bc46ecc RW |
184 | |
185 | @item | |
186 | The @emph{quote} disables evaluation of a parenthesized expression: the first | |
187 | term is not called over the other terms. Thus it effectively returns a list | |
188 | of terms. | |
189 | ||
b1eecb5c | 190 | @lisp |
7bc46ecc RW |
191 | > '(display (string-append "Hello " "Guix" "\n")) |
192 | (display (string-append "Hello " "Guix" "\n")) | |
193 | > '(2 a 5 7) | |
194 | (2 a 5 7) | |
b1eecb5c | 195 | @end lisp |
7bc46ecc RW |
196 | |
197 | @item | |
198 | The @emph{quasiquote} disables evaluation of a parenthesized expression until | |
199 | a comma re-enables it. Thus it provides us with fine-grained control over | |
200 | what is evaluated and what is not. | |
201 | ||
b1eecb5c | 202 | @lisp |
7bc46ecc RW |
203 | > `(2 a 5 7 (2 ,a 5 ,(+ a 4))) |
204 | (2 a 5 7 (2 3 5 7)) | |
b1eecb5c | 205 | @end lisp |
7bc46ecc RW |
206 | |
207 | Note that the above result is a list of mixed elements: numbers, symbols (here | |
208 | @code{a}) and the last element is a list itself. | |
209 | ||
210 | @item | |
211 | Multiple variables can be named locally with @code{let}: | |
212 | ||
b1eecb5c | 213 | @lisp |
7bc46ecc RW |
214 | > (define x 10) |
215 | > (let ((x 2) | |
216 | (y 3)) | |
217 | (list x y)) | |
218 | (2 3) | |
219 | > x | |
220 | 10 | |
221 | > y | |
222 | ERROR: In procedure module-lookup: Unbound variable: y | |
b1eecb5c | 223 | @end lisp |
7bc46ecc RW |
224 | |
225 | Use @code{let*} to allow later variable declarations to refer to earlier | |
226 | definitions. | |
227 | ||
b1eecb5c | 228 | @lisp |
7bc46ecc RW |
229 | > (let* ((x 2) |
230 | (y (* x 3))) | |
231 | (list x y)) | |
232 | (2 6) | |
b1eecb5c | 233 | @end lisp |
7bc46ecc RW |
234 | |
235 | @item | |
236 | The keyword syntax is @code{#:}; it is used to create unique identifiers. | |
237 | @pxref{Keywords,,, guile, GNU Guile Reference Manual}. | |
238 | ||
239 | @item | |
240 | The percentage @code{%} is typically used for read-only global variables in | |
241 | the build stage. Note that it is merely a convention, like @code{_} in C. | |
242 | Scheme treats @code{%} exactly the same as any other letter. | |
243 | ||
244 | @item | |
245 | Modules are created with @code{define-module}. For instance | |
246 | ||
b1eecb5c | 247 | @lisp |
7bc46ecc RW |
248 | (define-module (guix build-system ruby) |
249 | #:use-module (guix store) | |
250 | #:export (ruby-build | |
251 | ruby-build-system)) | |
b1eecb5c | 252 | @end lisp |
7bc46ecc RW |
253 | |
254 | defines the module @code{guix build-system ruby} which must be located in | |
255 | @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It | |
256 | depends on the @code{(guix store)} module and it exports two variables, | |
257 | @code{ruby-build} and @code{ruby-build-system}. | |
258 | @end itemize | |
259 | ||
260 | For a more detailed introduction, check out | |
261 | @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme | |
262 | at a Glance}, by Steve Litt. | |
263 | ||
264 | One of the reference Scheme books is the seminal ``Structure and | |
265 | Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay | |
266 | Sussman, with Julie Sussman. You'll find a | |
267 | @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy | |
268 | online}, together with | |
269 | @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/, | |
270 | videos of the lectures by the authors}. The book is available in Texinfo | |
271 | format as the @code{sicp} Guix package. Go ahead, run @code{guix install | |
ed79636c | 272 | sicp} and start reading with @code{info sicp} (@pxref{,,, sicp, Structure and Interpretation of Computer Programs}). |
7bc46ecc RW |
273 | An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also |
274 | available}. | |
275 | ||
276 | You'll find more books, tutorials and other resources at | |
277 | @url{https://schemers.org/}. | |
278 | ||
279 | ||
280 | @c ********************************************************************* | |
281 | @node Packaging | |
282 | @chapter Packaging | |
283 | ||
284 | @cindex packaging | |
285 | ||
286 | This chapter is dedicated to teaching you how to add packages to the | |
287 | collection of packages that come with GNU Guix. This involves writing package | |
288 | definitions in Guile Scheme, organizing them in package modules, and building | |
289 | them. | |
290 | ||
291 | @menu | |
292 | * Packaging Tutorial:: A tutorial on how to add packages to Guix. | |
293 | @end menu | |
294 | ||
295 | @node Packaging Tutorial | |
296 | @section Packaging Tutorial | |
297 | ||
298 | GNU Guix stands out as the @emph{hackable} package manager, mostly because it | |
299 | uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful | |
300 | high-level programming language, one of the | |
301 | @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme} | |
302 | dialects from the | |
303 | @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}. | |
304 | ||
305 | Package definitions are also written in Scheme, which empowers Guix in some | |
306 | very unique ways, unlike most other package managers that use shell scripts or | |
307 | simple languages. | |
308 | ||
309 | @itemize | |
310 | @item | |
311 | Use functions, structures, macros and all of Scheme expressiveness for your | |
312 | package definitions. | |
313 | ||
314 | @item | |
315 | Inheritance makes it easy to customize a package by inheriting from it and | |
316 | modifying only what is needed. | |
317 | ||
318 | @item | |
319 | Batch processing: the whole package collection can be parsed, filtered and | |
320 | processed. Building a headless server with all graphical interfaces stripped | |
321 | out? It's possible. Want to rebuild everything from source using specific | |
322 | compiler optimization flags? Pass the @code{#:make-flags "..."} argument to | |
323 | the list of packages. It wouldn't be a stretch to think | |
324 | @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this | |
325 | goes even further: the changes don't have to be thought out beforehand by the | |
326 | packager, they can be @emph{programmed} by the user! | |
327 | @end itemize | |
328 | ||
329 | The following tutorial covers all the basics around package creation with Guix. | |
330 | It does not assume much knowledge of the Guix system nor of the Lisp language. | |
331 | The reader is only expected to be familiar with the command line and to have some | |
332 | basic programming knowledge. | |
333 | ||
ffe059af | 334 | @node A "Hello World" package |
7bc46ecc RW |
335 | @subsection A "Hello World" package |
336 | ||
337 | The “Defining Packages” section of the manual introduces the basics of Guix | |
338 | packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In | |
339 | the following section, we will partly go over those basics again. | |
340 | ||
341 | ``GNU hello'' is a dummy project that serves as an idiomatic example for | |
342 | packaging. It uses the GNU build system (@code{./configure && make && make | |
343 | install}). Guix already provides a package definition which is a perfect | |
344 | example to start with. You can look up its declaration with @code{guix edit | |
345 | hello} from the command line. Let's see how it looks: | |
346 | ||
b1eecb5c | 347 | @lisp |
7bc46ecc RW |
348 | (define-public hello |
349 | (package | |
350 | (name "hello") | |
351 | (version "2.10") | |
352 | (source (origin | |
353 | (method url-fetch) | |
354 | (uri (string-append "mirror://gnu/hello/hello-" version | |
355 | ".tar.gz")) | |
356 | (sha256 | |
357 | (base32 | |
358 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
359 | (build-system gnu-build-system) | |
360 | (synopsis "Hello, GNU world: An example GNU package") | |
361 | (description | |
362 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
363 | serves as an example of standard GNU coding practices. As such, it supports | |
364 | command-line arguments, multiple languages, and so on.") | |
365 | (home-page "https://www.gnu.org/software/hello/") | |
366 | (license gpl3+))) | |
b1eecb5c | 367 | @end lisp |
7bc46ecc RW |
368 | |
369 | As you can see, most of it is rather straightforward. But let's review the | |
370 | fields together: | |
371 | ||
372 | @table @samp | |
373 | @item name | |
374 | The project name. Using Scheme conventions, we prefer to keep it | |
375 | lower case, without underscore and using dash-separated words. | |
376 | ||
377 | @item source | |
378 | This field contains a description of the source code origin. The | |
379 | @code{origin} record contains these fields: | |
380 | ||
381 | @enumerate | |
382 | @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods | |
383 | exist, such as @code{git-fetch} for Git repositories. | |
384 | @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here | |
385 | the special `mirror://gnu` refers to a set of well known locations, all of | |
386 | which can be used by Guix to fetch the source, should some of them fail. | |
387 | @item The @code{sha256} checksum of the requested file. This is essential to ensure | |
388 | the source is not corrupted. Note that Guix works with base32 strings, | |
389 | hence the call to the @code{base32} function. | |
390 | @end enumerate | |
391 | ||
392 | @item build-system | |
393 | ||
394 | This is where the power of abstraction provided by the Scheme language really | |
395 | shines: in this case, the @code{gnu-build-system} abstracts away the famous | |
396 | @code{./configure && make && make install} shell invocations. Other build | |
397 | systems include the @code{trivial-build-system} which does not do anything and | |
398 | requires from the packager to program all the build steps, the | |
399 | @code{python-build-system}, the @code{emacs-build-system}, and many more | |
400 | (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}). | |
401 | ||
402 | @item synopsis | |
403 | It should be a concise summary of what the package does. For many packages a | |
404 | tagline from the project's home page can be used as the synopsis. | |
405 | ||
406 | @item description | |
407 | Same as for the synopsis, it's fine to re-use the project description from the | |
408 | homepage. Note that Guix uses Texinfo syntax. | |
409 | ||
410 | @item home-page | |
411 | Use HTTPS if available. | |
412 | ||
413 | @item license | |
414 | See @code{guix/licenses.scm} in the project source for a full list of | |
415 | available licenses. | |
416 | @end table | |
417 | ||
418 | Time to build our first package! Nothing fancy here for now: we will stick to a | |
419 | dummy "my-hello", a copy of the above declaration. | |
420 | ||
421 | As with the ritualistic "Hello World" taught with most programming languages, | |
422 | this will possibly be the most "manual" approach. We will work out an ideal | |
423 | setup later; for now we will go the simplest route. | |
424 | ||
425 | Save the following to a file @file{my-hello.scm}. | |
426 | ||
b1eecb5c | 427 | @lisp |
7bc46ecc RW |
428 | (use-modules (guix packages) |
429 | (guix download) | |
430 | (guix build-system gnu) | |
431 | (guix licenses)) | |
432 | ||
433 | (package | |
434 | (name "my-hello") | |
435 | (version "2.10") | |
436 | (source (origin | |
437 | (method url-fetch) | |
438 | (uri (string-append "mirror://gnu/hello/hello-" version | |
439 | ".tar.gz")) | |
440 | (sha256 | |
441 | (base32 | |
442 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
443 | (build-system gnu-build-system) | |
444 | (synopsis "Hello, Guix world: An example custom Guix package") | |
445 | (description | |
446 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
447 | serves as an example of standard GNU coding practices. As such, it supports | |
448 | command-line arguments, multiple languages, and so on.") | |
449 | (home-page "https://www.gnu.org/software/hello/") | |
450 | (license gpl3+)) | |
b1eecb5c | 451 | @end lisp |
7bc46ecc RW |
452 | |
453 | We will explain the extra code in a moment. | |
454 | ||
455 | Feel free to play with the different values of the various fields. If you | |
456 | change the source, you'll need to update the checksum. Indeed, Guix refuses to | |
457 | build anything if the given checksum does not match the computed checksum of the | |
458 | source code. To obtain the correct checksum of the package declaration, we | |
459 | need to download the source, compute the sha256 checksum and convert it to | |
460 | base32. | |
461 | ||
462 | Thankfully, Guix can automate this task for us; all we need is to provide the | |
463 | URI: | |
464 | ||
465 | @c TRANSLATORS: This is example shell output. | |
466 | @example sh | |
467 | $ guix download mirror://gnu/hello/hello-2.10.tar.gz | |
468 | ||
469 | Starting download of /tmp/guix-file.JLYgL7 | |
470 | From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz... | |
471 | following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'... | |
472 | …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0% | |
473 | /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz | |
474 | 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i | |
475 | @end example | |
476 | ||
477 | In this specific case the output tells us which mirror was chosen. | |
478 | If the result of the above command is not the same as in the above snippet, | |
479 | update your @code{my-hello} declaration accordingly. | |
480 | ||
481 | Note that GNU package tarballs come with an OpenPGP signature, so you | |
482 | should definitely check the signature of this tarball with `gpg` to | |
483 | authenticate it before going further: | |
484 | ||
485 | @c TRANSLATORS: This is example shell output. | |
486 | @example sh | |
487 | $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig | |
488 | ||
489 | Starting download of /tmp/guix-file.03tFfb | |
490 | From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig... | |
491 | following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'... | |
492 | ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0% | |
493 | /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig | |
494 | 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf | |
495 | $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz | |
496 | gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET | |
497 | gpg: using RSA key A9553245FDE9B739 | |
498 | gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown] | |
499 | gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown] | |
500 | gpg: WARNING: This key is not certified with a trusted signature! | |
501 | gpg: There is no indication that the signature belongs to the owner. | |
502 | Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739 | |
503 | @end example | |
504 | ||
505 | You can then happily run | |
506 | ||
507 | @c TRANSLATORS: Do not translate this command | |
508 | @example sh | |
509 | $ guix package --install-from-file=my-hello.scm | |
510 | @end example | |
511 | ||
512 | You should now have @code{my-hello} in your profile! | |
513 | ||
514 | @c TRANSLATORS: Do not translate this command | |
515 | @example sh | |
516 | $ guix package --list-installed=my-hello | |
517 | my-hello 2.10 out | |
518 | /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10 | |
519 | @end example | |
520 | ||
521 | We've gone as far as we could without any knowledge of Scheme. Before moving | |
522 | on to more complex packages, now is the right time to brush up on your Scheme | |
523 | knowledge. @pxref{A Scheme Crash Course} to get up to speed. | |
524 | ||
ffe059af PN |
525 | @node Setup |
526 | @subsection Setup | |
7bc46ecc | 527 | |
ffe059af PN |
528 | In the rest of this chapter we will rely on some basic Scheme |
529 | programming knowledge. Now let's detail the different possible setups | |
530 | for working on Guix packages. | |
531 | ||
532 | There are several ways to set up a Guix packaging environment. | |
533 | ||
534 | We recommend you work directly on the Guix source checkout since it makes it | |
535 | easier for everyone to contribute to the project. | |
536 | ||
537 | But first, let's look at other possibilities. | |
538 | ||
539 | @node Local file | |
540 | @subsubsection Local file | |
541 | ||
542 | This is what we previously did with @samp{my-hello}. With the Scheme basics we've | |
543 | covered, we are now able to explain the leading chunks. As stated in @code{guix | |
544 | package --help}: | |
545 | ||
546 | @example | |
547 | -f, --install-from-file=FILE | |
548 | install the package that the code within FILE | |
549 | evaluates to | |
550 | @end example | |
551 | ||
552 | Thus the last expression @emph{must} return a package, which is the case in our | |
553 | earlier example. | |
554 | ||
555 | The @code{use-modules} expression tells which of the modules we need in the file. | |
556 | Modules are a collection of values and procedures. They are commonly called | |
557 | "libraries" or "packages" in other programming languages. | |
558 | ||
559 | @node @samp{GUIX_PACKAGE_PATH} | |
560 | @subsubsection @samp{GUIX_PACKAGE_PATH} | |
561 | ||
562 | @emph{Note: Starting from Guix 0.16, the more flexible Guix "channels" are the | |
563 | preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section.} | |
564 | ||
565 | It can be tedious to specify the file from the command line instead of simply | |
566 | calling @code{guix package --install my-hello} as you would do with the official | |
567 | packages. | |
568 | ||
569 | Guix makes it possible to streamline the process by adding as many "package | |
570 | declaration paths" as you want. | |
571 | ||
572 | Create a directory, say @samp{~./guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} | |
573 | environment variable: | |
574 | ||
575 | @example | |
576 | $ mkdir ~/guix-packages | |
577 | $ export GUIX_PACKAGE_PATH=~/guix-packages | |
578 | @end example | |
579 | ||
580 | To add several directories, separate them with a colon (@code{:}). | |
581 | ||
582 | Our previous @samp{my-hello} needs some adjustments though: | |
583 | ||
d482e13f | 584 | @lisp |
ffe059af PN |
585 | (define-module (my-hello) |
586 | #:use-module (guix licenses) | |
587 | #:use-module (guix packages) | |
588 | #:use-module (guix build-system gnu) | |
589 | #:use-module (guix download)) | |
590 | ||
591 | (define-public my-hello | |
592 | (package | |
593 | (name "my-hello") | |
594 | (version "2.10") | |
595 | (source (origin | |
596 | (method url-fetch) | |
597 | (uri (string-append "mirror://gnu/hello/hello-" version | |
598 | ".tar.gz")) | |
599 | (sha256 | |
600 | (base32 | |
601 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
602 | (build-system gnu-build-system) | |
603 | (synopsis "Hello, Guix world: An example custom Guix package") | |
604 | (description | |
605 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
606 | serves as an example of standard GNU coding practices. As such, it supports | |
607 | command-line arguments, multiple languages, and so on.") | |
608 | (home-page "https://www.gnu.org/software/hello/") | |
609 | (license gpl3+))) | |
d482e13f | 610 | @end lisp |
ffe059af PN |
611 | |
612 | Note that we have assigned the package value to an exported variable name with | |
613 | @code{define-public}. This is effectively assigning the package to the @code{my-hello} | |
614 | variable so that it can be referenced, among other as dependency of other | |
615 | packages. | |
616 | ||
617 | If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it | |
618 | will fail because the last expression, @code{define-public}, does not return a | |
619 | package. If you want to use @code{define-public} in this use-case nonetheless, make | |
620 | sure the file ends with an evaluation of @code{my-hello}: | |
621 | ||
d482e13f | 622 | @lisp |
ffe059af PN |
623 | ; ... |
624 | (define-public my-hello | |
625 | ; ... | |
626 | ) | |
627 | ||
628 | my-hello | |
d482e13f | 629 | @end lisp |
ffe059af PN |
630 | |
631 | This last example is not very typical. | |
632 | ||
633 | Now @samp{my-hello} should be part of the package collection like all other official | |
634 | packages. You can verify this with: | |
635 | ||
636 | @example | |
637 | $ guix package --show=my-hello | |
638 | @end example | |
639 | ||
640 | @node Guix channels | |
641 | @subsubsection Guix channels | |
642 | ||
643 | Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but | |
644 | provides better integration and provenance tracking. Channels are not | |
645 | necessarily local, they can be maintained as a public Git repository for | |
646 | instance. Of course, several channels can be used at the same time. | |
647 | ||
648 | @xref{Channels,,, guix, GNU Guix Reference Manual} for setup details. | |
649 | ||
650 | @node Direct checkout hacking | |
651 | @subsubsection Direct checkout hacking | |
652 | ||
653 | Working directly on the Guix project is recommended: it reduces the friction | |
654 | when the time comes to submit your changes upstream to let the community benefit | |
655 | from your hard work! | |
656 | ||
657 | Unlike most software distributions, the Guix repository holds in one place both | |
658 | the tooling (including the package manager) and the package definitions. This | |
659 | choice was made so that it would give developers the flexibility to modify the | |
660 | API without breakage by updating all packages at the same time. This reduces | |
661 | development inertia. | |
662 | ||
663 | Check out the official @uref{https://git-scm.com/, Git} repository: | |
664 | ||
665 | @example | |
666 | $ git clone https://git.savannah.gnu.org/git/guix.git | |
667 | @end example | |
668 | ||
669 | In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of | |
670 | the checkout. | |
671 | ||
672 | ||
e97a4a29 | 673 | Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix |
ffe059af PN |
674 | Reference Manual}) to set up the repository environment. |
675 | ||
676 | Once ready, you should be able to use the package definitions from the | |
677 | repository environment. | |
678 | ||
679 | Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}. | |
680 | ||
681 | The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package | |
e97a4a29 LC |
682 | collection of the repository (@pxref{Running Guix Before It Is |
683 | Installed,,, guix, GNU Guix Reference Manual}). | |
ffe059af PN |
684 | |
685 | @itemize | |
686 | @item | |
687 | Search packages, such as Ruby: | |
688 | ||
689 | @example | |
690 | $ cd $GUIX_CHECKOUT | |
691 | $ ./pre-inst-env guix package --list-available=ruby | |
692 | ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2 | |
693 | ruby 2.1.6 out gnu/packages/ruby.scm:91:2 | |
694 | ruby 2.2.2 out gnu/packages/ruby.scm:39:2 | |
695 | @end example | |
696 | ||
697 | @item | |
698 | Build a package, here Ruby version 2.1: | |
699 | ||
700 | @example | |
701 | $ ./pre-inst-env guix build --keep-failed ruby@@2.1 | |
702 | /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6 | |
703 | @end example | |
704 | ||
705 | @item | |
706 | Install it to your user profile: | |
707 | ||
708 | @example | |
709 | $ ./pre-inst-env guix package --install ruby@@2.1 | |
710 | @end example | |
711 | ||
712 | @item | |
713 | Check for common mistakes: | |
714 | ||
715 | @example | |
716 | $ ./pre-inst-env guix lint ruby@@2.1 | |
717 | @end example | |
718 | @end itemize | |
719 | ||
720 | Guix strives at maintaining a high packaging standard; when contributing to the | |
721 | Guix project, remember to | |
722 | ||
723 | @itemize | |
724 | @item | |
725 | follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}), | |
726 | @item | |
727 | and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual}). | |
728 | @end itemize | |
729 | ||
730 | Once you are happy with the result, you are welcome to send your contribution to | |
731 | make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual}) | |
732 | ||
733 | ||
734 | It's a community effort so the more join in, the better Guix becomes! | |
735 | ||
736 | @node Extended example | |
737 | @subsection Extended example | |
738 | ||
739 | The above "Hello World" example is as simple as it goes. Packages can be more | |
740 | complex than that and Guix can handle more advanced scenarios. Let's look at | |
741 | another, more sophisticated package (slightly modified from the source): | |
742 | ||
d482e13f | 743 | @lisp |
ffe059af PN |
744 | (define-module (gnu packages version-control) |
745 | #:use-module ((guix licenses) #:prefix license:) | |
746 | #:use-module (guix utils) | |
747 | #:use-module (guix packages) | |
748 | #:use-module (guix git-download) | |
749 | #:use-module (guix build-system cmake) | |
750 | #:use-module (gnu packages ssh) | |
751 | #:use-module (gnu packages web) | |
752 | #:use-module (gnu packages pkg-config) | |
753 | #:use-module (gnu packages python) | |
754 | #:use-module (gnu packages compression) | |
755 | #:use-module (gnu packages tls)) | |
756 | ||
757 | (define-public my-libgit2 | |
758 | (let ((commit "e98d0a37c93574d2c6107bf7f31140b548c6a7bf") | |
759 | (revision "1")) | |
760 | (package | |
761 | (name "my-libgit2") | |
762 | (version (git-version "0.26.6" revision commit)) | |
763 | (source (origin | |
764 | (method git-fetch) | |
765 | (uri (git-reference | |
766 | (url "https://github.com/libgit2/libgit2/") | |
767 | (commit commit))) | |
768 | (file-name (git-file-name name version)) | |
769 | (sha256 | |
770 | (base32 | |
771 | "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3")) | |
772 | (patches (search-patches "libgit2-mtime-0.patch")) | |
773 | (modules '((guix build utils))) | |
774 | (snippet '(begin | |
775 | ;; Remove bundled software. | |
776 | (delete-file-recursively "deps") | |
777 | #t)))) | |
778 | (build-system cmake-build-system) | |
779 | (outputs '("out" "debug")) | |
780 | (arguments | |
781 | `(#:tests? #t ; Run the test suite (this is the default) | |
782 | #:configure-flags '("-DUSE_SHA1DC=ON") ; SHA-1 collision detection | |
783 | #:phases | |
784 | (modify-phases %standard-phases | |
785 | (add-after 'unpack 'fix-hardcoded-paths | |
786 | (lambda _ | |
787 | (substitute* "tests/repo/init.c" | |
788 | (("#!/bin/sh") (string-append "#!" (which "sh")))) | |
789 | (substitute* "tests/clar/fs.h" | |
790 | (("/bin/cp") (which "cp")) | |
791 | (("/bin/rm") (which "rm"))) | |
792 | #t)) | |
793 | ;; Run checks more verbosely. | |
794 | (replace 'check | |
795 | (lambda _ (invoke "./libgit2_clar" "-v" "-Q"))) | |
796 | (add-after 'unpack 'make-files-writable-for-tests | |
797 | (lambda _ (for-each make-file-writable (find-files "." ".*"))))))) | |
798 | (inputs | |
799 | `(("libssh2" ,libssh2) | |
800 | ("http-parser" ,http-parser) | |
801 | ("python" ,python-wrapper))) | |
802 | (native-inputs | |
803 | `(("pkg-config" ,pkg-config))) | |
804 | (propagated-inputs | |
805 | ;; These two libraries are in 'Requires.private' in libgit2.pc. | |
806 | `(("openssl" ,openssl) | |
807 | ("zlib" ,zlib))) | |
808 | (home-page "https://libgit2.github.com/") | |
809 | (synopsis "Library providing Git core methods") | |
810 | (description | |
811 | "Libgit2 is a portable, pure C implementation of the Git core methods | |
812 | provided as a re-entrant linkable library with a solid API, allowing you to | |
813 | write native speed custom Git applications in any language with bindings.") | |
814 | ;; GPLv2 with linking exception | |
815 | (license license:gpl2)))) | |
d482e13f | 816 | @end lisp |
ffe059af PN |
817 | |
818 | (In those cases were you only want to tweak a few fields from a package | |
819 | definition, you should rely on inheritance instead of copy-pasting everything. | |
820 | See below.) | |
821 | ||
822 | Let's discuss those fields in depth. | |
823 | ||
824 | @subsubsection @code{git-fetch} method | |
825 | ||
826 | Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes | |
827 | a Git repository and a commit. The commit can be any Git reference such as | |
828 | tags, so if the @code{version} is tagged, then it can be used directly. Sometimes | |
829 | the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append | |
830 | "v" version))}. | |
831 | ||
832 | To ensure that the source code from the Git repository is stored in a unique | |
833 | directory with a readable name we use @code{(file-name (git-file-name name | |
834 | version))}. | |
835 | ||
836 | Note that there is also a @code{git-version} procedure that can be used to derive the | |
837 | version when packaging programs for a specific commit. | |
838 | ||
839 | @subsubsection Snippets | |
840 | ||
841 | Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching | |
842 | the source. They are a Guix-y alternative to the traditional @samp{.patch} files. | |
843 | Because of the quote, the code in only evaluated when passed to the Guix daemon | |
844 | for building. | |
845 | ||
846 | There can be as many snippet as needed. | |
847 | ||
848 | Snippets might need additional Guile modules which can be imported from the | |
849 | @code{modules} field. | |
850 | ||
851 | @subsubsection Inputs | |
852 | ||
853 | First, a syntactic comment: See the quasi-quote / comma syntax? | |
854 | ||
d482e13f | 855 | @lisp |
ffe059af PN |
856 | (native-inputs |
857 | `(("pkg-config" ,pkg-config))) | |
d482e13f | 858 | @end lisp |
ffe059af PN |
859 | |
860 | is equivalent to | |
861 | ||
d482e13f | 862 | @lisp |
ffe059af PN |
863 | (native-inputs |
864 | (list (list "pkg-config" pkg-config))) | |
d482e13f | 865 | @end lisp |
ffe059af PN |
866 | |
867 | You'll mostly see the former because it's shorter. | |
868 | ||
869 | There are 3 different input types. In short: | |
870 | ||
871 | @table @asis | |
872 | @item native-inputs | |
873 | Required for building but not runtime -- installing a package | |
874 | through a substitute won't install these inputs. | |
875 | @item inputs | |
876 | Installed in the store but not in the profile, as well as being | |
877 | present at build time. | |
878 | @item propagated-inputs | |
879 | Installed in the store and in the profile, as well as | |
880 | being present at build time. | |
881 | @end table | |
882 | ||
883 | @xref{Package Reference,,, guix, GNU Guix Reference Manual} for more details. | |
884 | ||
885 | The distinction between the various inputs is important: if a dependency can be | |
886 | handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or | |
887 | else it "pollutes" the user profile for no good reason. | |
888 | ||
889 | For instance, a user installing a graphical program that depends on a | |
890 | command line tool might only be interested in the graphical part, so there is no | |
891 | need to force the command line tool into the user profile. The dependency is a | |
892 | concern to the package, not to the user. @emph{Inputs} make it possible to handle | |
893 | dependencies without bugging the user by adding undesired executable files (or | |
894 | libraries) to their profile. | |
895 | ||
896 | Same goes for @emph{native-inputs}: once the program is installed, build-time | |
897 | dependencies can be safely garbage-collected. | |
898 | It also matters when a substitute is available, in which case only the @emph{inputs} | |
899 | and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to | |
900 | install a package from a substitute. | |
901 | ||
902 | @subsubsection Outputs | |
903 | ||
904 | Just like how a package can have multiple inputs, it can also produce multiple | |
905 | outputs. | |
906 | ||
907 | Each output corresponds to a separate directory in the store. | |
908 | ||
909 | The user can choose which output to install; this is useful to save space or | |
910 | to avoid polluting the user profile with unwanted executables or libraries. | |
911 | ||
912 | Output separation is optional. When the @code{outputs} field is left out, the | |
913 | default and only output (the complete package) is referred to as @code{"out"}. | |
914 | ||
915 | Typical separate output names include @code{debug} and @code{doc}. | |
916 | ||
917 | It's advised to separate outputs only when you've shown it's worth it: if the | |
918 | output size is significant (compare with @code{guix size}) or in case the package is | |
919 | modular. | |
920 | ||
921 | @subsubsection Build system arguments | |
922 | ||
923 | The @code{arguments} is a keyword-value list used to configure the build process. | |
924 | ||
925 | The simplest argument @code{#:tests?} can be used to disable the test suite when | |
926 | building the package. This is mostly useful when the package does not feature | |
927 | any test suite. It's strongly recommended to keep the test suite on if there is | |
928 | one. | |
929 | ||
930 | Another common argument is @code{:make-flags}, which specifies a list of flags to | |
931 | append when running make, as you would from the command line. For instance, the | |
932 | following flags | |
933 | ||
d482e13f | 934 | @lisp |
ffe059af PN |
935 | #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out")) |
936 | "CC=gcc") | |
d482e13f | 937 | @end lisp |
ffe059af PN |
938 | |
939 | translate into | |
940 | ||
941 | @example | |
942 | $ make CC=gcc prefix=/gnu/store/...-<out> | |
943 | @end example | |
944 | ||
945 | This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation | |
946 | directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage | |
947 | global variable pointing to the destination directory in the store (something like | |
948 | @samp{/gnu/store/...-my-libgit2-20180408}). | |
949 | ||
950 | Similarly, it's possible to set the "configure" flags. | |
951 | ||
d482e13f | 952 | @lisp |
ffe059af | 953 | #:configure-flags '("-DUSE_SHA1DC=ON") |
d482e13f | 954 | @end lisp |
ffe059af PN |
955 | |
956 | The @code{%build-inputs} variable is also generated in scope. It's an association | |
957 | table that maps the input names to their store directories. | |
958 | ||
959 | The @code{phases} keyword lists the sequential steps of the build system. Typically | |
960 | phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know | |
961 | more about those phases, you need to work out the appropriate build system | |
962 | definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}: | |
963 | ||
d482e13f | 964 | @lisp |
ffe059af PN |
965 | (define %standard-phases |
966 | ;; Standard build phases, as a list of symbol/procedure pairs. | |
967 | (let-syntax ((phases (syntax-rules () | |
968 | ((_ p ...) `((p . ,p) ...))))) | |
969 | (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack | |
970 | bootstrap | |
971 | patch-usr-bin-file | |
972 | patch-source-shebangs configure patch-generated-file-shebangs | |
973 | build check install | |
974 | patch-shebangs strip | |
975 | validate-runpath | |
976 | validate-documentation-location | |
977 | delete-info-dir-file | |
978 | patch-dot-desktop-files | |
979 | install-license-files | |
980 | reset-gzip-timestamps | |
981 | compress-documentation))) | |
d482e13f | 982 | @end lisp |
ffe059af PN |
983 | |
984 | Or from the REPL: | |
985 | ||
d482e13f | 986 | @lisp |
ffe059af PN |
987 | > (add-to-load-path "/path/to/guix/checkout") |
988 | > ,module (guix build gnu-build-system) | |
989 | > (map first %standard-phases) | |
990 | (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) | |
d482e13f | 991 | @end lisp |
ffe059af PN |
992 | |
993 | If you want to know more about what happens during those phases, consult the | |
994 | associated procedures. | |
995 | ||
996 | For instance, as of this writing the definition of @code{unpack} for the GNU build | |
997 | system is | |
998 | ||
d482e13f | 999 | @lisp |
ffe059af PN |
1000 | (define* (unpack #:key source #:allow-other-keys) |
1001 | "Unpack SOURCE in the working directory, and change directory within the | |
1002 | source. When SOURCE is a directory, copy it in a sub-directory of the current | |
1003 | working directory." | |
1004 | (if (file-is-directory? source) | |
1005 | (begin | |
1006 | (mkdir "source") | |
1007 | (chdir "source") | |
1008 | ||
1009 | ;; Preserve timestamps (set to the Epoch) on the copied tree so that | |
1010 | ;; things work deterministically. | |
1011 | (copy-recursively source "." | |
1012 | #:keep-mtime? #t)) | |
1013 | (begin | |
1014 | (if (string-suffix? ".zip" source) | |
1015 | (invoke "unzip" source) | |
1016 | (invoke "tar" "xvf" source)) | |
1017 | (chdir (first-subdirectory ".")))) | |
1018 | #t) | |
d482e13f | 1019 | @end lisp |
ffe059af PN |
1020 | |
1021 | Note the @code{chdir} call: it changes the working directory to where the source was | |
1022 | unpacked. | |
1023 | Thus every phase following the @code{unpack} will use the source as a working | |
1024 | directory, which is why we can directly work on the source files. | |
1025 | That is to say, unless a later phase changes the working directory to something | |
1026 | else. | |
1027 | ||
1028 | We modify the list of @code{%standard-phases} of the build system with the | |
1029 | @code{modify-phases} macro as per the list of specified modifications, which may have | |
1030 | the following forms: | |
1031 | ||
1032 | @itemize | |
1033 | @item | |
1034 | @code{(add-before PHASE NEW-PHASE PROCEDURE)}: Run @code{PROCEDURE} named @code{NEW-PHASE} before @code{PHASE}. | |
1035 | @item | |
1036 | @code{(add-after PHASE NEW-PHASE PROCEDURE)}: Same, but afterwards. | |
1037 | @item | |
1038 | @code{(replace PHASE PROCEDURE)}. | |
1039 | @item | |
1040 | @code{(delete PHASE)}. | |
1041 | @end itemize | |
1042 | ||
1043 | The @code{PROCEDURE} supports the keyword arguments @code{inputs} and @code{outputs}. Each | |
1044 | input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced | |
1045 | by their name in those variables. Thus @code{(assoc-ref outputs "out")} is the store | |
1046 | directory of the main output of the package. A phase procedure may look like | |
1047 | this: | |
1048 | ||
d482e13f | 1049 | @lisp |
ffe059af PN |
1050 | (lambda* (#:key inputs outputs #:allow-other-keys) |
1051 | (let (((bash-directory (assoc-ref inputs "bash")) | |
1052 | (output-directory (assoc-ref outputs "out")) | |
1053 | (doc-directory (assoc-ref outputs "doc")) | |
1054 | ; ... | |
1055 | #t) | |
d482e13f | 1056 | @end lisp |
ffe059af PN |
1057 | |
1058 | The procedure must return @code{#t} on success. It's brittle to rely on the return | |
1059 | value of the last expression used to tweak the phase because there is no | |
1060 | guarantee it would be a @code{#t}. Hence the trailing @code{#t} to ensure the right value | |
1061 | is returned on success. | |
1062 | ||
1063 | @subsubsection Code staging | |
1064 | ||
1065 | The astute reader may have noticed the quasi-quote and comma syntax in the | |
1066 | argument field. Indeed, the build code in the package declaration should not be | |
1067 | evaluated on the client side, but only when passed to the Guix daemon. This | |
1068 | mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}. | |
1069 | ||
1070 | @subsubsection "Utils" functions | |
1071 | ||
1072 | When customizing @code{phases}, we often need to write code that mimics the | |
1073 | equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.) commonly used during | |
1074 | regular "Unix-style" installations. | |
1075 | ||
1076 | Some like @code{chmod} are native to Guile. | |
1077 | @xref{,,, guile, Guile reference manual} for a complete list. | |
1078 | ||
1079 | Guix provides additional helper functions which prove especially handy in the | |
1080 | context of package management. | |
1081 | ||
1082 | Some of those functions can be found in | |
1083 | @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour | |
1084 | of the traditional Unix system commands: | |
1085 | ||
1086 | @table @asis | |
1087 | @item which | |
1088 | Like the @samp{which} system command. | |
1089 | @item find-files | |
1090 | Akin to the @samp{find} system command. | |
1091 | @item mkdir-p | |
1092 | Like @samp{mkdir -p}, which creates all parents as needed. | |
1093 | @item install-file | |
1094 | Similar to @samp{install} when installing a file to a (possibly | |
1095 | non-existing) directory. Guile has @code{copy-file} which works | |
1096 | like @samp{cp}. | |
1097 | @item copy-recursively | |
1098 | Like @samp{cp -r}. | |
1099 | @item delete-file-recursively | |
1100 | Like @samp{rm -rf}. | |
1101 | @item invoke | |
1102 | Run an executable. This should be used instead of @code{system*}. | |
1103 | @item with-directory-excursion | |
1104 | Run the body in a different working directory, | |
1105 | then restore the previous working directory. | |
1106 | @item substitute* | |
1107 | A "sed-like" function. | |
1108 | @end table | |
1109 | ||
1110 | @subsubsection Module prefix | |
1111 | ||
1112 | The license in our last example needs a prefix: this is because of how the | |
1113 | @code{license} module was imported in the package, as @code{#:use-module ((guix licenses) | |
1114 | #:prefix license:)}. The Guile module import mechanism | |
1115 | (@pxref{Using Guile Modules,,, guile, Guile reference manual}) | |
1116 | gives the user full control over namespacing: this is needed to avoid | |
1117 | clashes between, say, the | |
1118 | @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable | |
1119 | from @samp{compression.scm} (a @emph{package} value). | |
1120 | ||
1121 | @node Other build systems | |
1122 | @subsection Other build systems | |
1123 | ||
1124 | What we've seen so far covers the majority of packages using a build system | |
1125 | other than the @code{trivial-build-system}. The latter does not automate anything | |
1126 | and leaves you to build everything manually. This can be more demanding and we | |
1127 | won't cover it here for now, but thankfully it is rarely necessary to fall back | |
1128 | on this system. | |
1129 | ||
1130 | For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the | |
1131 | process is very similar to the GNU build system except for a few specialized | |
1132 | arguments. | |
1133 | ||
1134 | Learn more about build systems in | |
1135 | @itemize | |
1136 | @item | |
1137 | @uref{https://www.gnu.org/software/guix/manual/en/html_node/Build-Systems.html#Build-Systems, the manual, section 4.2 Build systems}, | |
1138 | @item | |
1139 | the source code in the @samp{$GUIX_CHECKOUT/guix/build} and | |
1140 | @samp{$GUIX_CHECKOUT/guix/build-system} directories. | |
1141 | @end itemize | |
1142 | ||
1143 | @node Programmable and automated package definition | |
1144 | @subsection Programmable and automated package definition | |
1145 | ||
1146 | We can't repeat it enough: having a full-fledged programming language at hand | |
1147 | empowers us in ways that reach far beyond traditional package management. | |
1148 | ||
1149 | Let's illustrate this with some awesome features of Guix! | |
1150 | ||
1151 | @node Recursive importers | |
1152 | @subsubsection Recursive importers | |
1153 | ||
1154 | You might find some build systems good enough that there is little to do at all | |
1155 | to write a package, to the point that it becomes repetitive and tedious after a | |
1156 | while. A @emph{raison d'être} of computers is to replace human beings at those | |
1157 | boring tasks. So let's tell Guix to do this for us and create the package | |
1158 | definition of an R package from CRAN (the output is trimmed for conciseness): | |
1159 | ||
1160 | @example | |
1161 | $ guix import cran --recursive walrus | |
1162 | ||
1163 | (define-public r-mc2d | |
1164 | ; ... | |
1165 | (license gpl2+))) | |
1166 | ||
1167 | (define-public r-jmvcore | |
1168 | ; ... | |
1169 | (license gpl2+))) | |
1170 | ||
1171 | (define-public r-wrs2 | |
1172 | ; ... | |
1173 | (license gpl3))) | |
1174 | ||
1175 | (define-public r-walrus | |
1176 | (package | |
1177 | (name "r-walrus") | |
1178 | (version "1.0.3") | |
1179 | (source | |
1180 | (origin | |
1181 | (method url-fetch) | |
1182 | (uri (cran-uri "walrus" version)) | |
1183 | (sha256 | |
1184 | (base32 | |
1185 | "1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj")))) | |
1186 | (build-system r-build-system) | |
1187 | (propagated-inputs | |
1188 | `(("r-ggplot2" ,r-ggplot2) | |
1189 | ("r-jmvcore" ,r-jmvcore) | |
1190 | ("r-r6" ,r-r6) | |
1191 | ("r-wrs2" ,r-wrs2))) | |
1192 | (home-page "https://github.com/jamovi/walrus") | |
1193 | (synopsis "Robust Statistical Methods") | |
1194 | (description | |
1195 | "This package provides a toolbox of common robust statistical | |
1196 | tests, including robust descriptives, robust t-tests, and robust ANOVA. | |
1197 | It is also available as a module for 'jamovi' (see | |
1198 | <https://www.jamovi.org> for more information). Walrus is based on the | |
1199 | WRS2 package by Patrick Mair, which is in turn based on the scripts and | |
1200 | work of Rand Wilcox. These analyses are described in depth in the book | |
1201 | 'Introduction to Robust Estimation & Hypothesis Testing'.") | |
1202 | (license gpl3))) | |
1203 | @end example | |
1204 | ||
1205 | The recursive importer won't import packages for which Guix already has package | |
1206 | definitions, except for the very first. | |
1207 | ||
1208 | Not all applications can be packaged this way, only those relying on a select | |
1209 | number of supported systems. Read about the full list of importers in | |
1210 | the guix import section of the manual | |
1211 | (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual}). | |
1212 | ||
1213 | @node Automatic update | |
1214 | @subsubsection Automatic update | |
1215 | ||
1216 | Guix can be smart enough to check for updates on systems it knows. It can | |
1217 | report outdated package definitions with | |
1218 | ||
1219 | @example | |
1220 | $ guix refresh hello | |
1221 | @end example | |
1222 | ||
1223 | In most cases, updating a package to a newer version requires little more than | |
1224 | changing the version number and the checksum. Guix can do that automatically as | |
1225 | well: | |
1226 | ||
1227 | @example | |
1228 | $ guix refresh hello --update | |
1229 | @end example | |
1230 | ||
1231 | @node Inheritance | |
1232 | @subsubsection Inheritance | |
1233 | ||
1234 | If you've started browsing the existing package definitions, you might have | |
1235 | noticed that a significant number of them have a @code{inherit} field: | |
1236 | ||
d482e13f | 1237 | @lisp |
ffe059af PN |
1238 | (define-public adwaita-icon-theme |
1239 | (package (inherit gnome-icon-theme) | |
1240 | (name "adwaita-icon-theme") | |
1241 | (version "3.26.1") | |
1242 | (source (origin | |
1243 | (method url-fetch) | |
1244 | (uri (string-append "mirror://gnome/sources/" name "/" | |
1245 | (version-major+minor version) "/" | |
1246 | name "-" version ".tar.xz")) | |
1247 | (sha256 | |
1248 | (base32 | |
1249 | "17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8")))) | |
1250 | (native-inputs | |
1251 | `(("gtk-encode-symbolic-svg" ,gtk+ "bin"))))) | |
d482e13f | 1252 | @end lisp |
ffe059af PN |
1253 | |
1254 | All unspecified fields are inherited from the parent package. This is very | |
1255 | convenient to create alternative packages, for instance with different source, | |
1256 | version or compilation options. | |
1257 | ||
1258 | @node Getting help | |
1259 | @subsection Getting help | |
1260 | ||
1261 | Sadly, some applications can be tough to package. Sometimes they need a patch to | |
1262 | work with the non-standard filesystem hierarchy enforced by the store. | |
1263 | Sometimes the tests won't run properly. (They can be skipped but this is not | |
1264 | recommended.) Other times the resulting package won't be reproducible. | |
1265 | ||
1266 | Should you be stuck, unable to figure out how to fix any sort of packaging | |
1267 | issue, don't hesitate to ask the community for help. | |
1268 | ||
1269 | See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc. | |
1270 | ||
1271 | @node Conclusion | |
1272 | @subsection Conclusion | |
1273 | ||
1274 | This tutorial was a showcase of the sophisticated package management that Guix | |
1275 | boasts. At this point we have mostly restricted this introduction to the | |
1276 | @code{gnu-build-system} which is a core abstraction layer on which more advanced | |
1277 | abstractions are based. | |
1278 | ||
1279 | Where do we go from here? Next we ought to dissect the innards of the build | |
1280 | system by removing all abstractions, using the @code{trivial-build-system}: this | |
1281 | should give us a thorough understanding of the process before investigating some | |
1282 | more advanced packaging techniques and edge cases. | |
1283 | ||
1284 | Other features worth exploring are the interactive editing and debugging | |
1285 | capabilities of Guix provided by the Guile REPL@. | |
1286 | ||
1287 | Those fancy features are completely optional and can wait; now is a good time | |
1288 | to take a well-deserved break. With what we've introduced here you should be | |
1289 | well armed to package lots of programs. You can get started right away and | |
1290 | hopefully we will see your contributions soon! | |
1291 | ||
1292 | @node References | |
1293 | @subsection References | |
1294 | ||
1295 | @itemize | |
1296 | @item | |
1297 | The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual} | |
1298 | ||
1299 | @item | |
1300 | @uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix} | |
1301 | ||
1302 | @item | |
1303 | @uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, "GNU Guix: Package without a scheme!"}, by Andreas Enge | |
1304 | @end itemize | |
7bc46ecc RW |
1305 | |
1306 | @c ********************************************************************* | |
1307 | @node System Configuration | |
1308 | @chapter System Configuration | |
1309 | ||
1310 | Guix offers a flexible language for declaratively configuring your Guix | |
1311 | System. This flexibility can at times be overwhelming. The purpose of this | |
1312 | chapter is to demonstrate some advanced configuration concepts. | |
1313 | ||
1314 | @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete | |
1315 | reference. | |
1316 | ||
1317 | @menu | |
1318 | * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. | |
1319 | @end menu | |
1320 | ||
1321 | @node Customizing the Kernel | |
1322 | @section Customizing the Kernel | |
1323 | ||
1324 | Guix is, at its core, a source based distribution with substitutes | |
1325 | (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building | |
1326 | packages from their source code is an expected part of regular package | |
1327 | installations and upgrades. Given this starting point, it makes sense that | |
1328 | efforts are made to reduce the amount of time spent compiling packages, and | |
1329 | recent changes and upgrades to the building and distribution of substitutes | |
1330 | continues to be a topic of discussion within Guix. | |
1331 | ||
1332 | The kernel, while not requiring an overabundance of RAM to build, does take a | |
1333 | rather long time on an average machine. The official kernel configuration, as | |
1334 | is the case with many GNU/Linux distributions, errs on the side of | |
1335 | inclusiveness, and this is really what causes the build to take such a long | |
1336 | time when the kernel is built from source. | |
1337 | ||
1338 | The Linux kernel, however, can also just be described as a regular old | |
1339 | package, and as such can be customized just like any other package. The | |
1340 | procedure is a little bit different, although this is primarily due to the | |
1341 | nature of how the package definition is written. | |
1342 | ||
1343 | The @code{linux-libre} kernel package definition is actually a procedure which | |
1344 | creates a package. | |
1345 | ||
b1eecb5c | 1346 | @lisp |
7bc46ecc RW |
1347 | (define* (make-linux-libre version hash supported-systems |
1348 | #:key | |
1349 | ;; A function that takes an arch and a variant. | |
1350 | ;; See kernel-config for an example. | |
1351 | (extra-version #f) | |
1352 | (configuration-file #f) | |
1353 | (defconfig "defconfig") | |
1354 | (extra-options %default-extra-linux-options) | |
1355 | (patches (list %boot-logo-patch))) | |
1356 | ...) | |
b1eecb5c | 1357 | @end lisp |
7bc46ecc RW |
1358 | |
1359 | The current @code{linux-libre} package is for the 5.1.x series, and is | |
1360 | declared like this: | |
1361 | ||
b1eecb5c | 1362 | @lisp |
7bc46ecc RW |
1363 | (define-public linux-libre |
1364 | (make-linux-libre %linux-libre-version | |
1365 | %linux-libre-hash | |
1366 | '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux") | |
1367 | #:patches %linux-libre-5.1-patches | |
1368 | #:configuration-file kernel-config)) | |
b1eecb5c | 1369 | @end lisp |
7bc46ecc RW |
1370 | |
1371 | Any keys which are not assigned values inherit their default value from the | |
1372 | @code{make-linux-libre} definition. When comparing the two snippets above, | |
1373 | you may notice that the code comment in the first doesn't actually refer to | |
1374 | the @code{#:extra-version} keyword; it is actually for | |
1375 | @code{#:configuration-file}. Because of this, it is not actually easy to | |
1376 | include a custom kernel configuration from the definition, but don't worry, | |
1377 | there are other ways to work with what we do have. | |
1378 | ||
1379 | There are two ways to create a kernel with a custom kernel configuration. The | |
1380 | first is to provide a standard @file{.config} file during the build process by | |
1381 | including an actual @file{.config} file as a native input to our custom | |
1382 | kernel. The following is a snippet from the custom @code{'configure} phase of | |
1383 | the @code{make-linux-libre} package definition: | |
1384 | ||
b1eecb5c | 1385 | @lisp |
7bc46ecc RW |
1386 | (let ((build (assoc-ref %standard-phases 'build)) |
1387 | (config (assoc-ref (or native-inputs inputs) "kconfig"))) | |
1388 | ||
1389 | ;; Use a custom kernel configuration file or a default | |
1390 | ;; configuration file. | |
1391 | (if config | |
1392 | (begin | |
1393 | (copy-file config ".config") | |
1394 | (chmod ".config" #o666)) | |
1395 | (invoke "make" ,defconfig)) | |
b1eecb5c | 1396 | @end lisp |
7bc46ecc RW |
1397 | |
1398 | Below is a sample kernel package. The @code{linux-libre} package is nothing | |
1399 | special and can be inherited from and have its fields overridden like any | |
1400 | other package: | |
1401 | ||
b1eecb5c | 1402 | @lisp |
7bc46ecc RW |
1403 | (define-public linux-libre/E2140 |
1404 | (package | |
1405 | (inherit linux-libre) | |
1406 | (native-inputs | |
1407 | `(("kconfig" ,(local-file "E2140.config")) | |
1408 | ,@@(alist-delete "kconfig" | |
1409 | (package-native-inputs linux-libre)))))) | |
b1eecb5c | 1410 | @end lisp |
7bc46ecc RW |
1411 | |
1412 | In the same directory as the file defining @code{linux-libre-E2140} is a file | |
1413 | named @file{E2140.config}, which is an actual kernel configuration file. The | |
1414 | @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the | |
1415 | only kernel configuration in the package is the one which was included in the | |
1416 | @code{native-inputs} field. | |
1417 | ||
1418 | The second way to create a custom kernel is to pass a new value to the | |
1419 | @code{extra-options} keyword of the @code{make-linux-libre} procedure. The | |
1420 | @code{extra-options} keyword works with another function defined right below | |
1421 | it: | |
1422 | ||
b1eecb5c | 1423 | @lisp |
7bc46ecc RW |
1424 | (define %default-extra-linux-options |
1425 | `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html | |
1426 | ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t) | |
1427 | ;; Modules required for initrd: | |
1428 | ("CONFIG_NET_9P" . m) | |
1429 | ("CONFIG_NET_9P_VIRTIO" . m) | |
1430 | ("CONFIG_VIRTIO_BLK" . m) | |
1431 | ("CONFIG_VIRTIO_NET" . m) | |
1432 | ("CONFIG_VIRTIO_PCI" . m) | |
1433 | ("CONFIG_VIRTIO_BALLOON" . m) | |
1434 | ("CONFIG_VIRTIO_MMIO" . m) | |
1435 | ("CONFIG_FUSE_FS" . m) | |
1436 | ("CONFIG_CIFS" . m) | |
1437 | ("CONFIG_9P_FS" . m))) | |
1438 | ||
1439 | (define (config->string options) | |
1440 | (string-join (map (match-lambda | |
1441 | ((option . 'm) | |
1442 | (string-append option "=m")) | |
1443 | ((option . #t) | |
1444 | (string-append option "=y")) | |
1445 | ((option . #f) | |
1446 | (string-append option "=n"))) | |
1447 | options) | |
1448 | "\n")) | |
b1eecb5c | 1449 | @end lisp |
7bc46ecc RW |
1450 | |
1451 | And in the custom configure script from the `make-linux-libre` package: | |
1452 | ||
b1eecb5c | 1453 | @lisp |
7bc46ecc RW |
1454 | ;; Appending works even when the option wasn't in the |
1455 | ;; file. The last one prevails if duplicated. | |
1456 | (let ((port (open-file ".config" "a")) | |
1457 | (extra-configuration ,(config->string extra-options))) | |
1458 | (display extra-configuration port) | |
1459 | (close-port port)) | |
1460 | ||
1461 | (invoke "make" "oldconfig")))) | |
b1eecb5c | 1462 | @end lisp |
7bc46ecc RW |
1463 | |
1464 | So by not providing a configuration-file the @file{.config} starts blank, and | |
1465 | then we write into it the collection of flags that we want. Here's another | |
1466 | custom kernel: | |
1467 | ||
b1eecb5c | 1468 | @lisp |
7bc46ecc RW |
1469 | (define %macbook41-full-config |
1470 | (append %macbook41-config-options | |
1471 | %filesystems | |
1472 | %efi-support | |
1473 | %emulation | |
1474 | (@@@@ (gnu packages linux) %default-extra-linux-options))) | |
1475 | ||
1476 | (define-public linux-libre-macbook41 | |
1477 | ;; XXX: Access the internal 'make-linux-libre' procedure, which is | |
1478 | ;; private and unexported, and is liable to change in the future. | |
1479 | ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux) %linux-libre-version) | |
1480 | (@@@@ (gnu packages linux) %linux-libre-hash) | |
1481 | '("x86_64-linux") | |
1482 | #:extra-version "macbook41" | |
1483 | #:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches) | |
1484 | #:extra-options %macbook41-config-options)) | |
b1eecb5c | 1485 | @end lisp |
7bc46ecc RW |
1486 | |
1487 | In the above example @code{%filesystems} is a collection of flags enabling | |
1488 | different filesystem support, @code{%efi-support} enables EFI support and | |
1489 | @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also. | |
1490 | @code{%default-extra-linux-options} are the ones quoted above, which had to be | |
1491 | added in since they were replaced in the @code{extra-options} keyword. | |
1492 | ||
1493 | This all sounds like it should be doable, but how does one even know which | |
1494 | modules are required for a particular system? Two places that can be helpful | |
1495 | in trying to answer this question is the | |
1496 | @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo | |
1497 | Handbook} and the | |
1498 | @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig, | |
1499 | documentation from the kernel itself}. From the kernel documentation, it | |
1500 | seems that @code{make localmodconfig} is the command we want. | |
1501 | ||
1502 | In order to actually run @code{make localmodconfig} we first need to get and | |
1503 | unpack the kernel source code: | |
1504 | ||
1505 | @example shell | |
1506 | tar xf $(guix build linux-libre --source) | |
1507 | @end example | |
1508 | ||
1509 | Once inside the directory containing the source code run @code{touch .config} | |
1510 | to create an initial, empty @file{.config} to start with. @code{make | |
1511 | localmodconfig} works by seeing what you already have in @file{.config} and | |
1512 | letting you know what you're missing. If the file is blank then you're | |
1513 | missing everything. The next step is to run: | |
1514 | ||
1515 | @example shell | |
1516 | guix environment linux-libre -- make localmodconfig | |
1517 | @end example | |
1518 | ||
1519 | and note the output. Do note that the @file{.config} file is still empty. | |
1520 | The output generally contains two types of warnings. The first start with | |
1521 | "WARNING" and can actually be ignored in our case. The second read: | |
1522 | ||
1523 | @example shell | |
1524 | module pcspkr did not have configs CONFIG_INPUT_PCSPKR | |
1525 | @end example | |
1526 | ||
1527 | For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the | |
1528 | @file{.config} in the directory, and append @code{=m}, so in the end it looks | |
1529 | like this: | |
1530 | ||
1531 | @example shell | |
1532 | CONFIG_INPUT_PCSPKR=m | |
1533 | CONFIG_VIRTIO=m | |
1534 | @end example | |
1535 | ||
1536 | After copying all the configuration options, run @code{make localmodconfig} | |
1537 | again to make sure that you don't have any output starting with "module". | |
1538 | After all of these machine specific modules there are a couple more left that | |
1539 | are also needed. @code{CONFIG_MODULES} is necessary so that you can build and | |
1540 | load modules separately and not have everything built into the kernel. | |
1541 | @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is | |
1542 | possible that there are other modules which you will need. | |
1543 | ||
1544 | This post does not aim to be a guide to configuring your own kernel however, | |
1545 | so if you do decide to build a custom kernel you'll have to seek out other | |
1546 | guides to create a kernel which is just right for your needs. | |
1547 | ||
1548 | The second way to setup the kernel configuration makes more use of Guix's | |
1549 | features and allows you to share configuration segments between different | |
1550 | kernels. For example, all machines using EFI to boot have a number of EFI | |
1551 | configuration flags that they need. It is likely that all the kernels will | |
1552 | share a list of filesystems to support. By using variables it is easier to | |
1553 | see at a glance what features are enabled and to make sure you don't have | |
1554 | features in one kernel but missing in another. | |
1555 | ||
1556 | Left undiscussed however, is Guix's initrd and its customization. It is | |
1557 | likely that you'll need to modify the initrd on a machine using a custom | |
1558 | kernel, since certain modules which are expected to be built may not be | |
1559 | available for inclusion into the initrd. | |
1560 | ||
4c463569 PN |
1561 | @c ********************************************************************* |
1562 | @node Advanced package management | |
1563 | @chapter Advanced package management | |
1564 | ||
1565 | Guix is a functional package manager that offers many features beyond | |
1566 | what more traditional package managers can do. To the uninitiated, | |
1567 | those features might not have obvious use cases at first. The purpose | |
1568 | of this chapter is to demonstrate some advanced package management | |
1569 | concepts. | |
1570 | ||
1571 | @pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete | |
1572 | reference. | |
1573 | ||
1574 | @menu | |
1575 | * Guix Profiles in Practice:: Strategies for multiple profiles and manifests. | |
1576 | @end menu | |
1577 | ||
1578 | @node Guix Profiles in Practice | |
1579 | @section Guix Profiles in Practice | |
1580 | ||
1581 | Guix provides a very useful feature that may be quite foreign to newcomers: | |
1582 | @emph{profiles}. They are a way to group package installations together and all users | |
f6c27c55 | 1583 | on the same system are free to use as many profiles as they want. |
4c463569 PN |
1584 | |
1585 | Whether you're a developer or not, you may find that multiple profiles bring you | |
1586 | great power and flexibility. While they shift the paradigm somewhat compared to | |
1587 | @emph{traditional package managers}, they are very convenient to use once you've | |
1588 | understood how to set them up. | |
1589 | ||
1590 | If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a | |
1591 | kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not | |
1592 | just Python software. Furthermore, profiles are self-sufficient: they capture | |
1593 | all the runtime dependencies which guarantees that all programs within a profile | |
1594 | will always work at any point in time. | |
1595 | ||
1596 | Multiple profiles have many benefits: | |
1597 | ||
1598 | @itemize | |
1599 | @item | |
1600 | Clean semantic separation of the various packages a user needs for different contexts. | |
1601 | ||
1602 | @item | |
1603 | Multiple profiles can be made available into the environment either on login | |
1604 | or within a dedicated shell. | |
1605 | ||
1606 | @item | |
1607 | Profiles can be loaded on demand. For instance, the user can use multiple | |
1608 | shells, each of them running different profiles. | |
1609 | ||
1610 | @item | |
1611 | Isolation: Programs from one profile will not use programs from the other, and | |
f6c27c55 | 1612 | the user can even install different versions of the same programs to the two |
4c463569 PN |
1613 | profiles without conflict. |
1614 | ||
1615 | @item | |
1616 | Deduplication: Profiles share dependencies that happens to be the exact same. | |
1617 | This makes multiple profiles storage-efficient. | |
1618 | ||
1619 | @item | |
1620 | Reproducible: when used with declarative manifests, a profile can be fully | |
1621 | specified by the Guix commit that was active when it was set up. This means | |
f6c27c55 PN |
1622 | that the exact same profile can be |
1623 | @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/, | |
1624 | set up anywhere and anytime}, with just the commit information. See the | |
1625 | section on @ref{Reproducible profiles}. | |
4c463569 PN |
1626 | |
1627 | @item | |
1628 | Easier upgrades and maintenance: Multiple profiles make it easy to keep | |
1629 | package listings at hand and make upgrades completely friction-less. | |
1630 | @end itemize | |
1631 | ||
1632 | Concretely, here follows some typical profiles: | |
1633 | ||
1634 | @itemize | |
1635 | @item | |
1636 | The dependencies of a project you are working on. | |
1637 | ||
1638 | @item | |
1639 | Your favourite programming language libraries. | |
1640 | ||
1641 | @item | |
1642 | Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop. | |
1643 | ||
1644 | @item | |
1645 | @TeX{}live (this one can be really useful when you need to install just one | |
1646 | package for this one document you've just received over email). | |
1647 | ||
1648 | @item | |
1649 | Games. | |
1650 | @end itemize | |
1651 | ||
1652 | Let's dive in the set up! | |
1653 | ||
1654 | @node Basic setup with manifests | |
1655 | @subsection Basic setup with manifests | |
1656 | ||
1657 | A Guix profile can be set up @emph{via} a so-called @emph{manifest specification} that looks like | |
1658 | this: | |
1659 | ||
b1eecb5c | 1660 | @lisp |
4c463569 PN |
1661 | (specifications->manifest |
1662 | '("package-1" | |
1663 | ;; Version 1.3 of package-2. | |
1664 | "package-2@@1.3" | |
1665 | ;; The "lib" output of package-3. | |
1666 | "package-3:lib" | |
1667 | ; ... | |
1668 | "package-N")) | |
b1eecb5c | 1669 | @end lisp |
4c463569 | 1670 | |
b1eecb5c | 1671 | @pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for |
4c463569 PN |
1672 | the syntax details. |
1673 | ||
1674 | We can create a manifest specification per profile and install them this way: | |
1675 | ||
1676 | @example | |
1677 | GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles | |
1678 | mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet | |
1679 | guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project | |
1680 | @end example | |
1681 | ||
1682 | Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory | |
1683 | where we will store our profiles in the rest of this article. | |
1684 | ||
1685 | Placing all your profiles in a single directory, with each profile getting its | |
1686 | own sub-directory, is somewhat cleaner. This way, each sub-directory will | |
1687 | contain all the symlinks for precisely one profile. Besides, "looping over | |
1688 | profiles" becomes obvious from any programming language (e.g. a shell script) by | |
1689 | simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}. | |
1690 | ||
1691 | Note that it's also possible to loop over the output of | |
1692 | ||
1693 | @example | |
1694 | guix package --list-profiles | |
1695 | @end example | |
1696 | ||
1697 | although you'll probably have to filter out @samp{~/.config/guix/current}. | |
1698 | ||
1699 | To enable all profiles on login, add this to your @samp{~/.bash_profile} (or similar): | |
1700 | ||
1701 | @example | |
1702 | for i in $GUIX_EXTRA_PROFILES/*; do | |
1703 | profile=$i/$(basename "$i") | |
1704 | if [ -f "$profile"/etc/profile ]; then | |
1705 | GUIX_PROFILE="$profile" | |
1706 | . "$GUIX_PROFILE"/etc/profile | |
1707 | fi | |
1708 | unset profile | |
1709 | done | |
1710 | @end example | |
1711 | ||
1712 | Note to Guix System users: the above reflects how your default profile | |
1713 | @samp{~/.guix-profile} is activated from @samp{/etc/profile}, that latter being loaded by | |
1714 | @samp{~/.bashrc} by default. | |
1715 | ||
1716 | You can obviously choose to only enable a subset of them: | |
1717 | ||
1718 | @example | |
1719 | for i in "$GUIX_EXTRA_PROFILES"/my-project-1 "$GUIX_EXTRA_PROFILES"/my-project-2; do | |
1720 | profile=$i/$(basename "$i") | |
1721 | if [ -f "$profile"/etc/profile ]; then | |
1722 | GUIX_PROFILE="$profile" | |
1723 | . "$GUIX_PROFILE"/etc/profile | |
1724 | fi | |
1725 | unset profile | |
1726 | done | |
1727 | @end example | |
1728 | ||
1729 | When a profile is off, it's straightforward to enable it for an individual shell | |
1730 | without "polluting" the rest of the user session: | |
1731 | ||
1732 | @example | |
1733 | GUIX_PROFILE="path/to/my-project" ; . "$GUIX_PROFILE"/etc/profile | |
1734 | @end example | |
1735 | ||
1736 | The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file | |
1737 | contains shell code that exports the right environment variables necessary to | |
1738 | activate the software contained in the profile. It is built automatically by | |
1739 | Guix and meant to be sourced. | |
1740 | It contains the same variables you would get if you ran: | |
1741 | ||
1742 | @example | |
1743 | guix package --search-paths=prefix --profile=$my_profile" | |
1744 | @end example | |
1745 | ||
1746 | Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}) | |
1747 | for the command line options. | |
1748 | ||
1749 | To upgrade a profile, simply install the manifest again: | |
1750 | ||
1751 | @example | |
1752 | guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project | |
1753 | @end example | |
1754 | ||
1755 | To upgrade all profiles, it's easy enough to loop over them. For instance, | |
1756 | assuming your manifest specifications are stored in | |
1757 | @samp{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name | |
1758 | of the profile (e.g. "project1"), you could do the following in Bourne shell: | |
1759 | ||
1760 | @example | |
1761 | for profile in "$GUIX_EXTRA_PROFILES"/*; do | |
1762 | guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm" | |
1763 | done | |
1764 | @end example | |
1765 | ||
1766 | Each profile has its own generations: | |
1767 | ||
1768 | @example | |
1769 | guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --list-generations | |
1770 | @end example | |
1771 | ||
1772 | You can roll-back to any generation of a given profile: | |
1773 | ||
1774 | @example | |
1775 | guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --switch-generations=17 | |
1776 | @end example | |
cb7b501d PN |
1777 | |
1778 | Finally, if you want to switch to a profile without inheriting from the | |
1779 | current environment, you can activate it from an empty shell: | |
1780 | ||
1781 | @example | |
1782 | env -i $(which bash) --login --noprofile --norc | |
1783 | . my-project/etc/profile | |
1784 | @end example | |
4c463569 PN |
1785 | |
1786 | @node Required packages | |
1787 | @subsection Required packages | |
1788 | ||
1789 | Activating a profile essentially boils down to exporting a bunch of | |
1790 | environmental variables. This is the role of the @samp{etc/profile} within the | |
1791 | profile. | |
1792 | ||
1793 | @emph{Note: Only the environmental variables of the packages that consume them will | |
1794 | be set.} | |
1795 | ||
1796 | For instance, @samp{MANPATH} won't be set if there is no consumer application for man | |
1797 | pages within the profile. So if you need to transparently access man pages once | |
1798 | the profile is loaded, you've got two options: | |
1799 | ||
1800 | @itemize | |
1801 | @item | |
1802 | Either export the variable manually, e.g. | |
1803 | @example | |
f6c27c55 | 1804 | export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH |
4c463569 PN |
1805 | @end example |
1806 | ||
1807 | @item | |
1808 | Or include @samp{man-db} to the profile manifest. | |
1809 | @end itemize | |
1810 | ||
1811 | The same is true for @samp{INFOPATH} (you can install @samp{info-reader}), | |
1812 | @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc. | |
1813 | ||
1814 | @node Default profile | |
1815 | @subsection Default profile | |
1816 | ||
1817 | What about the default profile that Guix keeps in @samp{~/.guix-profile}? | |
1818 | ||
1819 | You can assign it the role you want. Typically you would install the manifest | |
1820 | of the packages you want to use all the time. | |
1821 | ||
1822 | Alternatively, you could keep it "manifest-less" for throw-away packages | |
1823 | that you would just use for a couple of days. | |
1824 | This way makes it convenient to run | |
1825 | ||
1826 | @example | |
1827 | guix install package-foo | |
1828 | guix upgrade package-bar | |
1829 | @end example | |
1830 | ||
1831 | without having to specify the path to a profile. | |
1832 | ||
1833 | @node The benefits of manifests | |
1834 | @subsection The benefits of manifests | |
1835 | ||
1836 | Manifests are a convenient way to keep your package lists around and, say, | |
1837 | to synchronize them across multiple machines using a version control system. | |
1838 | ||
1839 | A common complaint about manifests is that they can be slow to install when they | |
1840 | contain large number of packages. This is especially cumbersome when you just | |
1841 | want get an upgrade for one package within a big manifest. | |
1842 | ||
1843 | This is one more reason to use multiple profiles, which happen to be just | |
1844 | perfect to break down manifests into multiple sets of semantically connected | |
1845 | packages. Using multiple, small profiles provides more flexibility and | |
1846 | usability. | |
1847 | ||
1848 | Manifests come with multiple benefits. In particular, they ease maintenance: | |
1849 | ||
1850 | @itemize | |
1851 | @item | |
1852 | When a profile is set up from a manifest, the manifest itself is | |
1853 | self-sufficient to keep a "package listing" around and reinstall the profile | |
1854 | later or on a different system. For ad-hoc profiles, we would need to | |
1855 | generate a manifest specification manually and maintain the package versions | |
1856 | for the packages that don't use the default version. | |
1857 | ||
1858 | @item | |
1859 | @code{guix package --upgrade} always tries to update the packages that have | |
1860 | propagated inputs, even if there is nothing to do. Guix manifests remove this | |
1861 | problem. | |
1862 | ||
1863 | @item | |
1864 | When partially upgrading a profile, conflicts may arise (due to diverging | |
1865 | dependencies between the updated and the non-updated packages) and they can be | |
1866 | annoying to resolve manually. Manifests remove this problem altogether since | |
1867 | all packages are always upgraded at once. | |
1868 | ||
1869 | @item | |
1870 | As mentioned above, manifests allow for reproducible profiles, while the | |
1871 | imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce | |
1872 | different profiles every time even when they hold the same packages. See | |
1873 | @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}. | |
1874 | ||
1875 | @item | |
1876 | Manifest specifications are usable by other @samp{guix} commands. For example, you | |
1877 | can run @code{guix weather -m manifest.scm} to see how many substitutes are | |
1878 | available, which can help you decide whether you want to try upgrading today | |
1879 | or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to | |
1880 | create a pack containing all the packages in the manifest (and their | |
1881 | transitive references). | |
1882 | ||
1883 | @item | |
1884 | Finally, manifests have a Scheme representation, the @samp{<manifest>} record type. | |
1885 | They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}. | |
1886 | @end itemize | |
1887 | ||
1888 | It's important to understand that while manifests can be used to declare | |
1889 | profiles, they are not strictly equivalent: profiles have the side effect that | |
1890 | they "pin" packages in the store, which prevents them from being | |
1891 | garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual}) | |
1892 | and ensures that they will still be available at any point in | |
1893 | the future. | |
1894 | ||
1895 | Let's take an example: | |
1896 | ||
1897 | @enumerate | |
1898 | @item | |
1899 | We have an environment for hacking on a project for which there isn't a Guix | |
1900 | package yet. We build the environment using a manifest, and then run @code{guix | |
1901 | environment -m manifest.scm}. So far so good. | |
1902 | ||
1903 | @item | |
1904 | Many weeks pass and we have run a couple of @code{guix pull} in the mean time. | |
1905 | Maybe a dependency from our manifest has been updated; or we may have run | |
1906 | @code{guix gc} and some packages needed by our manifest have been | |
1907 | garbage-collected. | |
1908 | ||
1909 | @item | |
1910 | Eventually, we set to work on that project again, so we run @code{guix environment | |
1911 | -m manifest.scm}. But now we have to wait for Guix to build and install | |
1912 | stuff! | |
1913 | @end enumerate | |
1914 | ||
1915 | Ideally, we could spare the rebuild time. And indeed we can, all we need is to | |
1916 | install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile; | |
1917 | . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our | |
1918 | hacking environment will be available at all times. | |
1919 | ||
1920 | @emph{Security warning:} While keeping old profiles around can be convenient, keep in | |
1921 | mind that outdated packages may not have received the latest security fixes. | |
1922 | ||
1923 | @node Reproducible profiles | |
1924 | @subsection Reproducible profiles | |
1925 | ||
1926 | To reproduce a profile bit-for-bit, we need two pieces of information: | |
1927 | ||
1928 | @itemize | |
1929 | @item | |
1930 | a manifest, | |
1931 | @item | |
1932 | a Guix channel specification. | |
1933 | @end itemize | |
1934 | ||
1935 | Indeed, manifests alone might not be enough: different Guix versions (or | |
1936 | different channels) can produce different outputs for a given manifest. | |
1937 | ||
1938 | You can output the Guix channel specification with @samp{guix describe | |
1939 | --format=channels}. | |
1940 | Save this to a file, say @samp{channel-specs.scm}. | |
1941 | ||
1942 | On another computer, you can use the channel specification file and the manifest | |
1943 | to reproduce the exact same profile: | |
1944 | ||
1945 | @example | |
1946 | GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles | |
1947 | GUIX_EXTRA=$HOME/.guix-extra | |
1948 | ||
1949 | mkdir "$GUIX_EXTRA"/my-project | |
1950 | guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix" | |
1951 | ||
1952 | mkdir -p "$GUIX_EXTRA_PROFILES/my-project" | |
1953 | "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project | |
1954 | @end example | |
1955 | ||
1956 | It's safe to delete the Guix channel profile you've just installed with the | |
1957 | channel specification, the project profile does not depend on it. | |
1958 | ||
7bc46ecc RW |
1959 | @c ********************************************************************* |
1960 | @node Acknowledgments | |
1961 | @chapter Acknowledgments | |
1962 | ||
1963 | Guix is based on the @uref{https://nixos.org/nix/, Nix package manager}, | |
1964 | which was designed and | |
1965 | implemented by Eelco Dolstra, with contributions from other people (see | |
1966 | the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package | |
1967 | management, and promoted unprecedented features, such as transactional | |
1968 | package upgrades and rollbacks, per-user profiles, and referentially | |
1969 | transparent build processes. Without this work, Guix would not exist. | |
1970 | ||
1971 | The Nix-based software distributions, Nixpkgs and NixOS, have also been | |
1972 | an inspiration for Guix. | |
1973 | ||
1974 | GNU@tie{}Guix itself is a collective work with contributions from a | |
1975 | number of people. See the @file{AUTHORS} file in Guix for more | |
1976 | information on these fine people. The @file{THANKS} file lists people | |
1977 | who have helped by reporting bugs, taking care of the infrastructure, | |
1978 | providing artwork and themes, making suggestions, and more---thank you! | |
1979 | ||
1980 | This document includes adapted sections from articles that have previously | |
1981 | been published on the Guix blog at @uref{https://guix.gnu.org/blog}. | |
1982 | ||
1983 | ||
1984 | @c ********************************************************************* | |
1985 | @node GNU Free Documentation License | |
1986 | @appendix GNU Free Documentation License | |
1987 | @cindex license, GNU Free Documentation License | |
1988 | @include fdl-1.3.texi | |
1989 | ||
1990 | @c ********************************************************************* | |
1991 | @node Concept Index | |
1992 | @unnumbered Concept Index | |
1993 | @printindex cp | |
1994 | ||
1995 | @bye | |
1996 | ||
1997 | @c Local Variables: | |
1998 | @c ispell-local-dictionary: "american"; | |
1999 | @c End: |