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

ChangeLog

+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.
+
 2006-02-19  Bud Davis  <jmdavis@link.com>
 
 	* MAINTAINERS (Write After Approval):  Remove myself.

Makefile.def

@@ -207,7 +207,9 @@ flags_to_pass = { flag= SHELL ; };
 flags_to_pass = { flag= YACC ; };
 
 // Host tools
+flags_to_pass = { flag= ADAFLAGS ; optional=true ; };
 flags_to_pass = { flag= AR_FLAGS ; };
+flags_to_pass = { flag= BOOT_ADAFLAGS ; optional=true ; };
 flags_to_pass = { flag= BOOT_CFLAGS ; };
 flags_to_pass = { flag= BOOT_LDFLAGS ; };
 flags_to_pass = { flag= CFLAGS ; };
@@ -241,6 +243,7 @@ flags_to_pass = { flag= STRIP_FOR_TARGET ; };
 flags_to_pass = { flag= WINDRES_FOR_TARGET ; };
 
 // Miscellaneous
+flags_to_pass = { flag= LANGUAGES ; optional=true ; };
 flags_to_pass = { flag= LEAN ; };
 
 // Inter-module dependencies
@@ -461,7 +464,7 @@ bootstrap_stage = {
 	id=1 ;
 	stage_configure_flags='--disable-intermodule \
 	  --disable-coverage --enable-languages="$(STAGE1_LANGUAGES)"' ;
-	stage_make_flags='CFLAGS="$(STAGE1_CFLAGS)"' ; };
+	stage_make_flags='CFLAGS="$(STAGE1_CFLAGS)" LIBCFLAGS="$(STAGE1_CFLAGS)"' ; };
 bootstrap_stage = {
 	id=2 ; prev=1 ;
 	bootstrap_target=bootstrap2 ;

configure.in

@@ -1060,8 +1060,6 @@ if test "${build}" != "${host}" ; then
   CXX=${CXX-${host_alias}-c++}
   CXXFLAGS=${CXXFLAGS-"-g -O2"}
   CC_FOR_BUILD=${CC_FOR_BUILD-gcc}
-  BUILD_PREFIX=${build_alias}-
-  BUILD_PREFIX_1=${build_alias}-
 
 else
   # Set reasonable default values for some tools even if not Canadian.
@@ -1073,9 +1071,6 @@ else
   # This is all going to change when we autoconfiscate...
 
   CC_FOR_BUILD="\$(CC)"
-  BUILD_PREFIX=
-  BUILD_PREFIX_1=loser-
-
   AC_PROG_CC
 
   # We must set the default linker to the linker used by gcc for the correct
@@ -2160,8 +2155,6 @@ AC_SUBST_FILE(ospace_frag)
 
 # Miscellanea: directories, flags, etc.
 AC_SUBST(RPATH_ENVVAR)
-AC_SUBST(BUILD_PREFIX)
-AC_SUBST(BUILD_PREFIX_1)
 AC_SUBST(tooldir)
 AC_SUBST(build_tooldir)
 AC_SUBST(CONFIGURE_GDB_TK)

gcc/ChangeLog

+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.
+
 2006-02-19  Roger Sayle  <roger@eyesopen.com>
 
 	PR middle-end/19543

gcc/Makefile.in

@@ -130,7 +130,7 @@ T_ADAFLAGS =
 SUBDIRS =@subdirs@ build
 
 # Selection of languages to be made.
-CONFIG_LANGUAGES = @all_languages@
+CONFIG_LANGUAGES = @all_selected_languages@
 LANGUAGES = c gcov$(exeext) gcov-dump$(exeext) $(CONFIG_LANGUAGES)
 
 # Selection of languages to be made during stage1 build.
@@ -150,6 +150,7 @@ BOOT_LANGUAGES = c @all_boot_languages@
 XCFLAGS =
 TCFLAGS =
 CFLAGS = -g
+LDFLAGS = @LDFLAGS@
 STAGE1_CFLAGS = -g @stage1_cflags@
 STAGE1_CHECKING = -DENABLE_CHECKING -DENABLE_ASSERT_CHECKING
 BOOT_CFLAGS = -g -O2
@@ -3193,17 +3194,23 @@ stmp-fixinc: gsyslimits.h macro_list \
 	fi
 	rm -rf include; mkdir include
 	-chmod a+rx include
-	(TARGET_MACHINE='$(target)'; srcdir=`cd $(srcdir); ${PWD_COMMAND}`; \
-	  SHELL='$(SHELL)'; MACRO_LIST=`${PWD_COMMAND}`/macro_list ; \
-	  export TARGET_MACHINE srcdir SHELL MACRO_LIST && \
-	  cd $(build_objdir)/fixincludes && \
-	  $(SHELL) ./fixinc.sh ../../gcc/include \
-	    $(SYSTEM_HEADER_DIR) $(OTHER_FIXINCLUDES_DIRS) )
-	rm -f include/syslimits.h
-	if [ -f include/limits.h ]; then \
-	  mv include/limits.h include/syslimits.h; \
+	if [ -d ../prev-gcc ]; then \
+	  cd ../prev-gcc && \
+	  $(MAKE) $(INSTALL_HEADERS_DIR) DESTDIR=`pwd`/../gcc/ \
+	    libsubdir=. ; \
 	else \
-	  cp $(srcdir)/gsyslimits.h include/syslimits.h; \
+	  (TARGET_MACHINE='$(target)'; srcdir=`cd $(srcdir); ${PWD_COMMAND}`; \
+	    SHELL='$(SHELL)'; MACRO_LIST=`${PWD_COMMAND}`/macro_list ; \
+	    export TARGET_MACHINE srcdir SHELL MACRO_LIST && \
+	    cd $(build_objdir)/fixincludes && \
+	    $(SHELL) ./fixinc.sh ../../gcc/include \
+	      $(SYSTEM_HEADER_DIR) $(OTHER_FIXINCLUDES_DIRS) ); \
+	  rm -f include/syslimits.h; \
+	  if [ -f include/limits.h ]; then \
+	    mv include/limits.h include/syslimits.h; \
+	  else \
+	    cp $(srcdir)/gsyslimits.h include/syslimits.h; \
+	  fi; \
 	fi
 	chmod a+r include/syslimits.h
 	$(STAMP) stmp-fixinc
@@ -4239,12 +4246,19 @@ bubblestrap:
 	  $(MAKE) $(REMAKEFLAGS) stage4_build || exit 1; \
 	fi
 
+BOOTSTRAPPING := $(shell if test -f ../stage_last; then echo yes; else echo no; fi)
+ifeq ($(BOOTSTRAPPING),yes)
+# Provide quickstrap as a target that people can type into the gcc directory,
+# and that fails if you're not into it.
+quickstrap: all
+else
 quickstrap:
 	if test -f stage_last ; then \
 	  LAST=`cat stage_last`; rm $$LAST; $(MAKE) $(REMAKEFLAGS) $$LAST; \
 	else \
 	  $(MAKE) $(REMAKEFLAGS) stage1_build; \
 	fi
+endif
 
 cleanstrap:
 	-$(MAKE) clean

gcc/configure.ac

@@ -817,30 +817,6 @@ AC_ARG_ENABLE(languages,
 esac],
 [enable_languages=c])
 
-subdirs=
-for lang in ${srcdir}/*/config-lang.in
-do
-	case $lang in
-	# The odd quoting in the next line works around
-	# an apparent bug in bash 1.12 on linux.
-changequote(,)dnl
-	${srcdir}/[*]/config-lang.in) ;;
-	*)
-	  lang_alias=`sed -n -e 's,^language=['"'"'"'"]\(.*\)["'"'"'"'].*$,\1,p' -e 's,^language=\([^   ]*\).*$,\1,p' $lang`
-	  if test "x$lang_alias" = x
-	  then
-	        echo "$lang doesn't set \$language." 1>&2
-	        exit 1
-	  fi
-	  case ",$enable_languages," in
-	  *,$lang_alias,*)
-	    subdirs="$subdirs `echo $lang | sed -e 's,^.*/\([^/]*\)/config-lang.in$,\1,'`" ;;
-	  esac
-	  ;;
-changequote([,])dnl
-	esac
-done
-
 
 # -------------------------
 # Checks for other programs
@@ -3258,22 +3234,10 @@ AC_SUBST(MAINT)dnl
 # Make empty files to contain the specs and options for each language.
 # Then add #include lines to for a compiler that has specs and/or options.
 
+subdirs=
 lang_opt_files=
 lang_specs_files=
 lang_tree_files=
-for subdir in . $subdirs
-do
-	if test -f $srcdir/$subdir/lang.opt; then
-	    lang_opt_files="$lang_opt_files $srcdir/$subdir/lang.opt"
-	fi
-	if test -f $srcdir/$subdir/lang-specs.h; then
-	    lang_specs_files="$lang_specs_files $srcdir/$subdir/lang-specs.h"
-	fi
-	if test -f $srcdir/$subdir/$subdir-tree.def; then
-	    lang_tree_files="$lang_tree_files $srcdir/$subdir/$subdir-tree.def"
-	fi
-done
-
 # These (without "all_") are set in each config-lang.in.
 # `language' must be a single word so is spelled singularly.
 all_languages=
@@ -3291,6 +3255,10 @@ all_gtfiles="$target_gtfiles"
 all_gtfiles_files_langs=
 all_gtfiles_files_files=
 
+# These are the languages that are set in --enable-languages,
+# and are available in the GCC tree.
+all_selected_languages=
+
 # Add the language fragments.
 # Languages are added via two mechanisms.  Some information must be
 # recorded in makefile variables, these are defined in config-lang.in.
@@ -3300,59 +3268,93 @@ all_gtfiles_files_files=
 
 language_hooks="Make-hooks"
 
-for s in $subdirs
+for lang in ${srcdir}/*/config-lang.in
 do
-		language=
-		boot_language=
-		compilers=
-		stagestuff=
-		outputs=
-		gtfiles=
-		. ${srcdir}/$s/config-lang.in
-		if test "x$language" = x
-		then
-			echo "${srcdir}/$s/config-lang.in doesn't set \$language." 1>&2
-			exit 1
-		fi
-		all_lang_makefrags="$all_lang_makefrags \$(srcdir)/$s/Make-lang.in"
-		if test -f ${srcdir}/$s/Makefile.in
-		then all_lang_makefiles="$s/Makefile"
-		fi
-		all_languages="$all_languages $language"
-		if test "x$boot_language" = xyes
-		then
-			all_boot_languages="$all_boot_languages $language"
-		fi
-		all_compilers="$all_compilers $compilers"
-		all_stagestuff="$all_stagestuff $stagestuff"
-		all_outputs="$all_outputs $outputs"
-		all_gtfiles="$all_gtfiles $gtfiles"
-                for f in $gtfiles
-                do
-                         all_gtfiles_files_langs="$all_gtfiles_files_langs ${s} "
-                         all_gtfiles_files_files="$all_gtfiles_files_files ${f} "
-                done
+    case $lang in
+    # The odd quoting in the next line works around
+    # an apparent bug in bash 1.12 on linux.
+changequote(,)dnl
+    ${srcdir}/[*]/config-lang.in)
+        continue ;;
+    *)
+        lang_alias=`sed -n -e 's,^language=['"'"'"'"]\(.*\)["'"'"'"'].*$,\1,p' -e 's,^language=\([^   ]*\).*$,\1,p' $lang`
+        if test "x$lang_alias" = x
+        then
+              echo "$lang doesn't set \$language." 1>&2
+              exit 1
+        fi
+        subdir="`echo $lang | sed -e 's,^.*/\([^/]*\)/config-lang.in$,\1,'`"
+        subdirs="$subdirs $subdir"
+        case ",$enable_languages," in
+        *,$lang_alias,*)
+            all_selected_languages="$all_selected_languages $lang_alias"
+	    if test -f $srcdir/$subdir/lang-specs.h; then
+	        lang_specs_files="$lang_specs_files $srcdir/$subdir/lang-specs.h"
+	    fi
+	    ;;
+        esac
+changequote([,])dnl
+
+	if test -f $srcdir/$subdir/lang.opt; then
+	    lang_opt_files="$lang_opt_files $srcdir/$subdir/lang.opt"
+	fi
+	if test -f $srcdir/$subdir/$subdir-tree.def; then
+	    lang_tree_files="$lang_tree_files $srcdir/$subdir/$subdir-tree.def"
+	fi
+
+	language=
+	boot_language=
+	compilers=
+	stagestuff=
+	outputs=
+	gtfiles=
+	. ${srcdir}/$subdir/config-lang.in
+	if test "x$language" = x
+	then
+		echo "${srcdir}/$subdir/config-lang.in doesn't set \$language." 1>&2
+		exit 1
+	fi
+	all_lang_makefrags="$all_lang_makefrags \$(srcdir)/$subdir/Make-lang.in"
+	if test -f ${srcdir}/$subdir/Makefile.in
+		then all_lang_makefiles="$subdir/Makefile"
+	fi
+	all_languages="$all_languages $language"
+	if test "x$boot_language" = xyes
+	then
+		all_boot_languages="$all_boot_languages $language"
+	fi
+	all_compilers="$all_compilers $compilers"
+	all_stagestuff="$all_stagestuff $stagestuff"
+	all_outputs="$all_outputs $outputs"
+	all_gtfiles="$all_gtfiles $gtfiles"
+        for f in $gtfiles
+        do
+                 all_gtfiles_files_langs="$all_gtfiles_files_langs ${subdir} "
+                 all_gtfiles_files_files="$all_gtfiles_files_files ${f} "
+        done
+	;;
+    esac
 done
 
 # Pick up gtfiles for c
 gtfiles=
-s="c"
+subdir="c"
 . ${srcdir}/c-config-lang.in
 all_gtfiles="$all_gtfiles $gtfiles"
 for f in $gtfiles
 do
-        all_gtfiles_files_langs="$all_gtfiles_files_langs ${s} "
+        all_gtfiles_files_langs="$all_gtfiles_files_langs ${subdir} "
         all_gtfiles_files_files="$all_gtfiles_files_files ${f} "
 done
 
 check_languages=
-for language in $all_languages
+for language in $all_selected_languages
 do
-		check_languages="$check_languages check-$language"
+	check_languages="$check_languages check-$language"
 done
 
 # We link each language in with a set of hooks, reached indirectly via
-# lang.${target}.
+# lang.${target}.  Only do so for selected languages.
 
 rm -f Make-hooks
 touch Make-hooks
@@ -3361,12 +3363,13 @@ target_list="all.cross start.encap rest.encap tags \
 	uninstall info man srcextra srcman srcinfo \
 	mostlyclean clean distclean maintainer-clean \
 	stage1 stage2 stage3 stage4 stageprofile stagefeedback"
+
 for t in $target_list
 do
 	x=
-	for lang in $all_languages
+	for lang in $all_selected_languages
 	do
-			x="$x $lang.$t"
+		x="$x $lang.$t"
 	done
 	echo "lang.$t: $x" >> Make-hooks
 done
@@ -3463,6 +3466,7 @@ AC_SUBST(all_gtfiles_files_files)
 AC_SUBST(all_lang_makefrags)
 AC_SUBST(all_lang_makefiles)
 AC_SUBST(all_languages)
+AC_SUBST(all_selected_languages)
 AC_SUBST(all_stagestuff)
 AC_SUBST(build_exeext)
 AC_SUBST(build_install_headers_dir)

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.
+