doc: Show bootstrapping at the package level.

* doc/images/bootstrap-packages.dot: New file.
* doc.am (DOT_FILES): Add it.
* doc/guix.texi (Bootstrapping): Show 'guix graph' commands.  Includes
'images/bootstrap-packages' and comment it.

1 files changed, 36 insertions, 7 deletions

diff --git a/doc/guix.texi b/doc/guix.texi
index f664ec6770..1081bd1866 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -10167,7 +10167,16 @@ re-create them if needed (more on that later).
 
 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
+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}
@@ -10203,9 +10212,6 @@ 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
@@ -10214,17 +10220,40 @@ 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 Make, which is a prerequisite for all the following packages.
-From there Findutils and Diffutils get built.
+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 are built.  GCC uses @code{ld}
+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.