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 | ||
27c273ec LC |
10 | @c Onion service for ci.guix.gnu.org. |
11 | @set SUBSTITUTE-TOR-URL https://4zwzi66wwdaalbhgnix55ea3ab4pvvw66ll2ow53kjub6se4q2bclcyd.onion | |
12 | ||
7bc46ecc | 13 | @copying |
56915dc2 | 14 | Copyright @copyright{} 2019, 2022 Ricardo Wurmus@* |
7bc46ecc RW |
15 | Copyright @copyright{} 2019 Efraim Flashner@* |
16 | Copyright @copyright{} 2019 Pierre Neidhardt@* | |
65051fdc | 17 | Copyright @copyright{} 2020 Oleg Pykhalov@* |
60651dd9 | 18 | Copyright @copyright{} 2020 Matthew Brooks@* |
145df67b | 19 | Copyright @copyright{} 2020 Marcin Karpezo@* |
c987b723 | 20 | Copyright @copyright{} 2020 Brice Waegeneire@* |
e3d2e618 | 21 | Copyright @copyright{} 2020 André Batista@* |
94551439 | 22 | Copyright @copyright{} 2020 Christine Lemmer-Webber@* |
c2ff06e5 | 23 | Copyright @copyright{} 2021 Joshua Branson@* |
7bc46ecc RW |
24 | |
25 | Permission is granted to copy, distribute and/or modify this document | |
26 | under the terms of the GNU Free Documentation License, Version 1.3 or | |
27 | any later version published by the Free Software Foundation; with no | |
28 | Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A | |
29 | copy of the license is included in the section entitled ``GNU Free | |
30 | Documentation License''. | |
31 | @end copying | |
32 | ||
33 | @dircategory System administration | |
34 | @direntry | |
35 | * Guix cookbook: (guix-cookbook). Tutorials and examples for GNU Guix. | |
36 | @end direntry | |
37 | ||
38 | @titlepage | |
39 | @title GNU Guix Cookbook | |
40 | @subtitle Tutorials and examples for using the GNU Guix Functional Package Manager | |
41 | @author The GNU Guix Developers | |
42 | ||
43 | @page | |
44 | @vskip 0pt plus 1filll | |
45 | ||
46 | @insertcopying | |
47 | @end titlepage | |
48 | ||
49 | @contents | |
50 | ||
51 | @c ********************************************************************* | |
52 | @node Top | |
53 | @top GNU Guix Cookbook | |
54 | ||
55 | This document presents tutorials and detailed examples for GNU@tie{}Guix, a | |
56 | functional package management tool written for the GNU system. Please | |
57 | @pxref{Top,,, guix, GNU Guix reference manual} for details about the system, | |
58 | its API, and related concepts. | |
59 | ||
60 | @c TRANSLATORS: You can replace the following paragraph with information on | |
61 | @c how to join your own translation team and how to report issues with the | |
62 | @c translation. | |
e0e65ed6 SM |
63 | This manual is also available in French (@pxref{Top,,, guix-cookbook.fr, |
64 | Livre de recettes de GNU Guix}) and German (@pxref{Top,,, | |
65 | guix-cookbook.de, GNU-Guix-Kochbuch}). If you would like to translate | |
66 | this document in your native language, consider joining | |
2a9784ff | 67 | @uref{https://translate.fedoraproject.org/projects/guix/documentation-cookbook, |
e0e65ed6 | 68 | Weblate} (@pxref{Translating Guix,,, guix, GNU Guix reference manual}). |
7bc46ecc RW |
69 | |
70 | @menu | |
71 | * Scheme tutorials:: Meet your new favorite language! | |
72 | * Packaging:: Packaging tutorials | |
73 | * System Configuration:: Customizing the GNU System | |
56915dc2 | 74 | * Containers:: Isolated environments and nested systems |
4c463569 | 75 | * Advanced package management:: Power to the users! |
d0fc1e83 | 76 | * Environment management:: Control environment |
7bc46ecc RW |
77 | |
78 | * Acknowledgments:: Thanks! | |
79 | * GNU Free Documentation License:: The license of this document. | |
80 | * Concept Index:: Concepts. | |
81 | ||
82 | @detailmenu | |
83 | --- The Detailed Node Listing --- | |
84 | ||
85 | Scheme tutorials | |
86 | ||
87 | * A Scheme Crash Course:: Learn the basics of Scheme | |
88 | ||
89 | Packaging | |
90 | ||
91 | * Packaging Tutorial:: Let's add a package to Guix! | |
92 | ||
93 | System Configuration | |
94 | ||
c2ff06e5 JB |
95 | * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY |
96 | * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. | |
7bc46ecc RW |
97 | |
98 | @end detailmenu | |
99 | @end menu | |
100 | ||
101 | @c ********************************************************************* | |
102 | @node Scheme tutorials | |
103 | @chapter Scheme tutorials | |
104 | ||
105 | GNU@tie{}Guix is written in the general purpose programming language Scheme, | |
106 | and many of its features can be accessed and manipulated programmatically. | |
107 | You can use Scheme to generate package definitions, to modify them, to build | |
108 | them, to deploy whole operating systems, etc. | |
109 | ||
110 | Knowing the basics of how to program in Scheme will unlock many of the | |
111 | advanced features Guix provides --- and you don't even need to be an | |
112 | experienced programmer to use them! | |
113 | ||
114 | Let's get started! | |
115 | ||
116 | @node A Scheme Crash Course | |
117 | @section A Scheme Crash Course | |
118 | ||
119 | @cindex Scheme, crash course | |
120 | ||
121 | Guix uses the Guile implementation of Scheme. To start playing with the | |
122 | language, install it with @code{guix install guile} and start a | |
96a95aa9 LC |
123 | @dfn{REPL}---short for @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop, |
124 | @dfn{read-eval-print loop}}---by running @code{guile} from the command line. | |
7bc46ecc | 125 | |
da7bee91 | 126 | Alternatively you can also run @code{guix shell guile -- guile} |
7bc46ecc RW |
127 | if you'd rather not have Guile installed in your user profile. |
128 | ||
cf1e6f5f LC |
129 | In the following examples, lines show what you would type at the REPL; |
130 | lines starting with ``@result{}'' show evaluation results, while lines | |
131 | starting with ``@print{}'' show things that get printed. @xref{Using Guile | |
96a95aa9 | 132 | Interactively,,, guile, GNU Guile Reference Manual}, for more details on the |
7bc46ecc RW |
133 | REPL. |
134 | ||
135 | @itemize | |
136 | @item | |
137 | Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in | |
138 | Lisp lingo). An expression can be a literal such as numbers and strings, or a | |
cd958802 LC |
139 | compound which is a parenthesized list of compounds and literals. @code{#true} |
140 | and @code{#false} (abbreviated @code{#t} and @code{#f}) stand for the | |
141 | Booleans ``true'' and ``false'', respectively. | |
7bc46ecc RW |
142 | |
143 | Examples of valid expressions: | |
144 | ||
b1eecb5c | 145 | @lisp |
7bc46ecc | 146 | "Hello World!" |
cf1e6f5f LC |
147 | @result{} "Hello World!" |
148 | ||
7bc46ecc | 149 | 17 |
cf1e6f5f LC |
150 | @result{} 17 |
151 | ||
152 | (display (string-append "Hello " "Guix" "\n")) | |
153 | @print{} Hello Guix! | |
154 | @result{} #<unspecified> | |
b1eecb5c | 155 | @end lisp |
7bc46ecc RW |
156 | |
157 | @item | |
158 | This last example is a function call nested in another function call. When a | |
159 | parenthesized expression is evaluated, the first term is the function and the | |
160 | rest are the arguments passed to the function. Every function returns the | |
161 | last evaluated expression as its return value. | |
162 | ||
163 | @item | |
164 | Anonymous functions are declared with the @code{lambda} term: | |
165 | ||
b1eecb5c | 166 | @lisp |
cf1e6f5f LC |
167 | (lambda (x) (* x x)) |
168 | @result{} #<procedure 120e348 at <unknown port>:24:0 (x)> | |
b1eecb5c | 169 | @end lisp |
7bc46ecc RW |
170 | |
171 | The above procedure returns the square of its argument. Since everything is | |
172 | an expression, the @code{lambda} expression returns an anonymous procedure, | |
173 | which can in turn be applied to an argument: | |
174 | ||
b1eecb5c | 175 | @lisp |
cf1e6f5f LC |
176 | ((lambda (x) (* x x)) 3) |
177 | @result{} 9 | |
b1eecb5c | 178 | @end lisp |
7bc46ecc RW |
179 | |
180 | @item | |
181 | Anything can be assigned a global name with @code{define}: | |
182 | ||
b1eecb5c | 183 | @lisp |
cf1e6f5f LC |
184 | (define a 3) |
185 | (define square (lambda (x) (* x x))) | |
186 | (square a) | |
187 | @result{} 9 | |
b1eecb5c | 188 | @end lisp |
7bc46ecc RW |
189 | |
190 | @item | |
191 | Procedures can be defined more concisely with the following syntax: | |
192 | ||
b1eecb5c | 193 | @lisp |
7bc46ecc | 194 | (define (square x) (* x x)) |
b1eecb5c | 195 | @end lisp |
7bc46ecc RW |
196 | |
197 | @item | |
198 | A list structure can be created with the @code{list} procedure: | |
199 | ||
b1eecb5c | 200 | @lisp |
cf1e6f5f LC |
201 | (list 2 a 5 7) |
202 | @result{} (2 3 5 7) | |
b1eecb5c | 203 | @end lisp |
7bc46ecc RW |
204 | |
205 | @item | |
6a893fa8 LC |
206 | The @dfn{quote} disables evaluation of a parenthesized expression: the |
207 | first term is not called over the other terms (@pxref{Expression Syntax, | |
208 | quote,, guile, GNU Guile Reference Manual}). Thus it effectively | |
209 | returns a list of terms. | |
7bc46ecc | 210 | |
b1eecb5c | 211 | @lisp |
cf1e6f5f LC |
212 | '(display (string-append "Hello " "Guix" "\n")) |
213 | @result{} (display (string-append "Hello " "Guix" "\n")) | |
214 | ||
215 | '(2 a 5 7) | |
216 | @result{} (2 a 5 7) | |
b1eecb5c | 217 | @end lisp |
7bc46ecc RW |
218 | |
219 | @item | |
6a893fa8 LC |
220 | The @dfn{quasiquote} disables evaluation of a parenthesized expression |
221 | until @dfn{unquote} (a comma) re-enables it. Thus it provides us with | |
222 | fine-grained control over what is evaluated and what is not. | |
7bc46ecc | 223 | |
b1eecb5c | 224 | @lisp |
cf1e6f5f LC |
225 | `(2 a 5 7 (2 ,a 5 ,(+ a 4))) |
226 | @result{} (2 a 5 7 (2 3 5 7)) | |
b1eecb5c | 227 | @end lisp |
7bc46ecc RW |
228 | |
229 | Note that the above result is a list of mixed elements: numbers, symbols (here | |
230 | @code{a}) and the last element is a list itself. | |
231 | ||
232 | @item | |
6a893fa8 LC |
233 | Multiple variables can be named locally with @code{let} (@pxref{Local |
234 | Bindings,,, guile, GNU Guile Reference Manual}): | |
7bc46ecc | 235 | |
b1eecb5c | 236 | @lisp |
cf1e6f5f LC |
237 | (define x 10) |
238 | (let ((x 2) | |
239 | (y 3)) | |
240 | (list x y)) | |
241 | @result{} (2 3) | |
242 | ||
243 | x | |
244 | @result{} 10 | |
245 | ||
246 | y | |
247 | @error{} In procedure module-lookup: Unbound variable: y | |
b1eecb5c | 248 | @end lisp |
7bc46ecc RW |
249 | |
250 | Use @code{let*} to allow later variable declarations to refer to earlier | |
251 | definitions. | |
252 | ||
b1eecb5c | 253 | @lisp |
cf1e6f5f LC |
254 | (let* ((x 2) |
255 | (y (* x 3))) | |
256 | (list x y)) | |
257 | @result{} (2 6) | |
b1eecb5c | 258 | @end lisp |
7bc46ecc RW |
259 | |
260 | @item | |
c0001b8b LC |
261 | @dfn{Keywords} are typically used to identify the named parameters of a |
262 | procedure. They are prefixed by @code{#:} (hash, colon) followed by | |
263 | alphanumeric characters: @code{#:like-this}. | |
264 | @xref{Keywords,,, guile, GNU Guile Reference Manual}. | |
7bc46ecc RW |
265 | |
266 | @item | |
267 | The percentage @code{%} is typically used for read-only global variables in | |
268 | the build stage. Note that it is merely a convention, like @code{_} in C. | |
269 | Scheme treats @code{%} exactly the same as any other letter. | |
270 | ||
271 | @item | |
6a893fa8 LC |
272 | Modules are created with @code{define-module} (@pxref{Creating Guile |
273 | Modules,,, guile, GNU Guile Reference Manual}). For instance | |
7bc46ecc | 274 | |
b1eecb5c | 275 | @lisp |
7bc46ecc RW |
276 | (define-module (guix build-system ruby) |
277 | #:use-module (guix store) | |
278 | #:export (ruby-build | |
279 | ruby-build-system)) | |
b1eecb5c | 280 | @end lisp |
7bc46ecc RW |
281 | |
282 | defines the module @code{guix build-system ruby} which must be located in | |
283 | @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It | |
284 | depends on the @code{(guix store)} module and it exports two variables, | |
285 | @code{ruby-build} and @code{ruby-build-system}. | |
286 | @end itemize | |
287 | ||
9100acb6 LC |
288 | @quotation Going further |
289 | Scheme is a language that has been widely used to teach programming and | |
290 | you'll find plenty of material using it as a vehicle. Here's a | |
291 | selection of documents to learn more about Scheme: | |
292 | ||
293 | @itemize | |
294 | @item | |
295 | @uref{https://spritely.institute/static/papers/scheme-primer.html, @i{A | |
296 | Scheme Primer}}, by Christine Lemmer-Webber and the Spritely Institute. | |
297 | ||
298 | @item | |
299 | @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, | |
300 | @i{Scheme at a Glance}}, by Steve Litt. | |
301 | ||
302 | @item | |
303 | @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, | |
304 | @i{Structure and Interpretation of Computer Programs}}, by Harold | |
305 | Abelson and Gerald Jay Sussman, with Julie Sussman. Colloquially known | |
306 | as ``SICP'', this book is a reference. | |
307 | ||
308 | You can also install it and read it from your computer: | |
309 | ||
310 | @example | |
311 | guix install sicp info-reader | |
312 | info sicp | |
313 | @end example | |
314 | ||
315 | An @uref{https://sarabander.github.io/sicp/, unofficial ebook} is also | |
316 | available. | |
317 | ||
318 | @end itemize | |
7bc46ecc RW |
319 | |
320 | You'll find more books, tutorials and other resources at | |
321 | @url{https://schemers.org/}. | |
9100acb6 | 322 | @end quotation |
7bc46ecc RW |
323 | |
324 | ||
325 | @c ********************************************************************* | |
326 | @node Packaging | |
327 | @chapter Packaging | |
328 | ||
329 | @cindex packaging | |
330 | ||
331 | This chapter is dedicated to teaching you how to add packages to the | |
332 | collection of packages that come with GNU Guix. This involves writing package | |
333 | definitions in Guile Scheme, organizing them in package modules, and building | |
334 | them. | |
335 | ||
336 | @menu | |
337 | * Packaging Tutorial:: A tutorial on how to add packages to Guix. | |
338 | @end menu | |
339 | ||
340 | @node Packaging Tutorial | |
341 | @section Packaging Tutorial | |
342 | ||
343 | GNU Guix stands out as the @emph{hackable} package manager, mostly because it | |
344 | uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful | |
345 | high-level programming language, one of the | |
346 | @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme} | |
347 | dialects from the | |
348 | @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}. | |
349 | ||
350 | Package definitions are also written in Scheme, which empowers Guix in some | |
351 | very unique ways, unlike most other package managers that use shell scripts or | |
352 | simple languages. | |
353 | ||
354 | @itemize | |
355 | @item | |
356 | Use functions, structures, macros and all of Scheme expressiveness for your | |
357 | package definitions. | |
358 | ||
359 | @item | |
360 | Inheritance makes it easy to customize a package by inheriting from it and | |
361 | modifying only what is needed. | |
5c3e94cd | 362 | |
7bc46ecc RW |
363 | @item |
364 | Batch processing: the whole package collection can be parsed, filtered and | |
365 | processed. Building a headless server with all graphical interfaces stripped | |
366 | out? It's possible. Want to rebuild everything from source using specific | |
367 | compiler optimization flags? Pass the @code{#:make-flags "..."} argument to | |
368 | the list of packages. It wouldn't be a stretch to think | |
369 | @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this | |
370 | goes even further: the changes don't have to be thought out beforehand by the | |
371 | packager, they can be @emph{programmed} by the user! | |
372 | @end itemize | |
373 | ||
374 | The following tutorial covers all the basics around package creation with Guix. | |
375 | It does not assume much knowledge of the Guix system nor of the Lisp language. | |
376 | The reader is only expected to be familiar with the command line and to have some | |
377 | basic programming knowledge. | |
378 | ||
0cbef07b LC |
379 | @node A ``Hello World'' package |
380 | @subsection A ``Hello World'' package | |
7bc46ecc | 381 | |
0cbef07b | 382 | The ``Defining Packages'' section of the manual introduces the basics of Guix |
7bc46ecc RW |
383 | packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In |
384 | the following section, we will partly go over those basics again. | |
385 | ||
0cbef07b | 386 | GNU@tie{}Hello is a dummy project that serves as an idiomatic example for |
7bc46ecc RW |
387 | packaging. It uses the GNU build system (@code{./configure && make && make |
388 | install}). Guix already provides a package definition which is a perfect | |
389 | example to start with. You can look up its declaration with @code{guix edit | |
390 | hello} from the command line. Let's see how it looks: | |
391 | ||
b1eecb5c | 392 | @lisp |
7bc46ecc RW |
393 | (define-public hello |
394 | (package | |
395 | (name "hello") | |
396 | (version "2.10") | |
397 | (source (origin | |
398 | (method url-fetch) | |
399 | (uri (string-append "mirror://gnu/hello/hello-" version | |
400 | ".tar.gz")) | |
401 | (sha256 | |
402 | (base32 | |
403 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
404 | (build-system gnu-build-system) | |
405 | (synopsis "Hello, GNU world: An example GNU package") | |
406 | (description | |
407 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
408 | serves as an example of standard GNU coding practices. As such, it supports | |
409 | command-line arguments, multiple languages, and so on.") | |
410 | (home-page "https://www.gnu.org/software/hello/") | |
411 | (license gpl3+))) | |
b1eecb5c | 412 | @end lisp |
7bc46ecc RW |
413 | |
414 | As you can see, most of it is rather straightforward. But let's review the | |
415 | fields together: | |
416 | ||
417 | @table @samp | |
418 | @item name | |
419 | The project name. Using Scheme conventions, we prefer to keep it | |
420 | lower case, without underscore and using dash-separated words. | |
421 | ||
422 | @item source | |
423 | This field contains a description of the source code origin. The | |
424 | @code{origin} record contains these fields: | |
425 | ||
426 | @enumerate | |
427 | @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods | |
428 | exist, such as @code{git-fetch} for Git repositories. | |
429 | @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here | |
430 | the special `mirror://gnu` refers to a set of well known locations, all of | |
431 | which can be used by Guix to fetch the source, should some of them fail. | |
432 | @item The @code{sha256} checksum of the requested file. This is essential to ensure | |
433 | the source is not corrupted. Note that Guix works with base32 strings, | |
434 | hence the call to the @code{base32} function. | |
435 | @end enumerate | |
436 | ||
437 | @item build-system | |
438 | ||
439 | This is where the power of abstraction provided by the Scheme language really | |
440 | shines: in this case, the @code{gnu-build-system} abstracts away the famous | |
441 | @code{./configure && make && make install} shell invocations. Other build | |
442 | systems include the @code{trivial-build-system} which does not do anything and | |
443 | requires from the packager to program all the build steps, the | |
444 | @code{python-build-system}, the @code{emacs-build-system}, and many more | |
445 | (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}). | |
446 | ||
447 | @item synopsis | |
448 | It should be a concise summary of what the package does. For many packages a | |
449 | tagline from the project's home page can be used as the synopsis. | |
450 | ||
451 | @item description | |
452 | Same as for the synopsis, it's fine to re-use the project description from the | |
453 | homepage. Note that Guix uses Texinfo syntax. | |
454 | ||
455 | @item home-page | |
456 | Use HTTPS if available. | |
457 | ||
458 | @item license | |
459 | See @code{guix/licenses.scm} in the project source for a full list of | |
460 | available licenses. | |
461 | @end table | |
462 | ||
463 | Time to build our first package! Nothing fancy here for now: we will stick to a | |
0cbef07b | 464 | dummy @code{my-hello}, a copy of the above declaration. |
7bc46ecc | 465 | |
0cbef07b LC |
466 | As with the ritualistic ``Hello World'' taught with most programming languages, |
467 | this will possibly be the most ``manual'' approach. We will work out an ideal | |
7bc46ecc RW |
468 | setup later; for now we will go the simplest route. |
469 | ||
470 | Save the following to a file @file{my-hello.scm}. | |
471 | ||
b1eecb5c | 472 | @lisp |
7bc46ecc RW |
473 | (use-modules (guix packages) |
474 | (guix download) | |
475 | (guix build-system gnu) | |
476 | (guix licenses)) | |
477 | ||
478 | (package | |
479 | (name "my-hello") | |
480 | (version "2.10") | |
481 | (source (origin | |
482 | (method url-fetch) | |
483 | (uri (string-append "mirror://gnu/hello/hello-" version | |
484 | ".tar.gz")) | |
485 | (sha256 | |
486 | (base32 | |
487 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
488 | (build-system gnu-build-system) | |
489 | (synopsis "Hello, Guix world: An example custom Guix package") | |
490 | (description | |
491 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
492 | serves as an example of standard GNU coding practices. As such, it supports | |
493 | command-line arguments, multiple languages, and so on.") | |
494 | (home-page "https://www.gnu.org/software/hello/") | |
495 | (license gpl3+)) | |
b1eecb5c | 496 | @end lisp |
7bc46ecc RW |
497 | |
498 | We will explain the extra code in a moment. | |
499 | ||
500 | Feel free to play with the different values of the various fields. If you | |
501 | change the source, you'll need to update the checksum. Indeed, Guix refuses to | |
502 | build anything if the given checksum does not match the computed checksum of the | |
503 | source code. To obtain the correct checksum of the package declaration, we | |
504 | need to download the source, compute the sha256 checksum and convert it to | |
505 | base32. | |
506 | ||
507 | Thankfully, Guix can automate this task for us; all we need is to provide the | |
508 | URI: | |
509 | ||
510 | @c TRANSLATORS: This is example shell output. | |
511 | @example sh | |
512 | $ guix download mirror://gnu/hello/hello-2.10.tar.gz | |
513 | ||
514 | Starting download of /tmp/guix-file.JLYgL7 | |
515 | From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz... | |
516 | following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'... | |
517 | …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0% | |
518 | /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz | |
519 | 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i | |
520 | @end example | |
521 | ||
522 | In this specific case the output tells us which mirror was chosen. | |
523 | If the result of the above command is not the same as in the above snippet, | |
524 | update your @code{my-hello} declaration accordingly. | |
525 | ||
526 | Note that GNU package tarballs come with an OpenPGP signature, so you | |
527 | should definitely check the signature of this tarball with `gpg` to | |
528 | authenticate it before going further: | |
529 | ||
530 | @c TRANSLATORS: This is example shell output. | |
531 | @example sh | |
532 | $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig | |
533 | ||
534 | Starting download of /tmp/guix-file.03tFfb | |
535 | From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig... | |
536 | following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'... | |
537 | ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0% | |
538 | /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig | |
539 | 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf | |
540 | $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz | |
541 | gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET | |
542 | gpg: using RSA key A9553245FDE9B739 | |
543 | gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown] | |
544 | gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown] | |
545 | gpg: WARNING: This key is not certified with a trusted signature! | |
546 | gpg: There is no indication that the signature belongs to the owner. | |
547 | Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739 | |
548 | @end example | |
549 | ||
550 | You can then happily run | |
551 | ||
552 | @c TRANSLATORS: Do not translate this command | |
553 | @example sh | |
554 | $ guix package --install-from-file=my-hello.scm | |
555 | @end example | |
556 | ||
557 | You should now have @code{my-hello} in your profile! | |
558 | ||
559 | @c TRANSLATORS: Do not translate this command | |
560 | @example sh | |
561 | $ guix package --list-installed=my-hello | |
562 | my-hello 2.10 out | |
563 | /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10 | |
564 | @end example | |
565 | ||
566 | We've gone as far as we could without any knowledge of Scheme. Before moving | |
567 | on to more complex packages, now is the right time to brush up on your Scheme | |
568 | knowledge. @pxref{A Scheme Crash Course} to get up to speed. | |
569 | ||
ffe059af PN |
570 | @node Setup |
571 | @subsection Setup | |
7bc46ecc | 572 | |
ffe059af PN |
573 | In the rest of this chapter we will rely on some basic Scheme |
574 | programming knowledge. Now let's detail the different possible setups | |
575 | for working on Guix packages. | |
576 | ||
577 | There are several ways to set up a Guix packaging environment. | |
578 | ||
579 | We recommend you work directly on the Guix source checkout since it makes it | |
580 | easier for everyone to contribute to the project. | |
581 | ||
582 | But first, let's look at other possibilities. | |
583 | ||
584 | @node Local file | |
585 | @subsubsection Local file | |
586 | ||
587 | This is what we previously did with @samp{my-hello}. With the Scheme basics we've | |
588 | covered, we are now able to explain the leading chunks. As stated in @code{guix | |
589 | package --help}: | |
590 | ||
591 | @example | |
592 | -f, --install-from-file=FILE | |
593 | install the package that the code within FILE | |
594 | evaluates to | |
595 | @end example | |
596 | ||
597 | Thus the last expression @emph{must} return a package, which is the case in our | |
598 | earlier example. | |
599 | ||
600 | The @code{use-modules} expression tells which of the modules we need in the file. | |
601 | Modules are a collection of values and procedures. They are commonly called | |
0cbef07b | 602 | ``libraries'' or ``packages'' in other programming languages. |
ffe059af PN |
603 | |
604 | @node @samp{GUIX_PACKAGE_PATH} | |
605 | @subsubsection @samp{GUIX_PACKAGE_PATH} | |
606 | ||
0cbef07b | 607 | @emph{Note: Starting from Guix 0.16, the more flexible Guix @dfn{channels} are the |
ffe059af PN |
608 | preferred way and supersede @samp{GUIX_PACKAGE_PATH}. See next section.} |
609 | ||
610 | It can be tedious to specify the file from the command line instead of simply | |
611 | calling @code{guix package --install my-hello} as you would do with the official | |
612 | packages. | |
613 | ||
0cbef07b LC |
614 | Guix makes it possible to streamline the process by adding as many ``package |
615 | declaration directories'' as you want. | |
ffe059af | 616 | |
a0fd4630 | 617 | Create a directory, say @file{~/guix-packages} and add it to the @samp{GUIX_PACKAGE_PATH} |
ffe059af PN |
618 | environment variable: |
619 | ||
620 | @example | |
621 | $ mkdir ~/guix-packages | |
622 | $ export GUIX_PACKAGE_PATH=~/guix-packages | |
623 | @end example | |
624 | ||
625 | To add several directories, separate them with a colon (@code{:}). | |
626 | ||
627 | Our previous @samp{my-hello} needs some adjustments though: | |
628 | ||
d482e13f | 629 | @lisp |
ffe059af PN |
630 | (define-module (my-hello) |
631 | #:use-module (guix licenses) | |
632 | #:use-module (guix packages) | |
633 | #:use-module (guix build-system gnu) | |
634 | #:use-module (guix download)) | |
635 | ||
636 | (define-public my-hello | |
637 | (package | |
638 | (name "my-hello") | |
639 | (version "2.10") | |
640 | (source (origin | |
641 | (method url-fetch) | |
642 | (uri (string-append "mirror://gnu/hello/hello-" version | |
643 | ".tar.gz")) | |
644 | (sha256 | |
645 | (base32 | |
646 | "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) | |
647 | (build-system gnu-build-system) | |
648 | (synopsis "Hello, Guix world: An example custom Guix package") | |
649 | (description | |
650 | "GNU Hello prints the message \"Hello, world!\" and then exits. It | |
651 | serves as an example of standard GNU coding practices. As such, it supports | |
652 | command-line arguments, multiple languages, and so on.") | |
653 | (home-page "https://www.gnu.org/software/hello/") | |
654 | (license gpl3+))) | |
d482e13f | 655 | @end lisp |
ffe059af PN |
656 | |
657 | Note that we have assigned the package value to an exported variable name with | |
658 | @code{define-public}. This is effectively assigning the package to the @code{my-hello} | |
659 | variable so that it can be referenced, among other as dependency of other | |
660 | packages. | |
661 | ||
662 | If you use @code{guix package --install-from-file=my-hello.scm} on the above file, it | |
663 | will fail because the last expression, @code{define-public}, does not return a | |
664 | package. If you want to use @code{define-public} in this use-case nonetheless, make | |
665 | sure the file ends with an evaluation of @code{my-hello}: | |
666 | ||
d482e13f | 667 | @lisp |
ffe059af PN |
668 | ; ... |
669 | (define-public my-hello | |
670 | ; ... | |
671 | ) | |
672 | ||
673 | my-hello | |
d482e13f | 674 | @end lisp |
ffe059af PN |
675 | |
676 | This last example is not very typical. | |
677 | ||
678 | Now @samp{my-hello} should be part of the package collection like all other official | |
679 | packages. You can verify this with: | |
680 | ||
681 | @example | |
682 | $ guix package --show=my-hello | |
683 | @end example | |
684 | ||
685 | @node Guix channels | |
686 | @subsubsection Guix channels | |
687 | ||
688 | Guix 0.16 features channels, which is very similar to @samp{GUIX_PACKAGE_PATH} but | |
689 | provides better integration and provenance tracking. Channels are not | |
690 | necessarily local, they can be maintained as a public Git repository for | |
691 | instance. Of course, several channels can be used at the same time. | |
692 | ||
693 | @xref{Channels,,, guix, GNU Guix Reference Manual} for setup details. | |
694 | ||
695 | @node Direct checkout hacking | |
696 | @subsubsection Direct checkout hacking | |
697 | ||
698 | Working directly on the Guix project is recommended: it reduces the friction | |
699 | when the time comes to submit your changes upstream to let the community benefit | |
700 | from your hard work! | |
701 | ||
702 | Unlike most software distributions, the Guix repository holds in one place both | |
703 | the tooling (including the package manager) and the package definitions. This | |
704 | choice was made so that it would give developers the flexibility to modify the | |
705 | API without breakage by updating all packages at the same time. This reduces | |
706 | development inertia. | |
707 | ||
708 | Check out the official @uref{https://git-scm.com/, Git} repository: | |
709 | ||
710 | @example | |
711 | $ git clone https://git.savannah.gnu.org/git/guix.git | |
712 | @end example | |
713 | ||
714 | In the rest of this article, we use @samp{$GUIX_CHECKOUT} to refer to the location of | |
715 | the checkout. | |
716 | ||
717 | ||
e97a4a29 | 718 | Follow the instructions in the manual (@pxref{Contributing,,, guix, GNU Guix |
ffe059af PN |
719 | Reference Manual}) to set up the repository environment. |
720 | ||
721 | Once ready, you should be able to use the package definitions from the | |
722 | repository environment. | |
723 | ||
724 | Feel free to edit package definitions found in @samp{$GUIX_CHECKOUT/gnu/packages}. | |
725 | ||
726 | The @samp{$GUIX_CHECKOUT/pre-inst-env} script lets you use @samp{guix} over the package | |
e97a4a29 LC |
727 | collection of the repository (@pxref{Running Guix Before It Is |
728 | Installed,,, guix, GNU Guix Reference Manual}). | |
ffe059af PN |
729 | |
730 | @itemize | |
731 | @item | |
732 | Search packages, such as Ruby: | |
733 | ||
734 | @example | |
735 | $ cd $GUIX_CHECKOUT | |
736 | $ ./pre-inst-env guix package --list-available=ruby | |
737 | ruby 1.8.7-p374 out gnu/packages/ruby.scm:119:2 | |
738 | ruby 2.1.6 out gnu/packages/ruby.scm:91:2 | |
739 | ruby 2.2.2 out gnu/packages/ruby.scm:39:2 | |
740 | @end example | |
741 | ||
742 | @item | |
743 | Build a package, here Ruby version 2.1: | |
744 | ||
745 | @example | |
746 | $ ./pre-inst-env guix build --keep-failed ruby@@2.1 | |
747 | /gnu/store/c13v73jxmj2nir2xjqaz5259zywsa9zi-ruby-2.1.6 | |
748 | @end example | |
749 | ||
750 | @item | |
751 | Install it to your user profile: | |
752 | ||
753 | @example | |
754 | $ ./pre-inst-env guix package --install ruby@@2.1 | |
755 | @end example | |
756 | ||
757 | @item | |
758 | Check for common mistakes: | |
759 | ||
760 | @example | |
761 | $ ./pre-inst-env guix lint ruby@@2.1 | |
762 | @end example | |
763 | @end itemize | |
764 | ||
765 | Guix strives at maintaining a high packaging standard; when contributing to the | |
766 | Guix project, remember to | |
767 | ||
768 | @itemize | |
769 | @item | |
770 | follow the coding style (@pxref{Coding Style,,, guix, GNU Guix Reference Manual}), | |
771 | @item | |
772 | and review the check list from the manual (@pxref{Submitting Patches,,, guix, GNU Guix Reference Manual}). | |
773 | @end itemize | |
774 | ||
775 | Once you are happy with the result, you are welcome to send your contribution to | |
776 | make it part of Guix. This process is also detailed in the manual. (@pxref{Contributing,,, guix, GNU Guix Reference Manual}) | |
777 | ||
778 | ||
779 | It's a community effort so the more join in, the better Guix becomes! | |
780 | ||
781 | @node Extended example | |
782 | @subsection Extended example | |
783 | ||
0cbef07b | 784 | The above ``Hello World'' example is as simple as it goes. Packages can be more |
ffe059af PN |
785 | complex than that and Guix can handle more advanced scenarios. Let's look at |
786 | another, more sophisticated package (slightly modified from the source): | |
787 | ||
d482e13f | 788 | @lisp |
ffe059af PN |
789 | (define-module (gnu packages version-control) |
790 | #:use-module ((guix licenses) #:prefix license:) | |
791 | #:use-module (guix utils) | |
792 | #:use-module (guix packages) | |
793 | #:use-module (guix git-download) | |
794 | #:use-module (guix build-system cmake) | |
795 | #:use-module (gnu packages ssh) | |
796 | #:use-module (gnu packages web) | |
797 | #:use-module (gnu packages pkg-config) | |
798 | #:use-module (gnu packages python) | |
799 | #:use-module (gnu packages compression) | |
800 | #:use-module (gnu packages tls)) | |
801 | ||
802 | (define-public my-libgit2 | |
803 | (let ((commit "e98d0a37c93574d2c6107bf7f31140b548c6a7bf") | |
804 | (revision "1")) | |
805 | (package | |
806 | (name "my-libgit2") | |
807 | (version (git-version "0.26.6" revision commit)) | |
808 | (source (origin | |
809 | (method git-fetch) | |
810 | (uri (git-reference | |
811 | (url "https://github.com/libgit2/libgit2/") | |
812 | (commit commit))) | |
813 | (file-name (git-file-name name version)) | |
814 | (sha256 | |
815 | (base32 | |
816 | "17pjvprmdrx4h6bb1hhc98w9qi6ki7yl57f090n9kbhswxqfs7s3")) | |
817 | (patches (search-patches "libgit2-mtime-0.patch")) | |
818 | (modules '((guix build utils))) | |
bc7dd3f7 LC |
819 | ;; Remove bundled software. |
820 | (snippet '(delete-file-recursively "deps")))) | |
ffe059af PN |
821 | (build-system cmake-build-system) |
822 | (outputs '("out" "debug")) | |
823 | (arguments | |
34513683 | 824 | `(#:tests? #true ; Run the test suite (this is the default) |
ffe059af PN |
825 | #:configure-flags '("-DUSE_SHA1DC=ON") ; SHA-1 collision detection |
826 | #:phases | |
827 | (modify-phases %standard-phases | |
828 | (add-after 'unpack 'fix-hardcoded-paths | |
829 | (lambda _ | |
830 | (substitute* "tests/repo/init.c" | |
831 | (("#!/bin/sh") (string-append "#!" (which "sh")))) | |
832 | (substitute* "tests/clar/fs.h" | |
833 | (("/bin/cp") (which "cp")) | |
bc7dd3f7 | 834 | (("/bin/rm") (which "rm"))))) |
ffe059af PN |
835 | ;; Run checks more verbosely. |
836 | (replace 'check | |
837 | (lambda _ (invoke "./libgit2_clar" "-v" "-Q"))) | |
838 | (add-after 'unpack 'make-files-writable-for-tests | |
34513683 | 839 | (lambda _ (for-each make-file-writable (find-files "." ".*"))))))) |
ffe059af | 840 | (inputs |
12c2648f | 841 | (list libssh2 http-parser python-wrapper)) |
ffe059af | 842 | (native-inputs |
12c2648f | 843 | (list pkg-config)) |
ffe059af PN |
844 | (propagated-inputs |
845 | ;; These two libraries are in 'Requires.private' in libgit2.pc. | |
12c2648f | 846 | (list openssl zlib)) |
ffe059af PN |
847 | (home-page "https://libgit2.github.com/") |
848 | (synopsis "Library providing Git core methods") | |
849 | (description | |
850 | "Libgit2 is a portable, pure C implementation of the Git core methods | |
851 | provided as a re-entrant linkable library with a solid API, allowing you to | |
852 | write native speed custom Git applications in any language with bindings.") | |
853 | ;; GPLv2 with linking exception | |
854 | (license license:gpl2)))) | |
d482e13f | 855 | @end lisp |
ffe059af PN |
856 | |
857 | (In those cases were you only want to tweak a few fields from a package | |
858 | definition, you should rely on inheritance instead of copy-pasting everything. | |
859 | See below.) | |
860 | ||
861 | Let's discuss those fields in depth. | |
862 | ||
863 | @subsubsection @code{git-fetch} method | |
864 | ||
865 | Unlike the @code{url-fetch} method, @code{git-fetch} expects a @code{git-reference} which takes | |
866 | a Git repository and a commit. The commit can be any Git reference such as | |
867 | tags, so if the @code{version} is tagged, then it can be used directly. Sometimes | |
868 | the tag is prefixed with a @code{v}, in which case you'd use @code{(commit (string-append | |
869 | "v" version))}. | |
870 | ||
ab83e1f0 LC |
871 | To ensure that the source code from the Git repository is stored in a |
872 | directory with a descriptive name, we use @code{(file-name (git-file-name name | |
ffe059af PN |
873 | version))}. |
874 | ||
4ebbd92c | 875 | The @code{git-version} procedure can be used to derive the |
ab83e1f0 LC |
876 | version when packaging programs for a specific commit, following the |
877 | Guix contributor guidelines (@pxref{Version Numbers,,, guix, GNU Guix | |
878 | Reference Manual}). | |
ffe059af | 879 | |
2f562699 LC |
880 | How does one obtain the @code{sha256} hash that's in there, you ask? By |
881 | invoking @command{guix hash} on a checkout of the desired commit, along | |
4ebbd92c | 882 | these lines: |
2f562699 LC |
883 | |
884 | @example | |
885 | git clone https://github.com/libgit2/libgit2/ | |
886 | cd libgit2 | |
887 | git checkout v0.26.6 | |
888 | guix hash -rx . | |
889 | @end example | |
890 | ||
891 | @command{guix hash -rx} computes a SHA256 hash over the whole directory, | |
892 | excluding the @file{.git} sub-directory (@pxref{Invoking guix hash,,, | |
893 | guix, GNU Guix Reference Manual}). | |
894 | ||
895 | In the future, @command{guix download} will hopefully be able to do | |
896 | these steps for you, just like it does for regular downloads. | |
897 | ||
ffe059af PN |
898 | @subsubsection Snippets |
899 | ||
900 | Snippets are quoted (i.e. non-evaluated) Scheme code that are a means of patching | |
2c8305d1 | 901 | the source. They are a Guix-y alternative to the traditional @file{.patch} files. |
ffe059af | 902 | Because of the quote, the code in only evaluated when passed to the Guix daemon |
0cbef07b | 903 | for building. There can be as many snippets as needed. |
ffe059af PN |
904 | |
905 | Snippets might need additional Guile modules which can be imported from the | |
906 | @code{modules} field. | |
907 | ||
908 | @subsubsection Inputs | |
909 | ||
ffe059af PN |
910 | There are 3 different input types. In short: |
911 | ||
912 | @table @asis | |
913 | @item native-inputs | |
914 | Required for building but not runtime -- installing a package | |
915 | through a substitute won't install these inputs. | |
916 | @item inputs | |
917 | Installed in the store but not in the profile, as well as being | |
918 | present at build time. | |
919 | @item propagated-inputs | |
920 | Installed in the store and in the profile, as well as | |
921 | being present at build time. | |
922 | @end table | |
923 | ||
63a11f92 | 924 | @xref{package Reference,,, guix, GNU Guix Reference Manual} for more details. |
ffe059af PN |
925 | |
926 | The distinction between the various inputs is important: if a dependency can be | |
927 | handled as an @emph{input} instead of a @emph{propagated input}, it should be done so, or | |
0cbef07b | 928 | else it ``pollutes'' the user profile for no good reason. |
ffe059af PN |
929 | |
930 | For instance, a user installing a graphical program that depends on a | |
931 | command line tool might only be interested in the graphical part, so there is no | |
932 | need to force the command line tool into the user profile. The dependency is a | |
933 | concern to the package, not to the user. @emph{Inputs} make it possible to handle | |
934 | dependencies without bugging the user by adding undesired executable files (or | |
935 | libraries) to their profile. | |
936 | ||
937 | Same goes for @emph{native-inputs}: once the program is installed, build-time | |
938 | dependencies can be safely garbage-collected. | |
939 | It also matters when a substitute is available, in which case only the @emph{inputs} | |
940 | and @emph{propagated inputs} will be fetched: the @emph{native inputs} are not required to | |
941 | install a package from a substitute. | |
942 | ||
12c2648f LC |
943 | @quotation Note |
944 | You may see here and there snippets where package inputs are written | |
945 | quite differently, like so: | |
946 | ||
947 | @lisp | |
948 | ;; The "old style" for inputs. | |
949 | (inputs | |
950 | `(("libssh2" ,libssh2) | |
951 | ("http-parser" ,http-parser) | |
952 | ("python" ,python-wrapper))) | |
953 | @end lisp | |
954 | ||
955 | This is the ``old style'', where each input in the list is explicitly | |
956 | given a label (a string). It is still supported but we recommend using | |
957 | the style above instead. @xref{package Reference,,, guix, GNU Guix | |
958 | Reference Manual}, for more info. | |
959 | @end quotation | |
960 | ||
ffe059af PN |
961 | @subsubsection Outputs |
962 | ||
963 | Just like how a package can have multiple inputs, it can also produce multiple | |
964 | outputs. | |
965 | ||
966 | Each output corresponds to a separate directory in the store. | |
967 | ||
968 | The user can choose which output to install; this is useful to save space or | |
969 | to avoid polluting the user profile with unwanted executables or libraries. | |
970 | ||
971 | Output separation is optional. When the @code{outputs} field is left out, the | |
972 | default and only output (the complete package) is referred to as @code{"out"}. | |
973 | ||
974 | Typical separate output names include @code{debug} and @code{doc}. | |
975 | ||
976 | It's advised to separate outputs only when you've shown it's worth it: if the | |
977 | output size is significant (compare with @code{guix size}) or in case the package is | |
978 | modular. | |
979 | ||
980 | @subsubsection Build system arguments | |
981 | ||
982 | The @code{arguments} is a keyword-value list used to configure the build process. | |
983 | ||
984 | The simplest argument @code{#:tests?} can be used to disable the test suite when | |
985 | building the package. This is mostly useful when the package does not feature | |
986 | any test suite. It's strongly recommended to keep the test suite on if there is | |
987 | one. | |
988 | ||
989 | Another common argument is @code{:make-flags}, which specifies a list of flags to | |
990 | append when running make, as you would from the command line. For instance, the | |
991 | following flags | |
992 | ||
d482e13f | 993 | @lisp |
ffe059af PN |
994 | #:make-flags (list (string-append "prefix=" (assoc-ref %outputs "out")) |
995 | "CC=gcc") | |
d482e13f | 996 | @end lisp |
ffe059af PN |
997 | |
998 | translate into | |
999 | ||
1000 | @example | |
1001 | $ make CC=gcc prefix=/gnu/store/...-<out> | |
1002 | @end example | |
1003 | ||
1004 | This sets the C compiler to @code{gcc} and the @code{prefix} variable (the installation | |
1005 | directory in Make parlance) to @code{(assoc-ref %outputs "out")}, which is a build-stage | |
1006 | global variable pointing to the destination directory in the store (something like | |
2c8305d1 | 1007 | @file{/gnu/store/...-my-libgit2-20180408}). |
ffe059af | 1008 | |
0cbef07b | 1009 | Similarly, it's possible to set the configure flags: |
ffe059af | 1010 | |
d482e13f | 1011 | @lisp |
ffe059af | 1012 | #:configure-flags '("-DUSE_SHA1DC=ON") |
d482e13f | 1013 | @end lisp |
ffe059af PN |
1014 | |
1015 | The @code{%build-inputs} variable is also generated in scope. It's an association | |
1016 | table that maps the input names to their store directories. | |
1017 | ||
1018 | The @code{phases} keyword lists the sequential steps of the build system. Typically | |
1019 | phases include @code{unpack}, @code{configure}, @code{build}, @code{install} and @code{check}. To know | |
1020 | more about those phases, you need to work out the appropriate build system | |
1021 | definition in @samp{$GUIX_CHECKOUT/guix/build/gnu-build-system.scm}: | |
1022 | ||
d482e13f | 1023 | @lisp |
ffe059af PN |
1024 | (define %standard-phases |
1025 | ;; Standard build phases, as a list of symbol/procedure pairs. | |
1026 | (let-syntax ((phases (syntax-rules () | |
1027 | ((_ p ...) `((p . ,p) ...))))) | |
1028 | (phases set-SOURCE-DATE-EPOCH set-paths install-locale unpack | |
1029 | bootstrap | |
1030 | patch-usr-bin-file | |
1031 | patch-source-shebangs configure patch-generated-file-shebangs | |
1032 | build check install | |
1033 | patch-shebangs strip | |
1034 | validate-runpath | |
1035 | validate-documentation-location | |
1036 | delete-info-dir-file | |
1037 | patch-dot-desktop-files | |
1038 | install-license-files | |
1039 | reset-gzip-timestamps | |
1040 | compress-documentation))) | |
d482e13f | 1041 | @end lisp |
ffe059af PN |
1042 | |
1043 | Or from the REPL: | |
1044 | ||
d482e13f | 1045 | @lisp |
cf1e6f5f LC |
1046 | (add-to-load-path "/path/to/guix/checkout") |
1047 | ,use (guix build gnu-build-system) | |
1048 | (map first %standard-phases) | |
1049 | @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) | |
d482e13f | 1050 | @end lisp |
ffe059af PN |
1051 | |
1052 | If you want to know more about what happens during those phases, consult the | |
1053 | associated procedures. | |
1054 | ||
1055 | For instance, as of this writing the definition of @code{unpack} for the GNU build | |
34513683 | 1056 | system is: |
ffe059af | 1057 | |
d482e13f | 1058 | @lisp |
ffe059af PN |
1059 | (define* (unpack #:key source #:allow-other-keys) |
1060 | "Unpack SOURCE in the working directory, and change directory within the | |
1061 | source. When SOURCE is a directory, copy it in a sub-directory of the current | |
1062 | working directory." | |
1063 | (if (file-is-directory? source) | |
1064 | (begin | |
1065 | (mkdir "source") | |
1066 | (chdir "source") | |
1067 | ||
1068 | ;; Preserve timestamps (set to the Epoch) on the copied tree so that | |
1069 | ;; things work deterministically. | |
1070 | (copy-recursively source "." | |
34513683 | 1071 | #:keep-mtime? #true)) |
ffe059af PN |
1072 | (begin |
1073 | (if (string-suffix? ".zip" source) | |
1074 | (invoke "unzip" source) | |
1075 | (invoke "tar" "xvf" source)) | |
1076 | (chdir (first-subdirectory ".")))) | |
34513683 | 1077 | #true) |
d482e13f | 1078 | @end lisp |
ffe059af PN |
1079 | |
1080 | Note the @code{chdir} call: it changes the working directory to where the source was | |
1081 | unpacked. | |
1082 | Thus every phase following the @code{unpack} will use the source as a working | |
1083 | directory, which is why we can directly work on the source files. | |
1084 | That is to say, unless a later phase changes the working directory to something | |
1085 | else. | |
1086 | ||
1087 | We modify the list of @code{%standard-phases} of the build system with the | |
1088 | @code{modify-phases} macro as per the list of specified modifications, which may have | |
1089 | the following forms: | |
1090 | ||
1091 | @itemize | |
1092 | @item | |
51f34e21 | 1093 | @code{(add-before @var{phase} @var{new-phase} @var{procedure})}: Run @var{procedure} named @var{new-phase} before @var{phase}. |
ffe059af | 1094 | @item |
51f34e21 | 1095 | @code{(add-after @var{phase} @var{new-phase} @var{procedure})}: Same, but afterwards. |
ffe059af | 1096 | @item |
51f34e21 | 1097 | @code{(replace @var{phase} @var{procedure})}. |
ffe059af | 1098 | @item |
51f34e21 | 1099 | @code{(delete @var{phase})}. |
ffe059af PN |
1100 | @end itemize |
1101 | ||
51f34e21 | 1102 | The @var{procedure} supports the keyword arguments @code{inputs} and @code{outputs}. Each |
ffe059af PN |
1103 | input (whether @emph{native}, @emph{propagated} or not) and output directory is referenced |
1104 | by their name in those variables. Thus @code{(assoc-ref outputs "out")} is the store | |
1105 | directory of the main output of the package. A phase procedure may look like | |
1106 | this: | |
1107 | ||
d482e13f | 1108 | @lisp |
ffe059af | 1109 | (lambda* (#:key inputs outputs #:allow-other-keys) |
78029882 LC |
1110 | (let ((bash-directory (assoc-ref inputs "bash")) |
1111 | (output-directory (assoc-ref outputs "out")) | |
1112 | (doc-directory (assoc-ref outputs "doc"))) | |
1113 | ;; ... | |
34513683 | 1114 | #true)) |
d482e13f | 1115 | @end lisp |
ffe059af | 1116 | |
cd958802 | 1117 | The procedure must return @code{#true} on success. It's brittle to rely on the return |
ffe059af | 1118 | value of the last expression used to tweak the phase because there is no |
cd958802 | 1119 | guarantee it would be a @code{#true}. Hence the trailing @code{#true} to ensure the right value |
ffe059af PN |
1120 | is returned on success. |
1121 | ||
1122 | @subsubsection Code staging | |
1123 | ||
1124 | The astute reader may have noticed the quasi-quote and comma syntax in the | |
1125 | argument field. Indeed, the build code in the package declaration should not be | |
1126 | evaluated on the client side, but only when passed to the Guix daemon. This | |
1127 | mechanism of passing code around two running processes is called @uref{https://arxiv.org/abs/1709.00833, code staging}. | |
1128 | ||
0cbef07b | 1129 | @subsubsection Utility functions |
ffe059af PN |
1130 | |
1131 | When customizing @code{phases}, we often need to write code that mimics the | |
cc765e47 | 1132 | equivalent system invocations (@code{make}, @code{mkdir}, @code{cp}, etc.)@: commonly used during |
0cbef07b | 1133 | regular ``Unix-style'' installations. |
ffe059af PN |
1134 | |
1135 | Some like @code{chmod} are native to Guile. | |
1136 | @xref{,,, guile, Guile reference manual} for a complete list. | |
1137 | ||
1138 | Guix provides additional helper functions which prove especially handy in the | |
1139 | context of package management. | |
1140 | ||
1141 | Some of those functions can be found in | |
1142 | @samp{$GUIX_CHECKOUT/guix/guix/build/utils.scm}. Most of them mirror the behaviour | |
1143 | of the traditional Unix system commands: | |
1144 | ||
48720afb | 1145 | @table @code |
ffe059af PN |
1146 | @item which |
1147 | Like the @samp{which} system command. | |
1148 | @item find-files | |
1149 | Akin to the @samp{find} system command. | |
1150 | @item mkdir-p | |
1151 | Like @samp{mkdir -p}, which creates all parents as needed. | |
1152 | @item install-file | |
1153 | Similar to @samp{install} when installing a file to a (possibly | |
1154 | non-existing) directory. Guile has @code{copy-file} which works | |
1155 | like @samp{cp}. | |
1156 | @item copy-recursively | |
1157 | Like @samp{cp -r}. | |
1158 | @item delete-file-recursively | |
1159 | Like @samp{rm -rf}. | |
1160 | @item invoke | |
1161 | Run an executable. This should be used instead of @code{system*}. | |
1162 | @item with-directory-excursion | |
1163 | Run the body in a different working directory, | |
1164 | then restore the previous working directory. | |
1165 | @item substitute* | |
0cbef07b | 1166 | A ``@command{sed}-like'' function. |
ffe059af PN |
1167 | @end table |
1168 | ||
61263e1b LC |
1169 | @xref{Build Utilities,,, guix, GNU Guix Reference Manual}, for more |
1170 | information on these utilities. | |
1171 | ||
ffe059af PN |
1172 | @subsubsection Module prefix |
1173 | ||
1174 | The license in our last example needs a prefix: this is because of how the | |
1175 | @code{license} module was imported in the package, as @code{#:use-module ((guix licenses) | |
1176 | #:prefix license:)}. The Guile module import mechanism | |
1177 | (@pxref{Using Guile Modules,,, guile, Guile reference manual}) | |
1178 | gives the user full control over namespacing: this is needed to avoid | |
1179 | clashes between, say, the | |
1180 | @samp{zlib} variable from @samp{licenses.scm} (a @emph{license} value) and the @samp{zlib} variable | |
1181 | from @samp{compression.scm} (a @emph{package} value). | |
1182 | ||
1183 | @node Other build systems | |
1184 | @subsection Other build systems | |
1185 | ||
1186 | What we've seen so far covers the majority of packages using a build system | |
1187 | other than the @code{trivial-build-system}. The latter does not automate anything | |
1188 | and leaves you to build everything manually. This can be more demanding and we | |
1189 | won't cover it here for now, but thankfully it is rarely necessary to fall back | |
1190 | on this system. | |
1191 | ||
1192 | For the other build systems, such as ASDF, Emacs, Perl, Ruby and many more, the | |
1193 | process is very similar to the GNU build system except for a few specialized | |
1194 | arguments. | |
1195 | ||
a9e25512 LC |
1196 | @xref{Build Systems,,, guix, GNU Guix Reference Manual}, for more |
1197 | information on build systems, or check the source code in the | |
1198 | @samp{$GUIX_CHECKOUT/guix/build} and | |
ffe059af | 1199 | @samp{$GUIX_CHECKOUT/guix/build-system} directories. |
ffe059af PN |
1200 | |
1201 | @node Programmable and automated package definition | |
1202 | @subsection Programmable and automated package definition | |
1203 | ||
1204 | We can't repeat it enough: having a full-fledged programming language at hand | |
1205 | empowers us in ways that reach far beyond traditional package management. | |
1206 | ||
1207 | Let's illustrate this with some awesome features of Guix! | |
1208 | ||
1209 | @node Recursive importers | |
1210 | @subsubsection Recursive importers | |
1211 | ||
1212 | You might find some build systems good enough that there is little to do at all | |
1213 | to write a package, to the point that it becomes repetitive and tedious after a | |
1214 | while. A @emph{raison d'être} of computers is to replace human beings at those | |
1215 | boring tasks. So let's tell Guix to do this for us and create the package | |
1216 | definition of an R package from CRAN (the output is trimmed for conciseness): | |
1217 | ||
1218 | @example | |
1219 | $ guix import cran --recursive walrus | |
1220 | ||
1221 | (define-public r-mc2d | |
1222 | ; ... | |
1223 | (license gpl2+))) | |
1224 | ||
1225 | (define-public r-jmvcore | |
1226 | ; ... | |
1227 | (license gpl2+))) | |
1228 | ||
1229 | (define-public r-wrs2 | |
1230 | ; ... | |
1231 | (license gpl3))) | |
1232 | ||
1233 | (define-public r-walrus | |
1234 | (package | |
1235 | (name "r-walrus") | |
1236 | (version "1.0.3") | |
1237 | (source | |
1238 | (origin | |
1239 | (method url-fetch) | |
1240 | (uri (cran-uri "walrus" version)) | |
1241 | (sha256 | |
1242 | (base32 | |
1243 | "1nk2glcvy4hyksl5ipq2mz8jy4fss90hx6cq98m3w96kzjni6jjj")))) | |
1244 | (build-system r-build-system) | |
1245 | (propagated-inputs | |
e60f803b | 1246 | (list r-ggplot2 r-jmvcore r-r6 r-wrs2)) |
ffe059af PN |
1247 | (home-page "https://github.com/jamovi/walrus") |
1248 | (synopsis "Robust Statistical Methods") | |
1249 | (description | |
1250 | "This package provides a toolbox of common robust statistical | |
1251 | tests, including robust descriptives, robust t-tests, and robust ANOVA. | |
1252 | It is also available as a module for 'jamovi' (see | |
1253 | <https://www.jamovi.org> for more information). Walrus is based on the | |
1254 | WRS2 package by Patrick Mair, which is in turn based on the scripts and | |
1255 | work of Rand Wilcox. These analyses are described in depth in the book | |
1256 | 'Introduction to Robust Estimation & Hypothesis Testing'.") | |
1257 | (license gpl3))) | |
1258 | @end example | |
1259 | ||
1260 | The recursive importer won't import packages for which Guix already has package | |
1261 | definitions, except for the very first. | |
1262 | ||
1263 | Not all applications can be packaged this way, only those relying on a select | |
1264 | number of supported systems. Read about the full list of importers in | |
1265 | the guix import section of the manual | |
1266 | (@pxref{Invoking guix import,,, guix, GNU Guix Reference Manual}). | |
1267 | ||
1268 | @node Automatic update | |
1269 | @subsubsection Automatic update | |
1270 | ||
1271 | Guix can be smart enough to check for updates on systems it knows. It can | |
1272 | report outdated package definitions with | |
1273 | ||
1274 | @example | |
1275 | $ guix refresh hello | |
1276 | @end example | |
1277 | ||
1278 | In most cases, updating a package to a newer version requires little more than | |
1279 | changing the version number and the checksum. Guix can do that automatically as | |
1280 | well: | |
1281 | ||
1282 | @example | |
1283 | $ guix refresh hello --update | |
1284 | @end example | |
1285 | ||
1286 | @node Inheritance | |
1287 | @subsubsection Inheritance | |
1288 | ||
1289 | If you've started browsing the existing package definitions, you might have | |
1290 | noticed that a significant number of them have a @code{inherit} field: | |
1291 | ||
d482e13f | 1292 | @lisp |
ffe059af PN |
1293 | (define-public adwaita-icon-theme |
1294 | (package (inherit gnome-icon-theme) | |
1295 | (name "adwaita-icon-theme") | |
1296 | (version "3.26.1") | |
1297 | (source (origin | |
1298 | (method url-fetch) | |
1299 | (uri (string-append "mirror://gnome/sources/" name "/" | |
1300 | (version-major+minor version) "/" | |
1301 | name "-" version ".tar.xz")) | |
1302 | (sha256 | |
1303 | (base32 | |
1304 | "17fpahgh5dyckgz7rwqvzgnhx53cx9kr2xw0szprc6bnqy977fi8")))) | |
e60f803b | 1305 | (native-inputs (list `(,gtk+ "bin"))))) |
d482e13f | 1306 | @end lisp |
ffe059af PN |
1307 | |
1308 | All unspecified fields are inherited from the parent package. This is very | |
1309 | convenient to create alternative packages, for instance with different source, | |
1310 | version or compilation options. | |
1311 | ||
1312 | @node Getting help | |
1313 | @subsection Getting help | |
1314 | ||
1315 | Sadly, some applications can be tough to package. Sometimes they need a patch to | |
e892b9c3 | 1316 | work with the non-standard file system hierarchy enforced by the store. |
ffe059af PN |
1317 | Sometimes the tests won't run properly. (They can be skipped but this is not |
1318 | recommended.) Other times the resulting package won't be reproducible. | |
1319 | ||
1320 | Should you be stuck, unable to figure out how to fix any sort of packaging | |
1321 | issue, don't hesitate to ask the community for help. | |
1322 | ||
1323 | See the @uref{https://www.gnu.org/software/guix/contact/, Guix homepage} for information on the mailing lists, IRC, etc. | |
1324 | ||
1325 | @node Conclusion | |
1326 | @subsection Conclusion | |
1327 | ||
1328 | This tutorial was a showcase of the sophisticated package management that Guix | |
1329 | boasts. At this point we have mostly restricted this introduction to the | |
1330 | @code{gnu-build-system} which is a core abstraction layer on which more advanced | |
1331 | abstractions are based. | |
1332 | ||
1333 | Where do we go from here? Next we ought to dissect the innards of the build | |
1334 | system by removing all abstractions, using the @code{trivial-build-system}: this | |
1335 | should give us a thorough understanding of the process before investigating some | |
1336 | more advanced packaging techniques and edge cases. | |
1337 | ||
1338 | Other features worth exploring are the interactive editing and debugging | |
1339 | capabilities of Guix provided by the Guile REPL@. | |
1340 | ||
1341 | Those fancy features are completely optional and can wait; now is a good time | |
1342 | to take a well-deserved break. With what we've introduced here you should be | |
1343 | well armed to package lots of programs. You can get started right away and | |
1344 | hopefully we will see your contributions soon! | |
1345 | ||
1346 | @node References | |
1347 | @subsection References | |
1348 | ||
1349 | @itemize | |
1350 | @item | |
1351 | The @uref{https://www.gnu.org/software/guix/manual/en/html_node/Defining-Packages.html, package reference in the manual} | |
1352 | ||
1353 | @item | |
1354 | @uref{https://gitlab.com/pjotrp/guix-notes/blob/master/HACKING.org, Pjotr’s hacking guide to GNU Guix} | |
1355 | ||
1356 | @item | |
0cbef07b | 1357 | @uref{https://www.gnu.org/software/guix/guix-ghm-andreas-20130823.pdf, ``GNU Guix: Package without a scheme!''}, by Andreas Enge |
ffe059af | 1358 | @end itemize |
7bc46ecc RW |
1359 | |
1360 | @c ********************************************************************* | |
1361 | @node System Configuration | |
1362 | @chapter System Configuration | |
1363 | ||
1364 | Guix offers a flexible language for declaratively configuring your Guix | |
1365 | System. This flexibility can at times be overwhelming. The purpose of this | |
1366 | chapter is to demonstrate some advanced configuration concepts. | |
1367 | ||
1368 | @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete | |
1369 | reference. | |
1370 | ||
1371 | @menu | |
c2ff06e5 | 1372 | * Auto-Login to a Specific TTY:: Automatically Login a User to a Specific TTY |
65051fdc | 1373 | * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System. |
07ef129d | 1374 | * Guix System Image API:: Customizing images to target specific platforms. |
5c3e94cd | 1375 | * Connecting to Wireguard VPN:: Connecting to a Wireguard VPN. |
65051fdc | 1376 | * Customizing a Window Manager:: Handle customization of a Window manager on Guix System. |
191e79da | 1377 | * Running Guix on a Linode Server:: Running Guix on a Linode Server |
60651dd9 | 1378 | * Setting up a bind mount:: Setting up a bind mount in the file-systems definition. |
c987b723 | 1379 | * Getting substitutes from Tor:: Configuring Guix daemon to get substitutes through Tor. |
00014f76 | 1380 | * Setting up NGINX with Lua:: Configuring NGINX web-server to load Lua modules. |
7bc46ecc RW |
1381 | @end menu |
1382 | ||
c2ff06e5 JB |
1383 | @node Auto-Login to a Specific TTY |
1384 | @section Auto-Login to a Specific TTY | |
1385 | ||
1386 | While the Guix manual explains auto-login one user to @emph{all} TTYs ( | |
1387 | @pxref{auto-login to TTY,,, guix, GNU Guix Reference Manual}), some | |
1388 | might prefer a situation, in which one user is logged into one TTY with | |
1389 | the other TTYs either configured to login different users or no one at | |
1390 | all. Note that one can auto-login one user to any TTY, but it is | |
1391 | usually advisable to avoid @code{tty1}, which, by default, is used to | |
1392 | log warnings and errors. | |
1393 | ||
1394 | Here is how one might set up auto login for one user to one tty: | |
1395 | ||
1396 | @lisp | |
1397 | (define (auto-login-to-tty config tty user) | |
1398 | (if (string=? tty (mingetty-configuration-tty config)) | |
1399 | (mingetty-configuration | |
1400 | (inherit config) | |
1401 | (auto-login user)) | |
1402 | config)) | |
1403 | ||
1404 | (define %my-services | |
1405 | (modify-services %base-services | |
1406 | ;; @dots{} | |
1407 | (mingetty-service-type config => | |
1408 | (auto-login-to-tty | |
1409 | config "tty3" "alice")))) | |
1410 | ||
1411 | (operating-system | |
1412 | ;; @dots{} | |
1413 | (services %my-services)) | |
1414 | @end lisp | |
1415 | ||
1416 | One could also @code{compose} (@pxref{Higher-Order Functions,,, guile, | |
1417 | The Guile Reference Manual}) @code{auto-login-to-tty} to login multiple | |
1418 | users to multiple ttys. | |
1419 | ||
1420 | Finally, here is a note of caution. Setting up auto login to a TTY, | |
1421 | means that anyone can turn on your computer and run commands as your | |
1422 | regular user. | |
1423 | However, if you have an encrypted root partition, and thus already need | |
1424 | to enter a passphrase when the system boots, auto-login might be a | |
1425 | convenient option. | |
1426 | ||
1427 | ||
7bc46ecc RW |
1428 | @node Customizing the Kernel |
1429 | @section Customizing the Kernel | |
1430 | ||
1431 | Guix is, at its core, a source based distribution with substitutes | |
1432 | (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building | |
1433 | packages from their source code is an expected part of regular package | |
1434 | installations and upgrades. Given this starting point, it makes sense that | |
1435 | efforts are made to reduce the amount of time spent compiling packages, and | |
1436 | recent changes and upgrades to the building and distribution of substitutes | |
1437 | continues to be a topic of discussion within Guix. | |
1438 | ||
1439 | The kernel, while not requiring an overabundance of RAM to build, does take a | |
1440 | rather long time on an average machine. The official kernel configuration, as | |
1441 | is the case with many GNU/Linux distributions, errs on the side of | |
1442 | inclusiveness, and this is really what causes the build to take such a long | |
1443 | time when the kernel is built from source. | |
1444 | ||
1445 | The Linux kernel, however, can also just be described as a regular old | |
1446 | package, and as such can be customized just like any other package. The | |
1447 | procedure is a little bit different, although this is primarily due to the | |
1448 | nature of how the package definition is written. | |
1449 | ||
1450 | The @code{linux-libre} kernel package definition is actually a procedure which | |
1451 | creates a package. | |
1452 | ||
b1eecb5c | 1453 | @lisp |
c7d74a9b LF |
1454 | (define* (make-linux-libre* version gnu-revision source supported-systems |
1455 | #:key | |
1456 | (extra-version #f) | |
1457 | ;; A function that takes an arch and a variant. | |
1458 | ;; See kernel-config for an example. | |
1459 | (configuration-file #f) | |
1460 | (defconfig "defconfig") | |
1461 | (extra-options %default-extra-linux-options)) | |
7bc46ecc | 1462 | ...) |
b1eecb5c | 1463 | @end lisp |
7bc46ecc | 1464 | |
c7d74a9b | 1465 | The current @code{linux-libre} package is for the 5.15.x series, and is |
7bc46ecc RW |
1466 | declared like this: |
1467 | ||
b1eecb5c | 1468 | @lisp |
c7d74a9b LF |
1469 | (define-public linux-libre-5.15 |
1470 | (make-linux-libre* linux-libre-5.15-version | |
1471 | linux-libre-5.15-gnu-revision | |
1472 | linux-libre-5.15-source | |
1473 | '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux" "riscv64-linux") | |
1474 | #:configuration-file kernel-config)) | |
b1eecb5c | 1475 | @end lisp |
7bc46ecc RW |
1476 | |
1477 | Any keys which are not assigned values inherit their default value from the | |
1478 | @code{make-linux-libre} definition. When comparing the two snippets above, | |
c7d74a9b LF |
1479 | notice the code comment that refers to @code{#:configuration-file}. Because of |
1480 | this, it is not actually easy to include a custom kernel configuration from the | |
1481 | definition, but don't worry, there are other ways to work with what we do have. | |
7bc46ecc RW |
1482 | |
1483 | There are two ways to create a kernel with a custom kernel configuration. The | |
1484 | first is to provide a standard @file{.config} file during the build process by | |
1485 | including an actual @file{.config} file as a native input to our custom | |
1486 | kernel. The following is a snippet from the custom @code{'configure} phase of | |
1487 | the @code{make-linux-libre} package definition: | |
1488 | ||
b1eecb5c | 1489 | @lisp |
7bc46ecc RW |
1490 | (let ((build (assoc-ref %standard-phases 'build)) |
1491 | (config (assoc-ref (or native-inputs inputs) "kconfig"))) | |
1492 | ||
1493 | ;; Use a custom kernel configuration file or a default | |
1494 | ;; configuration file. | |
1495 | (if config | |
1496 | (begin | |
1497 | (copy-file config ".config") | |
1498 | (chmod ".config" #o666)) | |
f5414906 | 1499 | (invoke "make" ,defconfig))) |
b1eecb5c | 1500 | @end lisp |
7bc46ecc RW |
1501 | |
1502 | Below is a sample kernel package. The @code{linux-libre} package is nothing | |
1503 | special and can be inherited from and have its fields overridden like any | |
1504 | other package: | |
1505 | ||
b1eecb5c | 1506 | @lisp |
7bc46ecc RW |
1507 | (define-public linux-libre/E2140 |
1508 | (package | |
1509 | (inherit linux-libre) | |
1510 | (native-inputs | |
1511 | `(("kconfig" ,(local-file "E2140.config")) | |
1512 | ,@@(alist-delete "kconfig" | |
1513 | (package-native-inputs linux-libre)))))) | |
b1eecb5c | 1514 | @end lisp |
7bc46ecc RW |
1515 | |
1516 | In the same directory as the file defining @code{linux-libre-E2140} is a file | |
1517 | named @file{E2140.config}, which is an actual kernel configuration file. The | |
1518 | @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the | |
1519 | only kernel configuration in the package is the one which was included in the | |
1520 | @code{native-inputs} field. | |
1521 | ||
1522 | The second way to create a custom kernel is to pass a new value to the | |
1523 | @code{extra-options} keyword of the @code{make-linux-libre} procedure. The | |
1524 | @code{extra-options} keyword works with another function defined right below | |
1525 | it: | |
1526 | ||
b1eecb5c | 1527 | @lisp |
7bc46ecc RW |
1528 | (define %default-extra-linux-options |
1529 | `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html | |
34513683 | 1530 | ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #true) |
7bc46ecc RW |
1531 | ;; Modules required for initrd: |
1532 | ("CONFIG_NET_9P" . m) | |
1533 | ("CONFIG_NET_9P_VIRTIO" . m) | |
1534 | ("CONFIG_VIRTIO_BLK" . m) | |
1535 | ("CONFIG_VIRTIO_NET" . m) | |
1536 | ("CONFIG_VIRTIO_PCI" . m) | |
1537 | ("CONFIG_VIRTIO_BALLOON" . m) | |
1538 | ("CONFIG_VIRTIO_MMIO" . m) | |
1539 | ("CONFIG_FUSE_FS" . m) | |
1540 | ("CONFIG_CIFS" . m) | |
1541 | ("CONFIG_9P_FS" . m))) | |
1542 | ||
1543 | (define (config->string options) | |
1544 | (string-join (map (match-lambda | |
1545 | ((option . 'm) | |
1546 | (string-append option "=m")) | |
34513683 | 1547 | ((option . #true) |
7bc46ecc | 1548 | (string-append option "=y")) |
34513683 | 1549 | ((option . #false) |
7bc46ecc RW |
1550 | (string-append option "=n"))) |
1551 | options) | |
1552 | "\n")) | |
b1eecb5c | 1553 | @end lisp |
7bc46ecc RW |
1554 | |
1555 | And in the custom configure script from the `make-linux-libre` package: | |
1556 | ||
b1eecb5c | 1557 | @lisp |
7bc46ecc RW |
1558 | ;; Appending works even when the option wasn't in the |
1559 | ;; file. The last one prevails if duplicated. | |
1560 | (let ((port (open-file ".config" "a")) | |
1561 | (extra-configuration ,(config->string extra-options))) | |
1562 | (display extra-configuration port) | |
1563 | (close-port port)) | |
1564 | ||
f5414906 | 1565 | (invoke "make" "oldconfig") |
b1eecb5c | 1566 | @end lisp |
7bc46ecc RW |
1567 | |
1568 | So by not providing a configuration-file the @file{.config} starts blank, and | |
1569 | then we write into it the collection of flags that we want. Here's another | |
1570 | custom kernel: | |
1571 | ||
b1eecb5c | 1572 | @lisp |
7bc46ecc RW |
1573 | (define %macbook41-full-config |
1574 | (append %macbook41-config-options | |
e892b9c3 | 1575 | %file-systems |
7bc46ecc RW |
1576 | %efi-support |
1577 | %emulation | |
1578 | (@@@@ (gnu packages linux) %default-extra-linux-options))) | |
1579 | ||
1580 | (define-public linux-libre-macbook41 | |
c7d74a9b | 1581 | ;; XXX: Access the internal 'make-linux-libre*' procedure, which is |
7bc46ecc | 1582 | ;; private and unexported, and is liable to change in the future. |
c7d74a9b LF |
1583 | ((@@@@ (gnu packages linux) make-linux-libre*) |
1584 | (@@@@ (gnu packages linux) linux-libre-version) | |
1585 | (@@@@ (gnu packages linux) linux-libre-gnu-revision) | |
1586 | (@@@@ (gnu packages linux) linux-libre-source) | |
1587 | '("x86_64-linux") | |
1588 | #:extra-version "macbook41" | |
1589 | #:extra-options %macbook41-config-options)) | |
b1eecb5c | 1590 | @end lisp |
7bc46ecc | 1591 | |
e892b9c3 TGR |
1592 | In the above example @code{%file-systems} is a collection of flags enabling |
1593 | different file system support, @code{%efi-support} enables EFI support and | |
7bc46ecc RW |
1594 | @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also. |
1595 | @code{%default-extra-linux-options} are the ones quoted above, which had to be | |
1596 | added in since they were replaced in the @code{extra-options} keyword. | |
1597 | ||
1598 | This all sounds like it should be doable, but how does one even know which | |
1599 | modules are required for a particular system? Two places that can be helpful | |
1600 | in trying to answer this question is the | |
1601 | @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo | |
1602 | Handbook} and the | |
1603 | @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig, | |
1604 | documentation from the kernel itself}. From the kernel documentation, it | |
1605 | seems that @code{make localmodconfig} is the command we want. | |
1606 | ||
1607 | In order to actually run @code{make localmodconfig} we first need to get and | |
1608 | unpack the kernel source code: | |
1609 | ||
1610 | @example shell | |
1611 | tar xf $(guix build linux-libre --source) | |
1612 | @end example | |
1613 | ||
1614 | Once inside the directory containing the source code run @code{touch .config} | |
1615 | to create an initial, empty @file{.config} to start with. @code{make | |
1616 | localmodconfig} works by seeing what you already have in @file{.config} and | |
1617 | letting you know what you're missing. If the file is blank then you're | |
1618 | missing everything. The next step is to run: | |
1619 | ||
1620 | @example shell | |
da7bee91 | 1621 | guix shell -D linux-libre -- make localmodconfig |
7bc46ecc RW |
1622 | @end example |
1623 | ||
1624 | and note the output. Do note that the @file{.config} file is still empty. | |
1625 | The output generally contains two types of warnings. The first start with | |
1626 | "WARNING" and can actually be ignored in our case. The second read: | |
1627 | ||
1628 | @example shell | |
1629 | module pcspkr did not have configs CONFIG_INPUT_PCSPKR | |
1630 | @end example | |
1631 | ||
1632 | For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the | |
1633 | @file{.config} in the directory, and append @code{=m}, so in the end it looks | |
1634 | like this: | |
1635 | ||
1636 | @example shell | |
1637 | CONFIG_INPUT_PCSPKR=m | |
1638 | CONFIG_VIRTIO=m | |
1639 | @end example | |
1640 | ||
1641 | After copying all the configuration options, run @code{make localmodconfig} | |
0cbef07b | 1642 | again to make sure that you don't have any output starting with ``module''. |
7bc46ecc RW |
1643 | After all of these machine specific modules there are a couple more left that |
1644 | are also needed. @code{CONFIG_MODULES} is necessary so that you can build and | |
1645 | load modules separately and not have everything built into the kernel. | |
1646 | @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is | |
1647 | possible that there are other modules which you will need. | |
1648 | ||
1649 | This post does not aim to be a guide to configuring your own kernel however, | |
1650 | so if you do decide to build a custom kernel you'll have to seek out other | |
1651 | guides to create a kernel which is just right for your needs. | |
1652 | ||
1653 | The second way to setup the kernel configuration makes more use of Guix's | |
1654 | features and allows you to share configuration segments between different | |
1655 | kernels. For example, all machines using EFI to boot have a number of EFI | |
1656 | configuration flags that they need. It is likely that all the kernels will | |
e892b9c3 | 1657 | share a list of file systems to support. By using variables it is easier to |
7bc46ecc RW |
1658 | see at a glance what features are enabled and to make sure you don't have |
1659 | features in one kernel but missing in another. | |
1660 | ||
1661 | Left undiscussed however, is Guix's initrd and its customization. It is | |
1662 | likely that you'll need to modify the initrd on a machine using a custom | |
1663 | kernel, since certain modules which are expected to be built may not be | |
1664 | available for inclusion into the initrd. | |
1665 | ||
07ef129d JB |
1666 | @node Guix System Image API |
1667 | @section Guix System Image API | |
1668 | ||
1669 | Historically, Guix System is centered around an @code{operating-system} | |
1670 | structure. This structure contains various fields ranging from the | |
1671 | bootloader and kernel declaration to the services to install. | |
1672 | ||
1673 | Depending on the target machine, that can go from a standard | |
1674 | @code{x86_64} machine to a small ARM single board computer such as the | |
1675 | Pine64, the image constraints can vary a lot. The hardware | |
1676 | manufacturers will impose different image formats with various partition | |
1677 | sizes and offsets. | |
1678 | ||
1679 | To create images suitable for all those machines, a new abstraction is | |
1680 | necessary: that's the goal of the @code{image} record. This record | |
1681 | contains all the required information to be transformed into a | |
1682 | standalone image, that can be directly booted on any target machine. | |
1683 | ||
1684 | @lisp | |
1685 | (define-record-type* <image> | |
1686 | image make-image | |
1687 | image? | |
1688 | (name image-name ;symbol | |
1689 | (default #f)) | |
1690 | (format image-format) ;symbol | |
1691 | (target image-target | |
1692 | (default #f)) | |
1693 | (size image-size ;size in bytes as integer | |
1694 | (default 'guess)) | |
1695 | (operating-system image-operating-system ;<operating-system> | |
1696 | (default #f)) | |
1697 | (partitions image-partitions ;list of <partition> | |
1698 | (default '())) | |
1699 | (compression? image-compression? ;boolean | |
1700 | (default #t)) | |
1701 | (volatile-root? image-volatile-root? ;boolean | |
1702 | (default #t)) | |
1703 | (substitutable? image-substitutable? ;boolean | |
1704 | (default #t))) | |
1705 | @end lisp | |
1706 | ||
1707 | This record contains the operating-system to instantiate. The | |
1708 | @code{format} field defines the image type and can be @code{efi-raw}, | |
1709 | @code{qcow2} or @code{iso9660} for instance. In the future, it could be | |
1710 | extended to @code{docker} or other image types. | |
1711 | ||
1712 | A new directory in the Guix sources is dedicated to images definition. For now | |
1713 | there are four files: | |
1714 | ||
1715 | @itemize @bullet | |
1716 | @item @file{gnu/system/images/hurd.scm} | |
1717 | @item @file{gnu/system/images/pine64.scm} | |
1718 | @item @file{gnu/system/images/novena.scm} | |
1719 | @item @file{gnu/system/images/pinebook-pro.scm} | |
1720 | @end itemize | |
1721 | ||
1722 | Let's have a look to @file{pine64.scm}. It contains the | |
1723 | @code{pine64-barebones-os} variable which is a minimal definition of an | |
1724 | operating-system dedicated to the @b{Pine A64 LTS} board. | |
1725 | ||
1726 | @lisp | |
1727 | (define pine64-barebones-os | |
1728 | (operating-system | |
1729 | (host-name "vignemale") | |
1730 | (timezone "Europe/Paris") | |
1731 | (locale "en_US.utf8") | |
1732 | (bootloader (bootloader-configuration | |
1733 | (bootloader u-boot-pine64-lts-bootloader) | |
da4e4094 | 1734 | (targets '("/dev/vda")))) |
07ef129d JB |
1735 | (initrd-modules '()) |
1736 | (kernel linux-libre-arm64-generic) | |
1737 | (file-systems (cons (file-system | |
1738 | (device (file-system-label "my-root")) | |
1739 | (mount-point "/") | |
1740 | (type "ext4")) | |
1741 | %base-file-systems)) | |
1742 | (services (cons (service agetty-service-type | |
1743 | (agetty-configuration | |
1744 | (extra-options '("-L")) ; no carrier detect | |
1745 | (baud-rate "115200") | |
1746 | (term "vt100") | |
1747 | (tty "ttyS0"))) | |
1748 | %base-services)))) | |
1749 | @end lisp | |
1750 | ||
1751 | The @code{kernel} and @code{bootloader} fields are pointing to packages | |
1752 | dedicated to this board. | |
1753 | ||
1754 | Right below, the @code{pine64-image-type} variable is also defined. | |
1755 | ||
1756 | @lisp | |
1757 | (define pine64-image-type | |
1758 | (image-type | |
1759 | (name 'pine64-raw) | |
1760 | (constructor (cut image-with-os arm64-disk-image <>)))) | |
1761 | @end lisp | |
1762 | ||
1763 | It's using a record we haven't talked about yet, the @code{image-type} record, | |
1764 | defined this way: | |
1765 | ||
1766 | @lisp | |
1767 | (define-record-type* <image-type> | |
1768 | image-type make-image-type | |
1769 | image-type? | |
1770 | (name image-type-name) ;symbol | |
1771 | (constructor image-type-constructor)) ;<operating-system> -> <image> | |
1772 | @end lisp | |
1773 | ||
1774 | The main purpose of this record is to associate a name to a procedure | |
1775 | transforming an @code{operating-system} to an image. To understand why | |
1776 | it is necessary, let's have a look to the command producing an image | |
1777 | from an @code{operating-system} configuration file: | |
1778 | ||
1779 | @example | |
1780 | guix system image my-os.scm | |
1781 | @end example | |
1782 | ||
1783 | This command expects an @code{operating-system} configuration but how | |
1784 | should we indicate that we want an image targeting a Pine64 board? We | |
1785 | need to provide an extra information, the @code{image-type}, by passing | |
1786 | the @code{--image-type} or @code{-t} flag, this way: | |
1787 | ||
1788 | @example | |
1789 | guix system image --image-type=pine64-raw my-os.scm | |
1790 | @end example | |
1791 | ||
1792 | This @code{image-type} parameter points to the @code{pine64-image-type} | |
1793 | defined above. Hence, the @code{operating-system} declared in | |
1794 | @code{my-os.scm} will be applied the @code{(cut image-with-os | |
1795 | arm64-disk-image <>)} procedure to turn it into an image. | |
1796 | ||
1797 | The resulting image looks like: | |
1798 | ||
1799 | @lisp | |
1800 | (image | |
1801 | (format 'disk-image) | |
1802 | (target "aarch64-linux-gnu") | |
1803 | (operating-system my-os) | |
1804 | (partitions | |
1805 | (list (partition | |
1806 | (inherit root-partition) | |
1807 | (offset root-offset))))) | |
1808 | @end lisp | |
1809 | ||
1810 | which is the aggregation of the @code{operating-system} defined in | |
1811 | @code{my-os.scm} to the @code{arm64-disk-image} record. | |
1812 | ||
1813 | But enough Scheme madness. What does this image API bring to the Guix user? | |
1814 | ||
1815 | One can run: | |
1816 | ||
1817 | @example | |
1818 | mathieu@@cervin:~$ guix system --list-image-types | |
1819 | The available image types are: | |
1820 | ||
1821 | - pinebook-pro-raw | |
1822 | - pine64-raw | |
1823 | - novena-raw | |
1824 | - hurd-raw | |
1825 | - hurd-qcow2 | |
1826 | - qcow2 | |
1827 | - uncompressed-iso9660 | |
1828 | - efi-raw | |
1829 | - arm64-raw | |
1830 | - arm32-raw | |
1831 | - iso9660 | |
1832 | @end example | |
1833 | ||
1834 | and by writing an @code{operating-system} file based on | |
1835 | @code{pine64-barebones-os}, you can customize your image to your | |
1836 | preferences in a file (@file{my-pine-os.scm}) like this: | |
1837 | ||
1838 | @lisp | |
1839 | (use-modules (gnu services linux) | |
1840 | (gnu system images pine64)) | |
1841 | ||
1842 | (let ((base-os pine64-barebones-os)) | |
1843 | (operating-system | |
1844 | (inherit base-os) | |
1845 | (timezone "America/Indiana/Indianapolis") | |
1846 | (services | |
1847 | (cons | |
1848 | (service earlyoom-service-type | |
1849 | (earlyoom-configuration | |
1850 | (prefer-regexp "icecat|chromium"))) | |
1851 | (operating-system-user-services base-os))))) | |
1852 | @end lisp | |
1853 | ||
1854 | run: | |
1855 | ||
1856 | @example | |
1857 | guix system image --image-type=pine64-raw my-pine-os.scm | |
1858 | @end example | |
1859 | ||
1860 | or, | |
1861 | ||
1862 | @example | |
1863 | guix system image --image-type=hurd-raw my-hurd-os.scm | |
1864 | @end example | |
1865 | ||
1866 | to get an image that can be written directly to a hard drive and booted | |
1867 | from. | |
1868 | ||
1869 | Without changing anything to @code{my-hurd-os.scm}, calling: | |
1870 | ||
1871 | @example | |
1872 | guix system image --image-type=hurd-qcow2 my-hurd-os.scm | |
1873 | @end example | |
1874 | ||
1875 | will instead produce a Hurd QEMU image. | |
1876 | ||
5c3e94cd MK |
1877 | @node Connecting to Wireguard VPN |
1878 | @section Connecting to Wireguard VPN | |
1879 | ||
1880 | To connect to a Wireguard VPN server you need the kernel module to be | |
1881 | loaded in memory and a package providing networking tools that support | |
1882 | it (e.g. @code{wireguard-tools} or @code{network-manager}). | |
1883 | ||
1884 | Here is a configuration example for Linux-Libre < 5.6, where the module | |
1885 | is out of tree and need to be loaded manually---following revisions of | |
1886 | the kernel have it built-in and so don't need such configuration: | |
1887 | ||
1888 | @lisp | |
1889 | (use-modules (gnu)) | |
1890 | (use-service-modules desktop) | |
1891 | (use-package-modules vpn) | |
1892 | ||
1893 | (operating-system | |
1894 | ;; … | |
1895 | (services (cons (simple-service 'wireguard-module | |
1896 | kernel-module-loader-service-type | |
1897 | '("wireguard")) | |
1898 | %desktop-services)) | |
1899 | (packages (cons wireguard-tools %base-packages)) | |
1900 | (kernel-loadable-modules (list wireguard-linux-compat))) | |
1901 | @end lisp | |
1902 | ||
1903 | After reconfiguring and restarting your system you can either use | |
1904 | Wireguard tools or NetworkManager to connect to a VPN server. | |
1905 | ||
1906 | @subsection Using Wireguard tools | |
1907 | ||
1908 | To test your Wireguard setup it is convenient to use @command{wg-quick}. | |
1909 | Just give it a configuration file @command{wg-quick up ./wg0.conf}; or | |
1910 | put that file in @file{/etc/wireguard} and run @command{wg-quick up wg0} | |
1911 | instead. | |
1912 | ||
1913 | @quotation Note | |
1914 | Be warned that the author described this command as a: “[…] very quick | |
1915 | and dirty bash script […]”. | |
1916 | @end quotation | |
1917 | ||
1918 | @subsection Using NetworkManager | |
1919 | ||
1920 | Thanks to NetworkManager support for Wireguard we can connect to our VPN | |
1921 | using @command{nmcli} command. Up to this point this guide assumes that | |
1922 | you're using Network Manager service provided by | |
1923 | @code{%desktop-services}. Ortherwise you need to adjust your services | |
1924 | list to load @code{network-manager-service-type} and reconfigure your | |
1925 | Guix system. | |
1926 | ||
1927 | To import your VPN configuration execute nmcli import command: | |
1928 | ||
1929 | @example shell | |
1930 | # nmcli connection import type wireguard file wg0.conf | |
1931 | Connection 'wg0' (edbee261-aa5a-42db-b032-6c7757c60fde) successfully added | |
1932 | @end example | |
1933 | ||
1934 | This will create a configuration file in | |
1935 | @file{/etc/NetworkManager/wg0.nmconnection}. Next connect to the | |
1936 | Wireguard server: | |
1937 | ||
1938 | @example shell | |
1939 | $ nmcli connection up wg0 | |
1940 | Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/6) | |
1941 | @end example | |
1942 | ||
1943 | By default NetworkManager will connect automatically on system boot. To | |
1944 | change that behaviour you need to edit your config: | |
1945 | ||
1946 | @example shell | |
1947 | # nmcli connection modify wg0 connection.autoconnect no | |
1948 | @end example | |
1949 | ||
1950 | For more specific information about NetworkManager and wireguard | |
1951 | @uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see | |
1952 | this post by thaller}. | |
1953 | ||
65051fdc OP |
1954 | @node Customizing a Window Manager |
1955 | @section Customizing a Window Manager | |
1956 | @cindex wm | |
1957 | ||
1958 | @node StumpWM | |
1959 | @subsection StumpWM | |
1960 | @cindex stumpwm | |
1961 | ||
1962 | You could install StumpWM with a Guix system by adding | |
145df67b | 1963 | @code{stumpwm} and optionally @code{`(,stumpwm "lib")} |
cc765e47 | 1964 | packages to a system configuration file, e.g.@: @file{/etc/config.scm}. |
65051fdc OP |
1965 | |
1966 | An example configuration can look like this: | |
1967 | ||
1968 | @lisp | |
1969 | (use-modules (gnu)) | |
1970 | (use-package-modules wm) | |
1971 | ||
1972 | (operating-system | |
1973 | ;; … | |
145df67b | 1974 | (packages (append (list sbcl stumpwm `(,stumpwm "lib")) |
65051fdc OP |
1975 | %base-packages))) |
1976 | @end lisp | |
1977 | ||
1978 | @cindex stumpwm fonts | |
1979 | By default StumpWM uses X11 fonts, which could be small or pixelated on | |
1980 | your system. You could fix this by installing StumpWM contrib Lisp | |
751d1f01 | 1981 | module @code{sbcl-ttf-fonts}, adding it to Guix system packages: |
65051fdc OP |
1982 | |
1983 | @lisp | |
1984 | (use-modules (gnu)) | |
1985 | (use-package-modules fonts wm) | |
1986 | ||
1987 | (operating-system | |
1988 | ;; … | |
145df67b | 1989 | (packages (append (list sbcl stumpwm `(,stumpwm "lib")) |
751d1f01 | 1990 | sbcl-ttf-fonts font-dejavu %base-packages))) |
65051fdc OP |
1991 | @end lisp |
1992 | ||
1993 | Then you need to add the following code to a StumpWM configuration file | |
1994 | @file{~/.stumpwm.d/init.lisp}: | |
1995 | ||
1996 | @lisp | |
1997 | (require :ttf-fonts) | |
1998 | (setf xft:*font-dirs* '("/run/current-system/profile/share/fonts/")) | |
1999 | (setf clx-truetype:+font-cache-filename+ (concat (getenv "HOME") "/.fonts/font-cache.sexp")) | |
2000 | (xft:cache-fonts) | |
2001 | (set-font (make-instance 'xft:font :family "DejaVu Sans Mono" :subfamily "Book" :size 11)) | |
2002 | @end lisp | |
2003 | ||
3142191d CB |
2004 | @node Session lock |
2005 | @subsection Session lock | |
2006 | @cindex sessionlock | |
2007 | ||
2008 | Depending on your environment, locking the screen of your session might come built in | |
2009 | or it might be something you have to set up yourself. If you use a desktop environment | |
2010 | like GNOME or KDE, it's usually built in. If you use a plain window manager like | |
2011 | StumpWM or EXWM, you might have to set it up yourself. | |
2012 | ||
2013 | @node Xorg | |
2014 | @subsubsection Xorg | |
2015 | ||
2016 | If you use Xorg, you can use the utility | |
2017 | @uref{https://www.mankier.com/1/xss-lock, xss-lock} to lock the screen of your session. | |
2018 | xss-lock is triggered by DPMS which since Xorg 1.8 is auto-detected and enabled if | |
2019 | ACPI is also enabled at kernel runtime. | |
2020 | ||
2021 | To use xss-lock, you can simple execute it and put it into the background before | |
2022 | you start your window manager from e.g. your @file{~/.xsession}: | |
2023 | ||
2024 | @example | |
2025 | xss-lock -- slock & | |
2026 | exec stumpwm | |
2027 | @end example | |
2028 | ||
2029 | In this example, xss-lock uses @code{slock} to do the actual locking of the screen when | |
2030 | it determines it's appropriate, like when you suspend your device. | |
2031 | ||
2032 | For slock to be allowed to be a screen locker for the graphical session, it needs to | |
2033 | be made setuid-root so it can authenticate users, and it needs a PAM service. This | |
2034 | can be achieved by adding the following service to your @file{config.scm}: | |
2035 | ||
2036 | @lisp | |
2037 | (screen-locker-service slock) | |
2038 | @end lisp | |
2039 | ||
2040 | If you manually lock your screen, e.g. by directly calling slock when you want to lock | |
2041 | your screen but not suspend it, it's a good idea to notify xss-lock about this so no | |
2042 | confusion occurs. This can be done by executing @code{xset s activate} immediately | |
2043 | before you execute slock. | |
2044 | ||
191e79da JB |
2045 | @node Running Guix on a Linode Server |
2046 | @section Running Guix on a Linode Server | |
2047 | @cindex linode, Linode | |
2048 | ||
2049 | To run Guix on a server hosted by @uref{https://www.linode.com, Linode}, | |
2050 | start with a recommended Debian server. We recommend using the default | |
2051 | distro as a way to bootstrap Guix. Create your SSH keys. | |
2052 | ||
2053 | @example | |
2054 | ssh-keygen | |
2055 | @end example | |
2056 | ||
2057 | Be sure to add your SSH key for easy login to the remote server. | |
2058 | This is trivially done via Linode's graphical interface for adding | |
2059 | SSH keys. Go to your profile and click add SSH Key. | |
2060 | Copy into it the output of: | |
2061 | ||
2062 | @example | |
2063 | cat ~/.ssh/<username>_rsa.pub | |
2064 | @end example | |
2065 | ||
de153970 GS |
2066 | Power the Linode down. |
2067 | ||
2068 | In the Linode's Storage tab, resize the Debian disk to be smaller. | |
2069 | 30 GB free space is recommended. Then click "Add a disk", and fill | |
2070 | out the form with the following: | |
191e79da | 2071 | |
191e79da JB |
2072 | @itemize @bullet |
2073 | @item | |
2074 | Label: "Guix" | |
2075 | ||
2076 | @item | |
2077 | Filesystem: ext4 | |
2078 | ||
2079 | @item | |
2080 | Set it to the remaining size | |
2081 | @end itemize | |
2082 | ||
de153970 GS |
2083 | In the Configurations tab, press "Edit" on the default Debian profile. |
2084 | Under "Block Device Assignment" click "Add a Device". It should be | |
2085 | @file{/dev/sdc} and you can select the "Guix" disk. Save Changes. | |
191e79da JB |
2086 | |
2087 | Now "Add a Configuration", with the following: | |
2088 | @itemize @bullet | |
2089 | @item | |
2090 | Label: Guix | |
2091 | ||
2092 | @item | |
2093 | Kernel:GRUB 2 (it's at the bottom! This step is @b{IMPORTANT!}) | |
2094 | ||
2095 | @item | |
2096 | Block device assignment: | |
2097 | ||
2098 | @item | |
2099 | @file{/dev/sda}: Guix | |
2100 | ||
2101 | @item | |
2102 | @file{/dev/sdb}: swap | |
2103 | ||
2104 | @item | |
2105 | Root device: @file{/dev/sda} | |
2106 | ||
2107 | @item | |
2108 | Turn off all the filesystem/boot helpers | |
2109 | @end itemize | |
2110 | ||
de153970 GS |
2111 | Now power it back up, booting with the Debian configuration. Once it's |
2112 | running, ssh to your server via @code{ssh | |
191e79da JB |
2113 | root@@@var{<your-server-IP-here>}}. (You can find your server IP address in |
2114 | your Linode Summary section.) Now you can run the "install guix from | |
2115 | @pxref{Binary Installation,,, guix, GNU Guix}" steps: | |
2116 | ||
2117 | @example | |
2118 | sudo apt-get install gpg | |
2119 | wget https://sv.gnu.org/people/viewgpg.php?user_id=15145 -qO - | gpg --import - | |
2120 | wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh | |
2121 | chmod +x guix-install.sh | |
2122 | ./guix-install.sh | |
2123 | guix pull | |
2124 | @end example | |
2125 | ||
2126 | Now it's time to write out a config for the server. The key information | |
2127 | is below. Save the resulting file as @file{guix-config.scm}. | |
2128 | ||
2129 | @lisp | |
2130 | (use-modules (gnu) | |
2131 | (guix modules)) | |
2132 | (use-service-modules networking | |
2133 | ssh) | |
2134 | (use-package-modules admin | |
2135 | certs | |
2136 | package-management | |
2137 | ssh | |
2138 | tls) | |
2139 | ||
2140 | (operating-system | |
2141 | (host-name "my-server") | |
2142 | (timezone "America/New_York") | |
2143 | (locale "en_US.UTF-8") | |
2144 | ;; This goofy code will generate the grub.cfg | |
2145 | ;; without installing the grub bootloader on disk. | |
2146 | (bootloader (bootloader-configuration | |
2147 | (bootloader | |
2148 | (bootloader | |
2149 | (inherit grub-bootloader) | |
34513683 | 2150 | (installer #~(const #true)))))) |
191e79da JB |
2151 | (file-systems (cons (file-system |
2152 | (device "/dev/sda") | |
2153 | (mount-point "/") | |
2154 | (type "ext4")) | |
2155 | %base-file-systems)) | |
2156 | ||
2157 | ||
2158 | (swap-devices (list "/dev/sdb")) | |
2159 | ||
2160 | ||
2161 | (initrd-modules (cons "virtio_scsi" ; Needed to find the disk | |
2162 | %base-initrd-modules)) | |
2163 | ||
2164 | (users (cons (user-account | |
2165 | (name "janedoe") | |
2166 | (group "users") | |
2167 | ;; Adding the account to the "wheel" group | |
2168 | ;; makes it a sudoer. | |
2169 | (supplementary-groups '("wheel")) | |
2170 | (home-directory "/home/janedoe")) | |
2171 | %base-user-accounts)) | |
2172 | ||
2173 | (packages (cons* nss-certs ;for HTTPS access | |
2174 | openssh-sans-x | |
2175 | %base-packages)) | |
2176 | ||
2177 | (services (cons* | |
2178 | (service dhcp-client-service-type) | |
2179 | (service openssh-service-type | |
2180 | (openssh-configuration | |
2181 | (openssh openssh-sans-x) | |
34513683 | 2182 | (password-authentication? #false) |
191e79da JB |
2183 | (authorized-keys |
2184 | `(("janedoe" ,(local-file "janedoe_rsa.pub")) | |
2185 | ("root" ,(local-file "janedoe_rsa.pub")))))) | |
2186 | %base-services))) | |
2187 | @end lisp | |
2188 | ||
2189 | Replace the following fields in the above configuration: | |
2190 | @lisp | |
2191 | (host-name "my-server") ; replace with your server name | |
2192 | ; if you chose a linode server outside the U.S., then | |
2193 | ; use tzselect to find a correct timezone string | |
2194 | (timezone "America/New_York") ; if needed replace timezone | |
2195 | (name "janedoe") ; replace with your username | |
2196 | ("janedoe" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key | |
2197 | ("root" ,(local-file "janedoe_rsa.pub")) ; replace with your ssh key | |
2198 | @end lisp | |
2199 | ||
2200 | The last line in the above example lets you log into the server as root | |
de153970 GS |
2201 | and set the initial root password (see the note at the end of this |
2202 | recipe about root login). After you have done this, you may | |
191e79da JB |
2203 | delete that line from your configuration and reconfigure to prevent root |
2204 | login. | |
2205 | ||
de153970 GS |
2206 | Copy your ssh public key (eg: @file{~/.ssh/id_rsa.pub}) as |
2207 | @file{@var{<your-username-here>}_rsa.pub} and put | |
191e79da JB |
2208 | @file{guix-config.scm} in the same directory. In a new terminal run |
2209 | these commands. | |
2210 | ||
2211 | @example | |
2212 | sftp root@@<remote server ip address> | |
de153970 GS |
2213 | put /path/to/files/<username>_rsa.pub . |
2214 | put /path/to/files/guix-config.scm . | |
191e79da JB |
2215 | @end example |
2216 | ||
2217 | In your first terminal, mount the guix drive: | |
2218 | ||
2219 | @example | |
2220 | mkdir /mnt/guix | |
2221 | mount /dev/sdc /mnt/guix | |
2222 | @end example | |
2223 | ||
de153970 GS |
2224 | Due to the way we set up the bootloader section of the guix-config.scm, |
2225 | only the grub configuration file will be installed. So, we need to copy | |
2226 | over some of the other GRUB stuff already installed on the Debian system: | |
191e79da JB |
2227 | |
2228 | @example | |
2229 | mkdir -p /mnt/guix/boot/grub | |
2230 | cp -r /boot/grub/* /mnt/guix/boot/grub/ | |
2231 | @end example | |
2232 | ||
2233 | Now initialize the Guix installation: | |
2234 | ||
2235 | @example | |
2236 | guix system init guix-config.scm /mnt/guix | |
2237 | @end example | |
2238 | ||
2239 | Ok, power it down! | |
2240 | Now from the Linode console, select boot and select "Guix". | |
2241 | ||
2242 | Once it boots, you should be able to log in via SSH! (The server config | |
2243 | will have changed though.) You may encounter an error like: | |
2244 | ||
2245 | @example | |
2246 | $ ssh root@@<server ip address> | |
2247 | @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ | |
2248 | @ WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! @ | |
2249 | @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ | |
2250 | IT IS POSSIBLE THAT SOMEONE IS DOING SOMETHING NASTY! | |
2251 | Someone could be eavesdropping on you right now (man-in-the-middle attack)! | |
2252 | It is also possible that a host key has just been changed. | |
2253 | The fingerprint for the ECDSA key sent by the remote host is | |
2254 | SHA256:0B+wp33w57AnKQuHCvQP0+ZdKaqYrI/kyU7CfVbS7R4. | |
2255 | Please contact your system administrator. | |
2256 | Add correct host key in /home/joshua/.ssh/known_hosts to get rid of this message. | |
2257 | Offending ECDSA key in /home/joshua/.ssh/known_hosts:3 | |
2258 | ECDSA host key for 198.58.98.76 has changed and you have requested strict checking. | |
2259 | Host key verification failed. | |
2260 | @end example | |
2261 | ||
2262 | Either delete @file{~/.ssh/known_hosts} file, or delete the offending line | |
2263 | starting with your server IP address. | |
2264 | ||
2265 | Be sure to set your password and root's password. | |
2266 | ||
2267 | @example | |
2268 | ssh root@@<remote ip address> | |
2269 | passwd ; for the root password | |
2270 | passwd <username> ; for the user password | |
2271 | @end example | |
2272 | ||
2273 | You may not be able to run the above commands at this point. If you | |
2274 | have issues remotely logging into your linode box via SSH, then you may | |
2275 | still need to set your root and user password initially by clicking on | |
2276 | the ``Launch Console'' option in your linode. Choose the ``Glish'' | |
2277 | instead of ``Weblish''. Now you should be able to ssh into the machine. | |
2278 | ||
de153970 | 2279 | Hooray! At this point you can shut down the server, delete the |
191e79da JB |
2280 | Debian disk, and resize the Guix to the rest of the size. |
2281 | Congratulations! | |
2282 | ||
2283 | By the way, if you save it as a disk image right at this point, you'll | |
2284 | have an easy time spinning up new Guix images! You may need to | |
2285 | down-size the Guix image to 6144MB, to save it as an image. Then you | |
2286 | can resize it again to the max size. | |
2287 | ||
60651dd9 MB |
2288 | @node Setting up a bind mount |
2289 | @section Setting up a bind mount | |
2290 | ||
2291 | To bind mount a file system, one must first set up some definitions | |
cc765e47 | 2292 | before the @code{operating-system} section of the system definition. In |
60651dd9 | 2293 | this example we will bind mount a folder from a spinning disk drive to |
2c8305d1 NG |
2294 | @file{/tmp}, to save wear and tear on the primary SSD, without |
2295 | dedicating an entire partition to be mounted as @file{/tmp}. | |
60651dd9 MB |
2296 | |
2297 | First, the source drive that hosts the folder we wish to bind mount | |
2298 | should be defined, so that the bind mount can depend on it. | |
2299 | ||
2300 | @lisp | |
2301 | (define source-drive ;; "source-drive" can be named anything you want. | |
2302 | (file-system | |
2303 | (device (uuid "UUID goes here")) | |
2304 | (mount-point "/path-to-spinning-disk-goes-here") | |
2305 | (type "ext4"))) ;; Make sure to set this to the appropriate type for your drive. | |
2306 | @end lisp | |
2307 | ||
2308 | The source folder must also be defined, so that guix will know it's not | |
2309 | a regular block device, but a folder. | |
2310 | @lisp | |
2311 | (define (%source-directory) "/path-to-spinning-disk-goes-here/tmp") ;; "source-directory" can be named any valid variable name. | |
2312 | @end lisp | |
2313 | ||
2314 | Finally, inside the @code{file-systems} definition, we must add the | |
2315 | mount itself. | |
2316 | ||
2317 | @lisp | |
2318 | (file-systems (cons* | |
2319 | ||
2320 | ...<other drives omitted for clarity>... | |
2321 | ||
2322 | source-drive ;; Must match the name you gave the source drive in the earlier definition. | |
2323 | ||
2324 | (file-system | |
2325 | (device (%source-directory)) ;; Make sure "source-directory" matches your earlier definition. | |
2326 | (mount-point "/tmp") | |
2327 | (type "none") ;; We are mounting a folder, not a partition, so this type needs to be "none" | |
2328 | (flags '(bind-mount)) | |
2329 | (dependencies (list source-drive)) ;; Ensure "source-drive" matches what you've named the variable for the drive. | |
2330 | ) | |
2331 | ||
2332 | ...<other drives omitted for clarity>... | |
2333 | ||
2334 | )) | |
2335 | @end lisp | |
2336 | ||
c987b723 BW |
2337 | @node Getting substitutes from Tor |
2338 | @section Getting substitutes from Tor | |
2339 | ||
2340 | Guix daemon can use a HTTP proxy to get substitutes, here we are | |
2341 | configuring it to get them via Tor. | |
2342 | ||
2343 | @quotation Warning | |
2344 | @emph{Not all} Guix daemon's traffic will go through Tor! Only | |
2345 | HTTP/HTTPS will get proxied; FTP, Git protocol, SSH, etc connections | |
2346 | will still go through the clearnet. Again, this configuration isn't | |
2347 | foolproof some of your traffic won't get routed by Tor at all. Use it | |
2348 | at your own risk. | |
f8945734 AB |
2349 | |
2350 | Also note that the procedure described here applies only to package | |
2351 | substitution. When you update your guix distribution with | |
2352 | @command{guix pull}, you still need to use @command{torsocks} if | |
2353 | you want to route the connection to guix's git repository servers | |
2354 | through Tor. | |
c987b723 BW |
2355 | @end quotation |
2356 | ||
2357 | Guix's substitute server is available as a Onion service, if you want | |
f8945734 | 2358 | to use it to get your substitutes through Tor configure your system as |
c987b723 BW |
2359 | follow: |
2360 | ||
2361 | @lisp | |
2362 | (use-modules (gnu)) | |
2363 | (use-service-module base networking) | |
2364 | ||
2365 | (operating-system | |
2366 | … | |
2367 | (services | |
2368 | (cons | |
2369 | (service tor-service-type | |
2370 | (tor-configuration | |
2371 | (config-file (plain-file "tor-config" | |
2372 | "HTTPTunnelPort 127.0.0.1:9250")))) | |
2373 | (modify-services %base-services | |
2374 | (guix-service-type | |
2375 | config => (guix-configuration | |
2376 | (inherit config) | |
2377 | ;; ci.guix.gnu.org's Onion service | |
27c273ec LC |
2378 | (substitute-urls |
2379 | "@value{SUBSTITUTE-TOR-URL}") | |
c987b723 BW |
2380 | (http-proxy "http://localhost:9250"))))))) |
2381 | @end lisp | |
2382 | ||
2383 | This will keep a tor process running that provides a HTTP CONNECT tunnel | |
2384 | which will be used by @command{guix-daemon}. The daemon can use other | |
2385 | protocols than HTTP(S) to get remote resources, request using those | |
2386 | protocols won't go through Tor since we are only setting a HTTP tunnel | |
2387 | here. Note that @code{substitutes-urls} is using HTTPS and not HTTP or | |
2388 | it won't work, that's a limitation of Tor's tunnel; you may want to use | |
2389 | @command{privoxy} instead to avoid such limitations. | |
2390 | ||
2391 | If you don't want to always get substitutes through Tor but using it just | |
2392 | some of the times, then skip the @code{guix-configuration}. When you | |
2393 | want to get a substitute from the Tor tunnel run: | |
2394 | ||
2395 | @example | |
2396 | sudo herd set-http-proxy guix-daemon http://localhost:9250 | |
27c273ec LC |
2397 | guix build \ |
2398 | --substitute-urls=@value{SUBSTITUTE-TOR-URL} @dots{} | |
c987b723 BW |
2399 | @end example |
2400 | ||
00014f76 OP |
2401 | @node Setting up NGINX with Lua |
2402 | @section Setting up NGINX with Lua | |
2403 | @cindex nginx, lua, openresty, resty | |
2404 | ||
2405 | NGINX could be extended with Lua scripts. | |
2406 | ||
2407 | Guix provides NGINX service with ability to load Lua module and specific | |
2408 | Lua packages, and reply to requests by evaluating Lua scripts. | |
2409 | ||
2410 | The following example demonstrates system definition with configuration | |
2411 | to evaluate @file{index.lua} Lua script on HTTP request to | |
2412 | @uref{http://localhost/hello} endpoint: | |
2413 | ||
2414 | @example | |
2415 | local shell = require "resty.shell" | |
2416 | ||
2417 | local stdin = "" | |
2418 | local timeout = 1000 -- ms | |
2419 | local max_size = 4096 -- byte | |
2420 | ||
2421 | local ok, stdout, stderr, reason, status = | |
2422 | shell.run([[/run/current-system/profile/bin/ls /tmp]], stdin, timeout, max_size) | |
2423 | ||
2424 | ngx.say(stdout) | |
2425 | @end example | |
2426 | ||
2427 | @lisp | |
2428 | (use-modules (gnu)) | |
2429 | (use-service-modules #;… web) | |
2430 | (use-package-modules #;… lua) | |
2431 | (operating-system | |
2432 | ;; … | |
2433 | (services | |
2434 | ;; … | |
2435 | (service nginx-service-type | |
2436 | (nginx-configuration | |
2437 | (modules | |
2438 | (list | |
2439 | (file-append nginx-lua-module "/etc/nginx/modules/ngx_http_lua_module.so"))) | |
2440 | (lua-package-path (list lua-resty-core | |
2441 | lua-resty-lrucache | |
2442 | lua-resty-signal | |
2443 | lua-tablepool | |
2444 | lua-resty-shell)) | |
2445 | (lua-package-cpath (list lua-resty-signal)) | |
2446 | (server-blocks | |
2447 | (list (nginx-server-configuration | |
2448 | (server-name '("localhost")) | |
2449 | (listen '("80")) | |
2450 | (root "/etc") | |
2451 | (locations (list | |
2452 | (nginx-location-configuration | |
2453 | (uri "/hello") | |
2454 | (body (list #~(format #f "content_by_lua_file ~s;" | |
2455 | #$(local-file "index.lua")))))))))))))) | |
2456 | @end lisp | |
2457 | ||
56915dc2 RW |
2458 | @c ********************************************************************* |
2459 | @node Containers | |
2460 | @chapter Containers | |
2461 | ||
2462 | The kernel Linux provides a number of shared facilities that are | |
2463 | available to processes in the system. These facilities include a shared | |
2464 | view on the file system, other processes, network devices, user and | |
2465 | group identities, and a few others. Since Linux 3.19 a user can choose | |
2466 | to @emph{unshare} some of these shared facilities for selected | |
2467 | processes, providing them (and their child processes) with a different | |
2468 | view on the system. | |
2469 | ||
2470 | A process with an unshared @code{mount} namespace, for example, has its | |
2471 | own view on the file system --- it will only be able to see directories | |
2472 | that have been explicitly bound in its mount namespace. A process with | |
2473 | its own @code{proc} namespace will consider itself to be the only | |
2474 | process running on the system, running as PID 1. | |
2475 | ||
2476 | Guix uses these kernel features to provide fully isolated environments | |
2477 | and even complete Guix System containers, lightweight virtual machines | |
2478 | that share the host system's kernel. This feature comes in especially | |
2479 | handy when using Guix on a foreign distribution to prevent interference | |
2480 | from foreign libraries or configuration files that are available | |
2481 | system-wide. | |
2482 | ||
2483 | @menu | |
2484 | * Guix Containers:: Perfectly isolated environments | |
2485 | * Guix System Containers:: A system inside your system | |
2486 | @end menu | |
2487 | ||
2488 | @node Guix Containers | |
2489 | @section Guix Containers | |
2490 | ||
2491 | The easiest way to get started is to use @command{guix shell} with the | |
2492 | @option{--container} option. @xref{Invoking guix shell,,, guix, GNU | |
2493 | Guix Reference Manual} for a reference of valid options. | |
2494 | ||
2495 | The following snippet spawns a minimal shell process with most | |
2496 | namespaces unshared from the system. The current working directory is | |
2497 | visible to the process, but anything else on the file system is | |
2498 | unavailable. This extreme isolation can be very useful when you want to | |
2499 | rule out any sort of interference from environment variables, globally | |
2500 | installed libraries, or configuration files. | |
2501 | ||
2502 | @example | |
2503 | guix shell --container | |
2504 | @end example | |
2505 | ||
2506 | It is a bleak environment, barren, desolate. You will find that not | |
2507 | even the GNU coreutils are available here, so to explore this deserted | |
2508 | wasteland you need to use built-in shell commands. Even the usually | |
2509 | gigantic @file{/gnu/store} directory is reduced to a faint shadow of | |
2510 | itself. | |
2511 | ||
2512 | @example sh | |
2513 | $ echo /gnu/store/* | |
2514 | /gnu/store/@dots{}-gcc-10.3.0-lib | |
2515 | /gnu/store/@dots{}-glibc-2.33 | |
2516 | /gnu/store/@dots{}-bash-static-5.1.8 | |
2517 | /gnu/store/@dots{}-ncurses-6.2.20210619 | |
2518 | /gnu/store/@dots{}-bash-5.1.8 | |
2519 | /gnu/store/@dots{}-profile | |
2520 | /gnu/store/@dots{}-readline-8.1.1 | |
2521 | @end example | |
2522 | ||
2523 | @cindex exiting a container | |
2524 | There isn't much you can do in an environment like this other than | |
2525 | exiting it. You can use @key{^D} or @command{exit} to terminate this | |
2526 | limited shell environment. | |
2527 | ||
2528 | @cindex exposing directories, container | |
2529 | @cindex sharing directories, container | |
2530 | @cindex mapping locations, container | |
2531 | You can make other directories available inside of the container | |
2532 | environment; use @option{--expose=DIRECTORY} to bind-mount the given | |
2533 | directory as a read-only location inside the container, or use | |
2534 | @option{--share=DIRECTORY} to make the location writable. With an | |
2535 | additional mapping argument after the directory name you can control the | |
2536 | name of the directory inside the container. In the following example we | |
2537 | map @file{/etc} on the host system to @file{/the/host/etc} inside a | |
2538 | container in which the GNU coreutils are installed. | |
2539 | ||
2540 | @example sh | |
2541 | $ guix shell --container --share=/etc=/the/host/etc coreutils | |
2542 | $ ls /the/host/etc | |
2543 | @end example | |
2544 | ||
2545 | Similarly, you can prevent the current working directory from being | |
2546 | mapped into the container with the @option{--no-cwd} option. Another | |
2547 | good idea is to create a dedicated directory that will serve as the | |
2548 | container's home directory, and spawn the container shell from that | |
2549 | directory. | |
2550 | ||
2551 | @cindex hide system libraries, container | |
2552 | @cindex avoid ABI mismatch, container | |
2553 | On a foreign system a container environment can be used to compile | |
2554 | software that cannot possibly be linked with system libraries or with | |
2555 | the system's compiler toolchain. A common use-case in a research | |
2556 | context is to install packages from within an R session. Outside of a | |
2557 | container environment there is a good chance that the foreign compiler | |
2558 | toolchain and incompatible system libraries are found first, resulting | |
2559 | in incompatible binaries that cannot be used by R. In a container shell | |
2560 | this problem disappears, as system libraries and executables simply | |
2561 | aren't available due to the unshared @code{mount} namespace. | |
2562 | ||
2563 | Let's take a comprehensive manifest providing a comfortable development | |
2564 | environment for use with R: | |
2565 | ||
2566 | @lisp | |
2567 | (specifications->manifest | |
2568 | (list "r-minimal" | |
2569 | ||
2570 | ;; base packages | |
2571 | "bash-minimal" | |
2572 | "glibc-locales" | |
2573 | "nss-certs" | |
2574 | ||
2575 | ;; Common command line tools lest the container is too empty. | |
2576 | "coreutils" | |
2577 | "grep" | |
2578 | "which" | |
2579 | "wget" | |
2580 | "sed" | |
2581 | ||
2582 | ;; R markdown tools | |
2583 | "pandoc" | |
2584 | ||
2585 | ;; Toolchain and common libraries for "install.packages" | |
2586 | "gcc-toolchain@@10" | |
2587 | "gfortran-toolchain" | |
2588 | "gawk" | |
2589 | "tar" | |
2590 | "gzip" | |
2591 | "unzip" | |
2592 | "make" | |
2593 | "cmake" | |
2594 | "pkg-config" | |
2595 | "cairo" | |
2596 | "libxt" | |
2597 | "openssl" | |
2598 | "curl" | |
2599 | "zlib")) | |
2600 | @end lisp | |
2601 | ||
2602 | Let's use this to run R inside a container environment. For convenience | |
2603 | we share the @code{net} namespace to use the host system's network | |
2604 | interfaces. Now we can build R packages from source the traditional way | |
2605 | without having to worry about ABI mismatch or incompatibilities. | |
2606 | ||
2607 | @example sh | |
2608 | $ guix shell --container --network --manifest=manifest.scm -- R | |
2609 | ||
2610 | R version 4.2.1 (2022-06-23) -- "Funny-Looking Kid" | |
2611 | Copyright (C) 2022 The R Foundation for Statistical Computing | |
2612 | @dots{} | |
2613 | > e <- Sys.getenv("GUIX_ENVIRONMENT") | |
2614 | > Sys.setenv(GIT_SSL_CAINFO=paste0(e, "/etc/ssl/certs/ca-certificates.crt")) | |
2615 | > Sys.setenv(SSL_CERT_FILE=paste0(e, "/etc/ssl/certs/ca-certificates.crt")) | |
2616 | > Sys.setenv(SSL_CERT_DIR=paste0(e, "/etc/ssl/certs")) | |
2617 | > install.packages("Cairo", lib=paste0(getwd())) | |
2618 | @dots{} | |
2619 | * installing *source* package 'Cairo' ... | |
2620 | @dots{} | |
2621 | * DONE (Cairo) | |
2622 | ||
2623 | The downloaded source packages are in | |
2624 | '/tmp/RtmpCuwdwM/downloaded_packages' | |
2625 | > library("Cairo", lib=getwd()) | |
2626 | > # success! | |
2627 | @end example | |
2628 | ||
2629 | Using container shells is fun, but they can become a little cumbersome | |
2630 | when you want to go beyond just a single interactive process. Some | |
2631 | tasks become a lot easier when they sit on the rock solid foundation of | |
2632 | a proper Guix System and its rich set of system services. The next | |
2633 | section shows you how to launch a complete Guix System inside of a | |
2634 | container. | |
2635 | ||
2636 | ||
2637 | @node Guix System Containers | |
2638 | @section Guix System Containers | |
2639 | ||
2640 | The Guix System provides a wide array of interconnected system services | |
2641 | that are configured declaratively to form a dependable stateless GNU | |
2642 | System foundation for whatever tasks you throw at it. Even when using | |
2643 | Guix on a foreign distribution you can benefit from the design of Guix | |
2644 | System by running a system instance as a container. Using the same | |
2645 | kernel features of unshared namespaces mentioned in the previous | |
2646 | section, the resulting Guix System instance is isolated from the host | |
2647 | system and only shares file system locations that you explicitly | |
2648 | declare. | |
2649 | ||
2650 | A Guix System container differs from the shell process created by | |
2651 | @command{guix shell --container} in a number of important ways. While | |
2652 | in a container shell the containerized process is a Bash shell process, | |
2653 | a Guix System container runs the Shepherd as PID 1. In a system | |
2654 | container all system services (@pxref{Services,,, guix, GNU Guix | |
2655 | Reference Manual}) are set up just as they would be on a Guix System in | |
2656 | a virtual machine or on bare metal---this includes daemons managed by | |
2657 | the GNU@tie{}Shepherd (@pxref{Shepherd Services,,, guix, GNU Guix | |
2658 | Reference Manual}) as well as other kinds of extensions to the operating | |
2659 | system (@pxref{Service Composition,,, guix, GNU Guix Reference Manual}). | |
2660 | ||
2661 | The perceived increase in complexity of running a Guix System container | |
2662 | is easily justified when dealing with more complex applications that | |
2663 | have higher or just more rigid requirements on their execution | |
2664 | contexts---configuration files, dedicated user accounts, directories for | |
2665 | caches or log files, etc. In Guix System the demands of this kind of | |
2666 | software are satisfied through the deployment of system services. | |
2667 | ||
2668 | ||
2669 | @node A Database Container | |
2670 | @subsection A Database Container | |
2671 | ||
2672 | A good example might be a PostgreSQL database server. Much of the | |
2673 | complexity of setting up such a database server is encapsulated in this | |
2674 | deceptively short service declaration: | |
2675 | ||
2676 | @lisp | |
2677 | (service postgresql-service-type | |
2678 | (postgresql-configuration | |
2679 | (postgresql postgresql-14))) | |
2680 | @end lisp | |
2681 | ||
2682 | A complete operating system declaration for use with a Guix System | |
2683 | container would look something like this: | |
2684 | ||
2685 | @lisp | |
2686 | (use-modules (gnu)) | |
2687 | (use-package-modules databases) | |
2688 | (use-service-modules databases) | |
2689 | ||
2690 | (operating-system | |
2691 | (host-name "container") | |
2692 | (timezone "Europe/Berlin") | |
2693 | (file-systems (cons (file-system | |
2694 | (device (file-system-label "does-not-matter")) | |
2695 | (mount-point "/") | |
2696 | (type "ext4")) | |
2697 | %base-file-systems)) | |
2698 | (bootloader (bootloader-configuration | |
2699 | (bootloader grub-bootloader) | |
2700 | (targets '("/dev/sdX")))) | |
2701 | (services | |
2702 | (cons* (service postgresql-service-type | |
2703 | (postgresql-configuration | |
2704 | (postgresql postgresql-14) | |
2705 | (config-file | |
2706 | (postgresql-config-file | |
2707 | (log-destination "stderr") | |
2708 | (hba-file | |
2709 | (plain-file "pg_hba.conf" | |
2710 | "\ | |
2711 | local all all trust | |
2712 | host all all 10.0.0.1/32 trust")) | |
2713 | (extra-config | |
2714 | '(("listen_addresses" "*") | |
2715 | ("log_directory" "/var/log/postgresql"))))))) | |
2716 | (service postgresql-role-service-type | |
2717 | (postgresql-role-configuration | |
2718 | (roles | |
2719 | (list (postgresql-role | |
2720 | (name "test") | |
2721 | (create-database? #t)))))) | |
2722 | %base-services))) | |
2723 | @end lisp | |
2724 | ||
2725 | With @code{postgresql-role-service-type} we define a role ``test'' and | |
2726 | create a matching database, so that we can test right away without any | |
2727 | further manual setup. The @code{postgresql-config-file} settings allow | |
2728 | a client from IP address 10.0.0.1 to connect without requiring | |
2729 | authentication---a bad idea in production systems, but convenient for | |
2730 | this example. | |
2731 | ||
2732 | Let's build a script that will launch an instance of this Guix System as | |
2733 | a container. Write the @code{operating-system} declaration above to a | |
2734 | file @file{os.scm} and then use @command{guix system container} to build | |
2735 | the launcher. (@pxref{Invoking guix system,,, guix, GNU Guix Reference | |
2736 | Manual}). | |
2737 | ||
2738 | @example | |
2739 | $ guix system container os.scm | |
2740 | The following derivations will be built: | |
2741 | /gnu/store/@dots{}-run-container.drv | |
2742 | @dots{} | |
2743 | building /gnu/store/@dots{}-run-container.drv... | |
2744 | /gnu/store/@dots{}-run-container | |
2745 | @end example | |
2746 | ||
2747 | Now that we have a launcher script we can run it to spawn the new system | |
2748 | with a running PostgreSQL service. Note that due to some as yet | |
2749 | unresolved limitations we need to run the launcher as the root user, for | |
2750 | example with @command{sudo}. | |
2751 | ||
2752 | @example | |
2753 | $ sudo /gnu/store/@dots{}-run-container | |
2754 | system container is running as PID 5983 | |
2755 | @dots{} | |
2756 | @end example | |
2757 | ||
2758 | Background the process with @key{Ctrl-z} followed by @command{bg}. Note | |
2759 | the process ID in the output; we will need it to connect to the | |
2760 | container later. You know what? Let's try attaching to the container | |
2761 | right now. We will use @command{nsenter}, a tool provided by the | |
2762 | @code{util-linux} package: | |
2763 | ||
2764 | @example | |
2765 | $ guix shell util-linux | |
2766 | $ sudo nsenter -a -t 5983 | |
2767 | root@@container /# pgrep -a postgres | |
2768 | 49 /gnu/store/@dots{}-postgresql-14.4/bin/postgres -D /var/lib/postgresql/data --config-file=/gnu/store/@dots{}-postgresql.conf -p 5432 | |
2769 | 51 postgres: checkpointer | |
2770 | 52 postgres: background writer | |
2771 | 53 postgres: walwriter | |
2772 | 54 postgres: autovacuum launcher | |
2773 | 55 postgres: stats collector | |
2774 | 56 postgres: logical replication launcher | |
2775 | root@@container /# exit | |
2776 | @end example | |
2777 | ||
2778 | The PostgreSQL service is running in the container! | |
2779 | ||
2780 | ||
2781 | @node Container Networking | |
2782 | @subsection Container Networking | |
2783 | @cindex container networking | |
2784 | ||
2785 | What good is a Guix System running a PostgreSQL database service as a | |
2786 | container when we can only talk to it with processes originating in the | |
2787 | container? It would be much better if we could talk to the database | |
2788 | over the network. | |
2789 | ||
2790 | The easiest way to do this is to create a pair of connected virtual | |
2791 | Ethernet devices (known as @code{veth}). We move one of the devices | |
2792 | (@code{ceth-test}) into the @code{net} namespace of the container and | |
2793 | leave the other end (@code{veth-test}) of the connection on the host | |
2794 | system. | |
2795 | ||
2796 | @example | |
2797 | pid=5983 | |
2798 | ns="guix-test" | |
2799 | host="veth-test" | |
2800 | client="ceth-test" | |
2801 | ||
2802 | # Attach the new net namespace "guix-test" to the container PID. | |
2803 | sudo ip netns attach $ns $pid | |
2804 | ||
2805 | # Create the pair of devices | |
2806 | sudo ip link add $host type veth peer name $client | |
2807 | ||
2808 | # Move the client device into the container's net namespace | |
2809 | sudo ip link set $client netns $ns | |
2810 | @end example | |
2811 | ||
2812 | Then we configure the host side: | |
2813 | ||
2814 | @example | |
2815 | sudo ip link set $host up | |
2816 | sudo ip addr add 10.0.0.1/24 dev $host | |
2817 | @end example | |
2818 | ||
2819 | @dots{}and then we configure the client side: | |
2820 | ||
2821 | @example | |
2822 | sudo ip netns exec $ns ip link set lo up | |
2823 | sudo ip netns exec $ns ip link set $client up | |
2824 | sudo ip netns exec $ns ip addr add 10.0.0.2/24 dev $client | |
2825 | @end example | |
2826 | ||
2827 | At this point the host can reach the container at IP address 10.0.0.2, | |
2828 | and the container can reach the host at IP 10.0.0.1. This is all we | |
2829 | need to talk to the database server inside the container from the host | |
2830 | system on the outside. | |
2831 | ||
2832 | @example | |
2833 | $ psql -h 10.0.0.2 -U test | |
2834 | psql (14.4) | |
2835 | Type "help" for help. | |
2836 | ||
2837 | test=> CREATE TABLE hello (who TEXT NOT NULL); | |
2838 | CREATE TABLE | |
2839 | test=> INSERT INTO hello (who) VALUES ('world'); | |
2840 | INSERT 0 1 | |
2841 | test=> SELECT * FROM hello; | |
2842 | who | |
2843 | ------- | |
2844 | world | |
2845 | (1 row) | |
2846 | @end example | |
2847 | ||
2848 | Now that we're done with this little demonstration let's clean up: | |
2849 | ||
2850 | @example | |
2851 | sudo kill $pid | |
2852 | sudo ip netns del $ns | |
2853 | sudo ip link del $host | |
2854 | @end example | |
2855 | ||
2856 | ||
4c463569 PN |
2857 | @c ********************************************************************* |
2858 | @node Advanced package management | |
2859 | @chapter Advanced package management | |
2860 | ||
2861 | Guix is a functional package manager that offers many features beyond | |
2862 | what more traditional package managers can do. To the uninitiated, | |
2863 | those features might not have obvious use cases at first. The purpose | |
2864 | of this chapter is to demonstrate some advanced package management | |
2865 | concepts. | |
2866 | ||
2867 | @pxref{Package Management,,, guix, GNU Guix Reference Manual} for a complete | |
2868 | reference. | |
2869 | ||
2870 | @menu | |
2871 | * Guix Profiles in Practice:: Strategies for multiple profiles and manifests. | |
2872 | @end menu | |
2873 | ||
2874 | @node Guix Profiles in Practice | |
2875 | @section Guix Profiles in Practice | |
2876 | ||
2877 | Guix provides a very useful feature that may be quite foreign to newcomers: | |
2878 | @emph{profiles}. They are a way to group package installations together and all users | |
f6c27c55 | 2879 | on the same system are free to use as many profiles as they want. |
4c463569 PN |
2880 | |
2881 | Whether you're a developer or not, you may find that multiple profiles bring you | |
2882 | great power and flexibility. While they shift the paradigm somewhat compared to | |
2883 | @emph{traditional package managers}, they are very convenient to use once you've | |
2884 | understood how to set them up. | |
2885 | ||
2886 | If you are familiar with Python's @samp{virtualenv}, you can think of a profile as a | |
2887 | kind of universal @samp{virtualenv} that can hold any kind of software whatsoever, not | |
2888 | just Python software. Furthermore, profiles are self-sufficient: they capture | |
2889 | all the runtime dependencies which guarantees that all programs within a profile | |
2890 | will always work at any point in time. | |
2891 | ||
2892 | Multiple profiles have many benefits: | |
2893 | ||
2894 | @itemize | |
2895 | @item | |
2896 | Clean semantic separation of the various packages a user needs for different contexts. | |
2897 | ||
2898 | @item | |
2899 | Multiple profiles can be made available into the environment either on login | |
2900 | or within a dedicated shell. | |
2901 | ||
2902 | @item | |
2903 | Profiles can be loaded on demand. For instance, the user can use multiple | |
2904 | shells, each of them running different profiles. | |
2905 | ||
2906 | @item | |
2907 | Isolation: Programs from one profile will not use programs from the other, and | |
f6c27c55 | 2908 | the user can even install different versions of the same programs to the two |
4c463569 PN |
2909 | profiles without conflict. |
2910 | ||
2911 | @item | |
2912 | Deduplication: Profiles share dependencies that happens to be the exact same. | |
2913 | This makes multiple profiles storage-efficient. | |
2914 | ||
2915 | @item | |
2916 | Reproducible: when used with declarative manifests, a profile can be fully | |
2917 | specified by the Guix commit that was active when it was set up. This means | |
f6c27c55 PN |
2918 | that the exact same profile can be |
2919 | @uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-rollbacks-oh-my/, | |
2920 | set up anywhere and anytime}, with just the commit information. See the | |
2921 | section on @ref{Reproducible profiles}. | |
4c463569 PN |
2922 | |
2923 | @item | |
2924 | Easier upgrades and maintenance: Multiple profiles make it easy to keep | |
af67e8d0 | 2925 | package listings at hand and make upgrades completely frictionless. |
4c463569 PN |
2926 | @end itemize |
2927 | ||
2928 | Concretely, here follows some typical profiles: | |
2929 | ||
2930 | @itemize | |
2931 | @item | |
2932 | The dependencies of a project you are working on. | |
2933 | ||
2934 | @item | |
2935 | Your favourite programming language libraries. | |
2936 | ||
2937 | @item | |
2938 | Laptop-specific programs (like @samp{powertop}) that you don't need on a desktop. | |
2939 | ||
2940 | @item | |
2941 | @TeX{}live (this one can be really useful when you need to install just one | |
2942 | package for this one document you've just received over email). | |
2943 | ||
2944 | @item | |
2945 | Games. | |
2946 | @end itemize | |
2947 | ||
2948 | Let's dive in the set up! | |
2949 | ||
2950 | @node Basic setup with manifests | |
2951 | @subsection Basic setup with manifests | |
2952 | ||
582b4bb4 LC |
2953 | A Guix profile can be set up @i{via} a @dfn{manifest}. A manifest is a |
2954 | snippet of Scheme code that specifies the set of packages you want to | |
2955 | have in your profile; it looks like this: | |
4c463569 | 2956 | |
b1eecb5c | 2957 | @lisp |
4c463569 PN |
2958 | (specifications->manifest |
2959 | '("package-1" | |
2960 | ;; Version 1.3 of package-2. | |
2961 | "package-2@@1.3" | |
2962 | ;; The "lib" output of package-3. | |
2963 | "package-3:lib" | |
2964 | ; ... | |
2965 | "package-N")) | |
b1eecb5c | 2966 | @end lisp |
4c463569 | 2967 | |
582b4bb4 LC |
2968 | @xref{Writing Manifests,,, guix, GNU Guix Reference Manual}, for |
2969 | more information about the syntax. | |
4c463569 PN |
2970 | |
2971 | We can create a manifest specification per profile and install them this way: | |
2972 | ||
2973 | @example | |
2974 | GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles | |
2975 | mkdir -p "$GUIX_EXTRA_PROFILES"/my-project # if it does not exist yet | |
2976 | guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project | |
2977 | @end example | |
2978 | ||
2979 | Here we set an arbitrary variable @samp{GUIX_EXTRA_PROFILES} to point to the directory | |
2980 | where we will store our profiles in the rest of this article. | |
2981 | ||
2982 | Placing all your profiles in a single directory, with each profile getting its | |
2983 | own sub-directory, is somewhat cleaner. This way, each sub-directory will | |
128b136e NG |
2984 | contain all the symlinks for precisely one profile. Besides, ``looping over |
2985 | profiles'' becomes obvious from any programming language (e.g.@: a shell script) by | |
4c463569 PN |
2986 | simply looping over the sub-directories of @samp{$GUIX_EXTRA_PROFILES}. |
2987 | ||
2988 | Note that it's also possible to loop over the output of | |
2989 | ||
2990 | @example | |
2991 | guix package --list-profiles | |
2992 | @end example | |
2993 | ||
2c8305d1 | 2994 | although you'll probably have to filter out @file{~/.config/guix/current}. |
4c463569 | 2995 | |
2c8305d1 | 2996 | To enable all profiles on login, add this to your @file{~/.bash_profile} (or similar): |
4c463569 PN |
2997 | |
2998 | @example | |
2999 | for i in $GUIX_EXTRA_PROFILES/*; do | |
3000 | profile=$i/$(basename "$i") | |
3001 | if [ -f "$profile"/etc/profile ]; then | |
3002 | GUIX_PROFILE="$profile" | |
3003 | . "$GUIX_PROFILE"/etc/profile | |
3004 | fi | |
3005 | unset profile | |
3006 | done | |
3007 | @end example | |
3008 | ||
3009 | Note to Guix System users: the above reflects how your default profile | |
2c8305d1 NG |
3010 | @file{~/.guix-profile} is activated from @file{/etc/profile}, that latter being loaded by |
3011 | @file{~/.bashrc} by default. | |
4c463569 PN |
3012 | |
3013 | You can obviously choose to only enable a subset of them: | |
3014 | ||
3015 | @example | |
3016 | for i in "$GUIX_EXTRA_PROFILES"/my-project-1 "$GUIX_EXTRA_PROFILES"/my-project-2; do | |
3017 | profile=$i/$(basename "$i") | |
3018 | if [ -f "$profile"/etc/profile ]; then | |
3019 | GUIX_PROFILE="$profile" | |
3020 | . "$GUIX_PROFILE"/etc/profile | |
3021 | fi | |
3022 | unset profile | |
3023 | done | |
3024 | @end example | |
3025 | ||
3026 | When a profile is off, it's straightforward to enable it for an individual shell | |
3027 | without "polluting" the rest of the user session: | |
3028 | ||
3029 | @example | |
3030 | GUIX_PROFILE="path/to/my-project" ; . "$GUIX_PROFILE"/etc/profile | |
3031 | @end example | |
3032 | ||
3033 | The key to enabling a profile is to @emph{source} its @samp{etc/profile} file. This file | |
3034 | contains shell code that exports the right environment variables necessary to | |
3035 | activate the software contained in the profile. It is built automatically by | |
3036 | Guix and meant to be sourced. | |
3037 | It contains the same variables you would get if you ran: | |
3038 | ||
3039 | @example | |
3040 | guix package --search-paths=prefix --profile=$my_profile" | |
3041 | @end example | |
3042 | ||
3043 | Once again, see (@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}) | |
3044 | for the command line options. | |
3045 | ||
3046 | To upgrade a profile, simply install the manifest again: | |
3047 | ||
3048 | @example | |
3049 | guix package -m /path/to/guix-my-project-manifest.scm -p "$GUIX_EXTRA_PROFILES"/my-project/my-project | |
3050 | @end example | |
3051 | ||
3052 | To upgrade all profiles, it's easy enough to loop over them. For instance, | |
3053 | assuming your manifest specifications are stored in | |
2c8305d1 | 3054 | @file{~/.guix-manifests/guix-$profile-manifest.scm}, with @samp{$profile} being the name |
cc765e47 | 3055 | of the profile (e.g.@: "project1"), you could do the following in Bourne shell: |
4c463569 PN |
3056 | |
3057 | @example | |
3058 | for profile in "$GUIX_EXTRA_PROFILES"/*; do | |
3059 | guix package --profile="$profile" --manifest="$HOME/.guix-manifests/guix-$profile-manifest.scm" | |
3060 | done | |
3061 | @end example | |
3062 | ||
3063 | Each profile has its own generations: | |
3064 | ||
3065 | @example | |
3066 | guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --list-generations | |
3067 | @end example | |
3068 | ||
3069 | You can roll-back to any generation of a given profile: | |
3070 | ||
3071 | @example | |
3072 | guix package -p "$GUIX_EXTRA_PROFILES"/my-project/my-project --switch-generations=17 | |
3073 | @end example | |
cb7b501d PN |
3074 | |
3075 | Finally, if you want to switch to a profile without inheriting from the | |
3076 | current environment, you can activate it from an empty shell: | |
3077 | ||
3078 | @example | |
3079 | env -i $(which bash) --login --noprofile --norc | |
3080 | . my-project/etc/profile | |
3081 | @end example | |
4c463569 PN |
3082 | |
3083 | @node Required packages | |
3084 | @subsection Required packages | |
3085 | ||
3086 | Activating a profile essentially boils down to exporting a bunch of | |
3087 | environmental variables. This is the role of the @samp{etc/profile} within the | |
3088 | profile. | |
3089 | ||
3090 | @emph{Note: Only the environmental variables of the packages that consume them will | |
3091 | be set.} | |
3092 | ||
3093 | For instance, @samp{MANPATH} won't be set if there is no consumer application for man | |
3094 | pages within the profile. So if you need to transparently access man pages once | |
3095 | the profile is loaded, you've got two options: | |
3096 | ||
3097 | @itemize | |
3098 | @item | |
3099 | Either export the variable manually, e.g. | |
3100 | @example | |
f6c27c55 | 3101 | export MANPATH=/path/to/profile$@{MANPATH:+:@}$MANPATH |
4c463569 PN |
3102 | @end example |
3103 | ||
3104 | @item | |
3105 | Or include @samp{man-db} to the profile manifest. | |
3106 | @end itemize | |
3107 | ||
3108 | The same is true for @samp{INFOPATH} (you can install @samp{info-reader}), | |
3109 | @samp{PKG_CONFIG_PATH} (install @samp{pkg-config}), etc. | |
3110 | ||
3111 | @node Default profile | |
3112 | @subsection Default profile | |
3113 | ||
2c8305d1 | 3114 | What about the default profile that Guix keeps in @file{~/.guix-profile}? |
4c463569 PN |
3115 | |
3116 | You can assign it the role you want. Typically you would install the manifest | |
3117 | of the packages you want to use all the time. | |
3118 | ||
128b136e | 3119 | Alternatively, you could keep it ``manifest-less'' for throw-away packages |
4c463569 PN |
3120 | that you would just use for a couple of days. |
3121 | This way makes it convenient to run | |
3122 | ||
3123 | @example | |
3124 | guix install package-foo | |
3125 | guix upgrade package-bar | |
3126 | @end example | |
3127 | ||
3128 | without having to specify the path to a profile. | |
3129 | ||
3130 | @node The benefits of manifests | |
3131 | @subsection The benefits of manifests | |
3132 | ||
3133 | Manifests are a convenient way to keep your package lists around and, say, | |
3134 | to synchronize them across multiple machines using a version control system. | |
3135 | ||
3136 | A common complaint about manifests is that they can be slow to install when they | |
3137 | contain large number of packages. This is especially cumbersome when you just | |
3138 | want get an upgrade for one package within a big manifest. | |
3139 | ||
3140 | This is one more reason to use multiple profiles, which happen to be just | |
3141 | perfect to break down manifests into multiple sets of semantically connected | |
3142 | packages. Using multiple, small profiles provides more flexibility and | |
3143 | usability. | |
3144 | ||
3145 | Manifests come with multiple benefits. In particular, they ease maintenance: | |
3146 | ||
3147 | @itemize | |
3148 | @item | |
3149 | When a profile is set up from a manifest, the manifest itself is | |
128b136e | 3150 | self-sufficient to keep a ``package listing'' around and reinstall the profile |
4c463569 PN |
3151 | later or on a different system. For ad-hoc profiles, we would need to |
3152 | generate a manifest specification manually and maintain the package versions | |
3153 | for the packages that don't use the default version. | |
3154 | ||
3155 | @item | |
3156 | @code{guix package --upgrade} always tries to update the packages that have | |
3157 | propagated inputs, even if there is nothing to do. Guix manifests remove this | |
3158 | problem. | |
3159 | ||
3160 | @item | |
3161 | When partially upgrading a profile, conflicts may arise (due to diverging | |
3162 | dependencies between the updated and the non-updated packages) and they can be | |
3163 | annoying to resolve manually. Manifests remove this problem altogether since | |
3164 | all packages are always upgraded at once. | |
3165 | ||
3166 | @item | |
3167 | As mentioned above, manifests allow for reproducible profiles, while the | |
3168 | imperative @code{guix install}, @code{guix upgrade}, etc. do not, since they produce | |
3169 | different profiles every time even when they hold the same packages. See | |
3170 | @uref{https://issues.guix.gnu.org/issue/33285, the related discussion on the matter}. | |
3171 | ||
3172 | @item | |
3173 | Manifest specifications are usable by other @samp{guix} commands. For example, you | |
3174 | can run @code{guix weather -m manifest.scm} to see how many substitutes are | |
3175 | available, which can help you decide whether you want to try upgrading today | |
3176 | or wait a while. Another example: you can run @code{guix pack -m manifest.scm} to | |
3177 | create a pack containing all the packages in the manifest (and their | |
3178 | transitive references). | |
3179 | ||
3180 | @item | |
3181 | Finally, manifests have a Scheme representation, the @samp{<manifest>} record type. | |
3182 | They can be manipulated in Scheme and passed to the various Guix @uref{https://en.wikipedia.org/wiki/Api, APIs}. | |
3183 | @end itemize | |
3184 | ||
3185 | It's important to understand that while manifests can be used to declare | |
3186 | profiles, they are not strictly equivalent: profiles have the side effect that | |
128b136e | 3187 | they ``pin'' packages in the store, which prevents them from being |
4c463569 PN |
3188 | garbage-collected (@pxref{Invoking guix gc,,, guix, GNU Guix Reference Manual}) |
3189 | and ensures that they will still be available at any point in | |
3190 | the future. | |
3191 | ||
3192 | Let's take an example: | |
3193 | ||
3194 | @enumerate | |
3195 | @item | |
3196 | We have an environment for hacking on a project for which there isn't a Guix | |
3197 | package yet. We build the environment using a manifest, and then run @code{guix | |
3198 | environment -m manifest.scm}. So far so good. | |
3199 | ||
3200 | @item | |
3201 | Many weeks pass and we have run a couple of @code{guix pull} in the mean time. | |
3202 | Maybe a dependency from our manifest has been updated; or we may have run | |
3203 | @code{guix gc} and some packages needed by our manifest have been | |
3204 | garbage-collected. | |
3205 | ||
3206 | @item | |
da7bee91 | 3207 | Eventually, we set to work on that project again, so we run @code{guix shell |
4c463569 PN |
3208 | -m manifest.scm}. But now we have to wait for Guix to build and install |
3209 | stuff! | |
3210 | @end enumerate | |
3211 | ||
3212 | Ideally, we could spare the rebuild time. And indeed we can, all we need is to | |
3213 | install the manifest to a profile and use @code{GUIX_PROFILE=/the/profile; | |
3214 | . "$GUIX_PROFILE"/etc/profile} as explained above: this guarantees that our | |
3215 | hacking environment will be available at all times. | |
3216 | ||
3217 | @emph{Security warning:} While keeping old profiles around can be convenient, keep in | |
3218 | mind that outdated packages may not have received the latest security fixes. | |
3219 | ||
3220 | @node Reproducible profiles | |
3221 | @subsection Reproducible profiles | |
3222 | ||
3223 | To reproduce a profile bit-for-bit, we need two pieces of information: | |
3224 | ||
3225 | @itemize | |
3226 | @item | |
3227 | a manifest, | |
3228 | @item | |
3229 | a Guix channel specification. | |
3230 | @end itemize | |
3231 | ||
3232 | Indeed, manifests alone might not be enough: different Guix versions (or | |
3233 | different channels) can produce different outputs for a given manifest. | |
3234 | ||
3235 | You can output the Guix channel specification with @samp{guix describe | |
3236 | --format=channels}. | |
3237 | Save this to a file, say @samp{channel-specs.scm}. | |
3238 | ||
3239 | On another computer, you can use the channel specification file and the manifest | |
3240 | to reproduce the exact same profile: | |
3241 | ||
3242 | @example | |
3243 | GUIX_EXTRA_PROFILES=$HOME/.guix-extra-profiles | |
3244 | GUIX_EXTRA=$HOME/.guix-extra | |
3245 | ||
3246 | mkdir "$GUIX_EXTRA"/my-project | |
3247 | guix pull --channels=channel-specs.scm --profile "$GUIX_EXTRA/my-project/guix" | |
3248 | ||
3249 | mkdir -p "$GUIX_EXTRA_PROFILES/my-project" | |
3250 | "$GUIX_EXTRA"/my-project/guix/bin/guix package --manifest=/path/to/guix-my-project-manifest.scm --profile="$GUIX_EXTRA_PROFILES"/my-project/my-project | |
3251 | @end example | |
3252 | ||
3253 | It's safe to delete the Guix channel profile you've just installed with the | |
3254 | channel specification, the project profile does not depend on it. | |
3255 | ||
d0fc1e83 OP |
3256 | @c ********************************************************************* |
3257 | @node Environment management | |
3258 | @chapter Environment management | |
3259 | ||
3260 | Guix provides multiple tools to manage environment. This chapter | |
3261 | demonstrate such utilities. | |
3262 | ||
3263 | @menu | |
3264 | * Guix environment via direnv:: Setup Guix environment with direnv | |
3265 | @end menu | |
3266 | ||
3267 | @node Guix environment via direnv | |
3268 | @section Guix environment via direnv | |
3269 | ||
3270 | Guix provides a @samp{direnv} package, which could extend shell after | |
3271 | directory change. This tool could be used to prepare a pure Guix | |
3272 | environment. | |
3273 | ||
3274 | The following example provides a shell function for @file{~/.direnvrc} | |
3275 | file, which could be used from Guix Git repository in | |
3276 | @file{~/src/guix/.envrc} file to setup a build environment similar to | |
3277 | described in @pxref{Building from Git,,, guix, GNU Guix Reference | |
3278 | Manual}. | |
3279 | ||
3280 | Create a @file{~/.direnvrc} with a Bash code: | |
3281 | ||
3282 | @example | |
3283 | # Thanks <https://github.com/direnv/direnv/issues/73#issuecomment-152284914> | |
3284 | export_function() | |
3285 | @{ | |
3286 | local name=$1 | |
3287 | local alias_dir=$PWD/.direnv/aliases | |
3288 | mkdir -p "$alias_dir" | |
3289 | PATH_add "$alias_dir" | |
3290 | local target="$alias_dir/$name" | |
3291 | if declare -f "$name" >/dev/null; then | |
3292 | echo "#!$SHELL" > "$target" | |
3293 | declare -f "$name" >> "$target" 2>/dev/null | |
3294 | # Notice that we add shell variables to the function trigger. | |
3295 | echo "$name \$*" >> "$target" | |
3296 | chmod +x "$target" | |
3297 | fi | |
3298 | @} | |
3299 | ||
3300 | use_guix() | |
3301 | @{ | |
3302 | # Set GitHub token. | |
3303 | export GUIX_GITHUB_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" | |
3304 | ||
3305 | # Unset 'GUIX_PACKAGE_PATH'. | |
3306 | export GUIX_PACKAGE_PATH="" | |
3307 | ||
3308 | # Recreate a garbage collector root. | |
3309 | gcroots="$HOME/.config/guix/gcroots" | |
3310 | mkdir -p "$gcroots" | |
3311 | gcroot="$gcroots/guix" | |
3312 | if [ -L "$gcroot" ] | |
3313 | then | |
3314 | rm -v "$gcroot" | |
3315 | fi | |
3316 | ||
3317 | # Miscellaneous packages. | |
3318 | PACKAGES_MAINTENANCE=( | |
3319 | direnv | |
3320 | git | |
3321 | git:send-email | |
3322 | git-cal | |
3323 | gnupg | |
3324 | guile-colorized | |
3325 | guile-readline | |
3326 | less | |
3327 | ncurses | |
3328 | openssh | |
3329 | xdot | |
3330 | ) | |
3331 | ||
3332 | # Environment packages. | |
3333 | PACKAGES=(help2man guile-sqlite3 guile-gcrypt) | |
3334 | ||
3335 | # Thanks <https://lists.gnu.org/archive/html/guix-devel/2016-09/msg00859.html> | |
3336 | eval "$(guix environment --search-paths --root="$gcroot" --pure guix --ad-hoc $@{PACKAGES[@@]@} $@{PACKAGES_MAINTENANCE[@@]@} "$@@")" | |
3337 | ||
3338 | # Predefine configure flags. | |
3339 | configure() | |
3340 | @{ | |
3341 | ./configure --localstatedir=/var --prefix= | |
3342 | @} | |
3343 | export_function configure | |
3344 | ||
3345 | # Run make and optionally build something. | |
3346 | build() | |
3347 | @{ | |
3348 | make -j 2 | |
3349 | if [ $# -gt 0 ] | |
3350 | then | |
3351 | ./pre-inst-env guix build "$@@" | |
3352 | fi | |
3353 | @} | |
3354 | export_function build | |
3355 | ||
3356 | # Predefine push Git command. | |
3357 | push() | |
3358 | @{ | |
3359 | git push --set-upstream origin | |
3360 | @} | |
3361 | export_function push | |
3362 | ||
3363 | clear # Clean up the screen. | |
3364 | git-cal --author='Your Name' # Show contributions calendar. | |
3365 | ||
3366 | # Show commands help. | |
3367 | echo " | |
3368 | build build a package or just a project if no argument provided | |
3369 | configure run ./configure with predefined parameters | |
3370 | push push to upstream Git repository | |
3371 | " | |
3372 | @} | |
3373 | @end example | |
3374 | ||
3375 | Every project containing @file{.envrc} with a string @code{use guix} | |
3376 | will have predefined environment variables and procedures. | |
3377 | ||
3378 | Run @command{direnv allow} to setup the environment for the first time. | |
3379 | ||
7bc46ecc RW |
3380 | @c ********************************************************************* |
3381 | @node Acknowledgments | |
3382 | @chapter Acknowledgments | |
3383 | ||
3384 | Guix is based on the @uref{https://nixos.org/nix/, Nix package manager}, | |
3385 | which was designed and | |
3386 | implemented by Eelco Dolstra, with contributions from other people (see | |
3387 | the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package | |
3388 | management, and promoted unprecedented features, such as transactional | |
3389 | package upgrades and rollbacks, per-user profiles, and referentially | |
3390 | transparent build processes. Without this work, Guix would not exist. | |
3391 | ||
3392 | The Nix-based software distributions, Nixpkgs and NixOS, have also been | |
3393 | an inspiration for Guix. | |
3394 | ||
3395 | GNU@tie{}Guix itself is a collective work with contributions from a | |
3396 | number of people. See the @file{AUTHORS} file in Guix for more | |
3397 | information on these fine people. The @file{THANKS} file lists people | |
3398 | who have helped by reporting bugs, taking care of the infrastructure, | |
3399 | providing artwork and themes, making suggestions, and more---thank you! | |
3400 | ||
3401 | This document includes adapted sections from articles that have previously | |
3402 | been published on the Guix blog at @uref{https://guix.gnu.org/blog}. | |
3403 | ||
3404 | ||
3405 | @c ********************************************************************* | |
3406 | @node GNU Free Documentation License | |
3407 | @appendix GNU Free Documentation License | |
3408 | @cindex license, GNU Free Documentation License | |
3409 | @include fdl-1.3.texi | |
3410 | ||
3411 | @c ********************************************************************* | |
3412 | @node Concept Index | |
3413 | @unnumbered Concept Index | |
3414 | @printindex cp | |
3415 | ||
3416 | @bye | |
3417 | ||
3418 | @c Local Variables: | |
3419 | @c ispell-local-dictionary: "american"; | |
3420 | @c End: |