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.
 
 
 
 
 
 

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