doc: Move "System Configuration" higher.

* doc/guix.texi (GNU Distribution): Move "System Configuration" right after "System Installation".
2014-07-16 11:35:45 +02:00 · 2014-07-16 11:35:45 +02:00 · cf4a912919
commit cf4a912919
parent 79ad1c6999
1 changed files with 467 additions and 468 deletions
--- 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,473 +2781,6 @@ 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 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
 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}):
@example
 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
@end example
 From there on, GDB will pick up debugging information from the
@code{.debug} files under @file{~/.guix-profile/lib/debug}.
 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}).
@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}).
@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 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.
 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 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}.
@node Packaging Guidelines
@section Packaging Guidelines
 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 meta-data} 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,
@ref{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:
@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/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{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.
@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
@node Software Freedom
@subsection Software Freedom
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
 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 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 Package Naming
@subsection Package Naming
 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 see @pxref{Python
 Modules} and @ref{Perl Modules} for special rules concerning modules for
 the Python and Perl languages.
@node Version Numbers
@subsection Version Numbers
 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
@node Python Modules
@subsection Python Modules
 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}.
@node Perl Modules
@subsection Perl Modules
 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 Bootstrapping
@section Bootstrapping
@c Adapted from the ELS 2013 paper.
@cindex bootstrapping
 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}.
 These bootstrap binaries are ``taken for granted'', though we can also
 re-create them if needed (more on that later).
@unnumberedsubsec 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.
@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
 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}).
 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.
 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}).
 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.
@unnumberedsubsec Building the Build Tools
@c TODO: Add a package-level dependency graph generated from (gnu
@c packages base).
 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.
@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
 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.
 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.
 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.
 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}).
@unnumberedsubsec Building the Bootstrap Binaries
 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.
 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):
@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.
@node System Configuration
@section System Configuration
@ -3846,6 +3379,472 @@ on-line documentation.  Thus, the commands @command{deco start ncsd},
 would expect (@pxref{Invoking deco,,, dmd, GNU dmd Manual}).
@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
 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}):
@example
 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
@end example
 From there on, GDB will pick up debugging information from the
@code{.debug} files under @file{~/.guix-profile/lib/debug}.
 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}).
@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}).
@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 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.
 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 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}.
@node Packaging Guidelines
@section Packaging Guidelines
 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 meta-data} 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,
@ref{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:
@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/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{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.
@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
@node Software Freedom
@subsection Software Freedom
@c Adapted from http://www.gnu.org/philosophy/philosophy.html.
 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 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 Package Naming
@subsection Package Naming
 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 see @pxref{Python
 Modules} and @ref{Perl Modules} for special rules concerning modules for
 the Python and Perl languages.
@node Version Numbers
@subsection Version Numbers
 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
@node Python Modules
@subsection Python Modules
 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}.
@node Perl Modules
@subsection Perl Modules
 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 Bootstrapping
@section Bootstrapping
@c Adapted from the ELS 2013 paper.
@cindex bootstrapping
 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}.
 These bootstrap binaries are ``taken for granted'', though we can also
 re-create them if needed (more on that later).
@unnumberedsubsec 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.
@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
 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}).
 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.
 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}).
 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.
@unnumberedsubsec Building the Build Tools
@c TODO: Add a package-level dependency graph generated from (gnu
@c packages base).
 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.
@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
 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.
 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.
 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.
 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}).
@unnumberedsubsec Building the Bootstrap Binaries
 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.
 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):
@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 *********************************************************************
@node Contributing
@chapter Contributing