]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | Building a native compiler | |
7 | ************************** | |
8 | ||
9 | For a native build, the default configuration is to perform | |
10 | a 3-stage bootstrap of the compiler when :samp:`make` is invoked. | |
11 | This will build the entire GCC system and ensure that it compiles | |
12 | itself correctly. It can be disabled with the :option:`--disable-bootstrap` | |
13 | parameter to :samp:`configure`, but bootstrapping is suggested because | |
14 | the compiler will be tested more completely and could also have | |
15 | better performance. | |
16 | ||
17 | The bootstrapping process will complete the following steps: | |
18 | ||
19 | * Build tools necessary to build the compiler. | |
20 | ||
21 | * Perform a 3-stage bootstrap of the compiler. This includes building | |
22 | three times the target tools for use by the compiler such as binutils | |
23 | (bfd, binutils, gas, gprof, ld, and opcodes) if they have been | |
24 | individually linked or moved into the top level GCC source tree before | |
25 | configuring. | |
26 | ||
27 | * Perform a comparison test of the stage2 and stage3 compilers. | |
28 | ||
29 | * Build runtime libraries using the stage3 compiler from the previous step. | |
30 | ||
31 | If you are short on disk space you might consider :samp:`make | |
32 | bootstrap-lean` instead. The sequence of compilation is the | |
33 | same described above, but object files from the stage1 and | |
34 | stage2 of the 3-stage bootstrap of the compiler are deleted as | |
35 | soon as they are no longer needed. | |
36 | ||
37 | If you wish to use non-default GCC flags when compiling the stage2 | |
38 | and stage3 compilers, set ``BOOT_CFLAGS`` on the command line when | |
39 | doing :samp:`make`. For example, if you want to save additional space | |
40 | during the bootstrap and in the final installation as well, you can | |
41 | build the compiler binaries without debugging information as in the | |
42 | following example. This will save roughly 40% of disk space both for | |
43 | the bootstrap and the final installation. (Libraries will still contain | |
44 | debugging information.) | |
45 | ||
46 | .. code-block:: bash | |
47 | ||
48 | make BOOT_CFLAGS='-O' bootstrap | |
49 | ||
50 | You can place non-default optimization flags into ``BOOT_CFLAGS`` ; they | |
51 | are less well tested here than the default of :samp:`-g -O2`, but should | |
52 | still work. In a few cases, you may find that you need to specify special | |
53 | flags such as :option:`-msoft-float` here to complete the bootstrap; or, | |
54 | if the native compiler miscompiles the stage1 compiler, you may need | |
55 | to work around this, by choosing ``BOOT_CFLAGS`` to avoid the parts | |
56 | of the stage1 compiler that were miscompiled, or by using :samp:`make | |
57 | bootstrap4` to increase the number of stages of bootstrap. | |
58 | ||
59 | ``BOOT_CFLAGS`` does not apply to bootstrapped target libraries. | |
60 | Since these are always compiled with the compiler currently being | |
61 | bootstrapped, you can use ``CFLAGS_FOR_TARGET`` to modify their | |
62 | compilation flags, as for non-bootstrapped target libraries. | |
63 | Again, if the native compiler miscompiles the stage1 compiler, you may | |
64 | need to work around this by avoiding non-working parts of the stage1 | |
65 | compiler. Use ``STAGE1_TFLAGS`` to this end. | |
66 | ||
67 | If you used the flag :option:`--enable-languages=...` to restrict | |
68 | the compilers to be built, only those you've actually enabled will be | |
69 | built. This will of course only build those runtime libraries, for | |
70 | which the particular compiler has been built. Please note, | |
71 | that re-defining :envvar:`LANGUAGES` when calling :samp:`make` | |
72 | **does not** work anymore! | |
73 | ||
74 | If the comparison of stage2 and stage3 fails, this normally indicates | |
75 | that the stage2 compiler has compiled GCC incorrectly, and is therefore | |
76 | a potentially serious bug which you should investigate and report. (On | |
77 | a few systems, meaningful comparison of object files is impossible; they | |
78 | always appear 'different'. If you encounter this problem, you will | |
79 | need to disable comparison in the :samp:`Makefile`.) | |
80 | ||
81 | If you do not want to bootstrap your compiler, you can configure with | |
82 | :option:`--disable-bootstrap`. In particular cases, you may want to | |
83 | bootstrap your compiler even if the target system is not the same as | |
84 | the one you are building on: for example, you could build a | |
85 | ``powerpc-unknown-linux-gnu`` toolchain on a | |
86 | ``powerpc64-unknown-linux-gnu`` host. In this case, pass | |
87 | :option:`--enable-bootstrap` to the configure script. | |
88 | ||
89 | ``BUILD_CONFIG`` can be used to bring in additional customization | |
90 | to the build. It can be set to a whitespace-separated list of names. | |
91 | For each such ``NAME``, top-level :samp:`config/ ``NAME``.mk` will | |
92 | be included by the top-level :samp:`Makefile`, bringing in any settings | |
93 | it contains. The default ``BUILD_CONFIG`` can be set using the | |
94 | configure option :option:`--with-build-config=NAME...`. Some | |
95 | examples of supported build configurations are: | |
96 | ||
97 | bootstrap-O1 | |
98 | Removes any :option:`-O` -started option from ``BOOT_CFLAGS``, and adds | |
99 | :option:`-O1` to it. :samp:`BUILD_CONFIG=bootstrap-O1` is equivalent to | |
100 | :samp:`BOOT_CFLAGS='-g -O1'`. | |
101 | ||
102 | bootstrap-O3 bootstrap-Og | |
103 | Analogous to ``bootstrap-O1``. | |
104 | ||
105 | bootstrap-lto | |
106 | Enables Link-Time Optimization for host tools during bootstrapping. | |
107 | :samp:`BUILD_CONFIG=bootstrap-lto` is equivalent to adding | |
108 | :option:`-flto` to :samp:`BOOT_CFLAGS`. This option assumes that the host | |
109 | supports the linker plugin (e.g. GNU ld version 2.21 or later or GNU gold | |
110 | version 2.21 or later). | |
111 | ||
112 | bootstrap-lto-noplugin | |
113 | This option is similar to ``bootstrap-lto``, but is intended for | |
114 | hosts that do not support the linker plugin. Without the linker plugin | |
115 | static libraries are not compiled with link-time optimizations. Since | |
116 | the GCC middle end and back end are in :samp:`libbackend.a` this means | |
117 | that only the front end is actually LTO optimized. | |
118 | ||
119 | bootstrap-lto-lean | |
120 | This option is similar to ``bootstrap-lto``, but is intended for | |
121 | faster build by only using LTO in the final bootstrap stage. | |
122 | With :samp:`make profiledbootstrap` the LTO frontend | |
123 | is trained only on generator files. | |
124 | ||
125 | bootstrap-debug | |
126 | Verifies that the compiler generates the same executable code, whether | |
127 | or not it is asked to emit debug information. To this end, this | |
128 | option builds stage2 host programs without debug information, and uses | |
129 | :samp:`contrib/compare-debug` to compare them with the stripped stage3 | |
130 | object files. If ``BOOT_CFLAGS`` is overridden so as to not enable | |
131 | debug information, stage2 will have it, and stage3 won't. This option | |
132 | is enabled by default when GCC bootstrapping is enabled, if | |
133 | ``strip`` can turn object files compiled with and without debug | |
134 | info into identical object files. In addition to better test | |
135 | coverage, this option makes default bootstraps faster and leaner. | |
136 | ||
137 | bootstrap-debug-big | |
138 | Rather than comparing stripped object files, as in | |
139 | ``bootstrap-debug``, this option saves internal compiler dumps | |
140 | during stage2 and stage3 and compares them as well, which helps catch | |
141 | additional potential problems, but at a great cost in terms of disk | |
142 | space. It can be specified in addition to :samp:`bootstrap-debug`. | |
143 | ||
144 | bootstrap-debug-lean | |
145 | This option saves disk space compared with ``bootstrap-debug-big``, | |
146 | but at the expense of some recompilation. Instead of saving the dumps | |
147 | of stage2 and stage3 until the final compare, it uses | |
148 | :option:`-fcompare-debug` to generate, compare and remove the dumps | |
149 | during stage3, repeating the compilation that already took place in | |
150 | stage2, whose dumps were not saved. | |
151 | ||
152 | bootstrap-debug-lib | |
153 | This option tests executable code invariance over debug information | |
154 | generation on target libraries, just like ``bootstrap-debug-lean`` | |
155 | tests it on host programs. It builds stage3 libraries with | |
156 | :option:`-fcompare-debug`, and it can be used along with any of the | |
157 | ``bootstrap-debug`` options above. | |
158 | ||
159 | There aren't ``-lean`` or ``-big`` counterparts to this option | |
160 | because most libraries are only build in stage3, so bootstrap compares | |
161 | would not get significant coverage. Moreover, the few libraries built | |
162 | in stage2 are used in stage3 host programs, so we wouldn't want to | |
163 | compile stage2 libraries with different options for comparison purposes. | |
164 | ||
165 | bootstrap-debug-ckovw | |
166 | Arranges for error messages to be issued if the compiler built on any | |
167 | stage is run without the option :option:`-fcompare-debug`. This is | |
168 | useful to verify the full :option:`-fcompare-debug` testing coverage. It | |
169 | must be used along with ``bootstrap-debug-lean`` and | |
170 | ``bootstrap-debug-lib``. | |
171 | ||
172 | bootstrap-cet | |
173 | This option enables Intel CET for host tools during bootstrapping. | |
174 | :samp:`BUILD_CONFIG=bootstrap-cet` is equivalent to adding | |
175 | :option:`-fcf-protection` to :samp:`BOOT_CFLAGS`. This option | |
176 | assumes that the host supports Intel CET (e.g. GNU assembler version | |
177 | 2.30 or later). | |
178 | ||
179 | bootstrap-time | |
180 | Arranges for the run time of each program started by the GCC driver, | |
181 | built in any stage, to be logged to :samp:`time.log`, in the top level of | |
182 | the build tree. | |
183 | ||
184 | bootstrap-asan | |
185 | Compiles GCC itself using Address Sanitization in order to catch invalid memory | |
186 | accesses within the GCC code. | |
187 | ||
188 | bootstrap-hwasan | |
189 | Compiles GCC itself using HWAddress Sanitization in order to catch invalid | |
190 | memory accesses within the GCC code. This option is only available on AArch64 | |
3ed1b4ce | 191 | systems that are running Linux kernel version 5.4 or later. |