gcc/doc/makefile.texi

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