gcc/doc/install/building/building-a-native-compiler.rst

   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
 191   systems that are running Linux kernel version 5.4 or later.