guix.texi

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

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}}).


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

@unnumberedsubsec 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
@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

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 do 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: