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.
 
 
 
 
 
 

822 lines
30 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. * Acknowledgments:: Thanks!
  50. * GNU Free Documentation License:: The license of this document.
  51. * Concept Index:: Concepts.
  52. @detailmenu
  53. --- The Detailed Node Listing ---
  54. Scheme tutorials
  55. * A Scheme Crash Course:: Learn the basics of Scheme
  56. Packaging
  57. * Packaging Tutorial:: Let's add a package to Guix!
  58. System Configuration
  59. * Customizing the Kernel:: Creating and using a custom Linux kernel
  60. @end detailmenu
  61. @end menu
  62. @c *********************************************************************
  63. @node Scheme tutorials
  64. @chapter Scheme tutorials
  65. GNU@tie{}Guix is written in the general purpose programming language Scheme,
  66. and many of its features can be accessed and manipulated programmatically.
  67. You can use Scheme to generate package definitions, to modify them, to build
  68. them, to deploy whole operating systems, etc.
  69. Knowing the basics of how to program in Scheme will unlock many of the
  70. advanced features Guix provides --- and you don't even need to be an
  71. experienced programmer to use them!
  72. Let's get started!
  73. @node A Scheme Crash Course
  74. @section A Scheme Crash Course
  75. @cindex Scheme, crash course
  76. Guix uses the Guile implementation of Scheme. To start playing with the
  77. language, install it with @code{guix install guile} and start a
  78. @uref{https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop,
  79. REPL} by running @code{guile} from the command line.
  80. Alternatively you can also run @code{guix environment --ad-hoc guile -- guile}
  81. if you'd rather not have Guile installed in your user profile.
  82. In the following examples we use the @code{>} symbol to denote the REPL
  83. prompt, that is, the line reserved for user input. @xref{Using Guile
  84. Interactively,,, guile, GNU Guile Reference Manual}) for more details on the
  85. REPL.
  86. @itemize
  87. @item
  88. Scheme syntax boils down to a tree of expressions (or @emph{s-expression} in
  89. Lisp lingo). An expression can be a literal such as numbers and strings, or a
  90. compound which is a parenthesized list of compounds and literals. @code{#t}
  91. and @code{#f} stand for the booleans "true" and "false", respectively.
  92. Examples of valid expressions:
  93. @example scheme
  94. > "Hello World!"
  95. "Hello World!"
  96. > 17
  97. 17
  98. > (display (string-append "Hello " "Guix" "\n"))
  99. "Hello Guix!"
  100. @end example
  101. @item
  102. This last example is a function call nested in another function call. When a
  103. parenthesized expression is evaluated, the first term is the function and the
  104. rest are the arguments passed to the function. Every function returns the
  105. last evaluated expression as its return value.
  106. @item
  107. Anonymous functions are declared with the @code{lambda} term:
  108. @example scheme
  109. > (lambda (x) (* x x))
  110. #<procedure 120e348 at <unknown port>:24:0 (x)>
  111. @end example
  112. The above procedure returns the square of its argument. Since everything is
  113. an expression, the @code{lambda} expression returns an anonymous procedure,
  114. which can in turn be applied to an argument:
  115. @example scheme
  116. > ((lambda (x) (* x x)) 3)
  117. 9
  118. @end example
  119. @item
  120. Anything can be assigned a global name with @code{define}:
  121. @example scheme
  122. > (define a 3)
  123. > (define square (lambda (x) (* x x)))
  124. > (square a)
  125. 9
  126. @end example
  127. @item
  128. Procedures can be defined more concisely with the following syntax:
  129. @example scheme
  130. (define (square x) (* x x))
  131. @end example
  132. @item
  133. A list structure can be created with the @code{list} procedure:
  134. @example scheme
  135. > (list 2 a 5 7)
  136. (2 3 5 7)
  137. @end example
  138. @item
  139. The @emph{quote} disables evaluation of a parenthesized expression: the first
  140. term is not called over the other terms. Thus it effectively returns a list
  141. of terms.
  142. @example scheme
  143. > '(display (string-append "Hello " "Guix" "\n"))
  144. (display (string-append "Hello " "Guix" "\n"))
  145. > '(2 a 5 7)
  146. (2 a 5 7)
  147. @end example
  148. @item
  149. The @emph{quasiquote} disables evaluation of a parenthesized expression until
  150. a comma re-enables it. Thus it provides us with fine-grained control over
  151. what is evaluated and what is not.
  152. @example scheme
  153. > `(2 a 5 7 (2 ,a 5 ,(+ a 4)))
  154. (2 a 5 7 (2 3 5 7))
  155. @end example
  156. Note that the above result is a list of mixed elements: numbers, symbols (here
  157. @code{a}) and the last element is a list itself.
  158. @item
  159. Multiple variables can be named locally with @code{let}:
  160. @example scheme
  161. > (define x 10)
  162. > (let ((x 2)
  163. (y 3))
  164. (list x y))
  165. (2 3)
  166. > x
  167. 10
  168. > y
  169. ERROR: In procedure module-lookup: Unbound variable: y
  170. @end example
  171. Use @code{let*} to allow later variable declarations to refer to earlier
  172. definitions.
  173. @example scheme
  174. > (let* ((x 2)
  175. (y (* x 3)))
  176. (list x y))
  177. (2 6)
  178. @end example
  179. @item
  180. The keyword syntax is @code{#:}; it is used to create unique identifiers.
  181. @pxref{Keywords,,, guile, GNU Guile Reference Manual}.
  182. @item
  183. The percentage @code{%} is typically used for read-only global variables in
  184. the build stage. Note that it is merely a convention, like @code{_} in C.
  185. Scheme treats @code{%} exactly the same as any other letter.
  186. @item
  187. Modules are created with @code{define-module}. For instance
  188. @example scheme
  189. (define-module (guix build-system ruby)
  190. #:use-module (guix store)
  191. #:export (ruby-build
  192. ruby-build-system))
  193. @end example
  194. defines the module @code{guix build-system ruby} which must be located in
  195. @file{guix/build-system/ruby.scm} somewhere in the Guile load path. It
  196. depends on the @code{(guix store)} module and it exports two variables,
  197. @code{ruby-build} and @code{ruby-build-system}.
  198. @end itemize
  199. For a more detailed introduction, check out
  200. @uref{http://www.troubleshooters.com/codecorn/scheme_guile/hello.htm, Scheme
  201. at a Glance}, by Steve Litt.
  202. One of the reference Scheme books is the seminal ``Structure and
  203. Interpretation of Computer Programs'', by Harold Abelson and Gerald Jay
  204. Sussman, with Julie Sussman. You'll find a
  205. @uref{https://mitpress.mit.edu/sites/default/files/sicp/index.html, free copy
  206. online}, together with
  207. @uref{https://ocw.mit.edu/courses/electrical-engineering-and-computer-science/6-001-structure-and-interpretation-of-computer-programs-spring-2005/video-lectures/,
  208. videos of the lectures by the authors}. The book is available in Texinfo
  209. format as the @code{sicp} Guix package. Go ahead, run @code{guix install
  210. sicp} and start reading with @code{info sicp} (or with the Emacs Info reader).
  211. An @uref{https://sarabander.github.io/sicp/, unofficial ebook is also
  212. available}.
  213. You'll find more books, tutorials and other resources at
  214. @url{https://schemers.org/}.
  215. @c *********************************************************************
  216. @node Packaging
  217. @chapter Packaging
  218. @cindex packaging
  219. This chapter is dedicated to teaching you how to add packages to the
  220. collection of packages that come with GNU Guix. This involves writing package
  221. definitions in Guile Scheme, organizing them in package modules, and building
  222. them.
  223. @menu
  224. * Packaging Tutorial:: A tutorial on how to add packages to Guix.
  225. @end menu
  226. @node Packaging Tutorial
  227. @section Packaging Tutorial
  228. GNU Guix stands out as the @emph{hackable} package manager, mostly because it
  229. uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful
  230. high-level programming language, one of the
  231. @uref{https://en.wikipedia.org/wiki/Scheme_%28programming_language%29, Scheme}
  232. dialects from the
  233. @uref{https://en.wikipedia.org/wiki/Lisp_%28programming_language%29, Lisp family}.
  234. Package definitions are also written in Scheme, which empowers Guix in some
  235. very unique ways, unlike most other package managers that use shell scripts or
  236. simple languages.
  237. @itemize
  238. @item
  239. Use functions, structures, macros and all of Scheme expressiveness for your
  240. package definitions.
  241. @item
  242. Inheritance makes it easy to customize a package by inheriting from it and
  243. modifying only what is needed.
  244. @item
  245. Batch processing: the whole package collection can be parsed, filtered and
  246. processed. Building a headless server with all graphical interfaces stripped
  247. out? It's possible. Want to rebuild everything from source using specific
  248. compiler optimization flags? Pass the @code{#:make-flags "..."} argument to
  249. the list of packages. It wouldn't be a stretch to think
  250. @uref{https://wiki.gentoo.org/wiki/USE_flag, Gentoo USE flags} here, but this
  251. goes even further: the changes don't have to be thought out beforehand by the
  252. packager, they can be @emph{programmed} by the user!
  253. @end itemize
  254. The following tutorial covers all the basics around package creation with Guix.
  255. It does not assume much knowledge of the Guix system nor of the Lisp language.
  256. The reader is only expected to be familiar with the command line and to have some
  257. basic programming knowledge.
  258. @subsection A "Hello World" package
  259. The “Defining Packages” section of the manual introduces the basics of Guix
  260. packaging (@pxref{Defining Packages,,, guix, GNU Guix Reference Manual}). In
  261. the following section, we will partly go over those basics again.
  262. ``GNU hello'' is a dummy project that serves as an idiomatic example for
  263. packaging. It uses the GNU build system (@code{./configure && make && make
  264. install}). Guix already provides a package definition which is a perfect
  265. example to start with. You can look up its declaration with @code{guix edit
  266. hello} from the command line. Let's see how it looks:
  267. @example scheme
  268. (define-public hello
  269. (package
  270. (name "hello")
  271. (version "2.10")
  272. (source (origin
  273. (method url-fetch)
  274. (uri (string-append "mirror://gnu/hello/hello-" version
  275. ".tar.gz"))
  276. (sha256
  277. (base32
  278. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  279. (build-system gnu-build-system)
  280. (synopsis "Hello, GNU world: An example GNU package")
  281. (description
  282. "GNU Hello prints the message \"Hello, world!\" and then exits. It
  283. serves as an example of standard GNU coding practices. As such, it supports
  284. command-line arguments, multiple languages, and so on.")
  285. (home-page "https://www.gnu.org/software/hello/")
  286. (license gpl3+)))
  287. @end example
  288. As you can see, most of it is rather straightforward. But let's review the
  289. fields together:
  290. @table @samp
  291. @item name
  292. The project name. Using Scheme conventions, we prefer to keep it
  293. lower case, without underscore and using dash-separated words.
  294. @item source
  295. This field contains a description of the source code origin. The
  296. @code{origin} record contains these fields:
  297. @enumerate
  298. @item The method, here @code{url-fetch} to download via HTTP/FTP, but other methods
  299. exist, such as @code{git-fetch} for Git repositories.
  300. @item The URI, which is typically some @code{https://} location for @code{url-fetch}. Here
  301. the special `mirror://gnu` refers to a set of well known locations, all of
  302. which can be used by Guix to fetch the source, should some of them fail.
  303. @item The @code{sha256} checksum of the requested file. This is essential to ensure
  304. the source is not corrupted. Note that Guix works with base32 strings,
  305. hence the call to the @code{base32} function.
  306. @end enumerate
  307. @item build-system
  308. This is where the power of abstraction provided by the Scheme language really
  309. shines: in this case, the @code{gnu-build-system} abstracts away the famous
  310. @code{./configure && make && make install} shell invocations. Other build
  311. systems include the @code{trivial-build-system} which does not do anything and
  312. requires from the packager to program all the build steps, the
  313. @code{python-build-system}, the @code{emacs-build-system}, and many more
  314. (@pxref{Build Systems,,, guix, GNU Guix Reference Manual}).
  315. @item synopsis
  316. It should be a concise summary of what the package does. For many packages a
  317. tagline from the project's home page can be used as the synopsis.
  318. @item description
  319. Same as for the synopsis, it's fine to re-use the project description from the
  320. homepage. Note that Guix uses Texinfo syntax.
  321. @item home-page
  322. Use HTTPS if available.
  323. @item license
  324. See @code{guix/licenses.scm} in the project source for a full list of
  325. available licenses.
  326. @end table
  327. Time to build our first package! Nothing fancy here for now: we will stick to a
  328. dummy "my-hello", a copy of the above declaration.
  329. As with the ritualistic "Hello World" taught with most programming languages,
  330. this will possibly be the most "manual" approach. We will work out an ideal
  331. setup later; for now we will go the simplest route.
  332. Save the following to a file @file{my-hello.scm}.
  333. @example scheme
  334. (use-modules (guix packages)
  335. (guix download)
  336. (guix build-system gnu)
  337. (guix licenses))
  338. (package
  339. (name "my-hello")
  340. (version "2.10")
  341. (source (origin
  342. (method url-fetch)
  343. (uri (string-append "mirror://gnu/hello/hello-" version
  344. ".tar.gz"))
  345. (sha256
  346. (base32
  347. "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
  348. (build-system gnu-build-system)
  349. (synopsis "Hello, Guix world: An example custom Guix package")
  350. (description
  351. "GNU Hello prints the message \"Hello, world!\" and then exits. It
  352. serves as an example of standard GNU coding practices. As such, it supports
  353. command-line arguments, multiple languages, and so on.")
  354. (home-page "https://www.gnu.org/software/hello/")
  355. (license gpl3+))
  356. @end example
  357. We will explain the extra code in a moment.
  358. Feel free to play with the different values of the various fields. If you
  359. change the source, you'll need to update the checksum. Indeed, Guix refuses to
  360. build anything if the given checksum does not match the computed checksum of the
  361. source code. To obtain the correct checksum of the package declaration, we
  362. need to download the source, compute the sha256 checksum and convert it to
  363. base32.
  364. Thankfully, Guix can automate this task for us; all we need is to provide the
  365. URI:
  366. @c TRANSLATORS: This is example shell output.
  367. @example sh
  368. $ guix download mirror://gnu/hello/hello-2.10.tar.gz
  369. Starting download of /tmp/guix-file.JLYgL7
  370. From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz...
  371. following redirection to `https://mirror.ibcp.fr/pub/gnu/hello/hello-2.10.tar.gz'...
  372. …10.tar.gz 709KiB 2.5MiB/s 00:00 [##################] 100.0%
  373. /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
  374. 0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i
  375. @end example
  376. In this specific case the output tells us which mirror was chosen.
  377. If the result of the above command is not the same as in the above snippet,
  378. update your @code{my-hello} declaration accordingly.
  379. Note that GNU package tarballs come with an OpenPGP signature, so you
  380. should definitely check the signature of this tarball with `gpg` to
  381. authenticate it before going further:
  382. @c TRANSLATORS: This is example shell output.
  383. @example sh
  384. $ guix download mirror://gnu/hello/hello-2.10.tar.gz.sig
  385. Starting download of /tmp/guix-file.03tFfb
  386. From https://ftpmirror.gnu.org/gnu/hello/hello-2.10.tar.gz.sig...
  387. following redirection to `https://ftp.igh.cnrs.fr/pub/gnu/hello/hello-2.10.tar.gz.sig'...
  388. ….tar.gz.sig 819B 1.2MiB/s 00:00 [##################] 100.0%
  389. /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig
  390. 0q0v86n3y38z17rl146gdakw9xc4mcscpk8dscs412j22glrv9jf
  391. $ gpg --verify /gnu/store/rzs8wba9ka7grrmgcpfyxvs58mly0sx6-hello-2.10.tar.gz.sig /gnu/store/hbdalsf5lpf01x4dcknwx6xbn6n5km6k-hello-2.10.tar.gz
  392. gpg: Signature made Sun 16 Nov 2014 01:08:37 PM CET
  393. gpg: using RSA key A9553245FDE9B739
  394. gpg: Good signature from "Sami Kerola <kerolasa@@iki.fi>" [unknown]
  395. gpg: aka "Sami Kerola (http://www.iki.fi/kerolasa/) <kerolasa@@iki.fi>" [unknown]
  396. gpg: WARNING: This key is not certified with a trusted signature!
  397. gpg: There is no indication that the signature belongs to the owner.
  398. Primary key fingerprint: 8ED3 96E3 7E38 D471 A005 30D3 A955 3245 FDE9 B739
  399. @end example
  400. You can then happily run
  401. @c TRANSLATORS: Do not translate this command
  402. @example sh
  403. $ guix package --install-from-file=my-hello.scm
  404. @end example
  405. You should now have @code{my-hello} in your profile!
  406. @c TRANSLATORS: Do not translate this command
  407. @example sh
  408. $ guix package --list-installed=my-hello
  409. my-hello 2.10 out
  410. /gnu/store/f1db2mfm8syb8qvc357c53slbvf1g9m9-my-hello-2.10
  411. @end example
  412. We've gone as far as we could without any knowledge of Scheme. Before moving
  413. on to more complex packages, now is the right time to brush up on your Scheme
  414. knowledge. @pxref{A Scheme Crash Course} to get up to speed.
  415. @c TODO: Continue the tutorial
  416. @c *********************************************************************
  417. @node System Configuration
  418. @chapter System Configuration
  419. Guix offers a flexible language for declaratively configuring your Guix
  420. System. This flexibility can at times be overwhelming. The purpose of this
  421. chapter is to demonstrate some advanced configuration concepts.
  422. @pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a complete
  423. reference.
  424. @menu
  425. * Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
  426. @end menu
  427. @node Customizing the Kernel
  428. @section Customizing the Kernel
  429. Guix is, at its core, a source based distribution with substitutes
  430. (@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such building
  431. packages from their source code is an expected part of regular package
  432. installations and upgrades. Given this starting point, it makes sense that
  433. efforts are made to reduce the amount of time spent compiling packages, and
  434. recent changes and upgrades to the building and distribution of substitutes
  435. continues to be a topic of discussion within Guix.
  436. The kernel, while not requiring an overabundance of RAM to build, does take a
  437. rather long time on an average machine. The official kernel configuration, as
  438. is the case with many GNU/Linux distributions, errs on the side of
  439. inclusiveness, and this is really what causes the build to take such a long
  440. time when the kernel is built from source.
  441. The Linux kernel, however, can also just be described as a regular old
  442. package, and as such can be customized just like any other package. The
  443. procedure is a little bit different, although this is primarily due to the
  444. nature of how the package definition is written.
  445. The @code{linux-libre} kernel package definition is actually a procedure which
  446. creates a package.
  447. @example scheme
  448. (define* (make-linux-libre version hash supported-systems
  449. #:key
  450. ;; A function that takes an arch and a variant.
  451. ;; See kernel-config for an example.
  452. (extra-version #f)
  453. (configuration-file #f)
  454. (defconfig "defconfig")
  455. (extra-options %default-extra-linux-options)
  456. (patches (list %boot-logo-patch)))
  457. ...)
  458. @end example
  459. The current @code{linux-libre} package is for the 5.1.x series, and is
  460. declared like this:
  461. @example scheme
  462. (define-public linux-libre
  463. (make-linux-libre %linux-libre-version
  464. %linux-libre-hash
  465. '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-linux")
  466. #:patches %linux-libre-5.1-patches
  467. #:configuration-file kernel-config))
  468. @end example
  469. Any keys which are not assigned values inherit their default value from the
  470. @code{make-linux-libre} definition. When comparing the two snippets above,
  471. you may notice that the code comment in the first doesn't actually refer to
  472. the @code{#:extra-version} keyword; it is actually for
  473. @code{#:configuration-file}. Because of this, it is not actually easy to
  474. include a custom kernel configuration from the definition, but don't worry,
  475. there are other ways to work with what we do have.
  476. There are two ways to create a kernel with a custom kernel configuration. The
  477. first is to provide a standard @file{.config} file during the build process by
  478. including an actual @file{.config} file as a native input to our custom
  479. kernel. The following is a snippet from the custom @code{'configure} phase of
  480. the @code{make-linux-libre} package definition:
  481. @example scheme
  482. (let ((build (assoc-ref %standard-phases 'build))
  483. (config (assoc-ref (or native-inputs inputs) "kconfig")))
  484. ;; Use a custom kernel configuration file or a default
  485. ;; configuration file.
  486. (if config
  487. (begin
  488. (copy-file config ".config")
  489. (chmod ".config" #o666))
  490. (invoke "make" ,defconfig))
  491. @end example
  492. Below is a sample kernel package. The @code{linux-libre} package is nothing
  493. special and can be inherited from and have its fields overridden like any
  494. other package:
  495. @example scheme
  496. (define-public linux-libre/E2140
  497. (package
  498. (inherit linux-libre)
  499. (native-inputs
  500. `(("kconfig" ,(local-file "E2140.config"))
  501. ,@@(alist-delete "kconfig"
  502. (package-native-inputs linux-libre))))))
  503. @end example
  504. In the same directory as the file defining @code{linux-libre-E2140} is a file
  505. named @file{E2140.config}, which is an actual kernel configuration file. The
  506. @code{defconfig} keyword of @code{make-linux-libre} is left blank here, so the
  507. only kernel configuration in the package is the one which was included in the
  508. @code{native-inputs} field.
  509. The second way to create a custom kernel is to pass a new value to the
  510. @code{extra-options} keyword of the @code{make-linux-libre} procedure. The
  511. @code{extra-options} keyword works with another function defined right below
  512. it:
  513. @example scheme
  514. (define %default-extra-linux-options
  515. `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html
  516. ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t)
  517. ;; Modules required for initrd:
  518. ("CONFIG_NET_9P" . m)
  519. ("CONFIG_NET_9P_VIRTIO" . m)
  520. ("CONFIG_VIRTIO_BLK" . m)
  521. ("CONFIG_VIRTIO_NET" . m)
  522. ("CONFIG_VIRTIO_PCI" . m)
  523. ("CONFIG_VIRTIO_BALLOON" . m)
  524. ("CONFIG_VIRTIO_MMIO" . m)
  525. ("CONFIG_FUSE_FS" . m)
  526. ("CONFIG_CIFS" . m)
  527. ("CONFIG_9P_FS" . m)))
  528. (define (config->string options)
  529. (string-join (map (match-lambda
  530. ((option . 'm)
  531. (string-append option "=m"))
  532. ((option . #t)
  533. (string-append option "=y"))
  534. ((option . #f)
  535. (string-append option "=n")))
  536. options)
  537. "\n"))
  538. @end example
  539. And in the custom configure script from the `make-linux-libre` package:
  540. @example scheme
  541. ;; Appending works even when the option wasn't in the
  542. ;; file. The last one prevails if duplicated.
  543. (let ((port (open-file ".config" "a"))
  544. (extra-configuration ,(config->string extra-options)))
  545. (display extra-configuration port)
  546. (close-port port))
  547. (invoke "make" "oldconfig"))))
  548. @end example
  549. So by not providing a configuration-file the @file{.config} starts blank, and
  550. then we write into it the collection of flags that we want. Here's another
  551. custom kernel:
  552. @example scheme
  553. (define %macbook41-full-config
  554. (append %macbook41-config-options
  555. %filesystems
  556. %efi-support
  557. %emulation
  558. (@@@@ (gnu packages linux) %default-extra-linux-options)))
  559. (define-public linux-libre-macbook41
  560. ;; XXX: Access the internal 'make-linux-libre' procedure, which is
  561. ;; private and unexported, and is liable to change in the future.
  562. ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux) %linux-libre-version)
  563. (@@@@ (gnu packages linux) %linux-libre-hash)
  564. '("x86_64-linux")
  565. #:extra-version "macbook41"
  566. #:patches (@@@@ (gnu packages linux) %linux-libre-5.1-patches)
  567. #:extra-options %macbook41-config-options))
  568. @end example
  569. In the above example @code{%filesystems} is a collection of flags enabling
  570. different filesystem support, @code{%efi-support} enables EFI support and
  571. @code{%emulation} enables a x86_64-linux machine to act in 32-bit mode also.
  572. @code{%default-extra-linux-options} are the ones quoted above, which had to be
  573. added in since they were replaced in the @code{extra-options} keyword.
  574. This all sounds like it should be doable, but how does one even know which
  575. modules are required for a particular system? Two places that can be helpful
  576. in trying to answer this question is the
  577. @uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gentoo
  578. Handbook} and the
  579. @uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highlight=localmodconfig,
  580. documentation from the kernel itself}. From the kernel documentation, it
  581. seems that @code{make localmodconfig} is the command we want.
  582. In order to actually run @code{make localmodconfig} we first need to get and
  583. unpack the kernel source code:
  584. @example shell
  585. tar xf $(guix build linux-libre --source)
  586. @end example
  587. Once inside the directory containing the source code run @code{touch .config}
  588. to create an initial, empty @file{.config} to start with. @code{make
  589. localmodconfig} works by seeing what you already have in @file{.config} and
  590. letting you know what you're missing. If the file is blank then you're
  591. missing everything. The next step is to run:
  592. @example shell
  593. guix environment linux-libre -- make localmodconfig
  594. @end example
  595. and note the output. Do note that the @file{.config} file is still empty.
  596. The output generally contains two types of warnings. The first start with
  597. "WARNING" and can actually be ignored in our case. The second read:
  598. @example shell
  599. module pcspkr did not have configs CONFIG_INPUT_PCSPKR
  600. @end example
  601. For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the
  602. @file{.config} in the directory, and append @code{=m}, so in the end it looks
  603. like this:
  604. @example shell
  605. CONFIG_INPUT_PCSPKR=m
  606. CONFIG_VIRTIO=m
  607. @end example
  608. After copying all the configuration options, run @code{make localmodconfig}
  609. again to make sure that you don't have any output starting with "module".
  610. After all of these machine specific modules there are a couple more left that
  611. are also needed. @code{CONFIG_MODULES} is necessary so that you can build and
  612. load modules separately and not have everything built into the kernel.
  613. @code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is
  614. possible that there are other modules which you will need.
  615. This post does not aim to be a guide to configuring your own kernel however,
  616. so if you do decide to build a custom kernel you'll have to seek out other
  617. guides to create a kernel which is just right for your needs.
  618. The second way to setup the kernel configuration makes more use of Guix's
  619. features and allows you to share configuration segments between different
  620. kernels. For example, all machines using EFI to boot have a number of EFI
  621. configuration flags that they need. It is likely that all the kernels will
  622. share a list of filesystems to support. By using variables it is easier to
  623. see at a glance what features are enabled and to make sure you don't have
  624. features in one kernel but missing in another.
  625. Left undiscussed however, is Guix's initrd and its customization. It is
  626. likely that you'll need to modify the initrd on a machine using a custom
  627. kernel, since certain modules which are expected to be built may not be
  628. available for inclusion into the initrd.
  629. @c *********************************************************************
  630. @node Acknowledgments
  631. @chapter Acknowledgments
  632. Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
  633. which was designed and
  634. implemented by Eelco Dolstra, with contributions from other people (see
  635. the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
  636. management, and promoted unprecedented features, such as transactional
  637. package upgrades and rollbacks, per-user profiles, and referentially
  638. transparent build processes. Without this work, Guix would not exist.
  639. The Nix-based software distributions, Nixpkgs and NixOS, have also been
  640. an inspiration for Guix.
  641. GNU@tie{}Guix itself is a collective work with contributions from a
  642. number of people. See the @file{AUTHORS} file in Guix for more
  643. information on these fine people. The @file{THANKS} file lists people
  644. who have helped by reporting bugs, taking care of the infrastructure,
  645. providing artwork and themes, making suggestions, and more---thank you!
  646. This document includes adapted sections from articles that have previously
  647. been published on the Guix blog at @uref{https://guix.gnu.org/blog}.
  648. @c *********************************************************************
  649. @node GNU Free Documentation License
  650. @appendix GNU Free Documentation License
  651. @cindex license, GNU Free Documentation License
  652. @include fdl-1.3.texi
  653. @c *********************************************************************
  654. @node Concept Index
  655. @unnumbered Concept Index
  656. @printindex cp
  657. @bye
  658. @c Local Variables:
  659. @c ispell-local-dictionary: "american";
  660. @c End: