gccinstall: Building
1
1 5 Building
1 **********
1
1 Now that GCC is configured, you are ready to build the compiler and
1 runtime libraries.
1
1 Some commands executed when making the compiler may fail (return a
1 nonzero status) and be ignored by 'make'. These failures, which are
1 often due to files that were not found, are expected, and can safely be
1 ignored.
1
1 It is normal to have compiler warnings when compiling certain files.
1 Unless you are a GCC developer, you can generally ignore these warnings
1 unless they cause compilation to fail. Developers should attempt to fix
1 any warnings encountered, however they can temporarily continue past
1 warnings-as-errors by specifying the configure flag '--disable-werror'.
1
1 On certain old systems, defining certain environment variables such
1 as 'CC' can interfere with the functioning of 'make'.
1
1 If you encounter seemingly strange errors when trying to build the
1 compiler in a directory other than the source directory, it could be
1 because you have previously configured the compiler in the source
1 directory. Make sure you have done all the necessary preparations.
1
1 If you build GCC on a BSD system using a directory stored in an old
1 System V file system, problems may occur in running 'fixincludes' if the
1 System V file system doesn't support symbolic links. These problems
1 result in a failure to fix the declaration of 'size_t' in 'sys/types.h'.
1 If you find that 'size_t' is a signed type and that type mismatches
1 occur, this could be the cause.
1
1 The solution is not to use such a directory for building GCC.
1
1 Similarly, when building from the source repository or snapshots, or
1 if you modify '*.l' files, you need the Flex lexical analyzer generator
1 installed. If you do not modify '*.l' files, releases contain the
1 Flex-generated files and you do not need Flex installed to build them.
1 There is still one Flex-based lexical analyzer (part of the build
1 machinery, not of GCC itself) that is used even if you only build the C
1 front end.
1
1 When building from the source repository or snapshots, or if you
1 modify Texinfo documentation, you need version 4.7 or later of Texinfo
1 installed if you want Info documentation to be regenerated. Releases
1 contain Info documentation pre-built for the unmodified documentation in
1 the release.
1
1 5.1 Building a native compiler
1 ==============================
1
1 For a native build, the default configuration is to perform a 3-stage
1 bootstrap of the compiler when 'make' is invoked. This will build the
1 entire GCC system and ensure that it compiles itself correctly. It can
1 be disabled with the '--disable-bootstrap' parameter to 'configure', but
1 bootstrapping is suggested because the compiler will be tested more
1 completely and could also have better performance.
1
1 The bootstrapping process will complete the following steps:
1
1 * Build tools necessary to build the compiler.
1
1 * Perform a 3-stage bootstrap of the compiler. This includes
1 building three times the target tools for use by the compiler such
1 as binutils (bfd, binutils, gas, gprof, ld, and opcodes) if they
1 have been individually linked or moved into the top level GCC
1 source tree before configuring.
1
1 * Perform a comparison test of the stage2 and stage3 compilers.
1
1 * Build runtime libraries using the stage3 compiler from the previous
1 step.
1
1 If you are short on disk space you might consider 'make
1 bootstrap-lean' instead. The sequence of compilation is the same
1 described above, but object files from the stage1 and stage2 of the
1 3-stage bootstrap of the compiler are deleted as soon as they are no
1 longer needed.
1
1 If you wish to use non-default GCC flags when compiling the stage2
1 and stage3 compilers, set 'BOOT_CFLAGS' on the command line when doing
1 'make'. For example, if you want to save additional space during the
1 bootstrap and in the final installation as well, you can build the
1 compiler binaries without debugging information as in the following
1 example. This will save roughly 40% of disk space both for the
1 bootstrap and the final installation. (Libraries will still contain
1 debugging information.)
1
1 make BOOT_CFLAGS='-O' bootstrap
1
1 You can place non-default optimization flags into 'BOOT_CFLAGS'; they
1 are less well tested here than the default of '-g -O2', but should still
1 work. In a few cases, you may find that you need to specify special
1 flags such as '-msoft-float' here to complete the bootstrap; or, if the
1 native compiler miscompiles the stage1 compiler, you may need to work
1 around this, by choosing 'BOOT_CFLAGS' to avoid the parts of the stage1
1 compiler that were miscompiled, or by using 'make bootstrap4' to
1 increase the number of stages of bootstrap.
1
1 'BOOT_CFLAGS' does not apply to bootstrapped target libraries. Since
1 these are always compiled with the compiler currently being
1 bootstrapped, you can use 'CFLAGS_FOR_TARGET' to modify their
1 compilation flags, as for non-bootstrapped target libraries. Again, if
1 the native compiler miscompiles the stage1 compiler, you may need to
1 work around this by avoiding non-working parts of the stage1 compiler.
1 Use 'STAGE1_TFLAGS' to this end.
1
1 If you used the flag '--enable-languages=...' to restrict the
1 compilers to be built, only those you've actually enabled will be built.
1 This will of course only build those runtime libraries, for which the
1 particular compiler has been built. Please note, that re-defining
1 'LANGUAGES' when calling 'make' *does not* work anymore!
1
1 If the comparison of stage2 and stage3 fails, this normally indicates
1 that the stage2 compiler has compiled GCC incorrectly, and is therefore
1 a potentially serious bug which you should investigate and report. (On
1 a few systems, meaningful comparison of object files is impossible; they
1 always appear "different". If you encounter this problem, you will need
1 to disable comparison in the 'Makefile'.)
1
1 If you do not want to bootstrap your compiler, you can configure with
1 '--disable-bootstrap'. In particular cases, you may want to bootstrap
1 your compiler even if the target system is not the same as the one you
1 are building on: for example, you could build a
1 'powerpc-unknown-linux-gnu' toolchain on a 'powerpc64-unknown-linux-gnu'
1 host. In this case, pass '--enable-bootstrap' to the configure script.
1
1 'BUILD_CONFIG' can be used to bring in additional customization to
1 the build. It can be set to a whitespace-separated list of names. For
1 each such 'NAME', top-level 'config/NAME.mk' will be included by the
1 top-level 'Makefile', bringing in any settings it contains. The default
1 'BUILD_CONFIG' can be set using the configure option
1 '--with-build-config=NAME...'. Some examples of supported build
1 configurations are:
1
1 'bootstrap-O1'
1 Removes any '-O'-started option from 'BOOT_CFLAGS', and adds '-O1'
1 to it. 'BUILD_CONFIG=bootstrap-O1' is equivalent to
1 'BOOT_CFLAGS='-g -O1''.
1
1 'bootstrap-O3'
1 Analogous to 'bootstrap-O1'.
1
1 'bootstrap-lto'
1 Enables Link-Time Optimization for host tools during bootstrapping.
1 'BUILD_CONFIG=bootstrap-lto' is equivalent to adding '-flto' to
1 'BOOT_CFLAGS'. This option assumes that the host supports the
1 linker plugin (e.g. GNU ld version 2.21 or later or GNU gold
1 version 2.21 or later).
1
1 'bootstrap-lto-noplugin'
1 This option is similar to 'bootstrap-lto', but is intended for
1 hosts that do not support the linker plugin. Without the linker
1 plugin static libraries are not compiled with link-time
1 optimizations. Since the GCC middle end and back end are in
1 'libbackend.a' this means that only the front end is actually LTO
1 optimized.
1
1 'bootstrap-debug'
1 Verifies that the compiler generates the same executable code,
1 whether or not it is asked to emit debug information. To this end,
1 this option builds stage2 host programs without debug information,
1 and uses 'contrib/compare-debug' to compare them with the stripped
1 stage3 object files. If 'BOOT_CFLAGS' is overridden so as to not
1 enable debug information, stage2 will have it, and stage3 won't.
1 This option is enabled by default when GCC bootstrapping is
1 enabled, if 'strip' can turn object files compiled with and without
1 debug info into identical object files. In addition to better test
1 coverage, this option makes default bootstraps faster and leaner.
1
1 'bootstrap-debug-big'
1 Rather than comparing stripped object files, as in
1 'bootstrap-debug', this option saves internal compiler dumps during
1 stage2 and stage3 and compares them as well, which helps catch
1 additional potential problems, but at a great cost in terms of disk
1 space. It can be specified in addition to 'bootstrap-debug'.
1
1 'bootstrap-debug-lean'
1 This option saves disk space compared with 'bootstrap-debug-big',
1 but at the expense of some recompilation. Instead of saving the
1 dumps of stage2 and stage3 until the final compare, it uses
1 '-fcompare-debug' to generate, compare and remove the dumps during
1 stage3, repeating the compilation that already took place in
1 stage2, whose dumps were not saved.
1
1 'bootstrap-debug-lib'
1 This option tests executable code invariance over debug information
1 generation on target libraries, just like 'bootstrap-debug-lean'
1 tests it on host programs. It builds stage3 libraries with
1 '-fcompare-debug', and it can be used along with any of the
1 'bootstrap-debug' options above.
1
1 There aren't '-lean' or '-big' counterparts to this option because
1 most libraries are only build in stage3, so bootstrap compares
1 would not get significant coverage. Moreover, the few libraries
1 built in stage2 are used in stage3 host programs, so we wouldn't
1 want to compile stage2 libraries with different options for
1 comparison purposes.
1
1 'bootstrap-debug-ckovw'
1 Arranges for error messages to be issued if the compiler built on
1 any stage is run without the option '-fcompare-debug'. This is
1 useful to verify the full '-fcompare-debug' testing coverage. It
1 must be used along with 'bootstrap-debug-lean' and
1 'bootstrap-debug-lib'.
1
1 'bootstrap-cet'
1 This option enables Intel CET for host tools during bootstrapping.
1 'BUILD_CONFIG=bootstrap-cet' is equivalent to adding
1 '-fcf-protection' to 'BOOT_CFLAGS'. This option assumes that the
1 host supports Intel CET (e.g. GNU assembler version 2.30 or
1 later).
1
1 'bootstrap-time'
1 Arranges for the run time of each program started by the GCC
1 driver, built in any stage, to be logged to 'time.log', in the top
1 level of the build tree.
1
1 5.2 Building a cross compiler
1 =============================
1
1 When building a cross compiler, it is not generally possible to do a
1 3-stage bootstrap of the compiler. This makes for an interesting
1 problem as parts of GCC can only be built with GCC.
1
1 To build a cross compiler, we recommend first building and installing
1 a native compiler. You can then use the native GCC compiler to build
1 the cross compiler. The installed native compiler needs to be GCC
1 version 2.95 or later.
1
1 Assuming you have already installed a native copy of GCC and
1 configured your cross compiler, issue the command 'make', which performs
1 the following steps:
1
1 * Build host tools necessary to build the compiler.
1
1 * Build target tools for use by the compiler such as binutils (bfd,
1 binutils, gas, gprof, ld, and opcodes) if they have been
1 individually linked or moved into the top level GCC source tree
1 before configuring.
1
1 * Build the compiler (single stage only).
1
1 * Build runtime libraries using the compiler from the previous step.
1
1 Note that if an error occurs in any step the make process will exit.
1
1 If you are not building GNU binutils in the same source tree as GCC,
1 you will need a cross-assembler and cross-linker installed before
1 configuring GCC. Put them in the directory 'PREFIX/TARGET/bin'. Here
1 is a table of the tools you should put in this directory:
1
1 'as'
1 This should be the cross-assembler.
1
1 'ld'
1 This should be the cross-linker.
1
1 'ar'
1 This should be the cross-archiver: a program which can manipulate
1 archive files (linker libraries) in the target machine's format.
1
1 'ranlib'
1 This should be a program to construct a symbol table in an archive
1 file.
1
1 The installation of GCC will find these programs in that directory,
1 and copy or link them to the proper place to for the cross-compiler to
1 find them when run later.
1
1 The easiest way to provide these files is to build the Binutils
1 package. Configure it with the same '--host' and '--target' options
1 that you use for configuring GCC, then build and install them. They
1 install their executables automatically into the proper directory.
1 Alas, they do not support all the targets that GCC supports.
1
1 If you are not building a C library in the same source tree as GCC,
1 you should also provide the target libraries and headers before
1 configuring GCC, specifying the directories with '--with-sysroot' or
1 '--with-headers' and '--with-libs'. Many targets also require "start
1 files" such as 'crt0.o' and 'crtn.o' which are linked into each
1 executable. There may be several alternatives for 'crt0.o', for use
1 with profiling or other compilation options. Check your target's
1 definition of 'STARTFILE_SPEC' to find out what start files it uses.
1
1 5.3 Building in parallel
1 ========================
1
1 GNU Make 3.80 and above, which is necessary to build GCC, support
1 building in parallel. To activate this, you can use 'make -j 2' instead
1 of 'make'. You can also specify a bigger number, and in most cases
1 using a value greater than the number of processors in your machine will
1 result in fewer and shorter I/O latency hits, thus improving overall
1 throughput; this is especially true for slow drives and network
1 filesystems.
1
1 5.4 Building the Ada compiler
1 =============================
1
1 In order to build GNAT, the Ada compiler, you need a working GNAT
1 compiler (GCC version 4.0 or later). This includes GNAT tools such as
1 'gnatmake' and 'gnatlink', since the Ada front end is written in Ada and
1 uses some GNAT-specific extensions.
1
1 In order to build a cross compiler, it is suggested to install the
1 new compiler as native first, and then use it to build the cross
1 compiler.
1
1 'configure' does not test whether the GNAT installation works and has
1 a sufficiently recent version; if too old a GNAT version is installed,
1 the build will fail unless '--enable-languages' is used to disable
1 building the Ada front end.
1
1 'ADA_INCLUDE_PATH' and 'ADA_OBJECT_PATH' environment variables must
1 not be set when building the Ada compiler, the Ada tools, or the Ada
1 runtime libraries. You can check that your build environment is clean
1 by verifying that 'gnatls -v' lists only one explicit path in each
1 section.
1
1 5.5 Building with profile feedback
1 ==================================
1
1 It is possible to use profile feedback to optimize the compiler itself.
1 This should result in a faster compiler binary. Experiments done on x86
1 using gcc 3.3 showed approximately 7 percent speedup on compiling C
1 programs. To bootstrap the compiler with profile feedback, use 'make
1 profiledbootstrap'.
1
1 When 'make profiledbootstrap' is run, it will first build a 'stage1'
1 compiler. This compiler is used to build a 'stageprofile' compiler
1 instrumented to collect execution counts of instruction and branch
1 probabilities. Training run is done by building 'stagetrain' compiler.
1 Finally a 'stagefeedback' compiler is built using the information
1 collected.
1
1 Unlike standard bootstrap, several additional restrictions apply.
1 The compiler used to build 'stage1' needs to support a 64-bit integral
1 type. It is recommended to only use GCC for this.
1
1 On Linux/x86_64 hosts with some restrictions (no virtualization) it
1 is also possible to do autofdo build with 'make autoprofiledback'. This
1 uses Linux perf to sample branches in the binary and then rebuild it
1 with feedback derived from the profile. Linux perf and the 'autofdo'
1 toolkit needs to be installed for this.
1
1 Only the profile from the current build is used, so when an error
1 occurs it is recommended to clean before restarting. Otherwise the code
1 quality may be much worse.
1