[PATCH] toplevel bootstrap documentation

[Paolo Bonzini <paolo dot bonzini at lu dot unisi dot ch>]

And at last, here is the toplevel bootstrap documentation.  I also have 
some updates for etc/configure.texi (which is not in the GCC repository) 
and I'll send them later.

Some of the documentation requires the patches I just sent.

Tested with make info and make dvi.  Ok for mainline?

Paolo
Index: gcc/gcc/doc/makefile.texi
===================================================================
--- gcc/gcc/doc/makefile.texi	(revision 110266)
+++ gcc/gcc/doc/makefile.texi	(working copy)
@@ -7,6 +7,8 @@
 @cindex makefile targets
 @cindex targets, makefile
 
+These targets are available from the @samp{gcc} directory:
+
 @table @code
 @item all
 This is the default target.  Depending on what your build/host/target
@@ -72,49 +74,59 @@ make check-gcc RUNTESTFLAGS="execute.exp
 
 Note that running the testsuite may require additional tools be
 installed, such as TCL or dejagnu.
+@end table
+
+The toplevel tree from which you start GCC compilation is not
+the GCC directory, but rather a complex Makefile that coordinates
+the various steps of the build, including bootstrapping the compiler
+and using the new compiler to build target libraries.
+
+When GCC is configured for a native configuration, the default action
+for @command{make} is to do a full three-stage bootstrap.  This means
+that GCC is built three times---once with the native compiler, once with
+the native-built compiler it just built, and once with the compiler it
+built the second time.  In theory, the last two should produce the same
+results, which @samp{make compare} can check.  Each stage is configured
+separately and compiled into a separate directory, to minimize problems
+due to ABI incompatibilities between the native compiler and GCC.
+
+If you do a change, rebuilding will also start from the first stage
+and ``bubble'' up the change through the three stages.  Each stage
+is taken from its build directory (if it had been built previously),
+rebuilt, and copied to its subdirectory.  This will allow you to, for
+example, continue a bootstrap after fixing a bug which causes the
+stage2 build to crash.  It does not provide as good coverage of the
+compiler as bootstrapping from scratch, but it ensures that the new
+code is syntactically correct (e.g. that you did not use GCC extensions
+by mistake), and avoids spurious bootstrap comparison
+failures@footnote{Except if the compiler was buggy and miscompiled
+  some of the files that were not modified.  In this case, it's best
+  to use @command{make restrap}.}.
 
-@item bootstrap
-Builds GCC three times---once with the native compiler, once with the
-native-built compiler it just built, and once with the compiler it built
-the second time.  In theory, the last two should produce the same
-results, which @samp{make compare} can check.  Each step of this process
-is called a ``stage'', and the results of each stage @var{N}
-(@var{N} = 1@dots{}3) are copied to a subdirectory @file{stage@var{N}/}.
+Other targets available from the top level include:
 
+@table @code
 @item bootstrap-lean
 Like @code{bootstrap}, except that the various stages are removed once
 they're no longer needed.  This saves disk space.
 
-@item bubblestrap
-This incrementally rebuilds each of the three stages, one at a time.
-It does this by ``bubbling'' the stages up from their subdirectories
-(if they had been built previously), rebuilding them, and copying them
-back to their subdirectories.  This will allow you to, for example,
-continue a bootstrap after fixing a bug which causes the stage2 build
-to crash.
-
-@item quickstrap
-Rebuilds the most recently built stage.  Since each stage requires
-special invocation, using this target means you don't have to keep
-track of which stage you're on or what invocation that stage needs.
+@item bootstrap2
+@itemx bootstrap2-lean
+Performs only the first two stages of bootstrap.  Unlike a three-stage
+bootstrap, this does not perform a comparison to test that the compiler
+is running properly.  Note that the disk space required by a ``lean''
+bootstrap is approximately independent of the number of stages.
+
+@item stage@var{N}-bubble (@var{N} = 1@dots{}4)
+Rebuild all the stages up to @var{N}, with the appropriate flags,
+``bubbling'' the changes as described above.
+
+@item all-stage@var{N} (@var{N} = 1@dots{}4)
+Assuming that stage @var{N} has already been built, rebuild it with the
+appropriate flags.  This is rarely needed.
 
 @item cleanstrap
-Removed everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
-
-@item restrap
-Like @code{cleanstrap}, except that the process starts from the first
-stage build, not from scratch.
-
-@item stage@var{N} (@var{N} = 1@dots{}4)
-For each stage, moves the appropriate files to the @file{stage@var{N}}
-subdirectory.
-
-@item unstage@var{N} (@var{N} = 1@dots{}4)
-Undoes the corresponding @code{stage@var{N}}.
-
-@item restage@var{N} (@var{N} = 1@dots{}4)
-Undoes the corresponding @code{stage@var{N}} and rebuilds it with the
-appropriate flags.
+Remove everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
 
 @item compare
 Compares the results of stages 2 and 3.  This ensures that the compiler
@@ -125,7 +137,47 @@ regardless of how it itself was compiled
 Builds a compiler with profiling feedback information.  For more
 information, see
 @ref{Building,,Building with profile feedback,gccinstall,Installing GCC}.
-This is actually a target in the top-level directory, which then
-recurses into the @file{gcc} subdirectory multiple times.
+
+@item restrap
+Restart a bootstrap, so that everything that was not built with
+the system compiler is rebuilt.
+
+@item stage@var{N}-start (@var{N} = 1@dots{}4)
+For each package that is bootstrapped, rename directories so that,
+for example, @file{gcc} points to the stage@var{N} GCC, compiled
+with the stage@var{N-1} GCC@footnote{Customarily, the system compiler
+  is also termed the @file{stage0} GCC.}.
+
+You will invoke this target if you need to test or debug the
+stage@var{N} GCC.  If you only need to execute GCC (but you need
+not run @samp{make} either to rebuild it or to run test suites),
+you should be able to work directly in the @file{stage@var{N}-gcc}
+directory.  This makes it easier to debug multiple stages in
+parallel.
+
+@item stage
+For each package that is bootstrapped, relocate its build directory
+to indicate its stage.  For example, if the @file{gcc} directory
+points to the stage2 GCC, after invoking this target it will be
+renamed to @file{stage2-gcc}.
 
 @end table
+
+If you wish to use non-default GCC flags when compiling the stage2 and
+stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
+@samp{make}.
+
+Usually, the first stage only builds the languages that the compiler
+is written in: typically, C and maybe Ada.  If you are debugging a
+miscompilation of a different stage2 front-end (for example, of the
+Fortran front-end), you may want to have front-ends for other languages
+in the first stage as well.  To do so, set @code{STAGE1_LANGUAGES}
+on the command line when doing @samp{make}.
+
+For example, in the aforementioned scenario of debugging a Fortran
+front-end miscompilation caused by the stage1 compiler, you may need a
+command like
+
+@example
+make stage2-bubble STAGE1_LANGUAGES=c,fortran
+@end example
Index: gcc/gcc/doc/install.texi
===================================================================
--- gcc/gcc/doc/install.texi	(revision 110266)
+++ gcc/gcc/doc/install.texi	(working copy)
@@ -527,6 +527,7 @@ Second, when configuring a native system
 your environment before running configure.  Otherwise the configuration
 scripts may fail.
 
+@ignore
 Note that the bootstrap compiler and the resulting GCC must be link
 compatible, else the bootstrap will fail with linker errors about
 incompatible object file formats.  Several multilibed targets are
@@ -537,6 +538,7 @@ affected by this requirement, see
 @ifhtml
 @uref{specific.html,,host/target specific installation notes}.
 @end ifhtml
+@end ignore
 
 To configure GCC:
 
@@ -1072,9 +1087,9 @@ Building the Ada compiler has special re
 If you do not pass this flag, or specify the option @code{all}, then all
 default languages available in the @file{gcc} sub-tree will be configured.
 Ada, Objective-C++, and treelang are not default languages; the rest are.
-Re-defining @code{LANGUAGES} when calling @samp{make bootstrap}
-@strong{does not} work anymore, as those language sub-directories might
-not have been configured!
+Re-defining @code{LANGUAGES} when calling @samp{make} @strong{does not}
+work anymore, as those language sub-directories might not have been
+configured!
 
 @item --disable-libada
 Specify that the run-time libraries and tools used by GNAT should not
@@ -1517,22 +1550,24 @@ documentation pre-built for the unmodifi
 
 @section Building a native compiler
 
-For a native build issue the command @samp{make bootstrap}.  This
-will build the entire GCC system, which includes the following steps:
+For a native build, the command @samp{make} will trigger a 3-stage
+bootstrap of the compiler.  This will build the entire GCC system
+and ensure that it compiles itself correctly, by doing the
+following steps:
 
 @itemize @bullet
 @item
-Build host tools necessary to build the compiler such as texinfo, bison,
+Build tools necessary to build the compiler such as texinfo, bison,
 gperf.
 
 @item
-Build target tools for use by the compiler such as binutils (bfd,
-binutils, gas, gprof, ld, and opcodes)
-if they have been individually linked
-or moved into the top level GCC source tree before configuring.
 
 @item
-Perform a 3-stage bootstrap of the compiler.
+Perform a 3-stage bootstrap of the compiler.  This includes building
+three times the target tools for use by the compiler, such as binutils
+(bfd, binutils, gas, gprof, ld, and opcodes), if they have been
+individually linked or moved into the top level GCC source tree before
+configuring.
 
 @item
 Perform a comparison test of the stage2 and stage3 compilers.
@@ -1543,8 +1578,8 @@ Build runtime libraries using the stage3
 @end itemize
 
 If you are short on disk space you might consider @samp{make
-bootstrap-lean} instead.  This is identical to @samp{make
-bootstrap} except that object files from the stage1 and
+bootstrap-lean} instead.  The sequence of compilation is the
+same described above, but object files from the stage1 and
 stage2 of the 3-stage bootstrap of the compiler are deleted as
 soon as they are no longer needed.
 
@@ -1561,7 +1596,7 @@ roughly 40% of disk space both for the b
 
 If you wish to use non-default GCC flags when compiling the stage2 and
 stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
-@samp{make bootstrap}.  Non-default optimization flags are less well
+@samp{make}.  Non-default optimization flags are less well
 tested here than the default of @samp{-g -O2}, but should still work.
 In a few cases, you may find that you need to specify special flags such
 as @option{-msoft-float} here to complete the bootstrap; or, if the
@@ -1570,17 +1605,17 @@ around this, by choosing @code{BOOT_CFLA
 stage1 compiler that were miscompiled, or by using @samp{make
 bootstrap4} to increase the number of stages of bootstrap.
 
-Note that using non-standard @code{CFLAGS} can cause bootstrap to fail in
-@file{libiberty}, if these trigger a warning with the new compiler.  For
-example using @samp{-O2 -g -mcpu=i686} on @code{i686-pc-linux-gnu} will
-cause bootstrap failure as @option{-mcpu=} is deprecated in 3.4.0 and above.
+Note that using non-standard @code{CFLAGS} can cause bootstrap to fail
+if these trigger a warning with the new compiler.  For example using
+@samp{-O2 -g -mcpu=i686} on @code{i686-pc-linux-gnu} will cause bootstrap
+failure as @option{-mcpu=} is deprecated in 3.4.0 and above.
 
 
 If you used the flag @option{--enable-languages=@dots{}} to restrict
 the compilers to be built, only those you've actually enabled will be
 built.  This will of course only build those runtime libraries, for
 which the particular compiler has been built.  Please note,
-that re-defining @env{LANGUAGES} when calling @samp{make bootstrap}
+that re-defining @env{LANGUAGES} when calling @samp{make}
 @strong{does not} work anymore!
 
 If the comparison of stage2 and stage3 fails, this normally indicates
@@ -1590,6 +1625,15 @@ a few systems, meaningful comparison of 
 always appear ``different''.  If you encounter this problem, you will
 need to disable comparison in the @file{Makefile}.)
 
+If you do not want to bootstrap your compiler, you can configure with
+@option{--disable-bootstrap}.  In particular cases, you may want to
+bootstrap your compiler even if the target system is not the same as
+the one you are building on: for example, you could build a
+@code{powerpc-unknown-linux-gnu} toolchain on a
+@code{powerpc64-unknown-linux-gnu} host.  In this case, pass
+@option{--enable-bootstrap} to the configure script.
+
+
 @section Building a cross compiler
 
 We recommend reading the
@@ -1674,21 +1718,25 @@ compilation options.  Check your target'
 
 @section Building in parallel
 
-You can use @samp{make bootstrap MAKE="make -j 2" -j 2}, or just
-@samp{make -j 2 bootstrap} for GNU Make 3.79 and above, instead of
-@samp{make bootstrap} to build GCC in parallel.
-You can also specify a bigger number, and in most cases using a value
-greater than the number of processors in your machine will result in
-fewer and shorter I/O latency hits, thus improving overall throughput;
-this is especially true for slow drives and network filesystems.
+You can use @samp{make -j 2}@footnote{Only supported by GNU Make 3.79
+  and above, which is anyway necessary to build GCC.}, instead of @samp{make},
+to build GCC in parallel.  You can also specify a bigger number, and
+in most cases using a value greater than the number of processors in
+your machine will result in fewer and shorter I/O latency hits, thus
+improving overall throughput; this is especially true for slow drives
+and network filesystems.
 
 @section Building the Ada compiler
 
 In order to build GNAT, the Ada compiler, you need a working GNAT
-compiler (GNAT version 3.14 or later, or GCC version 3.1 or later),
-including GNAT tools such as @command{gnatmake} and @command{gnatlink},
-since the Ada front end is written in Ada (with some
-GNAT-specific extensions), and GNU make.
+compiler (GNAT version 3.14 or later, or GCC version 3.1 or later).
+This includes GNAT tools such as @command{gnatmake} and
+@command{gnatlink}, since the Ada front end is written in Ada and
+uses some GNAT-specific extensions.
+
+In order to build a cross compiler, it is suggested to install
+the new compiler as native first, and then use it to build the cross
+compiler.
 
 @command{configure} does not test whether the GNAT installation works
 and has a sufficiently recent version; if too old a GNAT version is
@@ -1700,7 +1748,7 @@ used to disable building the Ada front e
 It is possible to use profile feedback to optimize the compiler itself.  This
 should result in a faster compiler binary.  Experiments done on x86 using gcc
 3.3 showed approximately 7 percent speedup on compiling C programs.  To
-bootstrap compiler with profile feedback, use @code{make profiledbootstrap}.
+bootstrap the compiler with profile feedback, use @code{make profiledbootstrap}.
 
 When @samp{make profiledbootstrap} is run, it will first build a @code{stage1}
 compiler.  This compiler is used to build a @code{stageprofile} compiler
@@ -1708,7 +1756,7 @@ instrumented to collect execution counts
 probabilities.  Then runtime libraries are compiled with profile collected.
 Finally a @code{stagefeedback} compiler is built using the information collected.
 
-Unlike @samp{make bootstrap} several additional restrictions apply.  The
+Unlike standard bootstrap, several additional restrictions apply.  The
 compiler used to build @code{stage1} needs to support a 64-bit integral type.
 It is recommended to only use GCC for this.  Also parallel make is currently
 not supported since collisions in profile collecting may occur.
@@ -2014,7 +2062,7 @@ it will not be created otherwise.  This 
 not as a bug, because it gives slightly more control to the packagers
 using the @code{DESTDIR} feature.
 
-If you built a released version of GCC using @samp{make bootstrap} then please
+If you are bootstrapping a released version of GCC then please
 quickly review the build status page for your release, available from
 @uref{http://gcc.gnu.org/buildstat.html}.
 If your system is not listed for the version of GCC that you built,
@@ -2472,17 +2520,16 @@ and it is not possible to build parallel
 supported; in particular, Craylibs are assumed to be in
 @file{/opt/ctl/craylibs/craylibs}.
 
-You absolutely @strong{must} use GNU make on this platform.  Also, you
-need to tell GCC where to find the assembler and the linker.  The
-simplest way to do so is by providing @option{--with-as} and
-@option{--with-ld} to @file{configure}, e.g.@:
+On this platform, you need to tell GCC where to find the assembler and
+the linker.  The simplest way to do so is by providing @option{--with-as}
+and @option{--with-ld} to @file{configure}, e.g.@:
 
 @smallexample
     configure --with-as=/opt/ctl/bin/cam --with-ld=/opt/ctl/bin/cld \
       --enable-languages=c
 @end smallexample
 
-The comparison test during @samp{make bootstrap} fails on Unicos/Mk
+The comparison test at the end of the bootstrapping process fails on Unicos/Mk
 because the assembler inserts timestamps into object files.  You should
 be able to work around this by doing @samp{make all} after getting this
 failure.
@@ -2809,9 +2856,9 @@ and Latin-America.
 
 The HP assembler on these systems has some problems.  Most notably the
 assembler inserts timestamps into each object file it creates, causing
-the 3-stage comparison test to fail during a @samp{make bootstrap}.
-You should be able to continue by saying @samp{make all} after getting
-the failure from @samp{make bootstrap}.
+the 3-stage comparison test to fail during a bootstrap.
+You should be able to continue by saying @samp{make all-host all-target}
+after getting the failure from @samp{make}.
 
 GCC 4.0 requires CVS binutils as of April 28, 2004 or later.  Earlier
 versions require binutils 2.8 or later.
@@ -2897,10 +2944,10 @@ many limitations.  For example, it does 
 definitions.  As a result, explicit template instantiations are required
 when using C++.  This makes it difficult if not impossible to build many
 C++ applications.  You can't generate debugging information when using
-the HP assembler.  Finally, @samp{make bootstrap} fails in the final
+the HP assembler.  Finally, bootstrapping fails in the final
 comparison of object modules due to the time stamps that it inserts into
 the modules.  The bootstrap can be continued from this point with
-@samp{make all}.
+@samp{make all-host all-target}.
 
 A recent linker patch must be installed for the correct operation of
 GCC 3.3 and later.  @code{PHSS_26559} and @code{PHSS_24304} are the
@@ -3065,7 +3112,7 @@ command like this:
 @emph{You should substitute @samp{i686} in the above command with the appropriate
 processor for your host.}
 
-After the usual @samp{make bootstrap} and
+After the usual @samp{make} and
 @samp{make install}, you can then access the UDK-targeted GCC
 tools by adding @command{udk-} before the commonly known name.  For
 example, to invoke the C compiler, you would use @command{udk-gcc}.
@@ -3114,9 +3161,6 @@ removed and the system libunwind library
 @heading @anchor{x-ibm-aix}*-ibm-aix*
 Support for AIX version 3 and older was discontinued in GCC 3.4.
 
-AIX Make frequently has problems with GCC makefiles.  GNU Make 3.79.1 or
-newer is recommended to build on this platform.
-
 ``out of memory'' bootstrap failures may indicate a problem with
 process resource limits (ulimit).  Hard limits are configured in the
 @file{/etc/security/limits} system configuration file.
@@ -3129,8 +3173,8 @@ one may use GNU Bash instead of AIX @com
    % export CONFIG_SHELL
 @end smallexample
 
-and then proceed as described in @uref{build.html,,the build instructions},
-where we strongly recommend using GNU make and specifying an absolute path
+and then proceed as described in @uref{build.html,,the build
+instructions}, where we strongly recommend specifying an absolute path
 to invoke @var{srcdir}/configure.
 
 Errors involving @code{alloca} when building GCC generally are due