From cf4a912919e68112a14b93592e89e69c61148419 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludovic=20Court=C3=A8s?= Date: Wed, 16 Jul 2014 11:35:45 +0200 Subject: doc: Move "System Configuration" higher. * doc/guix.texi (GNU Distribution): Move "System Configuration" right after "System Installation". --- doc/guix.texi | 1701 ++++++++++++++++++++++++++++----------------------------- 1 file changed, 850 insertions(+), 851 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 7187f76936..cbef829f7b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -2604,12 +2604,12 @@ For information on porting to other architectures or kernels, @menu * System Installation:: Installing the whole operating system. +* System Configuration:: Configuring a GNU system. * Installing Debugging Files:: Feeding the debugger. * 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 Configuration:: Configuring a GNU system. @end menu Building this distribution is a cooperative effort, and you are invited @@ -2781,1069 +2781,1068 @@ guix system disk-image --image-size=800MiB gnu/system/install.scm @file{gnu/system/install.scm} in the source tree for more information about the installation image. +@node System Configuration +@section System Configuration -@node Installing Debugging Files -@section Installing Debugging Files - -@cindex debugging files -Program binaries, as produced by the GCC compilers for instance, are -typically written in the ELF format, with a section containing -@dfn{debugging information}. Debugging information is what allows the -debugger, GDB, to map binary code to source code; it is required to -debug a compiled program in good conditions. - -The problem with debugging information is that is takes up a fair amount -of disk space. For example, debugging information for the GNU C Library -weighs in at more than 60 MiB. Thus, as a user, keeping all the -debugging info of all the installed programs is usually not an option. -Yet, space savings should not come at the cost of an impediment to -debugging---especially in the GNU system, which should make it easier -for users to exert their computing freedom (@pxref{GNU Distribution}). - -Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a -mechanism that allows users to get the best of both worlds: debugging -information can be stripped from the binaries and stored in separate -files. GDB is then able to load debugging information from those files, -when they are available (@pxref{Separate Debug Files,,, gdb, Debugging -with GDB}). - -The GNU distribution takes advantage of this by storing debugging -information in the @code{lib/debug} sub-directory of a separate package -output unimaginatively called @code{debug} (@pxref{Packages with -Multiple Outputs}). Users can choose to install the @code{debug} output -of a package when they need it. For instance, the following command -installs the debugging information for the GNU C Library and for GNU -Guile: - -@example -guix package -i glibc:debug guile:debug -@end example +@cindex system configuration +The GNU system supports a consistent whole-system configuration +mechanism. By that we mean that all aspects of the global system +configuration---such as the available system services, timezone and +locale settings, user accounts---are declared in a single place. Such +a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected. -GDB must then be told to look for debug files in the user's profile, by -setting the @code{debug-file-directory} variable (consider setting it -from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with -GDB}): +One of the advantages of putting all the system configuration under the +control of Guix is that it supports transactional system upgrades, and +makes it possible to roll-back to a previous system instantiation, +should something go wrong with the new one (@pxref{Features}). Another +one is that it makes it easy to replicate the exact same configuration +across different machines, or at different points in time, without +having to resort to additional administration tools layered on top of +the system's own tools. +@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example +This section describes this mechanism. First we focus on the system +administrator's viewpoint---explaining how the system is configured and +instantiated. Then we show how this mechanism can be extended, for +instance to support new system services. -From there on, GDB will pick up debugging information from the -@code{.debug} files under @file{~/.guix-profile/lib/debug}. +@menu +* Using the Configuration System:: Customizing your GNU system. +* File Systems:: Configuring file system mounts. +* User Accounts:: Specifying user accounts. +* Services:: Specifying system services. +* Invoking guix system:: Instantiating a system configuration. +* Defining Services:: Adding new service definitions. +@end menu -In addition, you will most likely want GDB to be able to show the source -code being debugged. To do that, you will have to unpack the source -code of the package of interest (obtained with @code{guix build ---source}, @pxref{Invoking guix build}), and to point GDB to that source -directory using the @code{directory} command (@pxref{Source Path, -@code{directory},, gdb, Debugging with GDB}). +@node Using the Configuration System +@subsection Using the Configuration System -@c XXX: keep me up-to-date -The @code{debug} output mechanism in Guix is implemented by the -@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is -opt-in---debugging information is available only for those packages -whose definition explicitly declares a @code{debug} output. This may be -changed to opt-out in the future, if our build farm servers can handle -the load. To check whether a package has a @code{debug} output, use -@command{guix package --list-available} (@pxref{Invoking guix package}). +The operating system is configured by providing an +@code{operating-system} declaration in a file that can then be passed to +the @command{guix system} command (@pxref{Invoking guix system}). A +simple setup, with the default system services, the default Linux-Libre +kernel, initial RAM disk, and boot loader looks like this: +@findex operating-system +@lisp +(use-modules (gnu) ; for 'user-account', '%base-services', etc. + (gnu packages emacs) ; for 'emacs' + (gnu services ssh)) ; for 'lsh-service' -@node Package Modules -@section Package Modules +(operating-system + (host-name "komputilo") + (timezone "Europe/Paris") + (locale "fr_FR.UTF-8") + (bootloader (grub-configuration + (device "/dev/sda"))) + (file-systems (list (file-system + (device "/dev/sda1") ; or partition label + (mount-point "/") + (type "ext3")))) + (users (list (user-account + (name "alice") + (password "") + (uid 1000) (gid 100) + (comment "Bob's sister") + (home-directory "/home/alice")))) + (packages (cons emacs %base-packages)) + (services (cons (lsh-service #:port 2222 #:allow-root-login? #t) + %base-services))) +@end lisp -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{} object (@pxref{Defining Packages}). +This example should be self-describing. Some of the fields defined +above, such as @code{host-name} and @code{bootloader}, are mandatory. +Others, such as @code{packages} and @code{services}, can be omitted, in +which case they get a default value. -The @code{(gnu packages @dots{})} module name space is special: it 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. +@vindex %base-packages +The @code{packages} field lists +packages that will be globally visible on the system, for all user +accounts---i.e., in every user's @code{PATH} environment variable---in +addition to the per-user profiles (@pxref{Invoking guix package}). The +@var{%base-packages} variable provides all the tools one would expect +for basic user and administrator tasks---including the GNU Core +Utilities, the GNU Networking Utilities, the GNU Zile lightweight text +editor, @command{find}, @command{grep}, etc. The example above adds +Emacs to those, taken from the @code{(gnu packages emacs)} module +(@pxref{Package Modules}). -Users can store package definitions in modules with different -names---e.g., @code{(my-packages emacs)}. In that case, commands such -as @command{guix package} and @command{guix build} have to be used with -the @code{-e} option so that they know where to find the package. +@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 +daemon listening on port 2222, and allowing remote @code{root} logins +(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood, +@code{lsh-service} arranges so that @code{lshd} is started with the +right command-line options, possibly with supporting configuration files +generated as needed (@pxref{Defining Services}). -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, -@ref{Bootstrapping}. +Assuming the above snippet is stored in the @file{my-system-config.scm} +file, the @command{guix system reconfigure my-system-config.scm} command +instantiates that configuration, and makes it the default GRUB boot +entry (@pxref{Invoking guix system}). The normal way to change the +system's configuration is by updating this file and re-running the +@command{guix system} command. -@node Packaging Guidelines -@section Packaging Guidelines +At the Scheme level, the bulk of an @code{operating-system} declaration +is instantiated with the following monadic procedure (@pxref{The Store +Monad}): -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. +@deffn {Monadic Procedure} operating-system-derivation os +Return a derivation that builds @var{os}, an @code{operating-system} +object (@pxref{Derivations}). -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 meta-data} along with that recipe, such as a -description and licensing information. +The output of the derivation is a single directory that refers to all +the packages, configuration files, and other supporting files needed to +instantiate @var{os}. +@end deffn -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, -@ref{Defining Packages}. +@node File Systems +@subsection File Systems -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: +The list of file systems to be mounted is specified in the +@code{file-systems} field of the operating system's declaration +(@pxref{Using the Configuration System}). Each file system is declared +using the @code{file-system} form, like this: @example -./pre-inst-env guix build gnew --keep-failed +(file-system + (mount-point "/home") + (device "/dev/sda3") + (type "ext4")) @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. +As usual, some of the fields are mandatory---those shown in the example +above---while others can be omitted. These are described below. -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: +@deftp {Data Type} file-system +Objects of this type represent file systems to be mounted. They +contain the following members: -@example -./pre-inst-env guile -c '(use-modules (gnu packages gnew))' -@end example +@table @asis +@item @code{type} +This is a string specifying the type of the file system---e.g., +@code{"ext4"}. -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/gnu/master, our continuous integration -system}. +@item @code{mount-point} +This designates the place where the file system is to be mounted. -@cindex substituter -Users can obtain the new package definition simply by running -@command{guix pull} (@pxref{Invoking guix pull}). When -@code{hydra.gnu.org} 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. +@item @code{device} +This names the ``source'' of the file system. By default it is the name +of a node under @file{/dev}, but its meaning depends on the @code{title} +field described below. +@item @code{title} (default: @code{'device}) +This is a symbol that specifies how the @code{device} field is to be +interpreted. -@menu -* Software Freedom:: What may go into the distribution. -* Package Naming:: What's in a name? -* Version Numbers:: When the name is not enough. -* Python Modules:: Taming the snake. -* Perl Modules:: Little pearls. -@end menu +When it is the symbol @code{device}, then the @code{device} field is +interpreted as a file name; when it is @code{label}, then @code{device} +is interpreted as a partition label name; when it is @code{uuid}, +@code{device} is interpreted as a partition unique identifier (UUID). -@node Software Freedom -@subsection Software Freedom +The @code{label} and @code{uuid} options offer a way to refer to disk +partitions without having to hard-code their actual device name. -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. +@item @code{flags} (default: @code{'()}) +This is a list of symbols denoting mount flags. Recognized flags +include @code{read-only} and @code{bind-mount}. -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. +@item @code{options} (default: @code{#f}) +This is either @code{#f}, or a string denoting mount options. -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. +@item @code{needed-for-boot?} (default: @code{#f}) +This Boolean value indicates whether the file system is needed when +booting. If that is true, then the file system is mounted when the +initial RAM disk (initrd) is loaded. This is always the case, for +instance, for the root file system. -Some packages 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 package definition's -@code{origin} form (@pxref{Defining Packages}). That way, @code{guix -build --source} returns the ``freed'' source rather than the unmodified -upstream source. +@item @code{check?} (default: @code{#t}) +This Boolean indicates whether the file system needs to be checked for +errors before being mounted. +@end table +@end deftp -@node Package Naming -@subsection Package Naming +@node User Accounts +@subsection User Accounts -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}. +User accounts are specified with the @code{user-account} form: -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}. +@example +(user-account + (name "alice") + (group "users") + (supplementary-groups '("wheel")) ; allow use of sudo, etc. + (comment "Bob's sister") + (home-directory "/home/alice")) +@end example -We do not add @code{lib} prefixes for library packages, unless these are -already part of the official project name. But see @pxref{Python -Modules} and @ref{Perl Modules} for special rules concerning modules for -the Python and Perl languages. +@deftp {Data Type} user-account +Objects of this type represent user accounts. The following members may +be specified: +@table @asis +@item @code{name} +The name of the user account. -@node Version Numbers -@subsection Version Numbers +@item @code{group} +This is the name (a string) or identifier (a number) of the user group +this account belongs to. -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. +@item @code{supplementary-groups} (default: @code{'()}) +Optionally, this can be defined as a list of group names that this +account belongs to. -The name inside the package definition is the same for all versions of a -package and does not contain any version number. +@item @code{uid} (default: @code{#f}) +This is the user ID for this account (a number), or @code{#f}. In the +latter case, a number is automatically chosen by the system when the +account is created. -For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: +@item @code{comment} (default: @code{""}) +A comment about the account, such as the account's owner full name. -@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 +@item @code{home-directory} +This is the name of the home directory for the account. +@item @code{shell} (default: Bash) +This is a G-expression denoting the file name of a program to be used as +the shell (@pxref{G-Expressions}). -@node Python Modules -@subsection Python Modules +@item @code{system?} (default: @code{#f}) +This Boolean value indicates whether the account is a ``system'' +account. System accounts are sometimes treated specially; for instance, +graphical login managers do not list them. -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}. +@item @code{password} (default: @code{#f}) +Unless @code{#f}, this is the password to be used for the account. -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. +@end table +@end deftp -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}. +User group declarations are even simpler: +@example +(user-group (name "students")) +@end example -@node Perl Modules -@subsection Perl Modules +@deftp {Data Type} user-group +This type is for, well, user groups. There are just a few fields: -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}. +@table @asis +@item @code{name} +The group's name. +@item @code{id} (default: @code{#f}) +The group identifier (a number). If @code{#f}, a new number is +automatically allocated when the group is created. +@item @code{password} (default: @code{#f}) +What, user groups can have a password? Well, apparently yes. Unless +@code{#f}, this field specifies the group's password. -@node Bootstrapping -@section Bootstrapping +@end table +@end deftp -@c Adapted from the ELS 2013 paper. +For convenience, a variable lists all the basic user groups one may +expect: -@cindex bootstrapping +@defvr {Scheme Variable} %base-groups +This is the list of basic user groups that users and/or packages expect +to be present on the system. This includes groups such as ``root'', +``wheel'', and ``users'', as well as groups used to control access to +specific devices such as ``audio'', ``disk'', and ``cdrom''. +@end defvr -Bootstrapping in our context refers to how the distribution gets built -``from nothing''. Remember that the build environment of a derivation -contains nothing but its declared inputs (@pxref{Introduction}). So -there's an obvious chicken-and-egg problem: how does the first package -get built? How does the first compiler get compiled? Note that this is -a question of interest only to the curious hacker, not to the regular -user, so you can shamelessly skip this section if you consider yourself -a ``regular user''. -@cindex bootstrap binaries -The GNU system is primarily made of C code, with libc at its core. The -GNU build system itself assumes the availability of a Bourne shell and -command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and -`grep'. Furthermore, build programs---programs that run -@code{./configure}, @code{make}, etc.---are written in Guile Scheme -(@pxref{Derivations}). Consequently, to be able to build anything at -all, from scratch, Guix relies on pre-built binaries of Guile, GCC, -Binutils, libc, and the other packages mentioned above---the -@dfn{bootstrap binaries}. +@node Services +@subsection Services -These bootstrap binaries are ``taken for granted'', though we can also -re-create them if needed (more on that later). +@cindex system services +An important part of preparing an @code{operating-system} declaration is +listing @dfn{system services} and their configuration (@pxref{Using the +Configuration System}). System services are typically daemons launched +when the system boots, or other actions needed at that time---e.g., +configuring network access. They are managed by GNU@tie{}dmd +(@pxref{Introduction,,, dmd, GNU dmd Manual}). -@unnumberedsubsec Preparing to Use the Bootstrap Binaries +The following sections document the available services, starting with +the core services. -@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. -@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations} +@menu +* Base Services:: Essential system services. +* Networking Services:: Network setup, SSH daemon, etc. +* X Window:: Graphical display. +@end menu -The figure above shows the very beginning of the dependency graph of the -distribution, corresponding to the package definitions of the @code{(gnu -packages bootstrap)} module. At this level of detail, things are -slightly complex. First, Guile itself consists of an ELF executable, -along with many source and compiled Scheme files that are dynamically -loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz} -tarball shown in this graph. This tarball is part of Guix's ``source'' -distribution, and gets inserted into the store with @code{add-to-store} -(@pxref{The Store}). +@node Base Services +@subsubsection Base Services -But how do we write a derivation that unpacks this tarball and adds it -to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} -derivation---the first one that gets built---uses @code{bash} as its -builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls -@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, -@file{xz}, and @file{mkdir} are statically-linked binaries, also part of -the Guix source distribution, whose sole purpose is to allow the Guile -tarball to be unpacked. +The @code{(gnu services base)} module provides definitions for the basic +services that one expects from the system. The services exported by +this module are listed below. -Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning -Guile that can be used to run subsequent build programs. Its first task -is to download tarballs containing the other pre-built binaries---this -is what the @code{.tar.xz.drv} derivations do. Guix modules such as -@code{ftp-client.scm} are used for this purpose. The -@code{module-import.drv} derivations import those modules in a directory -in the store, using the original layout. The -@code{module-import-compiled.drv} derivations compile those modules, and -write them in an output directory with the right layout. This -corresponds to the @code{#:modules} argument of -@code{build-expression->derivation} (@pxref{Derivations}). +@defvr {Scheme Variable} %base-services +This variable contains a list of basic services@footnote{Technically, +this is a list of monadic services. @xref{The Store Monad}.} one would +expect from the system: a login service (mingetty) on each tty, syslogd, +libc's name service cache daemon (nscd), the udev device manager, and +more. -Finally, the various tarballs are unpacked by the -derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, -etc., at which point we have a working C tool chain. +This is the default value of the @code{services} field of +@code{operating-system} declarations. Usually, when customizing a +system, you will want to append services to @var{%base-services}, like +this: +@example +(cons* (avahi-service) (lshd-service) %base-services) +@end example +@end defvr -@unnumberedsubsec Building the Build Tools +@deffn {Monadic Procedure} host-name-service @var{name} +Return a service that sets the host name to @var{name}. +@end deffn -@c TODO: Add a package-level dependency graph generated from (gnu -@c packages base). +@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @ + [#:auto-login #f] [#:login-program] [#:login-pause? #f] @ + [#:allow-empty-passwords? #f] +Return a service to run mingetty on @var{tty}. -Bootstrapping is complete when we have a full tool chain that does not -depend on the pre-built bootstrap tools discussed above. This -no-dependency requirement is verified by checking whether the files of -the final tool chain contain references to the @file{/gnu/store} -directories of the bootstrap inputs. The process that leads to this -``final'' tool chain is described by the package definitions found in -the @code{(gnu packages base)} module. +When @var{allow-empty-passwords?} is true, allow empty log-in password. When +@var{auto-login} is true, it must be a user name under which to log-in +automatically. @var{login-pause?} can be set to @code{#t} in conjunction with +@var{auto-login}, in which case the user will have to press a key before the +login shell is launched. -@c See . -The first tool that gets built with the bootstrap binaries is -GNU Make, which is a prerequisite for all the following packages. -From there Findutils and Diffutils get built. +When true, @var{login-program} is a gexp or a monadic gexp denoting the name +of the log-in program (the default is the @code{login} program from the Shadow +tool suite.) -Then come the first-stage Binutils and GCC, built as pseudo cross -tools---i.e., with @code{--target} equal to @code{--host}. They are -used to build libc. Thanks to this cross-build trick, this libc is -guaranteed not to hold any reference to the initial tool chain. +@var{motd} is a monadic value containing a text file to use as +the ``message of the day''. +@end deffn -From there the final Binutils and GCC are built. GCC uses @code{ld} -from the final Binutils, and links programs against the just-built libc. -This tool chain is used to build the other packages used by Guix and by -the GNU Build System: Guile, Bash, Coreutils, etc. +@deffn {Monadic Procedure} nscd-service [#:glibc glibc] +Return a service that runs libc's name service cache daemon (nscd). +@end deffn -And voilà! At this point we have the complete set of build tools that -the GNU Build System expects. These are in the @code{%final-inputs} -variables of the @code{(gnu packages base)} module, and are implicitly -used by any package that uses @code{gnu-build-system} (@pxref{Defining -Packages}). +@deffn {Monadic Procedure} syslog-service +Return a service that runs @code{syslogd} with reasonable default +settings. +@end deffn +@deffn {Monadic Procedure} guix-service [#:guix guix] @ + [#:builder-group "guixbuild"] [#:build-accounts 10] @ + [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @ + [#:extra-options '()] +Return a service that runs the build daemon from @var{guix}, and has +@var{build-accounts} user accounts available under @var{builder-group}. -@unnumberedsubsec Building the Bootstrap Binaries +When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key +provided by @var{guix} is authorized upon activation, meaning that substitutes +from @code{hydra.gnu.org} are used by default. -Because the final tool chain does not depend on the bootstrap binaries, -those rarely need to be updated. Nevertheless, it is useful to have an -automated way to produce them, should an update occur, and this is what -the @code{(gnu packages make-bootstrap)} module provides. +If @var{use-substitutes?} is false, the daemon is run with +@option{--no-substitutes} (@pxref{Invoking guix-daemon, +@option{--no-substitutes}}). -The following command builds the tarballs containing the bootstrap -binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture -of Coreutils and other basic command-line tools): +Finally, @var{extra-options} is a list of additional command-line options +passed to @command{guix-daemon}. +@end deffn -@example -guix build bootstrap-tarballs -@end example +@deffn {Monadic Procedure} udev-service [#:udev udev] +Run @var{udev}, which populates the @file{/dev} directory dynamically. +@end deffn -The generated tarballs are those that should be referred to in the -@code{(gnu packages bootstrap)} module mentioned at the beginning of -this section. +@node Networking Services +@subsubsection Networking Services -Still here? Then perhaps by now you've started to wonder: when do we -reach a fixed point? That is an interesting question! The answer is -unknown, but if you would like to investigate further (and have -significant computational and storage resources to do so), then let us -know. +The @code{(gnu system networking)} module provides services to configure +the network interface. -@node Porting -@section Porting to a New Platform +@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @ + [#:gateway #f] [#:name-services @code{'()}] +Return a service that starts @var{interface} with address @var{ip}. If +@var{gateway} is true, it must be a string specifying the default network +gateway. +@end deffn -As discussed above, the GNU distribution is self-contained, and -self-containment is achieved by relying on pre-built ``bootstrap -binaries'' (@pxref{Bootstrapping}). These binaries are specific to an -operating system kernel, CPU architecture, and application binary -interface (ABI). Thus, to port the distribution to a platform that is -not yet supported, one must build those bootstrap binaries, and update -the @code{(gnu packages bootstrap)} module to use them on that platform. +@deffn {Monadic Procedure} tor-service [#:tor tor] +Return a service to run the @uref{https://torproject.org,Tor} daemon. -Fortunately, Guix can @emph{cross compile} those bootstrap binaries. -When everything goes well, and assuming the GNU tool chain supports the -target platform, this can be as simple as running a command like this -one: +The daemon runs with the default settings (in particular the default exit +policy) as the @code{tor} unprivileged user. +@end deffn -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example +In addition, @code{(gnu system ssh)} provides the following service. -Once these are built, the @code{(gnu packages bootstrap)} module needs -to be updated to refer to these binaries on the target platform. In -addition, the @code{glibc-dynamic-linker} procedure in that module must -be augmented to return the right file name for libc's dynamic linker on -that platform; likewise, @code{system->linux-architecture} in @code{(gnu -packages linux)} must be taught about the new platform. +@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ + [#:interfaces '()] [#:port-number 22] @ + [#:allow-empty-passwords? #f] [#:root-login? #f] @ + [#:syslog-output? #t] [#:x11-forwarding? #t] @ + [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @ + [public-key-authentication? #t] [#:initialize? #f] +Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}. +@var{host-key} must designate a file containing the host key, and readable +only by root. -In practice, there may be some complications. First, it may be that the -extended GNU triplet that specifies an ABI (like the @code{eabi} suffix -above) is not recognized by all the GNU tools. Typically, glibc -recognizes some of these, whereas GCC uses an extra @code{--with-abi} -configure flag (see @code{gcc.scm} for examples of how to handle this). -Second, some of the required packages could fail to build for that -platform. Lastly, the generated binaries could be broken for some -reason. +When @var{initialize?} is true, automatically create the seed and host key +upon service activation if they do not exist yet. This may take long and +require interaction. +When @var{interfaces} is empty, lshd listens for connections on all the +network interfaces; otherwise, @var{interfaces} must be a list of host names +or addresses. -@node System Configuration -@section System Configuration +@var{allow-empty-passwords?} specifies whether to accepts log-ins with empty +passwords, and @var{root-login?} specifies whether to accepts log-ins as +root. -@cindex system configuration -The GNU system supports a consistent whole-system configuration -mechanism. By that we mean that all aspects of the global system -configuration---such as the available system services, timezone and -locale settings, user accounts---are declared in a single place. Such -a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected. +The other options should be self-descriptive. +@end deffn -One of the advantages of putting all the system configuration under the -control of Guix is that it supports transactional system upgrades, and -makes it possible to roll-back to a previous system instantiation, -should something go wrong with the new one (@pxref{Features}). Another -one is that it makes it easy to replicate the exact same configuration -across different machines, or at different points in time, without -having to resort to additional administration tools layered on top of -the system's own tools. -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ +@node X Window +@subsubsection X Window -This section describes this mechanism. First we focus on the system -administrator's viewpoint---explaining how the system is configured and -instantiated. Then we show how this mechanism can be extended, for -instance to support new system services. +Support for the X Window graphical display system---specifically +Xorg---is provided by the @code{(gnu services xorg)} module. Note that +there is no @code{xorg-service} procedure. Instead, the X server is +started by the @dfn{login manager}, currently SLiM. -@menu -* Using the Configuration System:: Customizing your GNU system. -* File Systems:: Configuring file system mounts. -* User Accounts:: Specifying user accounts. -* Services:: Specifying system services. -* Invoking guix system:: Instantiating a system configuration. -* Defining Services:: Adding new service definitions. -@end menu +@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @ + [#:auto-login? #f] [#:default-user ""] [#:startx] +Return a service that spawns the SLiM graphical login manager, which in +turn starts the X display server with @var{startx}, a command as returned by +@code{xorg-start-command}. -@node Using the Configuration System -@subsection Using the Configuration System +When @var{allow-empty-passwords?} is true, allow logins with an empty +password. When @var{auto-login?} is true, log in automatically as +@var{default-user}. +@end deffn -The operating system is configured by providing an -@code{operating-system} declaration in a file that can then be passed to -the @command{guix system} command (@pxref{Invoking guix system}). A -simple setup, with the default system services, the default Linux-Libre -kernel, initial RAM disk, and boot loader looks like this: -@findex operating-system -@lisp -(use-modules (gnu) ; for 'user-account', '%base-services', etc. - (gnu packages emacs) ; for 'emacs' - (gnu services ssh)) ; for 'lsh-service' - -(operating-system - (host-name "komputilo") - (timezone "Europe/Paris") - (locale "fr_FR.UTF-8") - (bootloader (grub-configuration - (device "/dev/sda"))) - (file-systems (list (file-system - (device "/dev/sda1") ; or partition label - (mount-point "/") - (type "ext3")))) - (users (list (user-account - (name "alice") - (password "") - (uid 1000) (gid 100) - (comment "Bob's sister") - (home-directory "/home/alice")))) - (packages (cons emacs %base-packages)) - (services (cons (lsh-service #:port 2222 #:allow-root-login? #t) - %base-services))) -@end lisp - -This example should be self-describing. Some of the fields defined -above, such as @code{host-name} and @code{bootloader}, are mandatory. -Others, such as @code{packages} and @code{services}, can be omitted, in -which case they get a default value. +@node Invoking guix system +@subsection Invoking @code{guix system} -@vindex %base-packages -The @code{packages} field lists -packages that will be globally visible on the system, for all user -accounts---i.e., in every user's @code{PATH} environment variable---in -addition to the per-user profiles (@pxref{Invoking guix package}). The -@var{%base-packages} variable provides all the tools one would expect -for basic user and administrator tasks---including the GNU Core -Utilities, the GNU Networking Utilities, the GNU Zile lightweight text -editor, @command{find}, @command{grep}, etc. The example above adds -Emacs to those, taken from the @code{(gnu packages emacs)} module -(@pxref{Package Modules}). +Once you have written an operating system declaration, as seen in the +previous section, it can be @dfn{instantiated} using the @command{guix +system} command. The synopsis is: -@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 -daemon listening on port 2222, and allowing remote @code{root} logins -(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood, -@code{lsh-service} arranges so that @code{lshd} is started with the -right command-line options, possibly with supporting configuration files -generated as needed (@pxref{Defining Services}). +@example +guix system @var{options}@dots{} @var{action} @var{file} +@end example -Assuming the above snippet is stored in the @file{my-system-config.scm} -file, the @command{guix system reconfigure my-system-config.scm} command -instantiates that configuration, and makes it the default GRUB boot -entry (@pxref{Invoking guix system}). The normal way to change the -system's configuration is by updating this file and re-running the -@command{guix system} command. +@var{file} must be the name of a file containing an +@code{operating-system} declaration. @var{action} specifies how the +operating system is instantiate. Currently the following values are +supported: -At the Scheme level, the bulk of an @code{operating-system} declaration -is instantiated with the following monadic procedure (@pxref{The Store -Monad}): +@table @code +@item reconfigure +Build the operating system described in @var{file}, activate it, and +switch to it@footnote{This action is usable only on systems already +running GNU.}. -@deffn {Monadic Procedure} operating-system-derivation os -Return a derivation that builds @var{os}, an @code{operating-system} -object (@pxref{Derivations}). +This effects all the configuration specified in @var{file}: user +accounts, system services, global package list, setuid programs, etc. -The output of the derivation is a single directory that refers to all -the packages, configuration files, and other supporting files needed to -instantiate @var{os}. -@end deffn +It also adds a GRUB menu entry for the new OS configuration, and moves +entries for older configurations to a submenu---unless +@option{--no-grub} is passed. -@node File Systems -@subsection File Systems +@item build +Build the operating system's derivation, which includes all the +configuration files and programs needed to boot and run the system. +This action does not actually install anything. -The list of file systems to be mounted is specified in the -@code{file-systems} field of the operating system's declaration -(@pxref{Using the Configuration System}). Each file system is declared -using the @code{file-system} form, like this: +@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 the GNU system. For instance: @example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) +guix system init my-os-config.scm /mnt @end example -As usual, some of the fields are mandatory---those shown in the example -above---while others can be omitted. These are described below. - -@deftp {Data Type} file-system -Objects of this type represent file systems to be mounted. They -contain the following members: +copies to @file{/mnt} all the store items required by the configuration +specified in @file{my-os-config.scm}. This includes configuration +files, packages, and so on. It also creates other essential files +needed for the system to operate correctly---e.g., the @file{/etc}, +@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. -@table @asis -@item @code{type} -This is a string specifying the type of the file system---e.g., -@code{"ext4"}. +This command also installs GRUB on the device specified in +@file{my-os-config}, unless the @option{--no-grub} option was passed. -@item @code{mount-point} -This designates the place where the file system is to be mounted. +@item vm +@cindex virtual machine +Build a virtual machine that contain the operating system declared in +@var{file}, and return a script to run that virtual machine (VM). -@item @code{device} -This names the ``source'' of the file system. By default it is the name -of a node under @file{/dev}, but its meaning depends on the @code{title} -field described below. +The VM shares its store with the host system. -@item @code{title} (default: @code{'device}) -This is a symbol that specifies how the @code{device} field is to be -interpreted. +@item vm-image +@itemx disk-image +Return a virtual machine or disk image of the operating system declared +in @var{file} that stands alone. Use the @option{--image-size} option +to specify the size of the image. -When it is the symbol @code{device}, then the @code{device} field is -interpreted as a file name; when it is @code{label}, then @code{device} -is interpreted as a partition label name; when it is @code{uuid}, -@code{device} is interpreted as a partition unique identifier (UUID). +When using @code{vm-image}, the returned image is in qcow2 format, which +the QEMU emulator can efficiently use. -The @code{label} and @code{uuid} options offer a way to refer to disk -partitions without having to hard-code their actual device name. +When using @code{disk-image}, a raw disk image is produced; it can be +copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is +the device corresponding to a USB stick, one can copy the image on it +using the following command: -@item @code{flags} (default: @code{'()}) -This is a list of symbols denoting mount flags. Recognized flags -include @code{read-only} and @code{bind-mount}. +@example +# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc +@end example -@item @code{options} (default: @code{#f}) -This is either @code{#f}, or a string denoting mount options. +@end table -@item @code{needed-for-boot?} (default: @code{#f}) -This Boolean value indicates whether the file system is needed when -booting. If that is true, then the file system is mounted when the -initial RAM disk (initrd) is loaded. This is always the case, for -instance, for the root file system. +@var{options} can contain any of the common build options provided by +@command{guix build} (@pxref{Invoking guix build}). In addition, +@var{options} can contain one of the following: -@item @code{check?} (default: @code{#t}) -This Boolean indicates whether the file system needs to be checked for -errors before being mounted. +@table @option +@item --system=@var{system} +@itemx -s @var{system} +Attempt to build for @var{system} instead of the host's system type. +This works as per @command{guix build} (@pxref{Invoking guix build}). +@item --image-size=@var{size} +For the @code{vm-image} and @code{disk-image} actions, create an image +of the given @var{size}. @var{size} may be a number of bytes, or it may +include a unit as a suffix, such as @code{MiB} for mebibytes and +@code{GB} for gigabytes. @end table -@end deftp -@node User Accounts -@subsection User Accounts - -User accounts are specified with the @code{user-account} form: +Note that all the actions above, except @code{build} and @code{init}, +rely on KVM support in the Linux-Libre kernel. Specifically, the +machine should have 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 daemon's +build users. -@example -(user-account - (name "alice") - (group "users") - (supplementary-groups '("wheel")) ; allow use of sudo, etc. - (comment "Bob's sister") - (home-directory "/home/alice")) -@end example +@node Defining Services +@subsection Defining Services -@deftp {Data Type} user-account -Objects of this type represent user accounts. The following members may -be specified: +The @code{(gnu services @dots{})} modules define several procedures that allow +users to declare the operating system's services (@pxref{Using the +Configuration System}). These procedures are @emph{monadic +procedures}---i.e., procedures that return a monadic value in the store +monad (@pxref{The Store Monad}). For examples of such procedures, +@xref{Services}. -@table @asis -@item @code{name} -The name of the user account. +@cindex service definition +The monadic value returned by those procedures is a @dfn{service +definition}---a structure as returned by the @code{service} form. +Service definitions specifies the inputs the service depends on, and an +expression to start and stop the service. Behind the scenes, service +definitions are ``translated'' into the form suitable for the +configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU +dmd Manual}). -@item @code{group} -This is the name (a string) or identifier (a number) of the user group -this account belongs to. +As an example, here is what the @code{nscd-service} procedure looks +like: -@item @code{supplementary-groups} (default: @code{'()}) -Optionally, this can be defined as a list of group names that this -account belongs to. +@lisp +(define (nscd-service) + (with-monad %store-monad + (return (service + (documentation "Run libc's name service cache daemon.") + (provision '(nscd)) + (activate #~(begin + (use-modules (guix build utils)) + (mkdir-p "/var/run/nscd"))) + (start #~(make-forkexec-constructor + (string-append #$glibc "/sbin/nscd") + "-f" "/dev/null" "--foreground")) + (stop #~(make-kill-destructor)) + (respawn? #f))))) +@end lisp -@item @code{uid} (default: @code{#f}) -This is the user ID for this account (a number), or @code{#f}. In the -latter case, a number is automatically chosen by the system when the -account is created. +@noindent +The @code{activate}, @code{start}, and @code{stop} fields are G-expressions +(@pxref{G-Expressions}). The @code{activate} field contains a script to +run at ``activation'' time; it makes sure that the @file{/var/run/nscd} +directory exists before @command{nscd} is started. -@item @code{comment} (default: @code{""}) -A comment about the account, such as the account's owner full name. +The @code{start} and @code{stop} fields refer to dmd's facilities to +start and stop processes (@pxref{Service De- and Constructors,,, dmd, +GNU dmd Manual}). The @code{provision} field specifies the name under +which this service is known to dmd, and @code{documentation} specifies +on-line documentation. Thus, the commands @command{deco start ncsd}, +@command{deco stop nscd}, and @command{deco doc nscd} will do what you +would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}). -@item @code{home-directory} -This is the name of the home directory for the account. -@item @code{shell} (default: Bash) -This is a G-expression denoting the file name of a program to be used as -the shell (@pxref{G-Expressions}). +@node Installing Debugging Files +@section Installing Debugging Files -@item @code{system?} (default: @code{#f}) -This Boolean value indicates whether the account is a ``system'' -account. System accounts are sometimes treated specially; for instance, -graphical login managers do not list them. +@cindex debugging files +Program binaries, as produced by the GCC compilers for instance, are +typically written in the ELF format, with a section containing +@dfn{debugging information}. Debugging information is what allows the +debugger, GDB, to map binary code to source code; it is required to +debug a compiled program in good conditions. -@item @code{password} (default: @code{#f}) -Unless @code{#f}, this is the password to be used for the account. +The problem with debugging information is that is takes up a fair amount +of disk space. For example, debugging information for the GNU C Library +weighs in at more than 60 MiB. Thus, as a user, keeping all the +debugging info of all the installed programs is usually not an option. +Yet, space savings should not come at the cost of an impediment to +debugging---especially in the GNU system, which should make it easier +for users to exert their computing freedom (@pxref{GNU Distribution}). -@end table -@end deftp +Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a +mechanism that allows users to get the best of both worlds: debugging +information can be stripped from the binaries and stored in separate +files. GDB is then able to load debugging information from those files, +when they are available (@pxref{Separate Debug Files,,, gdb, Debugging +with GDB}). -User group declarations are even simpler: +The GNU distribution takes advantage of this by storing debugging +information in the @code{lib/debug} sub-directory of a separate package +output unimaginatively called @code{debug} (@pxref{Packages with +Multiple Outputs}). Users can choose to install the @code{debug} output +of a package when they need it. For instance, the following command +installs the debugging information for the GNU C Library and for GNU +Guile: @example -(user-group (name "students")) +guix package -i glibc:debug guile:debug @end example -@deftp {Data Type} user-group -This type is for, well, user groups. There are just a few fields: +GDB must then be told to look for debug files in the user's profile, by +setting the @code{debug-file-directory} variable (consider setting it +from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with +GDB}): -@table @asis -@item @code{name} -The group's name. +@example +(gdb) set debug-file-directory ~/.guix-profile/lib/debug +@end example -@item @code{id} (default: @code{#f}) -The group identifier (a number). If @code{#f}, a new number is -automatically allocated when the group is created. +From there on, GDB will pick up debugging information from the +@code{.debug} files under @file{~/.guix-profile/lib/debug}. -@item @code{password} (default: @code{#f}) -What, user groups can have a password? Well, apparently yes. Unless -@code{#f}, this field specifies the group's password. +In addition, you will most likely want GDB to be able to show the source +code being debugged. To do that, you will have to unpack the source +code of the package of interest (obtained with @code{guix build +--source}, @pxref{Invoking guix build}), and to point GDB to that source +directory using the @code{directory} command (@pxref{Source Path, +@code{directory},, gdb, Debugging with GDB}). -@end table -@end deftp +@c XXX: keep me up-to-date +The @code{debug} output mechanism in Guix is implemented by the +@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is +opt-in---debugging information is available only for those packages +whose definition explicitly declares a @code{debug} output. This may be +changed to opt-out in the future, if our build farm servers can handle +the load. To check whether a package has a @code{debug} output, use +@command{guix package --list-available} (@pxref{Invoking guix package}). -For convenience, a variable lists all the basic user groups one may -expect: -@defvr {Scheme Variable} %base-groups -This is the list of basic user groups that users and/or packages expect -to be present on the system. This includes groups such as ``root'', -``wheel'', and ``users'', as well as groups used to control access to -specific devices such as ``audio'', ``disk'', and ``cdrom''. -@end defvr +@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{} object (@pxref{Defining Packages}). -@node Services -@subsection Services +The @code{(gnu packages @dots{})} module name space is special: it 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 system services -An important part of preparing an @code{operating-system} declaration is -listing @dfn{system services} and their configuration (@pxref{Using the -Configuration System}). System services are typically daemons launched -when the system boots, or other actions needed at that time---e.g., -configuring network access. They are managed by GNU@tie{}dmd -(@pxref{Introduction,,, dmd, GNU dmd Manual}). +Users can store package definitions in modules with different +names---e.g., @code{(my-packages emacs)}. In that case, commands such +as @command{guix package} and @command{guix build} have to be used with +the @code{-e} option so that they know where to find the package. -The following sections document the available services, starting with -the core services. +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, +@ref{Bootstrapping}. -@menu -* Base Services:: Essential system services. -* Networking Services:: Network setup, SSH daemon, etc. -* X Window:: Graphical display. -@end menu +@node Packaging Guidelines +@section Packaging Guidelines -@node Base Services -@subsubsection Base Services +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. -The @code{(gnu services base)} module provides definitions for the basic -services that one expects from the system. The services exported by -this module are listed below. +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 meta-data} along with that recipe, such as a +description and licensing information. -@defvr {Scheme Variable} %base-services -This variable contains a list of basic services@footnote{Technically, -this is a list of monadic services. @xref{The Store Monad}.} one would -expect from the system: a login service (mingetty) on each tty, syslogd, -libc's name service cache daemon (nscd), the udev device manager, and -more. +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, +@ref{Defining Packages}. -This is the default value of the @code{services} field of -@code{operating-system} declarations. Usually, when customizing a -system, you will want to append services to @var{%base-services}, like -this: +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: @example -(cons* (avahi-service) (lshd-service) %base-services) +./pre-inst-env guix build gnew --keep-failed @end example -@end defvr -@deffn {Monadic Procedure} host-name-service @var{name} -Return a service that sets the host name to @var{name}. -@end deffn +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. -@deffn {Monadic Procedure} mingetty-service @var{tty} [#:motd] @ - [#:auto-login #f] [#:login-program] [#:login-pause? #f] @ - [#:allow-empty-passwords? #f] -Return a service to run mingetty on @var{tty}. +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: -When @var{allow-empty-passwords?} is true, allow empty log-in password. When -@var{auto-login} is true, it must be a user name under which to log-in -automatically. @var{login-pause?} can be set to @code{#t} in conjunction with -@var{auto-login}, in which case the user will have to press a key before the -login shell is launched. +@example +./pre-inst-env guile -c '(use-modules (gnu packages gnew))' +@end example -When true, @var{login-program} is a gexp or a monadic gexp denoting the name -of the log-in program (the default is the @code{login} program from the Shadow -tool suite.) +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/gnu/master, our continuous integration +system}. -@var{motd} is a monadic value containing a text file to use as -the ``message of the day''. -@end deffn +@cindex substituter +Users can obtain the new package definition simply by running +@command{guix pull} (@pxref{Invoking guix pull}). When +@code{hydra.gnu.org} 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. -@deffn {Monadic Procedure} nscd-service [#:glibc glibc] -Return a service that runs libc's name service cache daemon (nscd). -@end deffn -@deffn {Monadic Procedure} syslog-service -Return a service that runs @code{syslogd} with reasonable default -settings. -@end deffn +@menu +* Software Freedom:: What may go into the distribution. +* Package Naming:: What's in a name? +* Version Numbers:: When the name is not enough. +* Python Modules:: Taming the snake. +* Perl Modules:: Little pearls. +@end menu -@deffn {Monadic Procedure} guix-service [#:guix guix] @ - [#:builder-group "guixbuild"] [#:build-accounts 10] @ - [#:authorize-hydra-key? #f] [#:use-substitutes? #t] @ - [#:extra-options '()] -Return a service that runs the build daemon from @var{guix}, and has -@var{build-accounts} user accounts available under @var{builder-group}. +@node Software Freedom +@subsection Software Freedom -When @var{authorize-hydra-key?} is true, the @code{hydra.gnu.org} public key -provided by @var{guix} is authorized upon activation, meaning that substitutes -from @code{hydra.gnu.org} are used by default. +@c Adapted from http://www.gnu.org/philosophy/philosophy.html. -If @var{use-substitutes?} is false, the daemon is run with -@option{--no-substitutes} (@pxref{Invoking guix-daemon, -@option{--no-substitutes}}). +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. -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{guix-daemon}. -@end deffn +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. -@deffn {Monadic Procedure} udev-service [#:udev udev] -Run @var{udev}, which populates the @file{/dev} directory dynamically. -@end deffn +Some packages 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 package definition's +@code{origin} form (@pxref{Defining Packages}). That way, @code{guix +build --source} returns the ``freed'' source rather than the unmodified +upstream source. -@node Networking Services -@subsubsection Networking Services -The @code{(gnu system networking)} module provides services to configure -the network interface. +@node Package Naming +@subsection Package Naming -@deffn {Monadic Procedure} static-networking-service @var{interface} @var{ip} @ - [#:gateway #f] [#:name-services @code{'()}] -Return a service that starts @var{interface} with address @var{ip}. If -@var{gateway} is true, it must be a string specifying the default network -gateway. -@end deffn +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}. -@deffn {Monadic Procedure} tor-service [#:tor tor] -Return a service to run the @uref{https://torproject.org,Tor} daemon. +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}. -The daemon runs with the default settings (in particular the default exit -policy) as the @code{tor} unprivileged user. -@end deffn +We do not add @code{lib} prefixes for library packages, unless these are +already part of the official project name. But see @pxref{Python +Modules} and @ref{Perl Modules} for special rules concerning modules for +the Python and Perl languages. -In addition, @code{(gnu system ssh)} provides the following service. -@deffn {Monadic Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ - [#:interfaces '()] [#:port-number 22] @ - [#:allow-empty-passwords? #f] [#:root-login? #f] @ - [#:syslog-output? #t] [#:x11-forwarding? #t] @ - [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @ - [public-key-authentication? #t] [#:initialize? #f] -Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}. -@var{host-key} must designate a file containing the host key, and readable -only by root. +@node Version Numbers +@subsection Version Numbers -When @var{initialize?} is true, automatically create the seed and host key -upon service activation if they do not exist yet. This may take long and -require interaction. +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. -When @var{interfaces} is empty, lshd listens for connections on all the -network interfaces; otherwise, @var{interfaces} must be a list of host names -or addresses. +The name inside the package definition is the same for all versions of a +package and does not contain any version number. -@var{allow-empty-passwords?} specifies whether to accepts log-ins with empty -passwords, and @var{root-login?} specifies whether to accepts log-ins as -root. +For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: -The other options should be self-descriptive. -@end deffn +@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 -@node X Window -@subsubsection X Window -Support for the X Window graphical display system---specifically -Xorg---is provided by the @code{(gnu services xorg)} module. Note that -there is no @code{xorg-service} procedure. Instead, the X server is -started by the @dfn{login manager}, currently SLiM. +@node Python Modules +@subsection Python Modules -@deffn {Monadic Procedure} slim-service [#:allow-empty-passwords? #f] @ - [#:auto-login? #f] [#:default-user ""] [#:startx] -Return a service that spawns the SLiM graphical login manager, which in -turn starts the X display server with @var{startx}, a command as returned by -@code{xorg-start-command}. +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}. -When @var{allow-empty-passwords?} is true, allow logins with an empty -password. When @var{auto-login?} is true, log in automatically as -@var{default-user}. -@end deffn +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}. -@node Invoking guix system -@subsection 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 -system} command. The synopsis is: +@node Perl Modules +@subsection Perl Modules -@example -guix system @var{options}@dots{} @var{action} @var{file} -@end example +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}. -@var{file} must be the name of a file containing an -@code{operating-system} declaration. @var{action} specifies how the -operating system is instantiate. Currently the following values are -supported: -@table @code -@item reconfigure -Build the operating system described in @var{file}, activate it, and -switch to it@footnote{This action is usable only on systems already -running GNU.}. -This effects all the configuration specified in @var{file}: user -accounts, system services, global package list, setuid programs, etc. +@node Bootstrapping +@section Bootstrapping -It also adds a GRUB menu entry for the new OS configuration, and moves -entries for older configurations to a submenu---unless -@option{--no-grub} is passed. +@c Adapted from the ELS 2013 paper. -@item build -Build the operating system's derivation, which includes all the -configuration files and programs needed to boot and run the system. -This action does not actually install anything. +@cindex bootstrapping -@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 the GNU system. For instance: +Bootstrapping in our context refers to how the distribution gets built +``from nothing''. Remember that the build environment of a derivation +contains nothing but its declared inputs (@pxref{Introduction}). So +there's an obvious chicken-and-egg problem: how does the first package +get built? How does the first compiler get compiled? Note that this is +a question of interest only to the curious hacker, not to the regular +user, so you can shamelessly skip this section if you consider yourself +a ``regular user''. -@example -guix system init my-os-config.scm /mnt -@end example +@cindex bootstrap binaries +The GNU system is primarily made of C code, with libc at its core. The +GNU build system itself assumes the availability of a Bourne shell and +command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and +`grep'. Furthermore, build programs---programs that run +@code{./configure}, @code{make}, etc.---are written in Guile Scheme +(@pxref{Derivations}). Consequently, to be able to build anything at +all, from scratch, Guix relies on pre-built binaries of Guile, GCC, +Binutils, libc, and the other packages mentioned above---the +@dfn{bootstrap binaries}. -copies to @file{/mnt} all the store items required by the configuration -specified in @file{my-os-config.scm}. This includes configuration -files, packages, and so on. It also creates other essential files -needed for the system to operate correctly---e.g., the @file{/etc}, -@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. +These bootstrap binaries are ``taken for granted'', though we can also +re-create them if needed (more on that later). -This command also installs GRUB on the device specified in -@file{my-os-config}, unless the @option{--no-grub} option was passed. +@unnumberedsubsec Preparing to Use the Bootstrap Binaries -@item vm -@cindex virtual machine -Build a virtual machine that contain the operating system declared in -@var{file}, and return a script to run that virtual machine (VM). +@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. +@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations} -The VM shares its store with the host system. +The figure above shows the very beginning of the dependency graph of the +distribution, corresponding to the package definitions of the @code{(gnu +packages bootstrap)} module. At this level of detail, things are +slightly complex. First, Guile itself consists of an ELF executable, +along with many source and compiled Scheme files that are dynamically +loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz} +tarball shown in this graph. This tarball is part of Guix's ``source'' +distribution, and gets inserted into the store with @code{add-to-store} +(@pxref{The Store}). -@item vm-image -@itemx disk-image -Return a virtual machine or disk image of the operating system declared -in @var{file} that stands alone. Use the @option{--image-size} option -to specify the size of the image. +But how do we write a derivation that unpacks this tarball and adds it +to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} +derivation---the first one that gets built---uses @code{bash} as its +builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls +@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, +@file{xz}, and @file{mkdir} are statically-linked binaries, also part of +the Guix source distribution, whose sole purpose is to allow the Guile +tarball to be unpacked. -When using @code{vm-image}, the returned image is in qcow2 format, which -the QEMU emulator can efficiently use. +Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning +Guile that can be used to run subsequent build programs. Its first task +is to download tarballs containing the other pre-built binaries---this +is what the @code{.tar.xz.drv} derivations do. Guix modules such as +@code{ftp-client.scm} are used for this purpose. The +@code{module-import.drv} derivations import those modules in a directory +in the store, using the original layout. The +@code{module-import-compiled.drv} derivations compile those modules, and +write them in an output directory with the right layout. This +corresponds to the @code{#:modules} argument of +@code{build-expression->derivation} (@pxref{Derivations}). -When using @code{disk-image}, a raw disk image is produced; it can be -copied as is to a USB stick, for instance. Assuming @code{/dev/sdc} is -the device corresponding to a USB stick, one can copy the image on it -using the following command: +Finally, the various tarballs are unpacked by the +derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, +etc., at which point we have a working C tool chain. -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example -@end table +@unnumberedsubsec Building the Build Tools -@var{options} can contain any of the common build options provided by -@command{guix build} (@pxref{Invoking guix build}). In addition, -@var{options} can contain one of the following: +@c TODO: Add a package-level dependency graph generated from (gnu +@c packages base). -@table @option -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system} instead of the host's system type. -This works as per @command{guix build} (@pxref{Invoking guix build}). +Bootstrapping is complete when we have a full tool chain that does not +depend on the pre-built bootstrap tools discussed above. This +no-dependency requirement is verified by checking whether the files of +the final tool chain contain references to the @file{/gnu/store} +directories of the bootstrap inputs. The process that leads to this +``final'' tool chain is described by the package definitions found in +the @code{(gnu packages base)} module. -@item --image-size=@var{size} -For the @code{vm-image} and @code{disk-image} actions, create an image -of the given @var{size}. @var{size} may be a number of bytes, or it may -include a unit as a suffix, such as @code{MiB} for mebibytes and -@code{GB} for gigabytes. -@end table +@c See . +The first tool that gets built with the bootstrap binaries is +GNU Make, which is a prerequisite for all the following packages. +From there Findutils and Diffutils get built. -Note that all the actions above, except @code{build} and @code{init}, -rely on KVM support in the Linux-Libre kernel. Specifically, the -machine should have 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 daemon's -build users. +Then come the first-stage Binutils and GCC, built as pseudo cross +tools---i.e., with @code{--target} equal to @code{--host}. They are +used to build libc. Thanks to this cross-build trick, this libc is +guaranteed not to hold any reference to the initial tool chain. -@node Defining Services -@subsection Defining Services +From there the final Binutils and GCC are built. GCC uses @code{ld} +from the final Binutils, and links programs against the just-built libc. +This tool chain is used to build the other packages used by Guix and by +the GNU Build System: Guile, Bash, Coreutils, etc. -The @code{(gnu services @dots{})} modules define several procedures that allow -users to declare the operating system's services (@pxref{Using the -Configuration System}). These procedures are @emph{monadic -procedures}---i.e., procedures that return a monadic value in the store -monad (@pxref{The Store Monad}). For examples of such procedures, -@xref{Services}. +And voilà! At this point we have the complete set of build tools that +the GNU Build System expects. These are in the @code{%final-inputs} +variables of the @code{(gnu packages base)} module, and are implicitly +used by any package that uses @code{gnu-build-system} (@pxref{Defining +Packages}). -@cindex service definition -The monadic value returned by those procedures is a @dfn{service -definition}---a structure as returned by the @code{service} form. -Service definitions specifies the inputs the service depends on, and an -expression to start and stop the service. Behind the scenes, service -definitions are ``translated'' into the form suitable for the -configuration file of dmd, the init system (@pxref{Services,,, dmd, GNU -dmd Manual}). -As an example, here is what the @code{nscd-service} procedure looks -like: +@unnumberedsubsec Building the Bootstrap Binaries -@lisp -(define (nscd-service) - (with-monad %store-monad - (return (service - (documentation "Run libc's name service cache daemon.") - (provision '(nscd)) - (activate #~(begin - (use-modules (guix build utils)) - (mkdir-p "/var/run/nscd"))) - (start #~(make-forkexec-constructor - (string-append #$glibc "/sbin/nscd") - "-f" "/dev/null" "--foreground")) - (stop #~(make-kill-destructor)) - (respawn? #f))))) -@end lisp +Because the final tool chain does not depend on the bootstrap binaries, +those rarely need to be updated. Nevertheless, it is useful to have an +automated way to produce them, should an update occur, and this is what +the @code{(gnu packages make-bootstrap)} module provides. -@noindent -The @code{activate}, @code{start}, and @code{stop} fields are G-expressions -(@pxref{G-Expressions}). The @code{activate} field contains a script to -run at ``activation'' time; it makes sure that the @file{/var/run/nscd} -directory exists before @command{nscd} is started. +The following command builds the tarballs containing the bootstrap +binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture +of Coreutils and other basic command-line tools): -The @code{start} and @code{stop} fields refer to dmd's facilities to -start and stop processes (@pxref{Service De- and Constructors,,, dmd, -GNU dmd Manual}). The @code{provision} field specifies the name under -which this service is known to dmd, and @code{documentation} specifies -on-line documentation. Thus, the commands @command{deco start ncsd}, -@command{deco stop nscd}, and @command{deco doc nscd} will do what you -would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}). +@example +guix build bootstrap-tarballs +@end example + +The generated tarballs are those that should be referred to in the +@code{(gnu packages bootstrap)} module mentioned at the beginning of +this section. + +Still here? Then perhaps by now you've started to wonder: when do we +reach a fixed point? That is an interesting question! The answer is +unknown, but if you would like to investigate further (and have +significant computational and storage resources to do so), then let us +know. + +@node Porting +@section 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 +binaries'' (@pxref{Bootstrapping}). These binaries are specific to an +operating system kernel, CPU architecture, and application binary +interface (ABI). Thus, to port the distribution to a platform that is +not yet supported, one must build those bootstrap binaries, and update +the @code{(gnu packages bootstrap)} module to use them on that platform. + +Fortunately, Guix can @emph{cross compile} those bootstrap binaries. +When everything goes well, and assuming the GNU tool chain supports the +target platform, this can be as simple as running a command like this +one: + +@example +guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs +@end example + +Once these are built, the @code{(gnu packages bootstrap)} module needs +to be updated to refer to these binaries on the target platform. In +addition, the @code{glibc-dynamic-linker} procedure in that module must +be augmented to return the right file name for libc's dynamic linker on +that platform; likewise, @code{system->linux-architecture} in @code{(gnu +packages linux)} must be taught about the new platform. + +In practice, there may be some complications. First, it may be that the +extended GNU triplet that specifies an ABI (like the @code{eabi} suffix +above) is not recognized by all the GNU tools. Typically, glibc +recognizes some of these, whereas GCC uses an extra @code{--with-abi} +configure flag (see @code{gcc.scm} for examples of how to handle this). +Second, some of the required packages could fail to build for that +platform. Lastly, the generated binaries could be broken for some +reason. @c ********************************************************************* -- cgit v1.2.3