guix.texi

@end defvr

@defvr {Scheme Variable} %shepherd-root-service
This service represents PID@tie{}1.
@end defvr


@node Documentation
@chapter Documentation

@cindex documentation, searching for
@cindex searching for documentation
@cindex Info, documentation format
@cindex man pages
@cindex manual pages
In most cases packages installed with Guix come with documentation.
There are two main documentation formats: ``Info'', a browseable
hypertext format used for GNU software, and ``manual pages'' (or ``man
pages''), the linear documentation format traditionally found on Unix.
Info manuals are accessed with the @command{info} command or with Emacs,
and man pages are accessed using @command{man}.

You can look for documentation of software installed on your system by
keyword.  For example, the following command searches for information
about ``TLS'' in Info manuals:

@example
$ info -k TLS
"(emacs)Network Security" -- STARTTLS
"(emacs)Network Security" -- TLS
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
@dots{}
@end example

@noindent
The command below searches for the same keyword in man pages:

@example
$ man -k TLS
SSL (7)              - OpenSSL SSL/TLS library
certtool (1)         - GnuTLS certificate tool
@dots {}
@end example

These searches are purely local to your computer so you have the
guarantee that documentation you find corresponds to what you have
actually installed, you can access it off-line, and your privacy is
respected.

Once you have these results, you can view the relevant documentation by
running, say:

@example
$ info "(gnutls)Core TLS API"
@end example

@noindent
or:

@example
$ man certtool
@end example

Info manuals contain sections and indices as well as hyperlinks like
those found in Web pages.  The @command{info} reader (@pxref{Top, Info
reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
bindings to navigate manuals.  @xref{Getting Started,,, info, Info: An
Introduction}, for an introduction to Info navigation.

@node Installing Debugging Files
@chapter 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 the packages
with definitions explicitly declaring 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 Security Updates
@chapter Security Updates

@cindex security updates
@cindex security vulnerabilities
Occasionally, important security vulnerabilities are discovered in software
packages and must be patched.  Guix developers try hard to keep track of
known vulnerabilities and to apply fixes as soon as possible in the
@code{master} branch of Guix (we do not yet provide a ``stable'' branch
containing only security updates.)  The @command{guix lint} tool helps
developers find out about vulnerable versions of software packages in the
distribution:

@smallexample
$ guix lint -c cve
gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
@dots{}
@end smallexample

@xref{Invoking guix lint}, for more information.

@quotation Note
As of version @value{VERSION}, the feature described below is considered
``beta''.
@end quotation

Guix follows a functional
package management discipline (@pxref{Introduction}), which implies
that, when a package is changed, @emph{every package that depends on it}
must be rebuilt.  This can significantly slow down the deployment of
fixes in core packages such as libc or Bash, since basically the whole
distribution would need to be rebuilt.  Using pre-built binaries helps
(@pxref{Substitutes}), but deployment may still take more time than
desired.

@cindex grafts
To address this, Guix implements @dfn{grafts}, a mechanism that allows
for fast deployment of critical updates without the costs associated
with a whole-distribution rebuild.  The idea is to rebuild only the
package that needs to be patched, and then to ``graft'' it onto packages
explicitly installed by the user and that were previously referring to
the original package.  The cost of grafting is typically very low, and
order of magnitudes lower than a full rebuild of the dependency chain.

@cindex replacements of packages, for grafts
For instance, suppose a security update needs to be applied to Bash.
Guix developers will provide a package definition for the ``fixed''
Bash, say @var{bash-fixed}, in the usual way (@pxref{Defining
Packages}).  Then, the original package definition is augmented with a
@code{replacement} field pointing to the package containing the bug fix:

@example
(define bash
  (package
    (name "bash")
    ;; @dots{}
    (replacement bash-fixed)))
@end example

From there on, any package depending directly or indirectly on Bash---as
reported by @command{guix gc --requisites} (@pxref{Invoking guix
gc})---that is installed is automatically ``rewritten'' to refer to
@var{bash-fixed} instead of @var{bash}.  This grafting process takes
time proportional to the size of the package, usually less than a
minute for an ``average'' package on a recent machine.  Grafting is
recursive: when an indirect dependency requires grafting, then grafting
``propagates'' up to the package that the user is installing.

Currently, the length of the name and version of the graft and that of
the package it replaces (@var{bash-fixed} and @var{bash} in the example
above) must be equal.  This restriction mostly comes from the fact that
grafting works by patching files, including binary files, directly.
Other restrictions may apply: for instance, when adding a graft to a
package providing a shared library, the original shared library and its
replacement must have the same @code{SONAME} and be binary-compatible.

The @option{--no-grafts} command-line option allows you to forcefully
avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
Thus, the command:

@example
guix build bash --no-grafts
@end example

@noindent
returns the store file name of the original Bash, whereas:

@example
guix build bash
@end example

@noindent
returns the store file name of the ``fixed'', replacement Bash.  This
allows you to distinguish between the two variants of Bash.

To verify which Bash your whole profile refers to, you can run
(@pxref{Invoking guix gc}):

@example
guix gc -R `readlink -f ~/.guix-profile` | grep bash
@end example

@noindent
@dots{} and compare the store file names that you get with those above.
Likewise for a complete Guix system generation:

@example
guix gc -R `guix system build my-config.scm` | grep bash
@end example

Lastly, to check which Bash running processes are using, you can use the
@command{lsof} command:

@example
lsof | grep /gnu/store/.*bash
@end example


@node Bootstrapping
@chapter 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).

@unnumberedsec Preparing to Use the Bootstrap Binaries

@c As of Emacs 24.3, Info-mode displays the image, but since it's a
@c large image, it's hard to scroll.  Oh well.
@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.  A similar figure can be generated with
@command{guix graph} (@pxref{Invoking guix graph}), along the lines of:

@example
guix graph -t derivation \
  -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
  | dot -Tps > t.ps
@end example

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.


@unnumberedsec Building the Build Tools

Bootstrapping is complete when we have a full tool chain that does not
depend on the pre-built bootstrap tools discussed above.  This
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 commencement)} module.

The @command{guix graph} command allows us to ``zoom out'' compared to
the graph above, by looking at the level of package objects instead of
individual derivations---remember that a package may translate to
several derivations, typically one derivation to download its source,
one to build the Guile modules it needs, and one to actually build the
package from source.  The command:

@example
guix graph -t bag \
  -e '(@@@@ (gnu packages commencement)
          glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps
@end example

@noindent
produces the dependency graph leading to the ``final'' C
library@footnote{You may notice the @code{glibc-intermediate} label,
suggesting that it is not @emph{quite} final, but as a good
approximation, we will consider it final.}, depicted below.

@image{images/bootstrap-packages,6in,,Dependency graph of the early packages}

@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@tie{}Make---noted @code{make-boot0} above---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 (not shown above) 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}
variable of the @code{(gnu packages commencement)} module, and are
implicitly used by any package that uses @code{gnu-build-system}
(@pxref{Build Systems, @code{gnu-build-system}}).


@unnumberedsec Building the Bootstrap Binaries

@cindex 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.

@unnumberedsec Reducing the Set of Bootstrap Binaries

Our bootstrap binaries currently include GCC, Guile, etc.  That's a lot
of binary code!  Why is that a problem?  It's a problem because these
big chunks of binary code are practically non-auditable, which makes it
hard to establish what source code produced them.  Every unauditable
binary also leaves us vulnerable to compiler backdoors as described by
Ken Thompson in the 1984 paper @emph{Reflections on Trusting Trust}.

This is mitigated by the fact that our bootstrap binaries were generated
from an earlier Guix revision.  Nevertheless it lacks the level of
transparency that we get in the rest of the package dependency graph,
where Guix always gives us a source-to-binary mapping.  Thus, our goal
is to reduce the set of bootstrap binaries to the bare minimum.

The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists
on-going projects to do that.  One of these is about replacing the
bootstrap GCC with a sequence of assemblers, interpreters, and compilers
of increasing complexity, which could be built from source starting from
a simple and auditable assembler.  Your help is welcome!


@node Porting
@chapter Porting to a New Platform

As discussed above, the GNU distribution is self-contained, and
self-containment is achieved by relying on pre-built ``bootstrap
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

For this to work, the @code{glibc-dynamic-linker} procedure in
@code{(gnu packages bootstrap)} 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.

Once these are built, the @code{(gnu packages bootstrap)} module needs
to be updated to refer to these binaries on the target platform.  That
is, the hashes and URLs of the bootstrap tarballs for the new platform
must be added alongside those of the currently supported platforms.  The
bootstrap Guile tarball is treated specially: it is expected to be
available locally, and @file{gnu/local.mk} has rules to download it for
the supported architectures; a rule for the new platform must be added
as well.

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 *********************************************************************
@include contributing.texi

@c *********************************************************************
@node Acknowledgments
@chapter Acknowledgments

Guix is based on the @uref{http://nixos.org/nix/, Nix package manager},
which was designed and
implemented by Eelco Dolstra, with contributions from other people (see
the @file{nix/AUTHORS} file in Guix.)  Nix pioneered functional package
management, and promoted unprecedented features, such as transactional
package upgrades and rollbacks, per-user profiles, and referentially
transparent build processes.  Without this work, Guix would not exist.

The Nix-based software distributions, Nixpkgs and NixOS, have also been
an inspiration for Guix.

GNU@tie{}Guix itself is a collective work with contributions from a
number of people.  See the @file{AUTHORS} file in Guix for more
information on these fine people.  The @file{THANKS} file lists people
who have helped by reporting bugs, taking care of the infrastructure,
providing artwork and themes, making suggestions, and more---thank you!


@c *********************************************************************
@node GNU Free Documentation License
@appendix GNU Free Documentation License
@cindex license, GNU Free Documentation License
@include fdl-1.3.texi

@c *********************************************************************
@node Concept Index
@unnumbered Concept Index
@printindex cp

@node Programming Index
@unnumbered Programming Index
@syncodeindex tp fn
@syncodeindex vr fn
@printindex fn

@bye

@c Local Variables:
@c ispell-local-dictionary: "american";
@c End: