diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 2741 |
1 files changed, 1224 insertions, 1517 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index c3a126fe2e..e94204f69f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -17,7 +17,7 @@ @set SUBSTITUTE-SERVER ci.guix.info @copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic Courtès@* +Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015, 2016 Alex Kost@* @@ -25,7 +25,7 @@ Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@* -Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@* +Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@* @@ -117,10 +117,16 @@ Project}. @menu * Introduction:: What is Guix about? * Installation:: Installing Guix. +* System Installation:: Installing the whole operating system. * Package Management:: Package installation, upgrade, etc. * Programming Interface:: Using Guix in Scheme. * Utilities:: Package management commands. -* GNU Distribution:: Software for your friendly GNU system. +* System Configuration:: Configuring the operating system. +* Documentation:: Browsing software user manuals. +* Installing Debugging Files:: Feeding the debugger. +* Security Updates:: Deploying security fixes quickly. +* Bootstrapping:: GNU/Linux built from scratch. +* Porting:: Targeting another platform or kernel. * Contributing:: Your help needed! * Acknowledgments:: Thanks! @@ -146,6 +152,16 @@ Setting Up the Daemon * Daemon Offload Setup:: Offloading builds to remote machines. * SELinux Support:: Using an SELinux policy for the daemon. +System Installation + +* Limitations:: What you can expect. +* Hardware Considerations:: Supported hardware. +* USB Stick and DVD Installation:: Preparing the installation medium. +* Preparing for Installation:: Networking, partitioning, etc. +* Proceeding with the Installation:: The real thing. +* Installing Guix in a VM:: Guix System playground. +* Building the Installation Image:: How this comes to be. + Package Management * Features:: How Guix will make your life brighter. @@ -171,6 +187,7 @@ Substitutes Programming Interface +* Package Modules:: Packages from the programmer's viewpoint. * Defining Packages:: Defining new packages. * Build Systems:: Specifying how packages are built. * The Store:: Manipulating the package store. @@ -210,28 +227,6 @@ Invoking @command{guix build} * Additional Build Options:: Options specific to 'guix build'. * Debugging Build Failures:: Real life packaging experience. -GNU Distribution - -* System Installation:: Installing the whole operating system. -* System Configuration:: Configuring the operating system. -* Documentation:: Browsing software user manuals. -* Installing Debugging Files:: Feeding the debugger. -* Security Updates:: Deploying security fixes quickly. -* Package Modules:: Packages from the programmer's viewpoint. -* Packaging Guidelines:: Growing the distribution. -* Bootstrapping:: GNU/Linux built from scratch. -* Porting:: Targeting another platform or kernel. - -System Installation - -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Proceeding with the Installation:: The real thing. -* Installing GuixSD in a VM:: GuixSD playground. -* Building the Installation Image:: How this comes to be. - System Configuration * Using the Configuration System:: Customizing your GNU system. @@ -247,7 +242,7 @@ System Configuration * Initial RAM Disk:: Linux-Libre bootstrapping. * Bootloader Configuration:: Configuring the boot loader. * Invoking guix system:: Instantiating a system configuration. -* Running GuixSD in a VM:: How to run GuixSD in a virtual machine. +* Running Guix in a VM:: How to run Guix System in a virtual machine. * Defining Services:: Adding new service definitions. Services @@ -286,32 +281,6 @@ Defining Services * Service Reference:: API reference. * Shepherd Services:: A particular type of service. -Packaging Guidelines - -* Software Freedom:: What may go into the distribution. -* Package Naming:: What's in a name? -* Version Numbers:: When the name is not enough. -* Synopses and Descriptions:: Helping users find the right package. -* Python Modules:: A touch of British comedy. -* Perl Modules:: Little pearls. -* Java Packages:: Coffee break. -* Fonts:: Fond of fonts. - -Contributing - -* Building from Git:: The latest and greatest. -* Running Guix Before It Is Installed:: Hacker tricks. -* The Perfect Setup:: The right tools. -* Coding Style:: Hygiene of the contributor. -* Submitting Patches:: Share your work. - -Coding Style - -* Programming Paradigm:: How to compose your elements. -* Modules:: Where to store your code? -* Data Types and Pattern Matching:: Implementing data structures. -* Formatting Code:: Writing conventions. - @end detailmenu @end menu @@ -322,11 +291,27 @@ Coding Style @cindex purpose GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using the international phonetic alphabet (IPA).} is a package -management tool for the GNU system. Guix makes it easy for unprivileged -users to install, upgrade, or remove packages, to roll back to a +management tool for and distribution of the GNU system. +Guix makes it easy for unprivileged +users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments. +@cindex Guix System +@cindex GuixSD, now Guix System +@cindex Guix System Distribution, now Guix System +You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it +complements the available tools without interference (@pxref{Installation}), +or you can use it as a standalone operating system distribution, +@dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix +System Distribution'' or ``GuixSD''. We now consider it makes more sense to +group everything under the ``Guix'' banner since, after all, Guix System is +readily available through the @command{guix system} command, even if you're +using a different distro underneath!}. @xref{GNU Distribution}. + +@node Managing Software the Guix Way +@section Managing Software the Guix Way + @cindex user interfaces Guix provides a command-line package management interface (@pxref{Invoking guix package}), a set of command-line utilities @@ -348,17 +333,6 @@ is also @emph{customizable}: users can @emph{derive} specialized package definitions from existing ones, including from the command line (@pxref{Package Transformation Options}). -@cindex Guix System Distribution -@cindex GuixSD -You can install GNU@tie{}Guix on top of an existing GNU/Linux system -where it complements the available tools without interference -(@pxref{Installation}), or you can use it as part of the standalone -@dfn{Guix System Distribution} or GuixSD (@pxref{GNU Distribution}). -With GNU@tie{}GuixSD, you @emph{declare} all aspects of the operating -system configuration and Guix takes care of instantiating the -configuration in a transactional, reproducible, and stateless fashion -(@pxref{System Configuration}). - @cindex functional package management @cindex isolation Under the hood, Guix implements the @dfn{functional package management} @@ -389,34 +363,113 @@ for transactional package upgrade and rollback, per-user installation, and garbage collection of packages (@pxref{Features}). +@node GNU Distribution +@section GNU Distribution + +@cindex Guix System +Guix comes with a distribution of the GNU system consisting entirely of +free software@footnote{The term ``free'' here refers to the +@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to +users of that software}.}. The +distribution can be installed on its own (@pxref{System Installation}), +but it is also possible to install Guix as a package manager on top of +an installed GNU/Linux system (@pxref{Installation}). When we need to +distinguish between the two, we refer to the standalone distribution as +Guix@tie{}System. + +The distribution provides core GNU packages such as GNU libc, GCC, and +Binutils, as well as many GNU and non-GNU applications. The complete +list of available packages can be browsed +@url{http://www.gnu.org/software/guix/packages,on-line} or by +running @command{guix package} (@pxref{Invoking guix package}): + +@example +guix package --list-available +@end example + +Our goal is to provide a practical 100% free software distribution of +Linux-based and other variants of GNU, with a focus on the promotion and +tight integration of GNU components, and an emphasis on programs and +tools that help users exert that freedom. + +Packages are currently available on the following platforms: + +@table @code + +@item x86_64-linux +Intel/AMD @code{x86_64} architecture, Linux-Libre kernel; + +@item i686-linux +Intel 32-bit architecture (IA32), Linux-Libre kernel; + +@item armhf-linux +ARMv7-A architecture with hard float, Thumb-2 and NEON, +using the EABI hard-float application binary interface (ABI), +and Linux-Libre kernel. + +@item aarch64-linux +little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is +currently in an experimental stage, with limited support. +@xref{Contributing}, for how to help! + +@item mips64el-linux +little-endian 64-bit MIPS processors, specifically the Loongson series, +n32 ABI, and Linux-Libre kernel. + +@end table + +With Guix@tie{}System, you @emph{declare} all aspects of the operating system +configuration and Guix takes care of instantiating the configuration in a +transactional, reproducible, and stateless fashion (@pxref{System +Configuration}). Guix System uses the Linux-libre kernel, the Shepherd +initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd +Manual}), the well-known GNU utilities and tool chain, as well as the +graphical environment or system services of your choice. + +Guix System is available on all the above platforms except +@code{mips64el-linux}. + +@noindent +For information on porting to other architectures or kernels, +@pxref{Porting}. + +Building this distribution is a cooperative effort, and you are invited +to join! @xref{Contributing}, for information about how you can help. + + @c ********************************************************************* @node Installation @chapter Installation @cindex installing Guix -@cindex official website -GNU Guix is available for download from its website at -@url{http://www.gnu.org/software/guix/}. This section describes the -software requirements of Guix, as well as how to install it and get -ready to use it. -Note that this section is concerned with the installation of the package -manager, which can be done on top of a running GNU/Linux system. If, -instead, you want to install the complete GNU operating system, -@pxref{System Installation}. +@quotation Note +We recommend the use of this +@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, +shell installer script} to install Guix on top of a running GNU/Linux system, +thereafter called a @dfn{foreign distro}.@footnote{This section is concerned +with the installation of the package manager, which can be done on top of a +running GNU/Linux system. If, instead, you want to install the complete GNU +operating system, @pxref{System Installation}.} The script automates the +download, installation, and initial configuration of Guix. It should be run +as the root user. +@end quotation @cindex foreign distro @cindex directories related to foreign distro - -When installed on a running GNU/Linux system---thereafter called a -@dfn{foreign distro}---GNU@tie{}Guix complements the available tools -without interference. Its data lives exclusively in two directories, -usually @file{/gnu/store} and @file{/var/guix}; other files on your -system, such as @file{/etc}, are left untouched. +When installed on a foreign distro, GNU@tie{}Guix complements the available +tools without interference. Its data lives exclusively in two directories, +usually @file{/gnu/store} and @file{/var/guix}; other files on your system, +such as @file{/etc}, are left untouched. Once installed, Guix can be updated by running @command{guix pull} (@pxref{Invoking guix pull}). +If you prefer to perform the installation steps manually or want to tweak +them, you may find the following subsections useful. They describe the +software requirements of Guix, as well as how to install it manually and get +ready to use it. + @menu * Binary Installation:: Getting Guix running in no time! * Requirements:: Software needed to build and run Guix. @@ -437,11 +490,6 @@ dependencies. This is often quicker than installing from source, which is described in the next sections. The only requirement is to have GNU@tie{}tar and Xz. -We provide a -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script}, which automates the download, installation, and -initial configuration of Guix. It should be run as the root user. - Installing goes along these lines: @enumerate @@ -638,11 +686,14 @@ build procedure for Guix is the same as for other GNU software, and is not covered here. Please see the files @file{README} and @file{INSTALL} in the Guix source tree for additional details. +@cindex official website +GNU Guix is available for download from its website at +@url{https://www.gnu.org/software/guix/}. + GNU Guix depends on the following packages: @itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or -later, including 2.2.x; +@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version 0.1.0 or later; @item @@ -752,7 +803,7 @@ as well as version numbers of the dependencies (@pxref{Requirements}) in your message. Guix also comes with a whole-system test suite that tests complete -GuixSD operating system instances. It can only run on systems where +Guix System instances. It can only run on systems where Guix is already installed, using: @example @@ -1051,13 +1102,11 @@ name, and they will be scheduled on matching build machines. @end table @end deftp -The @code{guile} command must be in the search path on the build -machines. In addition, the Guix modules must be in -@code{$GUILE_LOAD_PATH} on the build machine---you can check whether -this is the case by running: +The @command{guix} command must be in the search path on the build +machines. You can check whether this is the case by running: @example -ssh build-machine guile -c "'(use-modules (guix config))'" +ssh build-machine guix repl --version @end example There is one last thing to do once @file{machines.scm} is in place. As @@ -1132,8 +1181,8 @@ main node: Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that can be installed on a system where SELinux is enabled, in order to label Guix files and to specify the expected behavior of the daemon. Since -GuixSD does not provide an SELinux base policy, the daemon policy cannot -be used on GuixSD. +Guix System does not provide an SELinux base policy, the daemon policy cannot +be used on Guix System. @subsubsection Installing the SELinux policy @cindex SELinux, policy installation @@ -1481,14 +1530,14 @@ connections on the Unix-domain socket located at @section Application Setup @cindex foreign distro -When using Guix on top of GNU/Linux distribution other than GuixSD---a +When using Guix on top of GNU/Linux distribution other than Guix System---a so-called @dfn{foreign distro}---a few additional steps are needed to get everything in place. Here are some of them. @subsection Locales @anchor{locales-and-locpath} -@cindex locales, when not on GuixSD +@cindex locales, when not on Guix System @vindex LOCPATH @vindex GUIX_LOCPATH Packages installed @i{via} Guix will not use the locale data of the @@ -1674,20 +1723,682 @@ including GCC itself, the GNU C Library (headers and binaries, plus debugging symbols in the @code{debug} output), Binutils, and a linker wrapper. -@cindex attempt to use impure library, error message - The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches passed to the linker, add corresponding @code{-rpath} arguments, and -invoke the actual linker with this new set of arguments. By default, -the linker wrapper refuses to link to libraries outside the store to -ensure ``purity''. This can be annoying when using the toolchain to -link with local libraries. To allow references to libraries outside the -store you need to define the environment variable -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}. +invoke the actual linker with this new set of arguments. You can instruct the +wrapper to refuse to link against libraries not in the store by setting the +@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. @c TODO What else? @c ********************************************************************* +@node System Installation +@chapter System Installation + +@cindex installing Guix System +@cindex Guix System, installation +This section explains how to install Guix System +on a machine. Guix, as a package manager, can +also be installed on top of a running GNU/Linux system, +@pxref{Installation}. + +@ifinfo +@quotation Note +@c This paragraph is for people reading this from tty2 of the +@c installation image. +You are reading this documentation with an Info reader. For details on +how to use it, hit the @key{RET} key (``return'' or ``enter'') on the +link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU +Info}. Hit @kbd{l} afterwards to come back here. + +Alternately, run @command{info info} in another tty to keep the manual +available. +@end quotation +@end ifinfo + +@menu +* Limitations:: What you can expect. +* Hardware Considerations:: Supported hardware. +* USB Stick and DVD Installation:: Preparing the installation medium. +* Preparing for Installation:: Networking, partitioning, etc. +* Proceeding with the Installation:: The real thing. +* Installing Guix in a VM:: Guix System playground. +* Building the Installation Image:: How this comes to be. +@end menu + +@node Limitations +@section Limitations + +As of version @value{VERSION}, Guix System is +not production-ready. It may contain bugs and lack important +features. Thus, if you are looking for a stable production system that +respects your freedom as a computer user, a good solution at this point +is to consider @url{http://www.gnu.org/distros/free-distros.html, one of +the more established GNU/Linux distributions}. We hope you can soon switch +to the Guix System without fear, of course. In the meantime, you can +also keep using your distribution and try out the package manager on top +of it (@pxref{Installation}). + +Before you proceed with the installation, be aware of the following +noteworthy limitations applicable to version @value{VERSION}: + +@itemize +@item +The installation process does not include a graphical user interface and +requires familiarity with GNU/Linux (see the following subsections to +get a feel of what that means.) + +@item +Support for the Logical Volume Manager (LVM) is missing. + +@item +More and more system services are provided (@pxref{Services}), but some +may be missing. + +@item +More than 8,500 packages are available, but you might +occasionally find that a useful package is missing. + +@item +GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), +as well as a number of X11 window managers. However, some graphical +applications may be missing, as well as KDE. +@end itemize + +You have been warned! But more than a disclaimer, this is an invitation +to report issues (and success stories!), and to join us in improving it. +@xref{Contributing}, for more info. + + +@node Hardware Considerations +@section Hardware Considerations + +@cindex hardware support on Guix System +GNU@tie{}Guix focuses on respecting the user's computing freedom. It +builds around the kernel Linux-libre, which means that only hardware for +which free software drivers and firmware exist is supported. Nowadays, +a wide range of off-the-shelf hardware is supported on +GNU/Linux-libre---from keyboards to graphics cards to scanners and +Ethernet controllers. Unfortunately, there are still areas where +hardware vendors deny users control over their own computing, and such +hardware is not supported on Guix System. + +@cindex WiFi, hardware support +One of the main areas where free drivers or firmware are lacking is WiFi +devices. WiFi devices known to work include those using Atheros chips +(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre +driver, and those using Broadcom/AirForce chips (BCM43xx with +Wireless-Core Revision 5), which corresponds to the @code{b43-open} +Linux-libre driver. Free firmware exists for both and is available +out-of-the-box on Guix System, as part of @var{%base-firmware} +(@pxref{operating-system Reference, @code{firmware}}). + +@cindex RYF, Respects Your Freedom +The @uref{https://www.fsf.org/, Free Software Foundation} runs +@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a +certification program for hardware products that respect your freedom +and your privacy and ensure that you have control over your device. We +encourage you to check the list of RYF-certified devices. + +Another useful resource is the @uref{https://www.h-node.org/, H-Node} +web site. It contains a catalog of hardware devices with information +about their support in GNU/Linux. + + +@node USB Stick and DVD Installation +@section USB Stick and DVD Installation + +An ISO-9660 installation image that can be written to a USB stick or +burnt to a DVD can be downloaded from +@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz}, +where @var{system} is one of: + +@table @code +@item x86_64-linux +for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs; + +@item i686-linux +for a 32-bit GNU/Linux system on Intel-compatible CPUs. +@end table + +@c start duplication of authentication part from ``Binary Installation'' +Make sure to download the associated @file{.sig} file and to verify the +authenticity of the image against it, along these lines: + +@example +$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig +$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig +@end example + +If that command fails because you do not have the required public key, +then run this command to import it: + +@example +$ gpg --keyserver @value{KEY-SERVER} \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +@end example + +@noindent +and rerun the @code{gpg --verify} command. +@c end duplication + +This image contains the tools necessary for an installation. +It is meant to be copied @emph{as is} to a large-enough USB stick or DVD. + +@unnumberedsubsec Copying to a USB Stick + +To copy the image to a USB stick, follow these steps: + +@enumerate +@item +Decompress the image using the @command{xz} command: + +@example +xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz +@end example + +@item +Insert a USB stick of 1@tie{}GiB or more into your machine, and determine +its device name. Assuming that the USB stick is known as @file{/dev/sdX}, +copy the image with: + +@example +dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX +sync +@end example + +Access to @file{/dev/sdX} usually requires root privileges. +@end enumerate + +@unnumberedsubsec Burning on a DVD + +To copy the image to a DVD, follow these steps: + +@enumerate +@item +Decompress the image using the @command{xz} command: + +@example +xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz +@end example + +@item +Insert a blank DVD into your machine, and determine +its device name. Assuming that the DVD drive is known as @file{/dev/srX}, +copy the image with: + +@example +growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso +@end example + +Access to @file{/dev/srX} usually requires root privileges. +@end enumerate + +@unnumberedsubsec Booting + +Once this is done, you should be able to reboot the system and boot from +the USB stick or DVD. The latter usually requires you to get in the +BIOS or UEFI boot menu, where you can choose to boot from the USB stick. + +@xref{Installing Guix in a VM}, if, instead, you would like to install +Guix System in a virtual machine (VM). + + +@node Preparing for Installation +@section Preparing for Installation + +Once you have successfully booted your computer using the installation medium, +you should end up with the welcome page of the graphical installer. The +graphical installer is a text-based user interface built upon the newt +library. It shall guide you through all the different steps needed to install +GNU@tie{}Guix System. However, as the graphical installer is still under heavy +development, you might want to fallback to the original, shell based install +process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The +following sections describe the installation procedure assuming you're using +one of those TTYs. They are configured and can be used to run commands as +root. + +TTY2 shows this documentation, browsable using the Info reader commands +(@pxref{Top,,, info-stnd, Stand-alone GNU Info}). The installation system +runs the GPM mouse daemon, which allows you to select text with the left mouse +button and to paste it with the middle button. + +@quotation Note +Installation requires access to the Internet so that any missing +dependencies of your system configuration can be downloaded. See the +``Networking'' section below. +@end quotation + +The installation system includes many common tools needed for this task. +But it is also a full-blown Guix System, which means that you can +install additional packages, should you need it, using @command{guix +package} (@pxref{Invoking guix package}). + +@subsection Keyboard Layout + +@cindex keyboard layout +The installation image uses the US qwerty keyboard layout. If you want +to change it, you can use the @command{loadkeys} command. For example, +the following command selects the Dvorak keyboard layout: + +@example +loadkeys dvorak +@end example + +See the files under @file{/run/current-system/profile/share/keymaps} for +a list of available keyboard layouts. Run @command{man loadkeys} for +more information. + +@subsection Networking + +Run the following command to see what your network interfaces are called: + +@example +ifconfig -a +@end example + +@noindent +@dots{} or, using the GNU/Linux-specific @command{ip} command: + +@example +ip a +@end example + +@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 +Wired interfaces have a name starting with @samp{e}; for example, the +interface corresponding to the first on-board Ethernet controller is +called @samp{eno1}. Wireless interfaces have a name starting with +@samp{w}, like @samp{w1p2s0}. + +@table @asis +@item Wired connection +To configure a wired network run the following command, substituting +@var{interface} with the name of the wired interface you want to use. + +@example +ifconfig @var{interface} up +@end example + +@item Wireless connection +@cindex wireless +@cindex WiFi +To configure wireless networking, you can create a configuration file +for the @command{wpa_supplicant} configuration tool (its location is not +important) using one of the available text editors such as +@command{nano}: + +@example +nano wpa_supplicant.conf +@end example + +As an example, the following stanza can go to this file and will work +for many wireless networks, provided you give the actual SSID and +passphrase for the network you are connecting to: + +@example +network=@{ + ssid="@var{my-ssid}" + key_mgmt=WPA-PSK + psk="the network's secret passphrase" +@} +@end example + +Start the wireless service and run it in the background with the +following command (substitute @var{interface} with the name of the +network interface you want to use): + +@example +wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B +@end example + +Run @command{man wpa_supplicant} for more information. +@end table + +@cindex DHCP +At this point, you need to acquire an IP address. On a network where IP +addresses are automatically assigned @i{via} DHCP, you can run: + +@example +dhclient -v @var{interface} +@end example + +Try to ping a server to see if networking is up and running: + +@example +ping -c 3 gnu.org +@end example + +Setting up network access is almost always a requirement because the +image does not contain all the software and tools that may be needed. + +@cindex installing over SSH +If you want to, you can continue the installation remotely by starting +an SSH server: + +@example +herd start ssh-daemon +@end example + +Make sure to either set a password with @command{passwd}, or configure +OpenSSH public key authentication before logging in. + +@subsection Disk Partitioning + +Unless this has already been done, the next step is to partition, and +then format the target partition(s). + +The installation image includes several partitioning tools, including +Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), +@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with +the partition layout you want: + +@example +cfdisk +@end example + +If your disk uses the GUID Partition Table (GPT) format and you plan to +install BIOS-based GRUB (which is the default), make sure a BIOS Boot +Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB +manual}). + +@cindex EFI, installation +@cindex UEFI, installation +@cindex ESP, EFI system partition +If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition} +(ESP) is required. This partition can be mounted at @file{/boot/efi} for +instance and must have the @code{esp} flag set. E.g., for @command{parted}: + +@example +parted /dev/sda set 1 esp on +@end example + +@quotation Note +@vindex grub-bootloader +@vindex grub-efi-bootloader +Unsure whether to use EFI- or BIOS-based GRUB? If the directory +@file{/sys/firmware/efi} exists in the installation image, then you should +probably perform an EFI installation, using @code{grub-efi-bootloader}. +Otherwise you should use the BIOS-based GRUB, known as +@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on +bootloaders. +@end quotation + +Once you are done partitioning the target hard disk drive, you have to +create a file system on the relevant partition(s)@footnote{Currently +Guix System only supports ext4 and btrfs file systems. In particular, code +that reads file system UUIDs and labels only works for these file system +types.}. For the ESP, if you have one and assuming it is +@file{/dev/sda1}, run: + +@example +mkfs.fat -F32 /dev/sda1 +@end example + +Preferably, assign file systems a label so that you can easily and +reliably refer to them in @code{file-system} declarations (@pxref{File +Systems}). This is typically done using the @code{-L} option of +@command{mkfs.ext4} and related commands. So, assuming the target root +partition lives at @file{/dev/sda2}, a file system with the label +@code{my-root} can be created with: + +@example +mkfs.ext4 -L my-root /dev/sda2 +@end example + +@cindex encrypted disk +If you are instead planning to encrypt the root partition, you can use +the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, +@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, +@code{man cryptsetup}} for more information.) Assuming you want to +store the root partition on @file{/dev/sda2}, the command sequence would +be along these lines: + +@example +cryptsetup luksFormat /dev/sda2 +cryptsetup open --type luks /dev/sda2 my-partition +mkfs.ext4 -L my-root /dev/mapper/my-partition +@end example + +Once that is done, mount the target file system under @file{/mnt} +with a command like (again, assuming @code{my-root} is the label of the +root file system): + +@example +mount LABEL=my-root /mnt +@end example + +Also mount any other file systems you would like to use on the target +system relative to this path. If you have opted for @file{/boot/efi} as an +EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is +found by @code{guix system init} afterwards. + +Finally, if you plan to use one or more swap partitions (@pxref{Memory +Concepts, swap space,, libc, The GNU C Library Reference Manual}), make +sure to initialize them with @command{mkswap}. Assuming you have one +swap partition on @file{/dev/sda3}, you would run: + +@example +mkswap /dev/sda3 +swapon /dev/sda3 +@end example + +Alternatively, you may use a swap file. For example, assuming that in +the new system you want to use the file @file{/swapfile} as a swap file, +you would run@footnote{This example will work for many types of file +systems (e.g., ext4). However, for copy-on-write file systems (e.g., +btrfs), the required steps may be different. For details, see the +manual pages for @command{mkswap} and @command{swapon}.}: + +@example +# This is 10 GiB of swap space. Adjust "count" to change the size. +dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 +# For security, make the file readable and writable only by root. +chmod 600 /mnt/swapfile +mkswap /mnt/swapfile +swapon /mnt/swapfile +@end example + +Note that if you have encrypted the root partition and created a swap +file in its file system as described above, then the encryption also +protects the swap file, just like any other file in that file system. + +@node Proceeding with the Installation +@section Proceeding with the Installation + +With the target partitions ready and the target root mounted on +@file{/mnt}, we're ready to go. First, run: + +@example +herd start cow-store /mnt +@end example + +This makes @file{/gnu/store} copy-on-write, such that packages added to it +during the installation phase are written to the target disk on @file{/mnt} +rather than kept in memory. This is necessary because the first phase of +the @command{guix system init} command (see below) entails downloads or +builds to @file{/gnu/store} which, initially, is an in-memory file system. + +Next, you have to edit a file and +provide the declaration of the operating system to be installed. To +that end, the installation system comes with three text editors. We +recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which +supports syntax highlighting and parentheses matching; other editors +include GNU Zile (an Emacs clone), and +nvi (a clone of the original BSD @command{vi} editor). +We strongly recommend storing that file on the target root file system, say, +as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your +configuration file once you have rebooted into the newly-installed system. + +@xref{Using the Configuration System}, for an overview of the +configuration file. The example configurations discussed in that +section are available under @file{/etc/configuration} in the +installation image. Thus, to get started with a system configuration +providing a graphical display server (a ``desktop'' system), you can run +something along these lines: + +@example +# mkdir /mnt/etc +# cp /etc/configuration/desktop.scm /mnt/etc/config.scm +# nano /mnt/etc/config.scm +@end example + +You should pay attention to what your configuration file contains, and +in particular: + +@itemize +@item +Make sure the @code{bootloader-configuration} form refers to the target +you want to install GRUB on. It should mention @code{grub-bootloader} if +you are installing GRUB in the legacy way, or @code{grub-efi-bootloader} +for newer UEFI systems. For legacy systems, the @code{target} field +names a device, like @code{/dev/sda}; for UEFI systems it names a path +to a mounted EFI partition, like @code{/boot/efi}; do make sure the path is +currently mounted and a @code{file-sytem} entry is specified in your +configuration. + +@item +Be sure that your file system labels match the value of their respective +@code{device} fields in your @code{file-system} configuration, assuming +your @code{file-system} configuration uses the @code{file-system-label} +procedure in its @code{device} field. + +@item +If there are encrypted or RAID partitions, make sure to add a +@code{mapped-devices} field to describe them (@pxref{Mapped Devices}). +@end itemize + +Once you are done preparing the configuration file, the new system must +be initialized (remember that the target root file system is mounted +under @file{/mnt}): + +@example +guix system init /mnt/etc/config.scm /mnt +@end example + +@noindent +This copies all the necessary files and installs GRUB on +@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For +more information, @pxref{Invoking guix system}. This command may trigger +downloads or builds of missing packages, which can take some time. + +Once that command has completed---and hopefully succeeded!---you can run +@command{reboot} and boot into the new system. The @code{root} password +in the new system is initially empty; other users' passwords need to be +initialized by running the @command{passwd} command as @code{root}, +unless your configuration specifies otherwise +(@pxref{user-account-password, user account passwords}). + +@cindex upgrading Guix System +From then on, you can update the system whenever you want by running, say: + +@example +guix pull +sudo guix system reconfigure /etc/config.scm +@end example + +@noindent +This builds a new system generation with the latest packages and services +(@pxref{Invoking guix system}). We recommend doing that regularly so that +your system includes the latest security updates (@pxref{Security Updates}). + +@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. +@quotation Note +@cindex sudo vs. @command{guix pull} +Note that @command{sudo guix} runs your user's @command{guix} command and +@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To +explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. +@end quotation + +Join us on @code{#guix} on the Freenode IRC network or on +@email{guix-devel@@gnu.org} to share your experience---good or not so +good. + +@node Installing Guix in a VM +@section Installing Guix in a Virtual Machine + +@cindex virtual machine, Guix System installation +@cindex virtual private server (VPS) +@cindex VPS (virtual private server) +If you'd like to install Guix System in a virtual machine (VM) or on a +virtual private server (VPS) rather than on your beloved machine, this +section is for you. + +To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a +disk image, follow these steps: + +@enumerate +@item +First, retrieve and decompress the Guix system installation image as +described previously (@pxref{USB Stick and DVD Installation}). + +@item +Create a disk image that will hold the installed system. To make a +qcow2-formatted disk image, use the @command{qemu-img} command: + +@example +qemu-img create -f qcow2 guixsd.img 50G +@end example + +The resulting file will be much smaller than 50 GB (typically less than +1 MB), but it will grow as the virtualized storage device is filled up. + +@item +Boot the USB installation image in an VM: + +@example +qemu-system-x86_64 -m 1024 -smp 1 \ + -net user -net nic,model=virtio -boot menu=on \ + -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \ + -drive file=guixsd.img +@end example + +The ordering of the drives matters. + +In the VM console, quickly press the @kbd{F12} key to enter the boot +menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your +selection. + +@item +You're now root in the VM, proceed with the installation process. +@xref{Preparing for Installation}, and follow the instructions. +@end enumerate + +Once installation is complete, you can boot the system that's on your +@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do +that. + +@node Building the Installation Image +@section Building the Installation Image + +@cindex installation image +The installation image described above was built using the @command{guix +system} command, specifically: + +@example +guix system disk-image gnu/system/install.scm +@end example + +Have a look at @file{gnu/system/install.scm} in the source tree, +and see also @ref{Invoking guix system} for more information +about the installation image. + +@section Building the Installation Image for ARM Boards + +Many ARM boards require a specific variant of the +@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. + +If you build a disk image and the bootloader is not available otherwise +(on another boot drive etc), it's advisable to build an image that +includes the bootloader, specifically: + +@example +guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' +@end example + +@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid +board, a list of possible boards will be printed. + +@c ********************************************************************* @node Package Management @chapter Package Management @@ -1759,7 +2470,7 @@ In addition, any package transaction may be @emph{rolled back}. So, if, for example, an upgrade installs a new version of a package that turns out to have a serious bug, users may roll back to the previous instance of their profile, which was known to work well. Similarly, the global -system configuration on GuixSD is subject to +system configuration on Guix is subject to transactional upgrades and roll-back (@pxref{Using the Configuration System}). @@ -2100,10 +2811,6 @@ By default, @command{guix package} reports as an error @dfn{collisions} in the profile. Collisions happen when two or more different versions or variants of a given package end up in the profile. -@item --verbose -Produce verbose output. In particular, emit the build log of the -environment on the standard error port. - @item --bootstrap Use the bootstrap Guile to build the profile. This option is only useful to distribution developers. @@ -2120,7 +2827,8 @@ availability of packages: @itemx -s @var{regexp} @cindex searching for packages List the available packages whose name, synopsis, or description matches -@var{regexp}, sorted by relevance. Print all the metadata of matching packages in +@var{regexp} (in a case-insensitive fashion), sorted by relevance. +Print all the metadata of matching packages in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). @@ -2612,8 +3320,8 @@ guix gc -F 5G @end example It is perfectly safe to run as a non-interactive periodic job -(@pxref{Scheduled Job Execution}, for how to set up such a job on -GuixSD). Running @command{guix gc} with no arguments will collect as +(@pxref{Scheduled Job Execution}, for how to set up such a job). +Running @command{guix gc} with no arguments will collect as much garbage as it can, but that is often inconvenient: you may find yourself having to rebuild or re-download software that is ``dead'' from the GC viewpoint but that is necessary to build other pieces of @@ -2888,6 +3596,11 @@ Use @var{profile} instead of @file{~/.config/guix/current}. Show which channel commit(s) would be used and what would be built or substituted but do not actually do it. +@item --system=@var{system} +@itemx -s @var{system} +Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of +the system type of the build host. + @item --verbose Produce verbose output, writing build logs to the standard error output. @@ -3737,6 +4450,7 @@ This chapter describes all these APIs in turn, starting from high-level package definitions. @menu +* Package Modules:: Packages from the programmer's viewpoint. * Defining Packages:: Defining new packages. * Build Systems:: Specifying how packages are built. * The Store:: Manipulating the package store. @@ -3746,6 +4460,68 @@ package definitions. * Invoking guix repl:: Fiddling with Guix interactively. @end menu +@node Package Modules +@section Package Modules + +From a programming viewpoint, the package definitions of the +GNU distribution are provided by Guile modules in the @code{(gnu packages +@dots{})} name space@footnote{Note that packages under the @code{(gnu +packages @dots{})} module name space are not necessarily ``GNU +packages''. This module naming scheme follows the usual Guile module +naming convention: @code{gnu} means that these modules are distributed +as part of the GNU system, and @code{packages} identifies modules that +define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile +Reference Manual}). For instance, the @code{(gnu packages emacs)} +module exports a variable named @code{emacs}, which is bound to a +@code{<package>} object (@pxref{Defining Packages}). + +The @code{(gnu packages @dots{})} module name space is +automatically scanned for packages by the command-line tools. For +instance, when running @code{guix package -i emacs}, all the @code{(gnu +packages @dots{})} modules are scanned until one that exports a package +object whose name is @code{emacs} is found. This package search +facility is implemented in the @code{(gnu packages)} module. + +@cindex customization, of packages +@cindex package module search path +Users can store package definitions in modules with different +names---e.g., @code{(my-packages emacs)}@footnote{Note that the file +name and module name must match. For instance, the @code{(my-packages +emacs)} module must be stored in a @file{my-packages/emacs.scm} file +relative to the load path specified with @option{--load-path} or +@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, +guile, GNU Guile Reference Manual}, for details.}. There are two ways to make +these package definitions visible to the user interfaces: + +@enumerate +@item +By adding the directory containing your package modules to the search path +with the @code{-L} flag of @command{guix package} and other commands +(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH} +environment variable described below. + +@item +By defining a @dfn{channel} and configuring @command{guix pull} so that it +pulls from it. A channel is essentially a Git repository containing package +modules. @xref{Channels}, for more information on how to define and use +channels. +@end enumerate + +@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: + +@defvr {Environment Variable} GUIX_PACKAGE_PATH +This is a colon-separated list of directories to search for additional +package modules. Directories listed in this variable take precedence +over the own modules of the distribution. +@end defvr + +The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: +each package is built based solely on other packages in the +distribution. The root of this dependency graph is a small set of +@dfn{bootstrap binaries}, provided by the @code{(gnu packages +bootstrap)} module. For more information on bootstrapping, +@pxref{Bootstrapping}. + @node Defining Packages @section Defining Packages @@ -5024,7 +5800,7 @@ Return @code{#t} when @var{path} designates a valid store item and invalid, for instance because it is the result of an aborted or failed build.) -A @code{&nix-protocol-error} condition is raised if @var{path} is not +A @code{&store-protocol-error} condition is raised if @var{path} is not prefixed by the store directory (@file{/gnu/store}). @end deffn @@ -6356,10 +7132,15 @@ Likewise, when the build or substitution process lasts for more than By default, the daemon's setting is honored (@pxref{Invoking guix-daemon, @code{--timeout}}). -@item --verbosity=@var{level} -Use the given verbosity level. @var{level} must be an integer between 0 -and 5; higher means more verbose output. Setting a level of 4 or more -may be helpful when debugging setup issues with the build daemon. +@c Note: This option is actually not part of %standard-build-options but +@c most programs honor it. +@cindex verbosity, of the command-line tools +@cindex build logs, verbosity +@item -v @var{level} +@itemx --verbosity=@var{level} +Use the given verbosity @var{level}, an integer. Choosing 0 means that no +output is produced, 1 is for quiet output, and 2 shows all the build log +output on standard error. @item --cores=@var{n} @itemx -c @var{n} @@ -6372,6 +7153,11 @@ Allow at most @var{n} build jobs in parallel. @xref{Invoking guix-daemon, @code{--max-jobs}}, for details about this option and the equivalent @command{guix-daemon} option. +@item --debug=@var{level} +Produce debugging output coming from the build daemon. @var{level} must be an +integer between 0 and 5; higher means more verbose output. Setting a level of +4 or more may be helpful when debugging setup issues with the build daemon. + @end table Behind the scenes, @command{guix build} is essentially an interface to @@ -6540,9 +7326,9 @@ build}. @item --quiet @itemx -q -Build quietly, without displaying the build log. Upon completion, the -build log is kept in @file{/var} (or similar) and can always be -retrieved using the @option{--log-file} option. +Build quietly, without displaying the build log; this is equivalent to +@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var} +(or similar) and can always be retrieved using the @option{--log-file} option. @item --file=@var{file} @itemx -f @var{file} @@ -7391,6 +8177,22 @@ are many packages, though, for which it lacks a method to determine whether a new upstream release is available. However, the mechanism is extensible, so feel free to get in touch with us to add a new method! +@table @code + +@item --recursive +Consider the packages specified, and all the packages upon which they depend. + +@example +$ guix refresh --recursive coreutils +gnu/packages/acl.scm:35:2: warning: no updater for acl +gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4 +gnu/packages/xml.scm:68:2: warning: no updater for expat +gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp +@dots{} +@end example + +@end table + Sometimes the upstream name differs from the package name used in Guix, and @command{guix refresh} needs a little help. Most updaters honor the @code{upstream-name} property in package definitions, which can be used @@ -7564,6 +8366,22 @@ hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} The command above lists a set of packages that could be built to check for compatibility with an upgraded @code{flex} package. +@table @code + +@item --list-transitive +List all the packages which one or more packages depend upon. + +@example +$ guix refresh --list-transitive flex +flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6 +bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{} +@end example + +@end table + +The command above lists a set of packages which, when changed, would cause +@code{flex} to be rebuilt. + The following options can be used to customize GnuPG operation: @table @code @@ -7659,12 +8477,19 @@ Identify inputs that should most likely be native inputs. @item source @itemx home-page @itemx mirror-url +@itemx github-url @itemx source-file-name Probe @code{home-page} and @code{source} URLs and report those that are -invalid. Suggest a @code{mirror://} URL when applicable. Check that -the source file name is meaningful, e.g.@: is not -just a version number or ``git-checkout'', without a declared -@code{file-name} (@pxref{origin Reference}). +invalid. Suggest a @code{mirror://} URL when applicable. If the +@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub +URL. Check that the source file name is meaningful, e.g.@: is not just a +version number or ``git-checkout'', without a declared @code{file-name} +(@pxref{origin Reference}). + +@item source-unstable-tarball +Parse the @code{source} URL to determine if a tarball from GitHub is +autogenerated or if it is a release tarball. Unfortunately GitHub's +autogenerated tarballs are sometimes regenerated. @item cve @cindex security vulnerabilities @@ -8160,7 +8985,7 @@ guix environment guix --ad-hoc git strace Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility. In particular, when -using Guix on a host distro that is not GuixSD, it is desirable to +using Guix on a host distro that is not Guix System, it is desirable to prevent access to @file{/usr/bin} and other system-wide resources from the development environment. For example, the following command spawns a Guile REPL in a ``container'' where only the store and the current @@ -8213,7 +9038,7 @@ Running: guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' @end example -starts a shell with all the GuixSD base packages available. +starts a shell with all the base system packages available. The above commands only use the default output of the given packages. To select other outputs, two element tuples can be specified: @@ -8562,7 +9387,7 @@ Reference Manual}) on @var{port} (37146 by default). This is used primarily for debugging a running @command{guix publish} server. @end table -Enabling @command{guix publish} on a GuixSD system is a one-liner: just +Enabling @command{guix publish} on Guix System is a one-liner: just instantiate a @code{guix-publish-service-type} service in the @code{services} field of the @code{operating-system} declaration (@pxref{guix-publish-service-type, @code{guix-publish-service-type}}). @@ -8836,7 +9661,7 @@ system of the container. @var{arguments} are the additional options that will be passed to @var{program}. The following command launches an interactive login shell inside a -GuixSD container, started by @command{guix system container}, and whose +Guix system container, started by @command{guix system container}, and whose process ID is 9001: @example @@ -8896,7 +9721,9 @@ key is authorized. It also reports the size of the compressed archives (``nars'') provided by the server, the size the corresponding store items occupy in the store (assuming deduplication is turned off), and the server's throughput. The second part gives continuous integration -(CI) statistics, if the server supports it. +(CI) statistics, if the server supports it. In addition, using the +@option{--coverage} option, @command{guix weather} can list ``important'' +package substitutes missing on the server (see below). To achieve that, @command{guix weather} queries over HTTP(S) meta-data (@dfn{narinfos}) for all the relevant store items. Like @command{guix @@ -8924,6 +9751,37 @@ Instead of querying substitutes for all the packages, only ask for those specified in @var{file}. @var{file} must contain a @dfn{manifest}, as with the @code{-m} option of @command{guix package} (@pxref{Invoking guix package}). + +@item --coverage[=@var{count}] +@itemx -c [@var{count}] +Report on substitute coverage for packages: list packages with at least +@var{count} dependents (zero by default) for which substitutes are +unavailable. Dependent packages themselves are not listed: if @var{b} depends +on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though +@var{b} usually lacks substitutes as well. The result looks like this: + +@example +$ guix weather --substitute-urls=https://ci.guix.info -c 10 +computing 8,983 package derivations for x86_64-linux... +looking for 9,343 store items on https://ci.guix.info... +updating substitutes from 'https://ci.guix.info'... 100.0% +https://ci.guix.info + 64.7% substitutes available (6,047 out of 9,343) +@dots{} +2502 packages are missing from 'https://ci.guix.info' for 'x86_64-linux', among which: + 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 + 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 + 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 + @dots{} +@end example + +What this example shows is that @code{kcoreaddons} and presumably the 58 +packages that depend on it have no substitutes at @code{ci.guix.info}; +likewise for @code{qgpgme} and the 46 packages that depend on it. + +If you are a Guix developer, or if you are taking care of this build farm, +you'll probably want to have a closer look at these packages: they may simply +fail to build. @end table @node Invoking guix processes @@ -8982,730 +9840,9 @@ ClientPID: 19419 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} @end example -@c ********************************************************************* -@node GNU Distribution -@chapter GNU Distribution - -@cindex Guix System Distribution -@cindex GuixSD -Guix comes with a distribution of the GNU system consisting entirely of -free software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to -users of that software}.}. The -distribution can be installed on its own (@pxref{System Installation}), -but it is also possible to install Guix as a package manager on top of -an installed GNU/Linux system (@pxref{Installation}). To distinguish -between the two, we refer to the standalone distribution as the Guix -System Distribution, or GuixSD. - -The distribution provides core GNU packages such as GNU libc, GCC, and -Binutils, as well as many GNU and non-GNU applications. The complete -list of available packages can be browsed -@url{http://www.gnu.org/software/guix/packages,on-line} or by -running @command{guix package} (@pxref{Invoking guix package}): - -@example -guix package --list-available -@end example - -Our goal is to provide a practical 100% free software distribution of -Linux-based and other variants of GNU, with a focus on the promotion and -tight integration of GNU components, and an emphasis on programs and -tools that help users exert that freedom. - -Packages are currently available on the following platforms: - -@table @code - -@item x86_64-linux -Intel/AMD @code{x86_64} architecture, Linux-Libre kernel; - -@item i686-linux -Intel 32-bit architecture (IA32), Linux-Libre kernel; - -@item armhf-linux -ARMv7-A architecture with hard float, Thumb-2 and NEON, -using the EABI hard-float application binary interface (ABI), -and Linux-Libre kernel. - -@item aarch64-linux -little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is -currently in an experimental stage, with limited support. -@xref{Contributing}, for how to help! - -@item mips64el-linux -little-endian 64-bit MIPS processors, specifically the Loongson series, -n32 ABI, and Linux-Libre kernel. - -@end table - -GuixSD itself is currently only available on @code{i686} and @code{x86_64}. - -@noindent -For information on porting to other architectures or kernels, -@pxref{Porting}. - -@menu -* System Installation:: Installing the whole operating system. -* System Configuration:: Configuring the operating system. -* Documentation:: Browsing software user manuals. -* Installing Debugging Files:: Feeding the debugger. -* Security Updates:: Deploying security fixes quickly. -* Package Modules:: Packages from the programmer's viewpoint. -* Packaging Guidelines:: Growing the distribution. -* Bootstrapping:: GNU/Linux built from scratch. -* Porting:: Targeting another platform or kernel. -@end menu - -Building this distribution is a cooperative effort, and you are invited -to join! @xref{Contributing}, for information about how you can help. - -@node System Installation -@section System Installation - -@cindex installing GuixSD -@cindex Guix System Distribution -This section explains how to install the Guix System Distribution (GuixSD) -on a machine. The Guix package manager can -also be installed on top of a running GNU/Linux system, -@pxref{Installation}. - -@ifinfo -@quotation Note -@c This paragraph is for people reading this from tty2 of the -@c installation image. -You are reading this documentation with an Info reader. For details on -how to use it, hit the @key{RET} key (``return'' or ``enter'') on the -link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU -Info}. Hit @kbd{l} afterwards to come back here. - -Alternately, run @command{info info} in another tty to keep the manual -available. -@end quotation -@end ifinfo - -@menu -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Proceeding with the Installation:: The real thing. -* Installing GuixSD in a VM:: GuixSD playground. -* Building the Installation Image:: How this comes to be. -@end menu - -@node Limitations -@subsection Limitations - -As of version @value{VERSION}, the Guix System Distribution (GuixSD) is -not production-ready. It may contain bugs and lack important -features. Thus, if you are looking for a stable production system that -respects your freedom as a computer user, a good solution at this point -is to consider @url{http://www.gnu.org/distros/free-distros.html, one of -the more established GNU/Linux distributions}. We hope you can soon switch -to the GuixSD without fear, of course. In the meantime, you can -also keep using your distribution and try out the package manager on top -of it (@pxref{Installation}). - -Before you proceed with the installation, be aware of the following -noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -The installation process does not include a graphical user interface and -requires familiarity with GNU/Linux (see the following subsections to -get a feel of what that means.) - -@item -Support for the Logical Volume Manager (LVM) is missing. - -@item -More and more system services are provided (@pxref{Services}), but some -may be missing. - -@item -More than 8,500 packages are available, but you might -occasionally find that a useful package is missing. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), -as well as a number of X11 window managers. However, some graphical -applications may be missing, as well as KDE. -@end itemize - -You have been warned! But more than a disclaimer, this is an invitation -to report issues (and success stories!), and to join us in improving it. -@xref{Contributing}, for more info. - - -@node Hardware Considerations -@subsection Hardware Considerations - -@cindex hardware support on GuixSD -GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It -builds around the kernel Linux-libre, which means that only hardware for -which free software drivers and firmware exist is supported. Nowadays, -a wide range of off-the-shelf hardware is supported on -GNU/Linux-libre---from keyboards to graphics cards to scanners and -Ethernet controllers. Unfortunately, there are still areas where -hardware vendors deny users control over their own computing, and such -hardware is not supported on GuixSD. - -@cindex WiFi, hardware support -One of the main areas where free drivers or firmware are lacking is WiFi -devices. WiFi devices known to work include those using Atheros chips -(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre -driver, and those using Broadcom/AirForce chips (BCM43xx with -Wireless-Core Revision 5), which corresponds to the @code{b43-open} -Linux-libre driver. Free firmware exists for both and is available -out-of-the-box on GuixSD, as part of @var{%base-firmware} -(@pxref{operating-system Reference, @code{firmware}}). - -@cindex RYF, Respects Your Freedom -The @uref{https://www.fsf.org/, Free Software Foundation} runs -@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a -certification program for hardware products that respect your freedom -and your privacy and ensure that you have control over your device. We -encourage you to check the list of RYF-certified devices. - -Another useful resource is the @uref{https://www.h-node.org/, H-Node} -web site. It contains a catalog of hardware devices with information -about their support in GNU/Linux. - - -@node USB Stick and DVD Installation -@subsection USB Stick and DVD Installation - -An ISO-9660 installation image that can be written to a USB stick or -burnt to a DVD can be downloaded from -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz}, -where @var{system} is one of: - -@table @code -@item x86_64-linux -for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs; - -@item i686-linux -for a 32-bit GNU/Linux system on Intel-compatible CPUs. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the image against it, along these lines: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig -@end example - -If that command fails because you do not have the required public key, -then run this command to import it: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -and rerun the @code{gpg --verify} command. -@c end duplication - -This image contains the tools necessary for an installation. -It is meant to be copied @emph{as is} to a large-enough USB stick or DVD. - -@unnumberedsubsubsec Copying to a USB Stick - -To copy the image to a USB stick, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a USB stick of 1@tie{}GiB or more into your machine, and determine -its device name. Assuming that the USB stick is known as @file{/dev/sdX}, -copy the image with: - -@example -dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX -sync -@end example - -Access to @file{/dev/sdX} usually requires root privileges. -@end enumerate - -@unnumberedsubsubsec Burning on a DVD - -To copy the image to a DVD, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a blank DVD into your machine, and determine -its device name. Assuming that the DVD drive is known as @file{/dev/srX}, -copy the image with: - -@example -growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso -@end example - -Access to @file{/dev/srX} usually requires root privileges. -@end enumerate - -@unnumberedsubsubsec Booting - -Once this is done, you should be able to reboot the system and boot from -the USB stick or DVD. The latter usually requires you to get in the -BIOS or UEFI boot menu, where you can choose to boot from the USB stick. - -@xref{Installing GuixSD in a VM}, if, instead, you would like to install -GuixSD in a virtual machine (VM). - - -@node Preparing for Installation -@subsection Preparing for Installation - -Once you have successfully booted your computer using the installation medium, -you should end up with a root prompt. Several console TTYs are configured -and can be used to run commands as root. TTY2 shows this documentation, -browsable using the Info reader commands (@pxref{Top,,, info-stnd, -Stand-alone GNU Info}). The installation system runs the GPM mouse -daemon, which allows you to select text with the left mouse button and -to paste it with the middle button. - -@quotation Note -Installation requires access to the Internet so that any missing -dependencies of your system configuration can be downloaded. See the -``Networking'' section below. -@end quotation - -The installation system includes many common tools needed for this task. -But it is also a full-blown GuixSD system, which means that you can -install additional packages, should you need it, using @command{guix -package} (@pxref{Invoking guix package}). - -@subsubsection Keyboard Layout - -@cindex keyboard layout -The installation image uses the US qwerty keyboard layout. If you want -to change it, you can use the @command{loadkeys} command. For example, -the following command selects the Dvorak keyboard layout: - -@example -loadkeys dvorak -@end example - -See the files under @file{/run/current-system/profile/share/keymaps} for -a list of available keyboard layouts. Run @command{man loadkeys} for -more information. - -@subsubsection Networking - -Run the following command to see what your network interfaces are called: - -@example -ifconfig -a -@end example - -@noindent -@dots{} or, using the GNU/Linux-specific @command{ip} command: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Wired interfaces have a name starting with @samp{e}; for example, the -interface corresponding to the first on-board Ethernet controller is -called @samp{eno1}. Wireless interfaces have a name starting with -@samp{w}, like @samp{w1p2s0}. - -@table @asis -@item Wired connection -To configure a wired network run the following command, substituting -@var{interface} with the name of the wired interface you want to use. - -@example -ifconfig @var{interface} up -@end example - -@item Wireless connection -@cindex wireless -@cindex WiFi -To configure wireless networking, you can create a configuration file -for the @command{wpa_supplicant} configuration tool (its location is not -important) using one of the available text editors such as -@command{nano}: - -@example -nano wpa_supplicant.conf -@end example - -As an example, the following stanza can go to this file and will work -for many wireless networks, provided you give the actual SSID and -passphrase for the network you are connecting to: - -@example -network=@{ - ssid="@var{my-ssid}" - key_mgmt=WPA-PSK - psk="the network's secret passphrase" -@} -@end example - -Start the wireless service and run it in the background with the -following command (substitute @var{interface} with the name of the -network interface you want to use): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B -@end example - -Run @command{man wpa_supplicant} for more information. -@end table - -@cindex DHCP -At this point, you need to acquire an IP address. On a network where IP -addresses are automatically assigned @i{via} DHCP, you can run: - -@example -dhclient -v @var{interface} -@end example - -Try to ping a server to see if networking is up and running: - -@example -ping -c 3 gnu.org -@end example - -Setting up network access is almost always a requirement because the -image does not contain all the software and tools that may be needed. - -@cindex installing over SSH -If you want to, you can continue the installation remotely by starting -an SSH server: - -@example -herd start ssh-daemon -@end example - -Make sure to either set a password with @command{passwd}, or configure -OpenSSH public key authentication before logging in. - -@subsubsection Disk Partitioning - -Unless this has already been done, the next step is to partition, and -then format the target partition(s). - -The installation image includes several partitioning tools, including -Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), -@command{fdisk}, and @command{cfdisk}. Run it and set up your disk with -the partition layout you want: - -@example -cfdisk -@end example - -If your disk uses the GUID Partition Table (GPT) format and you plan to -install BIOS-based GRUB (which is the default), make sure a BIOS Boot -Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB -manual}). - -@cindex EFI, installation -@cindex UEFI, installation -@cindex ESP, EFI system partition -If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition} -(ESP) is required. This partition should be mounted at @file{/boot/efi} and -must have the @code{esp} flag set. E.g., for @command{parted}: - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Note -@vindex grub-bootloader -@vindex grub-efi-bootloader -Unsure whether to use EFI- or BIOS-based GRUB? If the directory -@file{/sys/firmware/efi} exists in the installation image, then you should -probably perform an EFI installation, using @code{grub-efi-bootloader}. -Otherwise you should use the BIOS-based GRUB, known as -@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on -bootloaders. -@end quotation - -Once you are done partitioning the target hard disk drive, you have to -create a file system on the relevant partition(s)@footnote{Currently -GuixSD only supports ext4 and btrfs file systems. In particular, code -that reads file system UUIDs and labels only works for these file system -types.}. For the ESP, if you have one and assuming it is -@file{/dev/sda1}, run: - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Preferably, assign file systems a label so that you can easily and -reliably refer to them in @code{file-system} declarations (@pxref{File -Systems}). This is typically done using the @code{-L} option of -@command{mkfs.ext4} and related commands. So, assuming the target root -partition lives at @file{/dev/sda2}, a file system with the label -@code{my-root} can be created with: - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex encrypted disk -If you are instead planning to encrypt the root partition, you can use -the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, -@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, -@code{man cryptsetup}} for more information.) Assuming you want to -store the root partition on @file{/dev/sda2}, the command sequence would -be along these lines: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Once that is done, mount the target file system under @file{/mnt} -with a command like (again, assuming @code{my-root} is the label of the -root file system): - -@example -mount LABEL=my-root /mnt -@end example - -Also mount any other file systems you would like to use on the target -system relative to this path. If you have @file{/boot} on a separate -partition for example, mount it at @file{/mnt/boot} now so it is found -by @code{guix system init} afterwards. - -Finally, if you plan to use one or more swap partitions (@pxref{Memory -Concepts, swap space,, libc, The GNU C Library Reference Manual}), make -sure to initialize them with @command{mkswap}. Assuming you have one -swap partition on @file{/dev/sda3}, you would run: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Alternatively, you may use a swap file. For example, assuming that in -the new system you want to use the file @file{/swapfile} as a swap file, -you would run@footnote{This example will work for many types of file -systems (e.g., ext4). However, for copy-on-write file systems (e.g., -btrfs), the required steps may be different. For details, see the -manual pages for @command{mkswap} and @command{swapon}.}: - -@example -# This is 10 GiB of swap space. Adjust "count" to change the size. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# For security, make the file readable and writable only by root. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Note that if you have encrypted the root partition and created a swap -file in its file system as described above, then the encryption also -protects the swap file, just like any other file in that file system. - -@node Proceeding with the Installation -@subsection Proceeding with the Installation - -With the target partitions ready and the target root mounted on -@file{/mnt}, we're ready to go. First, run: - -@example -herd start cow-store /mnt -@end example - -This makes @file{/gnu/store} copy-on-write, such that packages added to it -during the installation phase are written to the target disk on @file{/mnt} -rather than kept in memory. This is necessary because the first phase of -the @command{guix system init} command (see below) entails downloads or -builds to @file{/gnu/store} which, initially, is an in-memory file system. - -Next, you have to edit a file and -provide the declaration of the operating system to be installed. To -that end, the installation system comes with three text editors. We -recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which -supports syntax highlighting and parentheses matching; other editors -include GNU Zile (an Emacs clone), and -nvi (a clone of the original BSD @command{vi} editor). -We strongly recommend storing that file on the target root file system, say, -as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your -configuration file once you have rebooted into the newly-installed system. - -@xref{Using the Configuration System}, for an overview of the -configuration file. The example configurations discussed in that -section are available under @file{/etc/configuration} in the -installation image. Thus, to get started with a system configuration -providing a graphical display server (a ``desktop'' system), you can run -something along these lines: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -You should pay attention to what your configuration file contains, and -in particular: - -@itemize -@item -Make sure the @code{bootloader-configuration} form refers to the target -you want to install GRUB on. It should mention @code{grub-bootloader} if -you are installing GRUB in the legacy way, or @code{grub-efi-bootloader} -for newer UEFI systems. For legacy systems, the @code{target} field -names a device, like @code{/dev/sda}; for UEFI systems it names a path -to a mounted EFI partition, like @code{/boot/efi}, and do make sure the -path is actually mounted. - -@item -Be sure that your file system labels match the value of their respective -@code{device} fields in your @code{file-system} configuration, assuming -your @code{file-system} configuration uses the @code{file-system-label} -procedure in its @code{device} field. - -@item -If there are encrypted or RAID partitions, make sure to add a -@code{mapped-devices} field to describe them (@pxref{Mapped Devices}). -@end itemize - -Once you are done preparing the configuration file, the new system must -be initialized (remember that the target root file system is mounted -under @file{/mnt}): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -This copies all the necessary files and installs GRUB on -@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For -more information, @pxref{Invoking guix system}. This command may trigger -downloads or builds of missing packages, which can take some time. - -Once that command has completed---and hopefully succeeded!---you can run -@command{reboot} and boot into the new system. The @code{root} password -in the new system is initially empty; other users' passwords need to be -initialized by running the @command{passwd} command as @code{root}, -unless your configuration specifies otherwise -(@pxref{user-account-password, user account passwords}). - -@cindex upgrading GuixSD -From then on, you can update GuixSD whenever you want by running -@command{guix pull} as @code{root} (@pxref{Invoking guix pull}), and -then running @command{guix system reconfigure} to build a new system -generation with the latest packages and services (@pxref{Invoking guix -system}). We recommend doing that regularly so that your system -includes the latest security updates (@pxref{Security Updates}). - -Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience---good or not so -good. - -@node Installing GuixSD in a VM -@subsection Installing GuixSD in a Virtual Machine - -@cindex virtual machine, GuixSD installation -@cindex virtual private server (VPS) -@cindex VPS (virtual private server) -If you'd like to install GuixSD in a virtual machine (VM) or on a -virtual private server (VPS) rather than on your beloved machine, this -section is for you. - -To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a -disk image, follow these steps: - -@enumerate -@item -First, retrieve and decompress the GuixSD installation image as -described previously (@pxref{USB Stick and DVD Installation}). - -@item -Create a disk image that will hold the installed system. To make a -qcow2-formatted disk image, use the @command{qemu-img} command: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -The resulting file will be much smaller than 50 GB (typically less than -1 MB), but it will grow as the virtualized storage device is filled up. - -@item -Boot the USB installation image in an VM: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \ - -drive file=guixsd.img -@end example - -The ordering of the drives matters. - -In the VM console, quickly press the @kbd{F12} key to enter the boot -menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your -selection. - -@item -You're now root in the VM, proceed with the installation process. -@xref{Preparing for Installation}, and follow the instructions. -@end enumerate - -Once installation is complete, you can boot the system that's on your -@file{guixsd.img} image. @xref{Running GuixSD in a VM}, for how to do -that. - -@node Building the Installation Image -@subsection Building the Installation Image - -@cindex installation image -The installation image described above was built using the @command{guix -system} command, specifically: - -@example -guix system disk-image gnu/system/install.scm -@end example - -Have a look at @file{gnu/system/install.scm} in the source tree, -and see also @ref{Invoking guix system} for more information -about the installation image. - -@subsection Building the Installation Image for ARM Boards - -Many ARM boards require a specific variant of the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. - -If you build a disk image and the bootloader is not available otherwise -(on another boot drive etc), it's advisable to build an image that -includes the bootloader, specifically: - -@example -guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' -@end example - -@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid -board, a list of possible boards will be printed. @node System Configuration -@section System Configuration +@chapter System Configuration @cindex system configuration The Guix System Distribution supports a consistent whole-system configuration @@ -9743,12 +9880,12 @@ instance to support new system services. * Initial RAM Disk:: Linux-Libre bootstrapping. * Bootloader Configuration:: Configuring the boot loader. * Invoking guix system:: Instantiating a system configuration. -* Running GuixSD in a VM:: How to run GuixSD in a virtual machine. +* Running Guix in a VM:: How to run Guix System in a virtual machine. * Defining Services:: Adding new service definitions. @end menu @node Using the Configuration System -@subsection Using the Configuration System +@section Using the Configuration System The operating system is configured by providing an @code{operating-system} declaration in a file that can then be passed to @@ -9771,7 +9908,7 @@ Below we discuss the effect of some of the most important fields fields), and how to @dfn{instantiate} the operating system using @command{guix system}. -@unnumberedsubsubsec Bootloader +@unnumberedsubsec Bootloader @cindex legacy boot, on Intel machines @cindex BIOS boot, on Intel machines @@ -9792,7 +9929,7 @@ the @code{bootloader} field should contain something along these lines: @xref{Bootloader Configuration}, for more information on the available configuration options. -@unnumberedsubsubsec Globally-Visible Packages +@unnumberedsubsec Globally-Visible Packages @vindex %base-packages The @code{packages} field lists packages that will be globally visible @@ -9838,17 +9975,17 @@ version: %base-packages))) @end lisp -@unnumberedsubsubsec System Services +@unnumberedsubsec System Services @cindex services @vindex %base-services The @code{services} field lists @dfn{system services} to be made available when the system starts (@pxref{Services}). The @code{operating-system} declaration above specifies that, in -addition to the basic services, we want the @command{lshd} secure shell +addition to the basic services, we want the OpenSSH secure shell daemon listening on port 2222 (@pxref{Networking Services, -@code{lsh-service}}). Under the hood, -@code{lsh-service} arranges so that @code{lshd} is started with the +@code{openssh-service-type}}). Under the hood, +@code{openssh-service-type} arranges so that @command{sshd} is started with the right command-line options, possibly with supporting configuration files generated as needed (@pxref{Defining Services}). @@ -9930,7 +10067,7 @@ following expression returns a list that contains all the services in %desktop-services) @end example -@unnumberedsubsubsec Instantiating the System +@unnumberedsubsec Instantiating the System Assuming the @code{operating-system} declaration is stored in the @file{my-system-config.scm} @@ -9963,7 +10100,7 @@ the latest (e.g., after invoking @command{guix system roll-back}), since the operation might overwrite a later generation (@pxref{Invoking guix system}). -@unnumberedsubsubsec The Programming Interface +@unnumberedsubsec The Programming Interface At the Scheme level, the bulk of an @code{operating-system} declaration is instantiated with the following monadic procedure (@pxref{The Store @@ -9980,11 +10117,11 @@ instantiate @var{os}. This procedure is provided by the @code{(gnu system)} module. Along with @code{(gnu services)} (@pxref{Services}), this module contains the -guts of GuixSD. Make sure to visit it! +guts of Guix System. Make sure to visit it! @node operating-system Reference -@subsection @code{operating-system} Reference +@section @code{operating-system} Reference This section summarizes all the options available in @code{operating-system} declarations (@pxref{Using the Configuration @@ -10138,7 +10275,7 @@ is that only @code{root} and members of the @code{wheel} group may use @end deftp @node File Systems -@subsection File Systems +@section File Systems The list of file systems to be mounted is specified in the @code{file-systems} field of the operating system declaration @@ -10303,7 +10440,7 @@ and unmount user-space FUSE file systems. This requires the @end defvr @node Mapped Devices -@subsection Mapped Devices +@section Mapped Devices @cindex device mapping @cindex mapped devices @@ -10424,7 +10561,7 @@ automatically later. @node User Accounts -@subsection User Accounts +@section User Accounts @cindex users @cindex accounts @@ -10559,7 +10696,7 @@ special-case and is automatically added whether or not it is specified. @end defvr @node Locales -@subsection Locales +@section Locales @cindex locale A @dfn{locale} defines cultural conventions for a particular language @@ -10647,7 +10784,7 @@ instance it has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}. @end defvr -@subsubsection Locale Data Compatibility Considerations +@subsection Locale Data Compatibility Considerations @cindex incompatibility, of locale data @code{operating-system} declarations provide a @code{locale-libcs} field @@ -10669,7 +10806,7 @@ all, of the locale data from libc 2.21 (specifically, @code{LC_COLLATE} data is incompatible); thus calls to @code{setlocale} may fail, but programs will not abort. -The ``problem'' in GuixSD is that users have a lot of freedom: They can +The ``problem'' with Guix is that users have a lot of freedom: They can choose whether and when to upgrade software in their profiles, and might be using a libc version different from the one the system administrator used to build the system-wide locale data. @@ -10699,7 +10836,7 @@ both libc 2.21 and the current version of libc in @node Services -@subsection Services +@section Services @cindex system services An important part of preparing an @code{operating-system} declaration is @@ -10708,7 +10845,7 @@ Configuration System}). System services are typically daemons launched when the system boots, or other actions needed at that time---e.g., configuring network access. -GuixSD has a broad definition of ``service'' (@pxref{Service +Guix has a broad definition of ``service'' (@pxref{Service Composition}), but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd Services}). On a running system, the @command{herd} command allows you to list the available services, show their status, @@ -10777,7 +10914,7 @@ declaration. @end menu @node Base Services -@subsubsection Base Services +@subsection Base Services The @code{(gnu services base)} module provides definitions for the basic services that one expects from the system. The services exported by @@ -10796,7 +10933,9 @@ system, you will want to append services to @var{%base-services}, like this: @example -(cons* (avahi-service) (lsh-service) %base-services) +(append (list (service avahi-service-type) + (service openssh-service-type)) + %base-services) @end example @end defvr @@ -11426,11 +11565,12 @@ well as in the @var{groups} field of the @var{operating-system} record. ;; @dots{} (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (cons* android-udev-rules - (udev-configuration-rules config)))))))) + (modify-services %desktop-services + (udev-service-type + config => + (udev-configuration (inherit config) + (rules (cons android-udev-rules + (udev-configuration-rules config)))))))) @end example @defvr {Scheme Variable} urandom-seed-service-type @@ -11590,7 +11730,7 @@ commonly used for real-time audio systems. @end deffn @node Scheduled Job Execution -@subsubsection Scheduled Job Execution +@subsection Scheduled Job Execution @cindex cron @cindex mcron @@ -11638,9 +11778,11 @@ gexps to introduce job definitions that are passed to mcron (operating-system ;; @dots{} - (services (cons (mcron-service (list garbage-collector-job - updatedb-job - idutils-job)) + (services (cons (service mcron-service-type + (mcron-configuration + (jobs (list garbage-collector-job + updatedb-job + idutils-job)))) %base-services))) @end lisp @@ -11663,17 +11805,6 @@ also specify the number of tasks to display: # herd schedule mcron 10 @end example -@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron}] -Return an mcron service running @var{mcron} that schedules @var{jobs}, a -list of gexps denoting mcron job specifications. - -This is a shorthand for: -@example -(service mcron-service-type - (mcron-configuration (mcron mcron) (jobs jobs))) -@end example -@end deffn - @defvr {Scheme Variable} mcron-service-type This is the type of the @code{mcron} service, whose value is an @code{mcron-configuration} object. @@ -11700,7 +11831,7 @@ specifications,, mcron, GNU@tie{}mcron}). @node Log Rotation -@subsubsection Log Rotation +@subsection Log Rotation @cindex rottlog @cindex log rotation @@ -11802,7 +11933,7 @@ The list of syslog-controlled files to be rotated. By default it is: @end defvr @node Networking Services -@subsubsection Networking Services +@subsection Networking Services The @code{(gnu services networking)} module provides services to configure the network interface. @@ -12267,12 +12398,6 @@ Tor} anonymous networking daemon. The service is configured using a @end defvr -@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}] -This procedure is deprecated and will be removed in a future release. Return -a service of the @code{tor-service-type} type. @var{config-file} and -@var{tor} have the same meaning as in @code{<tor-configuration>}. -@end deffn - @deftp {Data Type} tor-configuration @table @asis @item @code{tor} (default: @code{tor}) @@ -12597,6 +12722,19 @@ This is a symbol specifying the logging level: @code{quiet}, @code{fatal}, @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man page for @file{sshd_config} for the full list of level names. +@item @code{extra-content} (default: @code{""}) +This field can be used to append arbitrary text to the configuration file. It +is especially useful for elaborate configurations that cannot be expressed +otherwise. This configuration, for example, would generally disable root +logins, but permit them from one specific IP address: + +@example +(openssh-configuration + (extra-content "\ +Match Address 192.168.0.1 + PermitRootLogin yes")) +@end example + @end table @end deftp @@ -12672,31 +12810,54 @@ browsers, from accessing Facebook. The @code{(gnu services avahi)} provides the following definition. -@deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @ - [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @ - [#:ipv6? #t] [#:wide-area? #f] @ - [#:domains-to-browse '()] [#:debug? #f] -Return a service that runs @command{avahi-daemon}, a system-wide +@defvr {Scheme Variable} avahi-service-type +This is the service that runs @command{avahi-daemon}, a system-wide mDNS/DNS-SD responder that allows for service discovery and -"zero-configuration" host name lookups (see @uref{http://avahi.org/}), and -extends the name service cache daemon (nscd) so that it can resolve -@code{.local} host names using -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally, -add the @var{avahi} package to the system profile so that commands such as -@command{avahi-browse} are directly usable. - -If @var{host-name} is different from @code{#f}, use that as the host name to +``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). +Its value must be a @code{zero-configuration} record---see below. + +This service extends the name service cache daemon (nscd) so that it can +resolve @code{.local} host names using +@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name +Service Switch}, for information on host name resolution. + +Additionally, add the @var{avahi} package to the system profile so that +commands such as @command{avahi-browse} are directly usable. +@end defvr + +@deftp {Data Type} avahi-configuration +Data type representation the configuration for Avahi. + +@table @asis + +@item @code{host-name} (default: @code{#f}) +If different from @code{#f}, use that as the host name to publish for this machine; otherwise, use the machine's actual host name. -When @var{publish?} is true, publishing of host names and services is allowed; -in particular, avahi-daemon will publish the machine's host name and IP -address via mDNS on the local network. +@item @code{publish?} (default: @code{#t}) +When true, allow host names and services to be published (broadcast) over the +network. -When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled. +@item @code{publish-workstation?} (default: @code{#t}) +When true, @command{avahi-daemon} publishes the machine's host name and IP +address via mDNS on the local network. To view the host names published on +your local network, you can run: -Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use IPv4/IPv6 -sockets. -@end deffn +@example +avahi-browse _workstation._tcp +@end example + +@item @code{wide-area?} (default: @code{#f}) +When true, DNS-SD over unicast DNS is enabled. + +@item @code{ipv4?} (default: @code{#t}) +@itemx @code{ipv6?} (default: @code{#t}) +These fields determine whether to use IPv4/IPv6 sockets. + +@item @code{domains-to-browse} (default: @code{'()}) +This is a list of domains to browse. +@end table +@end deftp @deffn {Scheme Variable} openvswitch-service-type This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} @@ -12717,7 +12878,7 @@ Package object of the Open vSwitch. @end deftp @node X Window -@subsubsection X Window +@subsection X Window @cindex X11 @cindex X Window System @@ -13001,11 +13162,11 @@ makes the good ol' XlockMore usable. @node Printing Services -@subsubsection Printing Services +@subsection Printing Services @cindex printer support with CUPS The @code{(gnu services cups)} module provides a Guix service definition -for the CUPS printing service. To add printer support to a GuixSD +for the CUPS printing service. To add printer support to a Guix system, add a @code{cups-service} to the operating system definition: @deffn {Scheme Variable} cups-service-type @@ -13842,7 +14003,7 @@ this: @node Desktop Services -@subsubsection Desktop Services +@subsection Desktop Services The @code{(gnu services desktop)} module provides services that are usually useful in the context of a ``desktop'' setup---that is, on a @@ -14150,7 +14311,7 @@ Users need to be in the @code{lp} group to access the D-Bus service. @end deffn @node Sound Services -@subsubsection Sound Services +@subsection Sound Services @cindex sound support @cindex ALSA @@ -14231,7 +14392,7 @@ details. @node Database Services -@subsubsection Database Services +@subsection Database Services @cindex database @cindex SQL @@ -14355,7 +14516,7 @@ Directory in which to store the database and related files. @end deftp @node Mail Services -@subsubsection Mail Services +@subsection Mail Services @cindex mail @cindex email @@ -15698,7 +15859,7 @@ Defaults to @samp{""}. Whew! Lots of configuration options. The nice thing about it though is -that GuixSD has a complete interface to Dovecot's configuration +that Guix has a complete interface to Dovecot's configuration language. This allows not only a nice way to declare configurations, but also offers reflective capabilities as well: users can write code to inspect and transform configurations from within Scheme. @@ -15826,7 +15987,7 @@ the @code{postmaster} mail to @code{bob} (which subsequently would deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). @node Messaging Services -@subsubsection Messaging Services +@subsection Messaging Services @cindex messaging @cindex jabber @@ -16089,7 +16250,7 @@ Defaults to @samp{"internal_plain"}. @deftypevr {@code{prosody-configuration} parameter} maybe-string log Set logging options. Advanced logging configuration is not yet supported -by the GuixSD Prosody Service. See @url{https://prosody.im/doc/logging}. +by the Guix Prosody Service. See @url{https://prosody.im/doc/logging}. Defaults to @samp{"*syslog"}. @end deftypevr @@ -16295,9 +16456,40 @@ Configuration snippet added as-is to the BitlBee configuration file. @end table @end deftp +@subsubheading Quassel Service + +@cindex IRC (Internet Relay Chat) +@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, +meaning that one or more clients can attach to and detach from the +central core. + +@defvr {Scheme Variable} quassel-service-type +This is the service type for the @url{https://quassel-irc.org/,Quassel} +IRC backend daemon. Its value is a @code{quassel-configuration} +(see below). +@end defvr + +@deftp {Data Type} quassel-configuration +This is the configuration for Quassel, with the following fields: + +@table @asis +@item @code{quassel} (default: @code{quassel}) +The Quassel package to use. + +@item @code{interface} (default: @code{"::,0.0.0.0"}) +@item @code{port} (default: @code{4242}) +Listen on the network interface(s) corresponding to the IPv4 or IPv6 +interfaces specified in the comma delimited @var{interface}, on +@var{port}. + +@item @code{loglevel} (default: @code{"Info"}) +The level of logging desired. Accepted values are Debug, Info, Warning +and Error. +@end table +@end deftp @node Telephony Services -@subsubsection Telephony Services +@subsection Telephony Services @cindex Murmur (VoIP server) @cindex VoIP server @@ -16313,7 +16505,7 @@ look like this: (service murmur-service-type (murmur-configuration (welcome-text - "Welcome to this Mumble server running on GuixSD!") + "Welcome to this Mumble server running on Guix!") (cert-required? #t) ;disallow text password logins (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) @@ -16502,7 +16694,7 @@ If it is set your server will be linked by this host name instead. @node Monitoring Services -@subsubsection Monitoring Services +@subsection Monitoring Services @subsubheading Tailon Service @@ -17007,7 +17199,7 @@ Defaults to @samp{10051}. @c %end of fragment @node Kerberos Services -@subsubsection Kerberos Services +@subsection Kerberos Services @cindex Kerberos The @code{(gnu services kerberos)} module provides services relating to @@ -17133,7 +17325,7 @@ Local accounts with lower values will silently fail to authenticate. @node Web Services -@subsubsection Web Services +@subsection Web Services @cindex web @cindex www @@ -17662,7 +17854,7 @@ A service type for the @code{fcgiwrap} FastCGI proxy. @end defvr @deftp {Data Type} fcgiwrap-configuration -Data type representing the configuration of the @code{fcgiwrap} serice. +Data type representing the configuration of the @code{fcgiwrap} service. This type has the following parameters: @table @asis @item @code{package} (default: @code{fcgiwrap}) @@ -17837,7 +18029,7 @@ The cat avatar generator is a simple service to demonstrate the use of php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for instance the hash of a user's email address. -@deffn {Scheme Procedure} cat-avatar-generator-serice @ +@deffn {Scheme Procedure} cat-avatar-generator-service @ [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] @@ -17934,7 +18126,7 @@ more information on X.509 certificates. @end quotation @node Certificate Services -@subsubsection Certificate Services +@subsection Certificate Services @cindex Web @cindex HTTP, HTTPS @@ -18080,7 +18272,7 @@ For each @code{certificate-configuration}, the certificate is saved to @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. @node DNS Services -@subsubsection DNS Services +@subsection DNS Services @cindex DNS (domain name system) @cindex domain name system (DNS) @@ -18649,7 +18841,7 @@ Defaults to @samp{()}. @node VPN Services -@subsubsection VPN Services +@subsection VPN Services @cindex VPN (virtual private network) @cindex virtual private network (VPN) @@ -19007,7 +19199,7 @@ Defaults to @samp{#f}. @node Network File System -@subsubsection Network File System +@subsection Network File System @cindex NFS The @code{(gnu services nfs)} module provides the following services, @@ -19122,7 +19314,7 @@ If it is @code{#f} then the daemon will use the host's fully qualified domain na @end deftp @node Continuous Integration -@subsubsection Continuous Integration +@subsection Continuous Integration @cindex continuous integration @uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a @@ -19239,7 +19431,7 @@ The Cuirass package to use. @end deftp @node Power Management Services -@subsubsection Power Management Services +@subsection Power Management Services @cindex tlp @cindex power management with TLP @@ -19773,7 +19965,7 @@ Package object of thermald. @end deftp @node Audio Services -@subsubsection Audio Services +@subsection Audio Services The @code{(gnu services audio)} module provides a service to start MPD (the Music Player Daemon). @@ -19823,7 +20015,7 @@ an absolute path can be specified here. @end deftp @node Virtualization Services -@subsubsection Virtualization services +@subsection Virtualization services The @code{(gnu services virtualization)} module provides services for the libvirt and virtlog daemons, as well as other virtualization-related @@ -20616,7 +20808,7 @@ Return the name of @var{platform}---a string such as @code{"arm"}. @end deffn @node Version Control Services -@subsubsection Version Control Services +@subsection Version Control Services The @code{(gnu services version-control)} module provides a service to allow remote access to local Git repositories. There are three options: @@ -21804,7 +21996,7 @@ This setting controls the commands and features to enable within Gitolite. @node Game Services -@subsubsection Game Services +@subsection Game Services @subsubheading The Battle for Wesnoth Service @cindex wesnothd @@ -21835,7 +22027,7 @@ The port to bind the server to. @end deftp @node Miscellaneous Services -@subsubsection Miscellaneous Services +@subsection Miscellaneous Services @cindex fingerprint @subsubheading Fingerprint Service @@ -21943,7 +22135,7 @@ that enables sharing the clipboard with a vm and setting the guest display resolution when the graphical console window resizes. @end deffn -@subsubsection Dictionary Services +@subsection Dictionary Services @cindex dictionary The @code{(gnu services dict)} module provides the following service: @@ -22041,8 +22233,35 @@ The following is an example @code{dicod-service} configuration. %dicod-database:gcide)))) @end example +@cindex Docker +@subsubheading Docker Service + +The @code{(gnu services docker)} module provides the following service. + +@defvr {Scheme Variable} docker-service-type + +This is the type of the service that runs @url{http://www.docker.com,Docker}, +a daemon that can execute application bundles (sometimes referred to as +``containers'') in isolated environments. + +@end defvr + +@deftp {Data Type} docker-configuration +This is the data type representing the configuration of Docker and Containerd. + +@table @asis + +@item @code{package} (default: @code{docker}) +The Docker package to use. + +@item @code{containerd} (default: @var{containerd}) +The Containerd package to use. + +@end table +@end deftp + @node Setuid Programs -@subsection Setuid Programs +@section Setuid Programs @cindex setuid programs Some programs need to run with ``root'' privileges, even when they are @@ -22088,7 +22307,7 @@ files in this directory refer to the ``real'' binaries, which are in the store. @node X.509 Certificates -@subsection X.509 Certificates +@section X.509 Certificates @cindex HTTPS, certificates @cindex X.509 certificates @@ -22109,9 +22328,9 @@ However, most other programs that can talk HTTPS---@command{wget}, certificates can be found. @cindex @code{nss-certs} -In GuixSD, this is done by adding a package that provides certificates +In Guix, this is done by adding a package that provides certificates to the @code{packages} field of the @code{operating-system} declaration -(@pxref{operating-system Reference}). GuixSD includes one such package, +(@pxref{operating-system Reference}). Guix includes one such package, @code{nss-certs}, which is a set of CA certificates provided as part of Mozilla's Network Security Services. @@ -22151,7 +22370,7 @@ variable in the relevant documentation. @node Name Service Switch -@subsection Name Service Switch +@section Name Service Switch @cindex name service switch @cindex NSS @@ -22208,8 +22427,8 @@ want is to have @code{.local} host lookup working. Note that, in this case, in addition to setting the @code{name-service-switch} of the @code{operating-system} declaration, -you also need to use @code{avahi-service} (@pxref{Networking Services, -@code{avahi-service}}), or @var{%desktop-services}, which includes it +you also need to use @code{avahi-service-type} (@pxref{Networking Services, +@code{avahi-service-type}}), or @var{%desktop-services}, which includes it (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible to the name service cache daemon (@pxref{Base Services, @code{nscd-service}}). @@ -22289,7 +22508,7 @@ Reference Manual}). For example: @end deftp @node Initial RAM Disk -@subsection Initial RAM Disk +@section Initial RAM Disk @cindex initrd @cindex initial RAM disk @@ -22360,7 +22579,7 @@ honors several options passed on the Linux kernel command line Tell the initial RAM disk to load @var{boot}, a file containing a Scheme program, once it has mounted the root file system. -GuixSD uses this option to yield control to a boot program that runs the +Guix uses this option to yield control to a boot program that runs the service activation programs and then spawns the GNU@tie{}Shepherd, the initialization system. @@ -22449,7 +22668,7 @@ automatically copied to the initrd. @end deffn @node Bootloader Configuration -@subsection Bootloader Configuration +@section Bootloader Configuration @cindex bootloader @cindex boot loader @@ -22633,7 +22852,7 @@ logos. @node Invoking guix system -@subsection Invoking @code{guix system} +@section Invoking @code{guix system} Once you have written an operating system declaration as seen in the previous section, it can be @dfn{instantiated} using the @command{guix @@ -22689,7 +22908,7 @@ As for @command{guix package --search}, the result is written in Build the operating system described in @var{file}, activate it, and switch to it@footnote{This action (and the related actions @code{switch-generation} and @code{roll-back}) are usable only on -systems already running GuixSD.}. +systems already running Guix System.}. This effects all the configuration specified in @var{file}: user accounts, system services, global package list, setuid programs, etc. @@ -22779,7 +22998,7 @@ This action does not actually install anything. @item init Populate the given directory with all the files necessary to run the operating system specified in @var{file}. This is useful for first-time -installations of GuixSD. For instance: +installations of Guix System. For instance: @example guix system init my-os-config.scm /mnt @@ -22801,6 +23020,16 @@ passed. @anchor{guix system vm} Build a virtual machine that contains the operating system declared in @var{file}, and return a script to run that virtual machine (VM). + +@quotation Note +The @code{vm} action and others below +can use KVM support in the Linux-libre kernel. Specifically, if the +machine has hardware virtualization support, the corresponding +KVM kernel module should be loaded, and the @file{/dev/kvm} device node +must exist and be readable and writable by the user and by the +build users of the daemon (@pxref{Build Environment Setup}). +@end quotation + Arguments given to the script are passed to QEMU as in the example below, which enables networking and requests 1@tie{}GiB of RAM for the emulated machine: @@ -22852,7 +23081,7 @@ You can specify the root file system type by using the @option{--file-system-type} option. It defaults to @code{ext4}. When using @code{vm-image}, the returned image is in qcow2 format, which -the QEMU emulator can efficiently use. @xref{Running GuixSD in a VM}, +the QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for more information on how to run the image in a virtual machine. When using @code{disk-image}, a raw disk image is produced; it can be @@ -22878,7 +23107,7 @@ docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ @end example This command starts a new Docker container from the specified image. It -will boot the GuixSD system in the usual manner, which means it will +will boot the Guix system in the usual manner, which means it will start any services you have defined in the operating system configuration. Depending on what you run in the Docker container, it may be necessary to give the container additional permissions. For @@ -22923,7 +23152,7 @@ following: Consider the operating-system @var{expr} evaluates to. This is an alternative to specifying a file which evaluates to an operating system. -This is used to generate the GuixSD installer @pxref{Building the +This is used to generate the Guix system installer @pxref{Building the Installation Image}). @item --system=@var{system} @@ -22997,17 +23226,8 @@ a list of available debugging commands. @end table @end table -@quotation Note -All the actions above, except @code{build} and @code{init}, -can use KVM support in the Linux-libre kernel. Specifically, if the -machine has hardware virtualization support, the corresponding -KVM kernel module should be loaded, and the @file{/dev/kvm} device node -must exist and be readable and writable by the user and by the -build users of the daemon (@pxref{Build Environment Setup}). -@end quotation - Once you have built, configured, re-configured, and re-re-configured -your GuixSD installation, you may find it useful to list the operating +your Guix installation, you may find it useful to list the operating system generations available on disk---and that you can choose from the bootloader boot menu: @@ -23060,12 +23280,12 @@ example graph. @end table -@node Running GuixSD in a VM -@subsection Running GuixSD in a Virtual Machine +@node Running Guix in a VM +@section Running Guix in a Virtual Machine @cindex virtual machine -To run GuixSD in a virtual machine (VM), one can either use the -pre-built GuixSD VM image distributed at +To run Guix in a virtual machine (VM), one can either use the +pre-built Guix VM image distributed at @indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} , or build their own virtual machine image using @command{guix system vm-image} (@pxref{Invoking guix system}). The returned image is in @@ -23126,7 +23346,7 @@ to your system definition and start the VM using it uses the ICMP protocol. You'll have to use a different command to check for network connectivity, for example @command{guix download}. -@subsubsection Connecting Through SSH +@subsection Connecting Through SSH @cindex SSH @cindex SSH server @@ -23152,7 +23372,7 @@ every time you modify your @command{config.scm} file and the @command{-o StrictHostKeyChecking=no} prevents you from having to allow a connection to an unknown host every time you connect. -@subsubsection Using @command{virt-viewer} with Spice +@subsection Using @command{virt-viewer} with Spice As an alternative to the default @command{qemu} graphical client you can use the @command{remote-viewer} from the @command{virt-viewer} package. To @@ -23172,7 +23392,7 @@ name=com.redhat.spice.0 You'll also need to add the @pxref{Miscellaneous Services, Spice service}. @node Defining Services -@subsection Defining Services +@section Defining Services The previous sections show the available services and how one can combine them in an @code{operating-system} declaration. But how do we define @@ -23186,7 +23406,7 @@ them in the first place? And what is a service anyway? @end menu @node Service Composition -@subsubsection Service Composition +@subsection Service Composition @cindex services @cindex daemons @@ -23204,11 +23424,11 @@ daemon; the @file{/etc} service populates the @file{/etc} directory of the system. @cindex service extensions -GuixSD services are connected by @dfn{extensions}. For instance, the -secure shell service @emph{extends} the Shepherd---the GuixSD +Guix system services are connected by @dfn{extensions}. For instance, the +secure shell service @emph{extends} the Shepherd---the initialization system, running as PID@tie{}1---by giving it the command lines to start and stop the secure shell daemon (@pxref{Networking -Services, @code{lsh-service}}); the UPower service extends the D-Bus +Services, @code{openssh-service-type}}); the UPower service extends the D-Bus service by passing it its @file{.service} specification, and extends the udev service by passing it device management rules (@pxref{Desktop Services, @code{upower-service}}); the Guix daemon service extends the @@ -23235,14 +23455,14 @@ particular operating system definition. Technically, developers can define @dfn{service types} to express these relations. There can be any number of services of a given type on the system---for instance, a system running two instances of the GNU secure -shell server (lsh) has two instances of @var{lsh-service-type}, with +shell server (lsh) has two instances of @code{lsh-service-type}, with different parameters. The following section describes the programming interface for service types and services. @node Service Types and Services -@subsubsection Service Types and Services +@subsection Service Types and Services A @dfn{service type} is a node in the DAG described above. Let us start with a simple example, the service type for the Guix build daemon @@ -23379,7 +23599,7 @@ Still here? The next section provides a reference of the programming interface for services. @node Service Reference -@subsubsection Service Reference +@subsection Service Reference We have seen an overview of service types (@pxref{Service Types and Services}). This section provides a reference on how to manipulate @@ -23604,13 +23824,13 @@ extend it by passing it lists of packages to add to the system profile. @node Shepherd Services -@subsubsection Shepherd Services +@subsection Shepherd Services @cindex shepherd services @cindex PID 1 @cindex init system The @code{(gnu services shepherd)} module provides a way to define -services managed by the GNU@tie{}Shepherd, which is the GuixSD +services managed by the GNU@tie{}Shepherd, which is the initialization system---the first process that is started when the system boots, also known as PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}). @@ -23748,7 +23968,7 @@ This service represents PID@tie{}1. @node Documentation -@section Documentation +@chapter Documentation @cindex documentation, searching for @cindex searching for documentation @@ -23812,7 +24032,7 @@ bindings to navigate manuals. @xref{Getting Started,,, info, Info: An Introduction}, for an introduction to Info navigation. @node Installing Debugging Files -@section Installing Debugging Files +@chapter Installing Debugging Files @cindex debugging files Program binaries, as produced by the GCC compilers for instance, are @@ -23878,7 +24098,7 @@ the load. To check whether a package has a @code{debug} output, use @node Security Updates -@section Security Updates +@chapter Security Updates @cindex security updates @cindex security vulnerabilities @@ -23983,7 +24203,7 @@ guix gc -R `readlink -f ~/.guix-profile` | grep bash @noindent @dots{} and compare the store file names that you get with those above. -Likewise for a complete GuixSD system generation: +Likewise for a complete Guix system generation: @example guix gc -R `guix system build my-config.scm` | grep bash @@ -23997,521 +24217,8 @@ lsof | grep /gnu/store/.*bash @end example -@node Package Modules -@section Package Modules - -From a programming viewpoint, the package definitions of the -GNU distribution are provided by Guile modules in the @code{(gnu packages -@dots{})} name space@footnote{Note that packages under the @code{(gnu -packages @dots{})} module name space are not necessarily ``GNU -packages''. This module naming scheme follows the usual Guile module -naming convention: @code{gnu} means that these modules are distributed -as part of the GNU system, and @code{packages} identifies modules that -define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile -Reference Manual}). For instance, the @code{(gnu packages emacs)} -module exports a variable named @code{emacs}, which is bound to a -@code{<package>} object (@pxref{Defining Packages}). - -The @code{(gnu packages @dots{})} module name space is -automatically scanned for packages by the command-line tools. For -instance, when running @code{guix package -i emacs}, all the @code{(gnu -packages @dots{})} modules are scanned until one that exports a package -object whose name is @code{emacs} is found. This package search -facility is implemented in the @code{(gnu packages)} module. - -@cindex customization, of packages -@cindex package module search path -Users can store package definitions in modules with different -names---e.g., @code{(my-packages emacs)}@footnote{Note that the file -name and module name must match. For instance, the @code{(my-packages -emacs)} module must be stored in a @file{my-packages/emacs.scm} file -relative to the load path specified with @option{--load-path} or -@code{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,, -guile, GNU Guile Reference Manual}, for details.}. There are two ways to make -these package definitions visible to the user interfaces: - -@enumerate -@item -By adding the directory containing your package modules to the search path -with the @code{-L} flag of @command{guix package} and other commands -(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH} -environment variable described below. - -@item -By defining a @dfn{channel} and configuring @command{guix pull} so that it -pulls from it. A channel is essentially a Git repository containing package -modules. @xref{Channels}, for more information on how to define and use -channels. -@end enumerate - -@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: - -@defvr {Environment Variable} GUIX_PACKAGE_PATH -This is a colon-separated list of directories to search for additional -package modules. Directories listed in this variable take precedence -over the own modules of the distribution. -@end defvr - -The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: -each package is built based solely on other packages in the -distribution. The root of this dependency graph is a small set of -@dfn{bootstrap binaries}, provided by the @code{(gnu packages -bootstrap)} module. For more information on bootstrapping, -@pxref{Bootstrapping}. - -@node Packaging Guidelines -@section Packaging Guidelines - -@cindex packages, creating -The GNU distribution is nascent and may well lack some of your favorite -packages. This section describes how you can help make the distribution -grow. @xref{Contributing}, for additional information on how you can -help. - -Free software packages are usually distributed in the form of -@dfn{source code tarballs}---typically @file{tar.gz} files that contain -all the source files. Adding a package to the distribution means -essentially two things: adding a @dfn{recipe} that describes how to -build the package, including a list of other packages required to build -it, and adding @dfn{package metadata} along with that recipe, such as a -description and licensing information. - -In Guix all this information is embodied in @dfn{package definitions}. -Package definitions provide a high-level view of the package. They are -written using the syntax of the Scheme programming language; in fact, -for each package we define a variable bound to the package definition, -and export that variable from a module (@pxref{Package Modules}). -However, in-depth Scheme knowledge is @emph{not} a prerequisite for -creating packages. For more information on package definitions, -@pxref{Defining Packages}. - -Once a package definition is in place, stored in a file in the Guix -source tree, it can be tested using the @command{guix build} command -(@pxref{Invoking guix build}). For example, assuming the new package is -called @code{gnew}, you may run this command from the Guix build tree -(@pxref{Running Guix Before It Is Installed}): - -@example -./pre-inst-env guix build gnew --keep-failed -@end example - -Using @code{--keep-failed} makes it easier to debug build failures since -it provides access to the failed build tree. Another useful -command-line option when debugging is @code{--log-file}, to access the -build log. - -If the package is unknown to the @command{guix} command, it may be that -the source file contains a syntax error, or lacks a @code{define-public} -clause to export the package variable. To figure it out, you may load -the module from Guile to get more information about the actual error: - -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example - -Once your package builds correctly, please send us a patch -(@pxref{Contributing}). Well, if you need help, we will be happy to -help you too. Once the patch is committed in the Guix repository, the -new package automatically gets built on the supported platforms by -@url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration -system}. - -@cindex substituter -Users can obtain the new package definition simply by running -@command{guix pull} (@pxref{Invoking guix pull}). When -@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the -package automatically downloads binaries from there -(@pxref{Substitutes}). The only place where human intervention is -needed is to review and apply the patch. - - -@menu -* Software Freedom:: What may go into the distribution. -* Package Naming:: What's in a name? -* Version Numbers:: When the name is not enough. -* Synopses and Descriptions:: Helping users find the right package. -* Python Modules:: A touch of British comedy. -* Perl Modules:: Little pearls. -* Java Packages:: Coffee break. -* Fonts:: Fond of fonts. -@end menu - -@node Software Freedom -@subsection Software Freedom - -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -@cindex free software -The GNU operating system has been developed so that users can have -freedom in their computing. GNU is @dfn{free software}, meaning that -users have the @url{http://www.gnu.org/philosophy/free-sw.html,four -essential freedoms}: to run the program, to study and change the program -in source code form, to redistribute exact copies, and to distribute -modified versions. Packages found in the GNU distribution provide only -software that conveys these four freedoms. - -In addition, the GNU distribution follow the -@url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free -software distribution guidelines}. Among other things, these guidelines -reject non-free firmware, recommendations of non-free software, and -discuss ways to deal with trademarks and patents. - -Some otherwise free upstream package sources contain a small and optional -subset that violates the above guidelines, for instance because this subset -is itself non-free code. When that happens, the offending items are removed -with appropriate patches or code snippets in the @code{origin} form of the -package (@pxref{Defining Packages}). This way, @code{guix -build --source} returns the ``freed'' source rather than the unmodified -upstream source. - - -@node Package Naming -@subsection Package Naming - -@cindex package name -A package has actually two names associated with it: -First, there is the name of the @emph{Scheme variable}, the one following -@code{define-public}. By this name, the package can be made known in the -Scheme code, for instance as input to another package. Second, there is -the string in the @code{name} field of a package definition. This name -is used by package management commands such as -@command{guix package} and @command{guix build}. - -Both are usually the same and correspond to the lowercase conversion of -the project name chosen upstream, with underscores replaced with -hyphens. For instance, GNUnet is available as @code{gnunet}, and -SDL_net as @code{sdl-net}. - -We do not add @code{lib} prefixes for library packages, unless these are -already part of the official project name. But @pxref{Python -Modules} and @ref{Perl Modules} for special rules concerning modules for -the Python and Perl languages. - -Font package names are handled differently, @pxref{Fonts}. - - -@node Version Numbers -@subsection Version Numbers - -@cindex package version -We usually package only the latest version of a given free software -project. But sometimes, for instance for incompatible library versions, -two (or more) versions of the same package are needed. These require -different Scheme variable names. We use the name as defined -in @ref{Package Naming} -for the most recent version; previous versions use the same name, suffixed -by @code{-} and the smallest prefix of the version number that may -distinguish the two versions. - -The name inside the package definition is the same for all versions of a -package and does not contain any version number. - -For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: - -@example -(define-public gtk+ - (package - (name "gtk+") - (version "3.9.12") - ...)) -(define-public gtk+-2 - (package - (name "gtk+") - (version "2.24.20") - ...)) -@end example -If we also wanted GTK+ 3.8.2, this would be packaged as -@example -(define-public gtk+-3.8 - (package - (name "gtk+") - (version "3.8.2") - ...)) -@end example - -@c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, -@c for a discussion of what follows. -@cindex version number, for VCS snapshots -Occasionally, we package snapshots of upstream's version control system -(VCS) instead of formal releases. This should remain exceptional, -because it is up to upstream developers to clarify what the stable -release is. Yet, it is sometimes necessary. So, what should we put in -the @code{version} field? - -Clearly, we need to make the commit identifier of the VCS snapshot -visible in the version string, but we also need to make sure that the -version string is monotonically increasing so that @command{guix package ---upgrade} can determine which version is newer. Since commit -identifiers, notably with Git, are not monotonically increasing, we add -a revision number that we increase each time we upgrade to a newer -snapshot. The resulting version string looks like this: - -@example -2.0.11-3.cabba9e - ^ ^ ^ - | | `-- upstream commit ID - | | - | `--- Guix package revision - | -latest upstream version -@end example - -It is a good idea to strip commit identifiers in the @code{version} -field to, say, 7 digits. It avoids an aesthetic annoyance (assuming -aesthetics have a role to play here) as well as problems related to OS -limits such as the maximum shebang length (127 bytes for the Linux -kernel.) It is best to use the full commit identifiers in -@code{origin}s, though, to avoid ambiguities. A typical package -definition may look like this: - -@example -(define my-package - (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") - (revision "1")) ;Guix package revision - (package - (version (git-version "0.9" revision commit)) - (source (origin - (method git-fetch) - (uri (git-reference - (url "git://example.org/my-package.git") - (commit commit))) - (sha256 (base32 "1mbikn@dots{}")) - (file-name (git-file-name name version)))) - ;; @dots{} - ))) -@end example - -@node Synopses and Descriptions -@subsection Synopses and Descriptions - -@cindex package description -@cindex package synopsis -As we have seen before, each package in GNU@tie{}Guix includes a -synopsis and a description (@pxref{Defining Packages}). Synopses and -descriptions are important: They are what @command{guix package ---search} searches, and a crucial piece of information to help users -determine whether a given package suits their needs. Consequently, -packagers should pay attention to what goes into them. - -Synopses must start with a capital letter and must not end with a -period. They must not start with ``a'' or ``the'', which usually does -not bring anything; for instance, prefer ``File-frobbing tool'' over ``A -tool that frobs files''. The synopsis should say what the package -is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is -used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines -matching a pattern''. - -Keep in mind that the synopsis must be meaningful for a very wide -audience. For example, ``Manipulate alignments in the SAM format'' -might make sense for a seasoned bioinformatics researcher, but might be -fairly unhelpful or even misleading to a non-specialized audience. It -is a good idea to come up with a synopsis that gives an idea of the -application domain of the package. In this example, this might give -something like ``Manipulate nucleotide sequence alignments'', which -hopefully gives the user a better idea of whether this is what they are -looking for. - -Descriptions should take between five and ten lines. Use full -sentences, and avoid using acronyms without first introducing them. -Please avoid marketing phrases such as ``world-leading'', -``industrial-strength'', and ``next-generation'', and avoid superlatives -like ``the most advanced''---they are not helpful to users looking for a -package and may even sound suspicious. Instead, try to be factual, -mentioning use cases and features. - -@cindex Texinfo markup, in package descriptions -Descriptions can include Texinfo markup, which is useful to introduce -ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or -hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you -should be careful when using some characters for example @samp{@@} and -curly braces which are the basic special characters in Texinfo -(@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces -such as @command{guix package --show} take care of rendering it -appropriately. - -Synopses and descriptions are translated by volunteers -@uref{http://translationproject.org/domain/guix-packages.html, at the -Translation Project} so that as many users as possible can read them in -their native language. User interfaces search them and display them in -the language specified by the current locale. - -To allow @command{xgettext} to extract them as translatable strings, -synopses and descriptions @emph{must be literal strings}. This means -that you cannot use @code{string-append} or @code{format} to construct -these strings: - -@lisp -(package - ;; @dots{} - (synopsis "This is translatable") - (description (string-append "This is " "*not*" " translatable."))) -@end lisp - -Translation is a lot of work so, as a packager, please pay even more -attention to your synopses and descriptions as every change may entail -additional work for translators. In order to help them, it is possible -to make recommendations or instructions visible to them by inserting -special comments like this (@pxref{xgettext Invocation,,, gettext, GNU -Gettext}): - -@example -;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. -(description "ARandR is designed to provide a simple visual front end -for the X11 resize-and-rotate (RandR) extension. @dots{}") -@end example - - -@node Python Modules -@subsection Python Modules - -@cindex python -We currently package Python 2 and Python 3, under the Scheme variable names -@code{python-2} and @code{python} as explained in @ref{Version Numbers}. -To avoid confusion and naming clashes with other programming languages, it -seems desirable that the name of a package for a Python module contains -the word @code{python}. - -Some modules are compatible with only one version of Python, others with both. -If the package Foo compiles only with Python 3, we name it -@code{python-foo}; if it compiles only with Python 2, we name it -@code{python2-foo}. If it is compatible with both versions, we create two -packages with the corresponding names. - -If a project already contains the word @code{python}, we drop this; -for instance, the module python-dateutil is packaged under the names -@code{python-dateutil} and @code{python2-dateutil}. If the project name -starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as -described above. - -@subsubsection Specifying Dependencies -@cindex inputs, for Python packages - -Dependency information for Python packages is usually available in the -package source tree, with varying degrees of accuracy: in the -@file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}. - -Your mission, when writing a recipe for a Python package, is to map -these dependencies to the appropriate type of ``input'' (@pxref{package -Reference, inputs}). Although the @code{pypi} importer normally does a -good job (@pxref{Invoking guix import}), you may want to check the -following check list to determine which dependency goes where. - -@itemize - -@item -We currently package Python 2 with @code{setuptools} and @code{pip} -installed like Python 3.4 has per default. Thus you don't need to -specify either of these as an input. @command{guix lint} will warn you -if you do. - -@item -Python dependencies required at run time go into -@code{propagated-inputs}. They are typically defined with the -@code{install_requires} keyword in @file{setup.py}, or in the -@file{requirements.txt} file. - -@item -Python packages required only at build time---e.g., those listed with -the @code{setup_requires} keyword in @file{setup.py}---or only for -testing---e.g., those in @code{tests_require}---go into -@code{native-inputs}. The rationale is that (1) they do not need to be -propagated because they are not needed at run time, and (2) in a -cross-compilation context, it's the ``native'' input that we'd want. - -Examples are the @code{pytest}, @code{mock}, and @code{nose} test -frameworks. Of course if any of these packages is also required at -run-time, it needs to go to @code{propagated-inputs}. - -@item -Anything that does not fall in the previous categories goes to -@code{inputs}, for example programs or C libraries required for building -Python packages containing C extensions. - -@item -If a Python package has optional dependencies (@code{extras_require}), -it is up to you to decide whether to add them or not, based on their -usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix -size}}). - -@end itemize - - -@node Perl Modules -@subsection Perl Modules - -@cindex perl -Perl programs standing for themselves are named as any other package, -using the lowercase upstream name. -For Perl packages containing a single class, we use the lowercase class name, -replace all occurrences of @code{::} by dashes and prepend the prefix -@code{perl-}. -So the class @code{XML::Parser} becomes @code{perl-xml-parser}. -Modules containing several classes keep their lowercase upstream name and -are also prepended by @code{perl-}. Such modules tend to have the word -@code{perl} somewhere in their name, which gets dropped in favor of the -prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}. - - -@node Java Packages -@subsection Java Packages - -@cindex java -Java programs standing for themselves are named as any other package, -using the lowercase upstream name. - -To avoid confusion and naming clashes with other programming languages, -it is desirable that the name of a package for a Java package is -prefixed with @code{java-}. If a project already contains the word -@code{java}, we drop this; for instance, the package @code{ngsjava} is -packaged under the name @code{java-ngs}. - -For Java packages containing a single class or a small class hierarchy, -we use the lowercase class name, replace all occurrences of @code{.} by -dashes and prepend the prefix @code{java-}. So the class -@code{apache.commons.cli} becomes package -@code{java-apache-commons-cli}. - - -@node Fonts -@subsection Fonts - -@cindex fonts -For fonts that are in general not installed by a user for typesetting -purposes, or that are distributed as part of a larger software package, -we rely on the general packaging rules for software; for instance, this -applies to the fonts delivered as part of the X.Org system or fonts that -are part of TeX Live. - -To make it easier for a user to search for fonts, names for other packages -containing only fonts are constructed as follows, independently of the -upstream package name. - -The name of a package containing only one font family starts with -@code{font-}; it is followed by the foundry name and a dash @code{-} -if the foundry is known, and the font family name, in which spaces are -replaced by dashes (and as usual, all upper case letters are transformed -to lower case). -For example, the Gentium font family by SIL is packaged under the name -@code{font-sil-gentium}. - -For a package containing several font families, the name of the collection -is used in the place of the font family name. -For instance, the Liberation fonts consist of three families, -Liberation Sans, Liberation Serif and Liberation Mono. -These could be packaged separately under the names -@code{font-liberation-sans} and so on; but as they are distributed together -under a common name, we prefer to package them together as -@code{font-liberation}. - -In the case where several formats of the same font family or font collection -are packaged separately, a short form of the format, prepended by a dash, -is added to the package name. We use @code{-ttf} for TrueType fonts, -@code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1 -fonts. - - - @node Bootstrapping -@section Bootstrapping +@chapter Bootstrapping @c Adapted from the ELS 2013 paper. @@ -24612,8 +24319,8 @@ compiler used to build the rest of GuixSD. @image{images/gcc-mesboot-bag-graph,6in,,Dependency graph of the gcc-mesboot} -@node Preparing to Use the Bootstrap Binaries -@subsection Preparing to Use the Bootstrap Binaries +@unnumberedsec Preparing to Use the Bootstrap Binaries + @c As of Emacs 24.3, Info-mode displays the image, but since it's a @c large image, it's hard to scroll. Oh well. @@ -24672,7 +24379,7 @@ Finally, the various tarballs are unpacked by the derivations @code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which point we have a working C tool chain. -@unnumberedsubsec Building the Build Tools +@unnumberedsec Building the Build Tools Bootstrapping is complete when we have a full tool chain that does not depend on the pre-built bootstrap tools discussed above. This @@ -24727,7 +24434,7 @@ implicitly used by any package that uses @code{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}). -@unnumberedsubsec Building the Bootstrap Binaries +@unnumberedsec Building the Bootstrap Binaries @cindex bootstrap binaries Because the final tool chain does not depend on the bootstrap binaries, @@ -24755,7 +24462,7 @@ unknown, but if you would like to investigate further (and have significant computational and storage resources to do so), then let us know. -@unnumberedsubsec Reducing the Set of Bootstrap Binaries +@unnumberedsec Reducing the Set of Bootstrap Binaries Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of binary code! Why is that a problem? It's a problem because these big chunks @@ -24789,7 +24496,7 @@ Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are also looking at any other bootstrap binaries. Your help is welcome! @node Porting -@section Porting to a New Platform +@chapter Porting to a New Platform As discussed above, the GNU distribution is self-contained, and self-containment is achieved by relying on pre-built ``bootstrap |