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