14. Additional Makefile and configure information.

14.1 Makefile Targets

all

This is the default target. Depending on what your build/host/target configuration is, it coordinates all the things that need to be built.

doc

Produce info-formatted documentation. Also, make dvi is available for DVI-formatted documentation, and make generated-manpages to generate man pages.

mostlyclean

Delete the files made while building the compiler.

clean

That, and all the other files built by make all.

distclean

That, and all the files created by configure.

extraclean

That, and any temporary or intermediate files, like emacs backup files.

maintainer-clean

Distclean plus any file that can be generated from other files. Note that additional tools may be required beyond what is normally needed to build gcc.

install

Installs gcc.

uninstall

Deletes installed files.

check

Run the testsuite. This creates a `testsuite' subdirectory that has various `.sum' and `.log' files containing the results of the testing. You can run subsets with, for example, make check-gcc. You can specify specific tests by setting RUNTESTFLAGS to be the name of the `.exp' file, optionally followed by (for some tests) an equals and a file wildcard, like:

make check-gcc RUNTESTFLAGS="execute.exp=19980413-*"

Note that running the testsuite may require additional tools be installed, such as TCL or dejagnu.

bootstrap

Builds gcc three times--once with the native compiler, once with the native-built compiler it just built, and once with the compiler it built the second time. In theory, the last two should produce the same results, which make compare can check. Each step of this process is called a "stage", and the results of each stage N (N = 1...3) are copied to a subdirectory `stageN/'.

bootstrap-lean

Like bootstrap, except that the various stages are removed once they're no longer needed. This saves disk space.

bubblestrap

Once bootstrapped, this incrementally rebuilds each of the three stages, one at a time. It does this by "bubbling" the stages up from their subdirectories, rebuilding them, and copying them back to their subdirectories. This will allow you to, for example, quickly rebuild a bootstrapped compiler after changing the sources, without having to do a full bootstrap.

quickstrap

Rebuilds the most recently built stage. Since each stage requires special invocation, using this target means you don't have to keep track of which stage you're on or what invocation that stage needs.

cleanstrap

Removed everything (make clean) and rebuilds (make bootstrap).

stageN (N = 1...4)

For each stage, moves the appropriate files to the `stageN' subdirectory.

unstageN (N = 1...4)

Undoes the corresponding stageN.

restageN (N = 1...4)

Undoes the corresponding stageN and rebuilds it with the appropriate flags.

compare

Compares the results of stages 2 and 3. This ensures that the compiler is running properly, since it should produce the same object files regardless of how it itself was compiled.

14.2 Configure Terms and History

This section is not instructions for building GCC. If you are trying to do a build, you should first read http://gcc.gnu.org/install/ or whatever installation instructions came with your source package.

The configure and build process has a long and colorful history, and can be confusing to anyone who doesn't know why things are the way they are. While there are other documents which describe the configuration process in detail, here are a few things that everyone working on GCC should know.

There are three system names that the build knows about: the machine you are building on (build), the machine that you are building for (host), and the machine that GCC will produce code for (target). When you configure GCC, you specify these with `--build=', `--host=', and `--target='.

Specifying the host without specifying the build should be avoided, as configure may (and once did) assume that the host you specify is also the build, which may not be true.

If build, host, and target are all the same, this is called a native. If build and host are the same but target is different, this is called a cross. If build, host, and target are all different this is called a canadian (for obscure reasons dealing with Canada's political party and the background of the person working on the build at that time). If host and target are the same, but build is different, you are using a cross-compiler to build a native for a different system. Some people call this a host-x-host, crossed native, or cross-built native. If build and target are the same, but host is different, you are using a cross compiler to build a cross compiler that produces code for the machine you're building on. This is rare, so there is no common say of describing it (although I propose calling it a crossback).

If build and host are the same, the GCC you are building will also be used to build the target libraries (like libstdc++). If build and host are different, you must have already build and installed a cross compiler that will be used to build the target libraries (if you configured with `--target=foo-bar', this compiler will be called foo-bar-gcc).

In the case of target libraries, the machine you're building for is the machine you specified with `--target'. So, build is the machine you're building on (no change there), host is the machine you're building for (the target libraries are built for the target, so host is the target you specified), and target doesn't apply (because you're not building a compiler, you're building libraries). The configure/make process will adjust these variables as needed. It also sets $with_cross_host to the original `--host' value in case you need it.

Libiberty, for example, is built twice. The first time, host comes from `--host' and the second time host comes from `--target'. Historically, libiberty has not been built for the build machine, though, which causes some interesting issues with programs used to generate sources for the build. Fixing this, so that libiberty is built three times, has long been on the to-do list.