Mirror of GNU Guix
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

2148 lines
77 KiB

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