From mboxrd@z Thu Jan 1 00:00:00 1970 From: Julien Lepiller Subject: Reworking the cookbook layout Date: Tue, 26 Nov 2019 23:11:59 +0100 Message-ID: <20191126231136.212ff31e@sybil.lepiller.eu> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="MP_/X/.FUkBbc7H7NFs4QlGqUSh" Return-path: Received: from eggs.gnu.org ([2001:470:142:3::10]:56038) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iZj4C-0003bG-3t for guix-devel@gnu.org; Tue, 26 Nov 2019 17:12:22 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iZj45-00042Z-LD for guix-devel@gnu.org; Tue, 26 Nov 2019 17:12:15 -0500 Received: from lepiller.eu ([2a00:5884:8208::1]:35086) by eggs.gnu.org with esmtps (TLS1.0:DHE_RSA_AES_256_CBC_SHA1:32) (Exim 4.71) (envelope-from ) id 1iZj44-0003ve-JW for guix-devel@gnu.org; Tue, 26 Nov 2019 17:12:09 -0500 Received: from lepiller.eu (localhost [127.0.0.1]) by lepiller.eu (OpenSMTPD) with ESMTP id 5917d134 for ; Tue, 26 Nov 2019 22:12:03 +0000 (UTC) Received: by lepiller.eu (OpenSMTPD) with ESMTPSA id cd340916 (TLSv1.2:ECDHE-RSA-AES256-GCM-SHA384:256:NO) for ; Tue, 26 Nov 2019 22:12:03 +0000 (UTC) List-Id: "Development of GNU Guix and the GNU System distribution." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-devel-bounces+gcggd-guix-devel=m.gmane.org@gnu.org Sender: "Guix-devel" To: guix-devel@gnu.org --MP_/X/.FUkBbc7H7NFs4QlGqUSh Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Content-Disposition: inline Hi Guix! Today I have been reading https://www.divio.com/blog/documentation/ which makes some good points on how to write good documentation. They suggest to divide documentation into four categories, depending on their purpose: - tutorials, written for newcomers. They should be to the point and guide a new user through every step of using the new system. - how-tos. They should be "goal-oriented" and allow a user who knows what they want to do, to learn how to do it. - explanations. They are more theoretical and should give more knowledge on how it all works. - reference. It should contain all the technical details of the code. Following these principles, I propose the attached patch, that changes the layout a bit. Instead of grouping articles by topic, I suggest grouping them by one of the first three categories above (the guix manual is the reference, and it's excellent, so we don't need a reference documentation in the cookbook). First, we have tutorials. We are missing a few things, but I imagine the following structure: start with a tutorial on guix, the package manager (helping a newcomer installing guix on a foreign distribution and taking their first steps with guix: install, remove, pull, upgrade). Then, we would propose the user to continue reading the tutorial on installing the guix system, or the guides on more advanced topics in package management. Then, a tutorial on the guix system will help the user install and understand the basic concepts of the system, for instance by installing it first in a virtual machine, then guiding them through their first install using the graphical installer. At the end, we would recommend them to continue with the scheme tutorial, because their configuration is actually a scheme file, and they could get more power by learning scheme. Or they could continue on to the guides on how to configure specific things. Then the scheme tutorial and the packaging tutorial we already have. The second part of the cookbook would be a bunch of how-tos, this time grouped by target audience (almost topics): package manager users, system users and packagers. That's where we would have things like "how to reproduce a scientific paper", "how to develop a software using guix", "how to configure my locales", "how to install on Android", "how to install the system on an ARM board", etc. I think this will be the biggest part of the cookbook, so I propose to directly have three chapters for it instead of one with three parts. The last part would be some discussions on how Guix works, what it is. This is currently empty, but I think it would make sense to discuss what a profile is, show how profile generations are symlinks, how the gc works, why the store is read-only, what is the relation between Guix and Docker (a recent discussion on the list), why does "guix pull" create a separate profile, and so on. I think having such a plan will also help us see what is missing and how to improve the cookbook concretely. Does it make sense? --MP_/X/.FUkBbc7H7NFs4QlGqUSh Content-Type: text/x-patch Content-Transfer-Encoding: quoted-printable Content-Disposition: attachment; filename=0001-doc-cookbook-Rework-layout.patch =46rom 270c835af7ca3cb214c990048f3f73f049cb80da Mon Sep 17 00:00:00 2001 From: Julien Lepiller Date: Tue, 26 Nov 2019 22:45:59 +0100 Subject: [PATCH] doc: cookbook: Rework layout. * doc/guix-cookbook.texi: Rework layout of articles. --- doc/guix-cookbook.texi | 784 ++++++++++++++++++++++------------------- 1 file changed, 414 insertions(+), 370 deletions(-) diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi index 869b9666df..4e6418b67d 100644 --- a/doc/guix-cookbook.texi +++ b/doc/guix-cookbook.texi @@ -43,9 +43,24 @@ Documentation License''. @top GNU Guix Cookbook =20 This document presents tutorials and detailed examples for GNU@tie{}Guix, a -functional package management tool written for the GNU system. Please -@pxref{Top,,, guix, GNU Guix reference manual} for details about the syste= m, -its API, and related concepts. +functional package management tool written for the GNU system. It is divi= ded +into three main parts: a section on tutorials that will guide you through = your +first experience with the package manager and many of its basic concepts. + +If you are a more experienced user, the second section of this document is= for +you: it contains a list of how-to guides that will guide you through more +advanced and detailed examples of how to use Guix. This section is further +divided into more parts, depending on your profile: whether you are a user= of +the package manager, the distribution or a developper, you will find infor= mation +on what you want to achieve here. + +If you are more interested in the concepts behind Guix, how it works inter= nally, +we recommend that you read the third section of this document. It contain= s various +explanations on Guix, and more theoretical concepts are discussed in this = section. + +If you are an advanced user of Guix and you want to learn everything that = Guix +can offer you, please @pxref{Top,,, guix, GNU Guix reference manual} for d= etails +about the system, its API, and related concepts. =20 @c TRANSLATORS: You can replace the following paragraph with information on @c how to join your own translation team and how to report issues with the @@ -54,11 +69,17 @@ If you would like to translate this document in your na= tive language, consider joining the @uref{https://translationproject.org/domain/guix-cookbook.html, Translation Project}. =20 +We hope that this document will help you in your journey learning about Gu= ix +and its concepts. If you spot any inaccuracy, error or misspelling in this +document, please report them so we can fix them quickly! Preferably, send= an +email to help-guix@@gnu.org. + @menu -* Scheme tutorials:: Meet your new favorite language! -* Packaging:: Packaging tutorials -* System Configuration:: Customizing the GNU System +* Tutorials:: Your journey starts here! * Advanced package management:: Power to the users! +* Advanced System Configuration:: Customizing the GNU System +* Advanced Packaging:: Guides for packagers +* Theory and Practice:: How it all works =20 * Acknowledgments:: Thanks! * GNU Free Documentation License:: The license of this document. @@ -67,40 +88,54 @@ Translation Project}. @detailmenu --- The Detailed Node Listing --- =20 -Scheme tutorials +Tutorials =20 * A Scheme Crash Course:: Learn the basics of Scheme - -Packaging - * Packaging Tutorial:: Let's add a package to Guix! =20 -System Configuration +Advanced System Configuration =20 -* Customizing the Kernel:: Creating and using a custom Linux kernel +* How to Customize the Kernel:: Creating and using a custom Linux kernel =20 +Advanced Packaging + +* Guix Profiles in Practice:: Strategies for multiple profiles and manif= ests. =20 @end detailmenu @end menu =20 @c ********************************************************************* -@node Scheme tutorials -@chapter Scheme tutorials - -GNU@tie{}Guix is written in the general purpose programming language Schem= e, -and many of its features can be accessed and manipulated programmatically. -You can use Scheme to generate package definitions, to modify them, to bui= ld -them, to deploy whole operating systems, etc. +@node Tutorials +@chapter Tutorials + +Welcome to the tutorial section of this document! These tutorials will gu= ide +you in your first steps with Guix and its various facets. You do not need +to follow these tutorials in any particular order, and you can skip those = you +don't want to learn about. + +GNU@tie{}Guix is a package manager designed to respect user freedom. Guix= can +be used on top of any system running the kernel Linux, or it can be used a= s a +standalone operating system distribution. GNU@tie{}Guix is written in the +general purpose programming language Scheme, and many of its features can = be +accessed and manipulated programmatically. You can use Scheme to generate +package definitions, to modify them, to build them, to deploy whole operat= ing +systems, etc. =20 Knowing the basics of how to program in Scheme will unlock many of the advanced features Guix provides --- and you don't even need to be an -experienced programmer to use them! +experienced programmer to use them! Start with @ref{A=C2=A0Scheme Crash C= ourse} +if you are new to Guile. + +Guix wouldn't exist without its volunteer packagers, dedicated at maintain= ing +and augmenting a package set of more than 10,000 packages! You can also l= earn +how to package your own packages with the @ref{Packaging Tutorial}. Who k= nows? +You might even enjoy contributing some of these to Guix itself! =20 Let's get started! =20 +@c ********************************************************************* @node A Scheme Crash Course @section A Scheme Crash Course - @cindex Scheme, crash course =20 Guix uses the Guile implementation of Scheme. To start playing with the @@ -278,22 +313,9 @@ You'll find more books, tutorials and other resources = at =20 =20 @c ********************************************************************* -@node Packaging -@chapter Packaging - -@cindex packaging - -This chapter is dedicated to teaching you how to add packages to the -collection of packages that come with GNU Guix. This involves writing pac= kage -definitions in Guile Scheme, organizing them in package modules, and build= ing -them. - -@menu -* Packaging Tutorial:: A tutorial on how to add packages to Guix. -@end menu - @node Packaging Tutorial @section Packaging Tutorial +@cindex packaging =20 GNU Guix stands out as the @emph{hackable} package manager, mostly because= it uses @uref{https://www.gnu.org/software/guile/, GNU Guile}, a powerful @@ -1303,372 +1325,117 @@ The @uref{https://www.gnu.org/software/guix/manua= l/en/html_node/Defining-Package @end itemize =20 @c ********************************************************************* -@node System Configuration -@chapter System Configuration +@node Advanced package management +@chapter Advanced package management =20 -Guix offers a flexible language for declaratively configuring your Guix -System. This flexibility can at times be overwhelming. The purpose of th= is -chapter is to demonstrate some advanced configuration concepts. +Guix is a functional package manager that offers many features beyond +what more traditional package managers can do. To the uninitiated, +those features might not have obvious use cases at first. The purpose +of this chapter is to demonstrate some advanced package management +concepts. =20 -@pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a comp= lete +@pxref{Package Management,,, guix, GNU Guix Reference Manual} for a comple= te reference. =20 @menu -* Customizing the Kernel:: Creating and using a custom Linux kernel on= Guix System. +* Guix Profiles in Practice:: Strategies for multiple profiles and man= ifests. @end menu =20 -@node Customizing the Kernel -@section Customizing the Kernel - -Guix is, at its core, a source based distribution with substitutes -(@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such buil= ding -packages from their source code is an expected part of regular package -installations and upgrades. Given this starting point, it makes sense that -efforts are made to reduce the amount of time spent compiling packages, and -recent changes and upgrades to the building and distribution of substitutes -continues to be a topic of discussion within Guix. +@node Guix Profiles in Practice +@section Guix Profiles in Practice =20 -The kernel, while not requiring an overabundance of RAM to build, does tak= e a -rather long time on an average machine. The official kernel configuration= , as -is the case with many GNU/Linux distributions, errs on the side of -inclusiveness, and this is really what causes the build to take such a long -time when the kernel is built from source. +Guix provides a very useful feature that may be quite foreign to newcomers: +@emph{profiles}. They are a way to group package installations together a= nd all users +on the same system are free to use as many profiles as they want. =20 -The Linux kernel, however, can also just be described as a regular old -package, and as such can be customized just like any other package. The -procedure is a little bit different, although this is primarily due to the -nature of how the package definition is written. +Whether you're a developer or not, you may find that multiple profiles bri= ng you +great power and flexibility. While they shift the paradigm somewhat compa= red to +@emph{traditional package managers}, they are very convenient to use once = you've +understood how to set them up. =20 -The @code{linux-libre} kernel package definition is actually a procedure w= hich -creates a package. +If you are familiar with Python's @samp{virtualenv}, you can think of a pr= ofile as a +kind of universal @samp{virtualenv} that can hold any kind of software wha= tsoever, not +just Python software. Furthermore, profiles are self-sufficient: they cap= ture +all the runtime dependencies which guarantees that all programs within a p= rofile +will always work at any point in time. =20 -@lisp -(define* (make-linux-libre version hash supported-systems - #:key - ;; A function that takes an arch and a variant. - ;; See kernel-config for an example. - (extra-version #f) - (configuration-file #f) - (defconfig "defconfig") - (extra-options %default-extra-linux-options) - (patches (list %boot-logo-patch))) - ...) -@end lisp +Multiple profiles have many benefits: =20 -The current @code{linux-libre} package is for the 5.1.x series, and is -declared like this: +@itemize +@item +Clean semantic separation of the various packages a user needs for differe= nt contexts. =20 -@lisp -(define-public linux-libre - (make-linux-libre %linux-libre-version - %linux-libre-hash - '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-l= inux") - #:patches %linux-libre-5.1-patches - #:configuration-file kernel-config)) -@end lisp +@item +Multiple profiles can be made available into the environment either on log= in +or within a dedicated shell. =20 -Any keys which are not assigned values inherit their default value from the -@code{make-linux-libre} definition. When comparing the two snippets above, -you may notice that the code comment in the first doesn't actually refer to -the @code{#:extra-version} keyword; it is actually for -@code{#:configuration-file}. Because of this, it is not actually easy to -include a custom kernel configuration from the definition, but don't worry, -there are other ways to work with what we do have. +@item +Profiles can be loaded on demand. For instance, the user can use multiple +shells, each of them running different profiles. =20 -There are two ways to create a kernel with a custom kernel configuration. = The -first is to provide a standard @file{.config} file during the build proces= s by -including an actual @file{.config} file as a native input to our custom -kernel. The following is a snippet from the custom @code{'configure} phas= e of -the @code{make-linux-libre} package definition: +@item +Isolation: Programs from one profile will not use programs from the other,= and +the user can even install different versions of the same programs to the t= wo +profiles without conflict. =20 -@lisp -(let ((build (assoc-ref %standard-phases 'build)) - (config (assoc-ref (or native-inputs inputs) "kconfig"))) +@item +Deduplication: Profiles share dependencies that happens to be the exact sa= me. +This makes multiple profiles storage-efficient. =20 - ;; Use a custom kernel configuration file or a default - ;; configuration file. - (if config - (begin - (copy-file config ".config") - (chmod ".config" #o666)) - (invoke "make" ,defconfig)) -@end lisp +@item +Reproducible: when used with declarative manifests, a profile can be fully +specified by the Guix commit that was active when it was set up. This mea= ns +that the exact same profile can be +@uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-ro= llbacks-oh-my/, +set up anywhere and anytime}, with just the commit information. See the +section on @ref{Reproducible profiles}. =20 -Below is a sample kernel package. The @code{linux-libre} package is nothi= ng -special and can be inherited from and have its fields overridden like any -other package: +@item +Easier upgrades and maintenance: Multiple profiles make it easy to keep +package listings at hand and make upgrades completely friction-less. +@end itemize =20 -@lisp -(define-public linux-libre/E2140 - (package - (inherit linux-libre) - (native-inputs - `(("kconfig" ,(local-file "E2140.config")) - ,@@(alist-delete "kconfig" - (package-native-inputs linux-libre)))))) -@end lisp +Concretely, here follows some typical profiles: =20 -In the same directory as the file defining @code{linux-libre-E2140} is a f= ile -named @file{E2140.config}, which is an actual kernel configuration file. = The -@code{defconfig} keyword of @code{make-linux-libre} is left blank here, so= the -only kernel configuration in the package is the one which was included in = the -@code{native-inputs} field. +@itemize +@item +The dependencies of a project you are working on. =20 -The second way to create a custom kernel is to pass a new value to the -@code{extra-options} keyword of the @code{make-linux-libre} procedure. The -@code{extra-options} keyword works with another function defined right bel= ow -it: +@item +Your favourite programming language libraries. =20 -@lisp -(define %default-extra-linux-options - `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html - ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t) - ;; Modules required for initrd: - ("CONFIG_NET_9P" . m) - ("CONFIG_NET_9P_VIRTIO" . m) - ("CONFIG_VIRTIO_BLK" . m) - ("CONFIG_VIRTIO_NET" . m) - ("CONFIG_VIRTIO_PCI" . m) - ("CONFIG_VIRTIO_BALLOON" . m) - ("CONFIG_VIRTIO_MMIO" . m) - ("CONFIG_FUSE_FS" . m) - ("CONFIG_CIFS" . m) - ("CONFIG_9P_FS" . m))) +@item +Laptop-specific programs (like @samp{powertop}) that you don't need on a d= esktop. =20 -(define (config->string options) - (string-join (map (match-lambda - ((option . 'm) - (string-append option "=3Dm")) - ((option . #t) - (string-append option "=3Dy")) - ((option . #f) - (string-append option "=3Dn"))) - options) - "\n")) -@end lisp +@item +@TeX{}live (this one can be really useful when you need to install just one +package for this one document you've just received over email). =20 -And in the custom configure script from the `make-linux-libre` package: +@item +Games. +@end itemize =20 -@lisp -;; Appending works even when the option wasn't in the -;; file. The last one prevails if duplicated. -(let ((port (open-file ".config" "a")) - (extra-configuration ,(config->string extra-options))) - (display extra-configuration port) - (close-port port)) +Let's dive in the set up! =20 -(invoke "make" "oldconfig")))) -@end lisp +@node Basic setup with manifests +@subsection Basic setup with manifests =20 -So by not providing a configuration-file the @file{.config} starts blank, = and -then we write into it the collection of flags that we want. Here's another -custom kernel: +A Guix profile can be set up @emph{via} a so-called @emph{manifest specifi= cation} that looks like +this: =20 @lisp -(define %macbook41-full-config - (append %macbook41-config-options - %filesystems - %efi-support - %emulation - (@@@@ (gnu packages linux) %default-extra-linux-options))) - -(define-public linux-libre-macbook41 - ;; XXX: Access the internal 'make-linux-libre' procedure, which is - ;; private and unexported, and is liable to change in the future. - ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux)= %linux-libre-version) - (@@@@ (gnu packages linux) %linux-libre-hash) - '("x86_64-linux") - #:extra-version "macbook41" - #:patches (@@@@ (gnu packages linux) %linux-libre-5.= 1-patches) - #:extra-options %macbook41-config-options)) +(specifications->manifest + '("package-1" + ;; Version 1.3 of package-2. + "package-2@@1.3" + ;; The "lib" output of package-3. + "package-3:lib" + ; ... + "package-N")) @end lisp =20 -In the above example @code{%filesystems} is a collection of flags enabling -different filesystem support, @code{%efi-support} enables EFI support and -@code{%emulation} enables a x86_64-linux machine to act in 32-bit mode als= o. -@code{%default-extra-linux-options} are the ones quoted above, which had t= o be -added in since they were replaced in the @code{extra-options} keyword. - -This all sounds like it should be doable, but how does one even know which -modules are required for a particular system? Two places that can be help= ful -in trying to answer this question is the -@uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gen= too -Handbook} and the -@uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highl= ight=3Dlocalmodconfig, -documentation from the kernel itself}. From the kernel documentation, it -seems that @code{make localmodconfig} is the command we want. - -In order to actually run @code{make localmodconfig} we first need to get a= nd -unpack the kernel source code: - -@example shell -tar xf $(guix build linux-libre --source) -@end example - -Once inside the directory containing the source code run @code{touch .conf= ig} -to create an initial, empty @file{.config} to start with. @code{make -localmodconfig} works by seeing what you already have in @file{.config} and -letting you know what you're missing. If the file is blank then you're -missing everything. The next step is to run: - -@example shell -guix environment linux-libre -- make localmodconfig -@end example - -and note the output. Do note that the @file{.config} file is still empty. -The output generally contains two types of warnings. The first start with -"WARNING" and can actually be ignored in our case. The second read: - -@example shell -module pcspkr did not have configs CONFIG_INPUT_PCSPKR -@end example - -For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the -@file{.config} in the directory, and append @code{=3Dm}, so in the end it = looks -like this: - -@example shell -CONFIG_INPUT_PCSPKR=3Dm -CONFIG_VIRTIO=3Dm -@end example - -After copying all the configuration options, run @code{make localmodconfig} -again to make sure that you don't have any output starting with "module". -After all of these machine specific modules there are a couple more left t= hat -are also needed. @code{CONFIG_MODULES} is necessary so that you can build= and -load modules separately and not have everything built into the kernel. -@code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is -possible that there are other modules which you will need. - -This post does not aim to be a guide to configuring your own kernel howeve= r, -so if you do decide to build a custom kernel you'll have to seek out other -guides to create a kernel which is just right for your needs. - -The second way to setup the kernel configuration makes more use of Guix's -features and allows you to share configuration segments between different -kernels. For example, all machines using EFI to boot have a number of EFI -configuration flags that they need. It is likely that all the kernels will -share a list of filesystems to support. By using variables it is easier to -see at a glance what features are enabled and to make sure you don't have -features in one kernel but missing in another. - -Left undiscussed however, is Guix's initrd and its customization. It is -likely that you'll need to modify the initrd on a machine using a custom -kernel, since certain modules which are expected to be built may not be -available for inclusion into the initrd. - -@c ********************************************************************* -@node Advanced package management -@chapter Advanced package management - -Guix is a functional package manager that offers many features beyond -what more traditional package managers can do. To the uninitiated, -those features might not have obvious use cases at first. The purpose -of this chapter is to demonstrate some advanced package management -concepts. - -@pxref{Package Management,,, guix, GNU Guix Reference Manual} for a comple= te -reference. - -@menu -* Guix Profiles in Practice:: Strategies for multiple profiles and man= ifests. -@end menu - -@node Guix Profiles in Practice -@section Guix Profiles in Practice - -Guix provides a very useful feature that may be quite foreign to newcomers: -@emph{profiles}. They are a way to group package installations together a= nd all users -on the same system are free to use as many profiles as they want. - -Whether you're a developer or not, you may find that multiple profiles bri= ng you -great power and flexibility. While they shift the paradigm somewhat compa= red to -@emph{traditional package managers}, they are very convenient to use once = you've -understood how to set them up. - -If you are familiar with Python's @samp{virtualenv}, you can think of a pr= ofile as a -kind of universal @samp{virtualenv} that can hold any kind of software wha= tsoever, not -just Python software. Furthermore, profiles are self-sufficient: they cap= ture -all the runtime dependencies which guarantees that all programs within a p= rofile -will always work at any point in time. - -Multiple profiles have many benefits: - -@itemize -@item -Clean semantic separation of the various packages a user needs for differe= nt contexts. - -@item -Multiple profiles can be made available into the environment either on log= in -or within a dedicated shell. - -@item -Profiles can be loaded on demand. For instance, the user can use multiple -shells, each of them running different profiles. - -@item -Isolation: Programs from one profile will not use programs from the other,= and -the user can even install different versions of the same programs to the t= wo -profiles without conflict. - -@item -Deduplication: Profiles share dependencies that happens to be the exact sa= me. -This makes multiple profiles storage-efficient. - -@item -Reproducible: when used with declarative manifests, a profile can be fully -specified by the Guix commit that was active when it was set up. This mea= ns -that the exact same profile can be -@uref{https://guix.gnu.org/blog/2018/multi-dimensional-transactions-and-ro= llbacks-oh-my/, -set up anywhere and anytime}, with just the commit information. See the -section on @ref{Reproducible profiles}. - -@item -Easier upgrades and maintenance: Multiple profiles make it easy to keep -package listings at hand and make upgrades completely friction-less. -@end itemize - -Concretely, here follows some typical profiles: - -@itemize -@item -The dependencies of a project you are working on. - -@item -Your favourite programming language libraries. - -@item -Laptop-specific programs (like @samp{powertop}) that you don't need on a d= esktop. - -@item -@TeX{}live (this one can be really useful when you need to install just one -package for this one document you've just received over email). - -@item -Games. -@end itemize - -Let's dive in the set up! - -@node Basic setup with manifests -@subsection Basic setup with manifests - -A Guix profile can be set up @emph{via} a so-called @emph{manifest specifi= cation} that looks like -this: - -@lisp -(specifications->manifest - '("package-1" - ;; Version 1.3 of package-2. - "package-2@@1.3" - ;; The "lib" output of package-3. - "package-3:lib" - ; ... - "package-N")) -@end lisp - -@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for -the syntax details. +@pxref{Invoking guix package,,, guix, GNU Guix Reference Manual}, for +the syntax details. =20 We can create a manifest specification per profile and install them this w= ay: =20 @@ -1955,6 +1722,283 @@ mkdir -p "$GUIX_EXTRA_PROFILES/my-project" It's safe to delete the Guix channel profile you've just installed with the channel specification, the project profile does not depend on it. =20 +@node Advanced System Configuration +@chapter Advanced System Configuration + +Guix offers a flexible language for declaratively configuring your Guix +System. This flexibility can at times be overwhelming. The purpose of th= is +chapter is to demonstrate some advanced configuration concepts. + +@pxref{System Configuration,,, guix, GNU Guix Reference Manual} for a comp= lete +reference. + +@menu +* How to Customize the Kernel:: Creating and using a custom Linux kernel = on Guix System. +@end menu + +@node How to Customize the Kernel +@section How to Customize the Kernel + +Guix is, at its core, a source based distribution with substitutes +(@pxref{Substitutes,,, guix, GNU Guix Reference Manual}), and as such buil= ding +packages from their source code is an expected part of regular package +installations and upgrades. Given this starting point, it makes sense that +efforts are made to reduce the amount of time spent compiling packages, and +recent changes and upgrades to the building and distribution of substitutes +continues to be a topic of discussion within Guix. + +The kernel, while not requiring an overabundance of RAM to build, does tak= e a +rather long time on an average machine. The official kernel configuration= , as +is the case with many GNU/Linux distributions, errs on the side of +inclusiveness, and this is really what causes the build to take such a long +time when the kernel is built from source. + +The Linux kernel, however, can also just be described as a regular old +package, and as such can be customized just like any other package. The +procedure is a little bit different, although this is primarily due to the +nature of how the package definition is written. + +The @code{linux-libre} kernel package definition is actually a procedure w= hich +creates a package. + +@lisp +(define* (make-linux-libre version hash supported-systems + #:key + ;; A function that takes an arch and a variant. + ;; See kernel-config for an example. + (extra-version #f) + (configuration-file #f) + (defconfig "defconfig") + (extra-options %default-extra-linux-options) + (patches (list %boot-logo-patch))) + ...) +@end lisp + +The current @code{linux-libre} package is for the 5.1.x series, and is +declared like this: + +@lisp +(define-public linux-libre + (make-linux-libre %linux-libre-version + %linux-libre-hash + '("x86_64-linux" "i686-linux" "armhf-linux" "aarch64-l= inux") + #:patches %linux-libre-5.1-patches + #:configuration-file kernel-config)) +@end lisp + +Any keys which are not assigned values inherit their default value from the +@code{make-linux-libre} definition. When comparing the two snippets above, +you may notice that the code comment in the first doesn't actually refer to +the @code{#:extra-version} keyword; it is actually for +@code{#:configuration-file}. Because of this, it is not actually easy to +include a custom kernel configuration from the definition, but don't worry, +there are other ways to work with what we do have. + +There are two ways to create a kernel with a custom kernel configuration. = The +first is to provide a standard @file{.config} file during the build proces= s by +including an actual @file{.config} file as a native input to our custom +kernel. The following is a snippet from the custom @code{'configure} phas= e of +the @code{make-linux-libre} package definition: + +@lisp +(let ((build (assoc-ref %standard-phases 'build)) + (config (assoc-ref (or native-inputs inputs) "kconfig"))) + + ;; Use a custom kernel configuration file or a default + ;; configuration file. + (if config + (begin + (copy-file config ".config") + (chmod ".config" #o666)) + (invoke "make" ,defconfig)) +@end lisp + +Below is a sample kernel package. The @code{linux-libre} package is nothi= ng +special and can be inherited from and have its fields overridden like any +other package: + +@lisp +(define-public linux-libre/E2140 + (package + (inherit linux-libre) + (native-inputs + `(("kconfig" ,(local-file "E2140.config")) + ,@@(alist-delete "kconfig" + (package-native-inputs linux-libre)))))) +@end lisp + +In the same directory as the file defining @code{linux-libre-E2140} is a f= ile +named @file{E2140.config}, which is an actual kernel configuration file. = The +@code{defconfig} keyword of @code{make-linux-libre} is left blank here, so= the +only kernel configuration in the package is the one which was included in = the +@code{native-inputs} field. + +The second way to create a custom kernel is to pass a new value to the +@code{extra-options} keyword of the @code{make-linux-libre} procedure. The +@code{extra-options} keyword works with another function defined right bel= ow +it: + +@lisp +(define %default-extra-linux-options + `(;; https://lists.gnu.org/archive/html/guix-devel/2014-04/msg00039.html + ("CONFIG_DEVPTS_MULTIPLE_INSTANCES" . #t) + ;; Modules required for initrd: + ("CONFIG_NET_9P" . m) + ("CONFIG_NET_9P_VIRTIO" . m) + ("CONFIG_VIRTIO_BLK" . m) + ("CONFIG_VIRTIO_NET" . m) + ("CONFIG_VIRTIO_PCI" . m) + ("CONFIG_VIRTIO_BALLOON" . m) + ("CONFIG_VIRTIO_MMIO" . m) + ("CONFIG_FUSE_FS" . m) + ("CONFIG_CIFS" . m) + ("CONFIG_9P_FS" . m))) + +(define (config->string options) + (string-join (map (match-lambda + ((option . 'm) + (string-append option "=3Dm")) + ((option . #t) + (string-append option "=3Dy")) + ((option . #f) + (string-append option "=3Dn"))) + options) + "\n")) +@end lisp + +And in the custom configure script from the `make-linux-libre` package: + +@lisp +;; Appending works even when the option wasn't in the +;; file. The last one prevails if duplicated. +(let ((port (open-file ".config" "a")) + (extra-configuration ,(config->string extra-options))) + (display extra-configuration port) + (close-port port)) + +(invoke "make" "oldconfig")))) +@end lisp + +So by not providing a configuration-file the @file{.config} starts blank, = and +then we write into it the collection of flags that we want. Here's another +custom kernel: + +@lisp +(define %macbook41-full-config + (append %macbook41-config-options + %filesystems + %efi-support + %emulation + (@@@@ (gnu packages linux) %default-extra-linux-options))) + +(define-public linux-libre-macbook41 + ;; XXX: Access the internal 'make-linux-libre' procedure, which is + ;; private and unexported, and is liable to change in the future. + ((@@@@ (gnu packages linux) make-linux-libre) (@@@@ (gnu packages linux)= %linux-libre-version) + (@@@@ (gnu packages linux) %linux-libre-hash) + '("x86_64-linux") + #:extra-version "macbook41" + #:patches (@@@@ (gnu packages linux) %linux-libre-5.= 1-patches) + #:extra-options %macbook41-config-options)) +@end lisp + +In the above example @code{%filesystems} is a collection of flags enabling +different filesystem support, @code{%efi-support} enables EFI support and +@code{%emulation} enables a x86_64-linux machine to act in 32-bit mode als= o. +@code{%default-extra-linux-options} are the ones quoted above, which had t= o be +added in since they were replaced in the @code{extra-options} keyword. + +This all sounds like it should be doable, but how does one even know which +modules are required for a particular system? Two places that can be help= ful +in trying to answer this question is the +@uref{https://wiki.gentoo.org/wiki/Handbook:AMD64/Installation/Kernel, Gen= too +Handbook} and the +@uref{https://www.kernel.org/doc/html/latest/admin-guide/README.html?highl= ight=3Dlocalmodconfig, +documentation from the kernel itself}. From the kernel documentation, it +seems that @code{make localmodconfig} is the command we want. + +In order to actually run @code{make localmodconfig} we first need to get a= nd +unpack the kernel source code: + +@example shell +tar xf $(guix build linux-libre --source) +@end example + +Once inside the directory containing the source code run @code{touch .conf= ig} +to create an initial, empty @file{.config} to start with. @code{make +localmodconfig} works by seeing what you already have in @file{.config} and +letting you know what you're missing. If the file is blank then you're +missing everything. The next step is to run: + +@example shell +guix environment linux-libre -- make localmodconfig +@end example + +and note the output. Do note that the @file{.config} file is still empty. +The output generally contains two types of warnings. The first start with +"WARNING" and can actually be ignored in our case. The second read: + +@example shell +module pcspkr did not have configs CONFIG_INPUT_PCSPKR +@end example + +For each of these lines, copy the @code{CONFIG_XXXX_XXXX} portion into the +@file{.config} in the directory, and append @code{=3Dm}, so in the end it = looks +like this: + +@example shell +CONFIG_INPUT_PCSPKR=3Dm +CONFIG_VIRTIO=3Dm +@end example + +After copying all the configuration options, run @code{make localmodconfig} +again to make sure that you don't have any output starting with "module". +After all of these machine specific modules there are a couple more left t= hat +are also needed. @code{CONFIG_MODULES} is necessary so that you can build= and +load modules separately and not have everything built into the kernel. +@code{CONFIG_BLK_DEV_SD} is required for reading from hard drives. It is +possible that there are other modules which you will need. + +This post does not aim to be a guide to configuring your own kernel howeve= r, +so if you do decide to build a custom kernel you'll have to seek out other +guides to create a kernel which is just right for your needs. + +The second way to setup the kernel configuration makes more use of Guix's +features and allows you to share configuration segments between different +kernels. For example, all machines using EFI to boot have a number of EFI +configuration flags that they need. It is likely that all the kernels will +share a list of filesystems to support. By using variables it is easier to +see at a glance what features are enabled and to make sure you don't have +features in one kernel but missing in another. + +Left undiscussed however, is Guix's initrd and its customization. It is +likely that you'll need to modify the initrd on a machine using a custom +kernel, since certain modules which are expected to be built may not be +available for inclusion into the initrd. + +@c ********************************************************************* +@node Advanced Packaging +@chapter Advanced Packaging + +One of the goals of GNU@tie{}Guix as a package manager is to provide users= with +facilities to create their own packages. This section is dedicated to gui= des +on how to perform some packaging tasks that are not covered by the packagi= ng +tutorial. + +This section is currently empty. We appreciate any help you can provide! + +@c ********************************************************************* +@node Theory and Practice +@chapter Theory and Practice + +GNU@tie{}Guix uses many theoretical concepts and has a very unique way of +working that can be very puzzling to people used to more traditional forms +of package management. This section will teach you all the theoretical +knowledge, implementation choices and inner workings of Guix that you need +to fully grasp it. + +This section is currently empty. We appreciate any help you can provide! + @c ********************************************************************* @node Acknowledgments @chapter Acknowledgments --=20 2.24.0 --MP_/X/.FUkBbc7H7NFs4QlGqUSh--