re PR bootstrap/25670 (build fail with 'make all-gcc')

2006-02-20  Paolo Bonzini  <bonzini@gnu.org>

	PR bootstrap/25670

	* Makefile.tpl ([+compare-target+]): Print explanation messages.

	* Makefile.def (ADAFLAGS, BOOT_ADAFLAGS, LANGUAGES): New flags_to_pass.
	* Makefile.tpl (BASE_FLAGS_TO_PASS): Support optional flags_to_pass.
	(EXTRA_GCC_FLAGS): Remove ADAFLAGS, BOOT_ADAFLAGS, LANGUAGES,
	BUILD_PREFIX, BUILD_PREFIX_1.
	* configure.in: (BUILD_PREFIX, BUILD_PREFIX_1): Don't substitute.

	* Makefile.def (bootstrap stage 1): Pass LIBCFLAGS too.
	* Makefile.tpl (POSTSTAGE1_FLAGS_TO_PASS): Override LIBCFLAGS too.

	* Makefile.tpl (configure-stage[+id+]-[+prefix+][+module+],
	all-stage[+id+]-[+prefix+][+module+], : Use $(current_stage) instead
	of `cat stage_current`.  Always provide the `r' and `s' variables.
	(clean-stage[+id+]-[+prefix+][+module+]): Likewise, and make it into
	a single shell execution.
	(configure-[+prefix+][+module+], all-[+prefix+][+module+]): For
	bootstrapped modules, make the stage1 module if the build was not
	started yet, else build the current stage.
	(all-host, all-target): Omit bootstrapped modules (if bootstrapping).
	(all-build, all-host, all-target, [+make_target+]-host,
	[+make_target+]-target): Do not use \-continued lines.
	(target modules): Depend on stage_last, not all-gcc, if bootstrapping.
	(current_stage, restrap, stage_last): New.

	* Makefile.in: Regenerate.
	* configure: Regenerate.

gcc:
2006-02-20  Paolo Bonzini  <bonzini@gnu.org>

	PR bootstrap/25476

	* Makefile.in (LDFLAGS): Define from autoconf substitution.

	* Makefile.in (BOOTSTRAPPING): New.
	(quickstrap): New definition if BOOTSTRAPPING=yes.

	* Makefile.in (CONFIG_LANGUAGES): Substitute all_selected_languages.
	* configure.ac: Substitute all_selected_languages with the languages
	that were configured.  For all the other variables except
	lang_specs_files, include all the languages in the tree.
	* configure: Regenerate.
	
	* Makefile.in (stmp-fixinc): Copy includes from the prev-gcc directory,
	if there is one.  Run the commands to run fixincludes in the same
	subshell.

	* doc/makefile.texi: Document new makefile targets from toplevel bootstrap.
	* doc/install.texi: Document exact conventions for searching target tools.
	Document --with-build-time-tools.  Document toplevel bootstrap.  Document
	something more about building an Ada cross-compiler.  Don't list GNU Make
	requirements which affect all platforms.

From-SVN: r111295

2 files changed, 205 insertions, 105 deletions

diff --git a/gcc/doc/install.texi b/gcc/doc/install.texi
index f76cead..846323f 100644
--- a/gcc/doc/install.texi
+++ b/gcc/doc/install.texi
@@ -527,6 +527,7 @@ Second, when configuring a native system, either @command{cc} or
 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:
 
@@ -777,7 +779,8 @@ assembler found is not actually the GNU assembler.  (Confusion may also
 result if the compiler finds the GNU assembler but has not been
 configured with @option{--with-gnu-as}.)  If you have more than one
 assembler installed on your system, you may want to use this option in
-connection with @option{--with-as=@var{pathname}}.
+connection with @option{--with-as=@var{pathname}} or
+@option{--with-build-time-tools=@var{pathname}}.
 
 The following systems are the only ones where it makes a difference
 whether you use the GNU assembler.  On any other system,
@@ -800,28 +803,40 @@ the 386, if you use the GNU assembler, you should also use the GNU linker
 (and specify @option{--with-gnu-ld}).
 
 @item @anchor{with-as}--with-as=@var{pathname}
-Specify that the
-compiler should use the assembler pointed to by @var{pathname}, rather
-than the one found by the standard rules to find an assembler, which
-are:
+Specify that the compiler should use the assembler pointed to by
+@var{pathname}, rather than the one found by the standard rules to find
+an assembler, which are:
 @itemize @bullet
 @item
-Check the @file{@var{libexec}/gcc/@var{target}/@var{version}}
-directory, where @var{libexec} defaults to
-@file{@var{exec-prefix}/libexec} and @var{exec-prefix} defaults to
-@var{prefix} which defaults to @file{/usr/local} unless overridden by
-the @option{--prefix=@var{pathname}} switch described
-above.  @var{target} is the target system triple, such as
-@samp{sparc-sun-solaris2.7}, and @var{version} denotes the GCC
-version, such as 3.0.
+Unless GCC is being built with a cross compiler, check the
+@file{@var{libexec}/gcc/@var{target}/@var{version}} directory.
+@var{libexec} defaults to @file{@var{exec-prefix}/libexec};
+@var{exec-prefix} defaults to @var{prefix}, which
+defaults to @file{/usr/local} unless overridden by the
+@option{--prefix=@var{pathname}} switch described above.  @var{target}
+is the target system triple, such as @samp{sparc-sun-solaris2.7}, and
+@var{version} denotes the GCC version, such as 3.0.
+
 @item
-Check operating system specific directories (e.g.@: @file{/usr/ccs/bin} on
+If the target system is the same that you are building on, check
+operating system specific directories (e.g.@: @file{/usr/ccs/bin} on
 Sun Solaris 2).
+
+@item
+Check in the @env{PATH} for a tool whose name is prefixed by the
+target system triple.
+
+@item
+Check in the @env{PATH} for a tool whose name is not prefixed by the
+target system triple, if the host and target system triple are
+the same (in other words, we use a host tool if it can be used for
+the target as well).
 @end itemize
-Note that these rules do not check for the value of @env{PATH}.  You may
-want to use @option{--with-as} if no assembler is installed in the
-directories listed above, or if you have multiple assemblers installed
-and want to choose one that is not found by the above rules.
+
+You may want to use @option{--with-as} if no assembler
+is installed in the directories listed above, or if you have multiple
+assemblers installed and want to choose one that is not found by the
+above rules.
 
 @item @anchor{with-gnu-ld}--with-gnu-ld
 Same as @uref{#with-gnu-as,,@option{--with-gnu-as}}
@@ -1072,9 +1087,9 @@ Building the Ada compiler has special requirements, see below.
 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
@@ -1294,11 +1309,29 @@ Specifies a list of directories which contain the target runtime
 libraries.  These libraries will be copied into the @file{gcc} install
 directory.  If the directory list is omitted, this option has no
 effect.
+
 @item --with-newlib
 Specifies that @samp{newlib} is
 being used as the target C library.  This causes @code{__eprintf} to be
 omitted from @file{libgcc.a} on the assumption that it will be provided by
 @samp{newlib}.
+
+@item --with-build-time-tools=@var{dir}
+Specifies where to find the set of target tools (assembler, linker, etc.)
+that will be used while building GCC itself.  This option can be useful
+if the directory layouts are different between the system you are building
+GCC on, and the system where you will deploy it.
+
+For example, on a @option{ia64-hp-hpux} system, you may have the GNU
+assembler and linker in @file{/usr/bin}, and the native tools in a
+different path, and build a toolchain that expects to find the
+native tools in @file{/usr/bin}.
+
+When you use this option, you should ensure that @var{dir} includes
+@command{ar}, @command{as}, @command{ld}, @command{nm},
+@command{ranlib} and @command{strip} if necessary, and possibly
+@command{objdump}.  Otherwise, GCC may use an inconsistent set of
+tools.
 @end table
 
 @subheading Fortran-Specific Options
@@ -1521,22 +1554,22 @@ documentation pre-built for the unmodified documentation in the release.
 
 @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.
@@ -1547,8 +1580,8 @@ Build runtime libraries using the stage3 compiler from the previous step.
 @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.
 
@@ -1565,7 +1598,7 @@ roughly 40% of disk space both for the bootstrap and the final installation.
 
 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
@@ -1574,17 +1607,17 @@ around this, by choosing @code{BOOT_CFLAGS} to avoid the parts of the
 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
@@ -1594,6 +1627,15 @@ a few systems, meaningful comparison of object files is impossible; they
 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
@@ -1678,21 +1720,25 @@ compilation options.  Check your target's definition of
 
 @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
@@ -1704,7 +1750,7 @@ used to disable building the Ada front end.
 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
@@ -1712,7 +1758,7 @@ instrumented to collect execution counts of instruction and branch
 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.
@@ -2018,7 +2064,7 @@ it will not be created otherwise.  This is regarded as a feature,
 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,
@@ -2476,17 +2522,16 @@ and it is not possible to build parallel applications.  Cray modules are not
 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.
@@ -2824,9 +2869,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.
@@ -2912,10 +2957,10 @@ many limitations.  For example, it does not support weak symbols or alias
 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
@@ -3080,7 +3125,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}.
@@ -3129,9 +3174,6 @@ removed and the system libunwind library will always be used.
 @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.
@@ -3144,8 +3186,8 @@ one may use GNU Bash instead of AIX @command{/bin/sh}, e.g.,
    % 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
diff --git a/gcc/doc/makefile.texi b/gcc/doc/makefile.texi
index 3fb3072..8dcf496 100644
--- a/gcc/doc/makefile.texi
+++ b/gcc/doc/makefile.texi
@@ -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=19980413-*"
 
 Note that running the testsuite may require additional tools be
 installed, such as TCL or dejagnu.
+@end table
 
-@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}/}.
+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}.}.
+
+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 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 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 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 cleanstrap
-Removed everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
+@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 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.
+@item cleanstrap
+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,53 @@ 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
+
+Alternatively, you can use per-language targets to build and test
+languages that are not enabled by default in stage1.  For example,
+@command{make f951} will build a Fortran compiler even in the stage1
+build directory.
+