gcc/doc/makefile.texi

   1 @c Copyright (C) 2001, 2002, 2003, 2004, 2006, 2008, 2010
   2 @c Free Software Foundation, Inc.
   3 @c This is part of the GCC manual.
   4 @c For copying conditions, see the file gcc.texi.
   5
   6 @node Makefile
   7 @subsection Makefile Targets
   8 @cindex makefile targets
   9 @cindex targets, makefile
  10
  11 These targets are available from the @samp{gcc} directory:
  12
  13 @table @code
  14 @item all
  15 This is the default target.  Depending on what your build/host/target
  16 configuration is, it coordinates all the things that need to be built.
  17
  18 @item doc
  19 Produce info-formatted documentation and man pages.  Essentially it
  20 calls @samp{make man} and @samp{make info}.
  21
  22 @item dvi
  23 Produce DVI-formatted documentation.
  24
  25 @item pdf
  26 Produce PDF-formatted documentation.
  27
  28 @item html
  29 Produce HTML-formatted documentation.
  30
  31 @item man
  32 Generate man pages.
  33
  34 @item info
  35 Generate info-formatted pages.
  36
  37 @item mostlyclean
  38 Delete the files made while building the compiler.
  39
  40 @item clean
  41 That, and all the other files built by @samp{make all}.
  42
  43 @item distclean
  44 That, and all the files created by @command{configure}.
  45
  46 @item maintainer-clean
  47 Distclean plus any file that can be generated from other files.  Note
  48 that additional tools may be required beyond what is normally needed to
  49 build GCC.
  50
  51 @item srcextra
  52 Generates files in the source directory that are not version-controlled but
  53 should go into a release tarball.
  54
  55 @item srcinfo
  56 @itemx srcman
  57 Copies the info-formatted and manpage documentation into the source
  58 directory usually for the purpose of generating a release tarball.
  59
  60 @item install
  61 Installs GCC.
  62
  63 @item uninstall
  64 Deletes installed files, though this is not supported.
  65
  66 @item check
  67 Run the testsuite.  This creates a @file{testsuite} subdirectory that
  68 has various @file{.sum} and @file{.log} files containing the results of
  69 the testing.  You can run subsets with, for example, @samp{make check-gcc}.
  70 You can specify specific tests by setting @env{RUNTESTFLAGS} to be the name
  71 of the @file{.exp} file, optionally followed by (for some tests) an equals
  72 and a file wildcard, like:
  73
  74 @smallexample
  75 make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"
  76 @end smallexample
  77
  78 Note that running the testsuite may require additional tools be
  79 installed, such as Tcl or DejaGnu.
  80 @end table
  81
  82 The toplevel tree from which you start GCC compilation is not
  83 the GCC directory, but rather a complex Makefile that coordinates
  84 the various steps of the build, including bootstrapping the compiler
  85 and using the new compiler to build target libraries.
  86
  87 When GCC is configured for a native configuration, the default action
  88 for @command{make} is to do a full three-stage bootstrap.  This means
  89 that GCC is built three times---once with the native compiler, once with
  90 the native-built compiler it just built, and once with the compiler it
  91 built the second time.  In theory, the last two should produce the same
  92 results, which @samp{make compare} can check.  Each stage is configured
  93 separately and compiled into a separate directory, to minimize problems
  94 due to ABI incompatibilities between the native compiler and GCC.
  95
  96 If you do a change, rebuilding will also start from the first stage
  97 and ``bubble'' up the change through the three stages.  Each stage
  98 is taken from its build directory (if it had been built previously),
  99 rebuilt, and copied to its subdirectory.  This will allow you to, for
 100 example, continue a bootstrap after fixing a bug which causes the
 101 stage2 build to crash.  It does not provide as good coverage of the
 102 compiler as bootstrapping from scratch, but it ensures that the new
 103 code is syntactically correct (e.g., that you did not use GCC extensions
 104 by mistake), and avoids spurious bootstrap comparison
 105 failures@footnote{Except if the compiler was buggy and miscompiled
 106 some of the files that were not modified.  In this case, it's best
 107 to use @command{make restrap}.}.
 108
 109 Other targets available from the top level include:
 110
 111 @table @code
 112 @item bootstrap-lean
 113 Like @code{bootstrap}, except that the various stages are removed once
 114 they're no longer needed.  This saves disk space.
 115
 116 @item bootstrap2
 117 @itemx bootstrap2-lean
 118 Performs only the first two stages of bootstrap.  Unlike a three-stage
 119 bootstrap, this does not perform a comparison to test that the compiler
 120 is running properly.  Note that the disk space required by a ``lean''
 121 bootstrap is approximately independent of the number of stages.
 122
 123 @item stage@var{N}-bubble (@var{N} = 1@dots{}4, profile, feedback)
 124 Rebuild all the stages up to @var{N}, with the appropriate flags,
 125 ``bubbling'' the changes as described above.
 126
 127 @item all-stage@var{N} (@var{N} = 1@dots{}4, profile, feedback)
 128 Assuming that stage @var{N} has already been built, rebuild it with the
 129 appropriate flags.  This is rarely needed.
 130
 131 @item cleanstrap
 132 Remove everything (@samp{make clean}) and rebuilds (@samp{make bootstrap}).
 133
 134 @item compare
 135 Compares the results of stages 2 and 3.  This ensures that the compiler
 136 is running properly, since it should produce the same object files
 137 regardless of how it itself was compiled.
 138
 139 @item profiledbootstrap
 140 Builds a compiler with profiling feedback information.  In this case,
 141 the second and third stages are named @samp{profile} and @samp{feedback},
 142 respectively.  For more information, see
 143 @ref{Building,,Building with profile feedback,gccinstall,Installing GCC}.
 144
 145 @item restrap
 146 Restart a bootstrap, so that everything that was not built with
 147 the system compiler is rebuilt.
 148
 149 @item stage@var{N}-start (@var{N} = 1@dots{}4, profile, feedback)
 150 For each package that is bootstrapped, rename directories so that,
 151 for example, @file{gcc} points to the stage@var{N} GCC, compiled
 152 with the stage@var{N-1} GCC@footnote{Customarily, the system compiler
 153 is also termed the @file{stage0} GCC.}.
 154
 155 You will invoke this target if you need to test or debug the
 156 stage@var{N} GCC@.  If you only need to execute GCC (but you need
 157 not run @samp{make} either to rebuild it or to run test suites),
 158 you should be able to work directly in the @file{stage@var{N}-gcc}
 159 directory.  This makes it easier to debug multiple stages in
 160 parallel.
 161
 162 @item stage
 163 For each package that is bootstrapped, relocate its build directory
 164 to indicate its stage.  For example, if the @file{gcc} directory
 165 points to the stage2 GCC, after invoking this target it will be
 166 renamed to @file{stage2-gcc}.
 167
 168 @end table
 169
 170 If you wish to use non-default GCC flags when compiling the stage2 and
 171 stage3 compilers, set @code{BOOT_CFLAGS} on the command line when doing
 172 @samp{make}.
 173
 174 Usually, the first stage only builds the languages that the compiler
 175 is written in: typically, C and maybe Ada.  If you are debugging a
 176 miscompilation of a different stage2 front-end (for example, of the
 177 Fortran front-end), you may want to have front-ends for other languages
 178 in the first stage as well.  To do so, set @code{STAGE1_LANGUAGES}
 179 on the command line when doing @samp{make}.
 180
 181 For example, in the aforementioned scenario of debugging a Fortran
 182 front-end miscompilation caused by the stage1 compiler, you may need a
 183 command like
 184
 185 @example
 186 make stage2-bubble STAGE1_LANGUAGES=c,fortran
 187 @end example
 188
 189 Alternatively, you can use per-language targets to build and test
 190 languages that are not enabled by default in stage1.  For example,
 191 @command{make f951} will build a Fortran compiler even in the stage1
 192 build directory.
 193