Imported gcc-4.4.3

[msp430-gcc.git] / gcc / doc / makefile.texi

diff --git a/gcc/doc/makefile.texi b/gcc/doc/makefile.texi
index 6d6b0253aa6b131fa683dc907efa855e8a052e34..4c8d9ae46d4de728b9e27af12bd1685700bedfff 100644 (file)
--- a/gcc/doc/makefile.texi
+++ b/gcc/doc/makefile.texi
@@ -1,4 +1,5 @@
-@c Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+@c Copyright (C) 2001, 2002, 2003, 2004, 2006, 2008
+@c Free Software Foundation, Inc.

 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 
 @c This is part of the GCC manual.
 @c For copying conditions, see the file gcc.texi.
 


@@ -7,33 +8,56 @@
 @cindex makefile targets
 @cindex targets, makefile
 
 @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
 configuration is, it coordinates all the things that need to be built.
 
 @item doc
 @table @code
 @item all
 This is the default target.  Depending on what your build/host/target
 configuration is, it coordinates all the things that need to be built.
 
 @item doc

-Produce info-formatted documentation.  Also, @code{make dvi} is
-available for DVI-formatted documentation, and @code{make
-generated-manpages} to generate man pages.
+Produce info-formatted documentation and man pages.  Essentially it
+calls @samp{make man} and @samp{make info}.
+
+@item dvi
+Produce DVI-formatted documentation.
+
+@item pdf
+Produce PDF-formatted documentation.
+
+@item html
+Produce HTML-formatted documentation.
+
+@item man
+Generate man pages.
+
+@item info
+Generate info-formatted pages.

 
 @item mostlyclean
 Delete the files made while building the compiler.
 
 @item clean
 
 @item mostlyclean
 Delete the files made while building the compiler.
 
 @item clean

-That, and all the other files built by @code{make all}.
+That, and all the other files built by @samp{make all}.

 
 @item distclean
 
 @item distclean

-That, and all the files created by @code{configure}.
-
-@item extraclean
-That, and any temporary or intermediate files, like emacs backup files.
+That, and all the files created by @command{configure}.

 
 @item maintainer-clean
 Distclean plus any file that can be generated from other files.  Note
 that additional tools may be required beyond what is normally needed to
 build gcc.
 
 
 @item maintainer-clean
 Distclean plus any file that can be generated from other files.  Note
 that additional tools may be required beyond what is normally needed to
 build gcc.
 

+@item srcextra
+Generates files in the source directory that do not exist in CVS but
+should go into a release tarball.  One example is @file{gcc/java/parse.c}
+which is generated from the CVS source file @file{gcc/java/parse.y}.
+
+@item srcinfo
+@itemx srcman
+Copies the info-formatted and manpage documentation into the source
+directory usually for the purpose of generating a release tarball.
+

 @item install
 Installs gcc.
 
 @item install
 Installs gcc.
 


@@ -43,7 +67,7 @@ Deletes installed files.
 @item check
 Run the testsuite.  This creates a @file{testsuite} subdirectory that
 has various @file{.sum} and @file{.log} files containing the results of
 @item check
 Run the testsuite.  This creates a @file{testsuite} subdirectory that
 has various @file{.sum} and @file{.log} files containing the results of

-the testing.  You can run subsets with, for example, @code{make check-gcc}.
+the testing.  You can run subsets with, for example, @samp{make check-gcc}.

 You can specify specific tests by setting RUNTESTFLAGS to be the name
 of the @file{.exp} file, optionally followed by (for some tests) an equals
 and a file wildcard, like:
 You can specify specific tests by setting RUNTESTFLAGS to be the name
 of the @file{.exp} file, optionally followed by (for some tests) an equals
 and a file wildcard, like:


@@ -54,49 +78,116 @@ make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
 
 Note that running the testsuite may require additional tools be
 installed, such as TCL or dejagnu.
 
 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 @code{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 bootstrap-lean
 Like @code{bootstrap}, except that the various stages are removed once
 they're no longer needed.  This saves disk space.
 

-@item bubblestrap
-Once bootstrapped, this incrementally rebuilds each of the three stages,
-one at a time.  It does this by ``bubbling'' the stages up from their
-subdirectories, rebuilding them, and copying them back to their
-subdirectories.  This will allow you to, for example, quickly rebuild a
-bootstrapped compiler after changing the sources, without having to do a
-full bootstrap.
+@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 (@code{make clean}) and rebuilds (@code{make bootstrap}).
-
-@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 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 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
 is running properly, since it should produce the same object files
 regardless of how it itself was compiled.
 
 
 @item compare
 Compares the results of stages 2 and 3.  This ensures that the compiler
 is running properly, since it should produce the same object files
 regardless of how it itself was compiled.
 

+@item profiledbootstrap
+Builds a compiler with profiling feedback information.  For more
+information, see
+@ref{Building,,Building with profile feedback,gccinstall,Installing GCC}.
+
+@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
 @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.
+