Regenerating GCC Configuration

This page is not about how to configure GCC when building it: build-time configuration is documented here (how to configure) and here (configure terms) and here (host config).

This page describes incompletely the configuration machinery and give some tips to the developer (the hacker who is adding code and features into GCC); in particular, this page explains how to (and when) re-generate the configure1 scripts from their master source. I BasileStarynkevitch am also seeking advice and welcome changes!

The configure shell scripts inside the source tree are usually generated 2. The source tree contains both the generated configure scripts and the generating input. The configure scripts should be run in the build directory (which should not be the source directory) to set up various things in the build directory, in particular Makefile (in the build tree) generated from Makefile.in (in the source tree), and config.h header to be included (in the build tree) generated from config.in (template in the source tree).

Overview of the configuration process

tools overview

The configure shell scripts (and config.in header templates) in the source tree are generated from configure.ac files by autoconf (and related, eg autoheader) packages. Autoconf is an extensible package of M4 macros that produce shell scripts to automatically configure software source code packages. Automake (with aclocal) is a tool (written in Perl) for automatically generating Makefiles. See also the autobook (from which some sentences are borrowed here) and this (newer) or this (older) tutorial. Libtool is a command line interface to the compiler and linker that makes it easy to portably generate static and shared libraries. The configure script generated by autoconf would transform the Makefile.in file into a Makefile used by the make program. The Makefile.in file is sometimes big, and can be generated by automake from a Makefile.am file. Some Makefile.in files (used to generate Makefile in the build tree) are generated by autogen from Makefile.tpl and Makefile.def files. Autogen is a (GUILE scriptable) tool designed to simplify the creation and maintenance of programs that contain large amounts of repetitious text.

In the source tree (either distributed source tarballs or source gotten from SVN) there are several configure files which have been generated (and of course, their generating file, usually configure.ac is also given). These generated configure files are given for convenience; a GCC hacker is expected to patch or edit the source configure.ac file and re-generate the configure file inside the source (not the build) directory.

The version of the generating tools are important. The toplevel configure file was recently still generated by autoconf 2.13 and switched to 2.59 in february 2007 while the others are generated by autoconf 2.59 (a move to 2.61 is planned).

Remember that autoconf, while m4 based, use its own characters (left [ and right ] brackets) for quoting.

There are two level of configurations, the topmost $GCCTOP/configure and the one in $GCCTOP/gcc/configure. Some configure arguments are passed from the topmost to the lower, but the topmost --help don't mention them. See this ''gcc@'' thread and this ''autoconf@'' one.

configuration details

In this section $GCCTOP is the GCC source directory path (that you've got by svn or from source tarballs) and $BUILDIR is the build directory (where the build happens, containg generated files). A plain GCC user who is building the (native) compiler usually just do

mkdir $BUILDIR
cd $BUILDIR
$GCCTOP/configure
make bootstrap
make install

I advise to have the $BUILDIR outside of $GCCTOP. But you are not a plain GCC user, but a hacker, and you want to contribute to GCC and have to understand the building process.

The toplevel $GCCTOP/configure is generated from $GCCTOP/configure.ac by autoconf 2.59 (or from $GCCTOP/configure.in by autoconf 2.13 for older versions of GCC) . Multilib support also uses $GCCTOP/config-ml.in but you rarely need to edit $GCCTOP/config-ml.in

The toplevel $GCCTOP/Makefile.in 3 is generated from $GCCTOP/Makefile.def and $GCCTOP/Makefile.tpl by autogen. You might want to edit $GCCTOP/Makefile.def or $GCCTOP/Makefile.tpl, and you should never edit $GCCTOP/Makefile.in because it is generated. However, since the user is only expected to run the $GCCTOP/configure script (with additional arguments), the $GCCTOP/gcc/configure script is run at build time; these two scripts share data thru variables defined in $GCCTOP/Makefile.tpl (which you want to edit to share variables between both).

Most of the GCC stuff happens inside $GCCTOP/gcc/; this is where you hack front-ends (new languages), back-ends (new targets), middle-ends (new optimizations). For example, to add a new middle-end source file you'll need to edit $GCCTOP/gcc/Makefile.in.

The $GCCTOP/gcc/configure script is generated from $GCCTOP/gcc/configure.ac by autoconf 2.59 (or better). You'll need to edit $GCCTOP/gcc/configure.ac to add new configurable features or packages. Some autoconf macros are defined in $GCCTOP/gcc/acinclude.m4, like gcc_AC_FUNC_MMAP_BLACKLIST; an additional issue is that the $GCCTOP/gcc/configure does not recieve explicit arguments from the user, because only the topmost $GCCTOP/configure is run (with possible arguments) by the user, but it triggers the runs (at make time) of the lower scripts like $GCCTOP/gcc/configure (which don't get arguments from the user, but only from the top script).

Front-end specific make fragments are in files like $GCCTOP/gcc/cp/Make-lang.in (for C++) or $GCCTOP/gcc/objc/Make-lang.in(for Objective C), etc...

tips (to GCC hackers)

adding a feature

To add a configurable feature (e.g. FOO, which can be enabled or disabled at configure time by some appropriate --enable-FOO or --disable-FOO option) edit the $GCCTOP/gcc/configure.ac in the source directory. Usually you do not need to edit neither the topmost $GCCTOP/configure.in nor the topmost $GCCTOP/Makefile.tpl`. To add a configurable feature, use the AC_ARG_ENABLE macro of autoconf; this macro takes a feature name, a help string, and optional enabling/disabling and default shell code. For example the libssp feature 4 is handled in the topmost configure.in with

AC_ARG_ENABLE(libssp,
[  --enable-libssp        Builds libssp directory],
ENABLE_LIBSSP=$enableval,
ENABLE_LIBSSP=yes)

Of course, some further code is required to test and implement this feature.

using an external package

To add a configurable package (e.g. BAR, which can be enabled or disabled at configure time by some appropriate --with-BAR or --without-BAR option) edit the topmost configure.in in the source directory, and use the AC_ARG_WITH macro of autoconf; this macro takes a package name, a help string, and optional enabling/disabling and default shell code. For instance the gmp package 5 is handled in the topmost configure.in with

AC_ARG_WITH(gmp-dir, [  --with-gmp-dir=PATH     Specify source directory for GMP library])

Again, some more code is required.

checking for particular functions

The autoconf machinery is able to check for many particular functions using AC_FUNC_* macros in */configure.ac files. For instance AC_FUNC_FORK checks for a working fork system call, and if it is available, a HAVE_WORKING_FORK is defined in a file libiberty/config.h generated in the build directory. Also other functions can be checked with AC_CHECK_FUNC and AC_CHECK_FUNCS and other similar macros.

system includes

System include (e.g. <stdio.h> or <sys/mman.h> files) for the compiler are not supposed to be directly included in the source tree. The generated gcc/auto-host.h file (generated in the build directory by configure, and indirectly by autoconf and autoheader from configure.ac) contains stuff like

/* Define to 1 if you have the `alphasort' function. */
#ifndef USED_FOR_TARGET
#define HAVE_ALPHASORT 1
#endif

and the gcc/system.h file of the source directory contains stuff like

#ifdef HAVE_UNISTD_H
# include <unistd.h>
#endif

which include the real system header. Of course the source code (e.g. gcc/*.c files) can also use similar preprocessor conditionals.

hints

Run the top GCC configure script with --disable-multilib --disable-bootstrap --enable-checks --enable-maintainer-mode flags (and also --enable-languages=c if you are only working on C related stuff (eg C frontend or common middle-end or some backend). The -enable-maintainer-mode helps in having the configure files regenerated when needed

Read carefully the start comments in every configure.ac file you depend upon, because it describes the required version of autoconf and the set of commands to generate the configure file.

To regenerate all the generated files in the source tree $GCCTOP try

cd $GCCTOP
autogen Makefile.def
autoconf-2.59

Notice that the trunk (future 4.3) version of gcc has changed to autoconf-2.59 since svn revision 121758 (february 2007). Before that, it was autoconf-2.13 for the top. See this thread.

After that, if some configuration changed inside $GCCTOP/gcc, try

cd $GCCTOP/gcc
autoheader-2.59
autoconf-2.59

The two autoconf above might be autoreconf, but don't mess the versions. If you got an error message (perhaps because you messed something), try a second time the appropriate autoconf or autoheader. You can remove the various autom4te.cache directories. There should be no warnings or errors.

Regenerating All ''configure'' Files

The following can be used for regenerating all configure files:

$ find ./ -name configure.ac | while read f; do (cd "$(dirname "$f")"/ && autoconf2.64); done

As always, watch for any errors appearing, and inspect the regenerated files' differences.

example: adding a new (host) library

Suppose that you are hacking a front-end, middle-end or back-end to use a new external library FOO in host (inside the compiler itself) for a feature FOOBAR6; you want this addition to be configurable (at GCC build time, in the topmost $GCCTOP/configure script) with --with-FOO and --enable-FOOBAR; then, in addition to your C code patches, you'll need to

  1. Add into $GCCTOP/gcc/configure.ac additional AC_ARG_VAR-s for FOOLIBS (the libFOO) and FOOINC (its include path). You want the HAVE_FOO preprocessor flag to be appropriately handled (in particular in generated $GCCBUILD/gcc/auto-host.h included by $GCCBUILD/gcc/config.h) so inside $GCCTOP/gcc/configure.ac you add

    AC_ARG_VAR(FOOLIBS,[How to link FOO])
    AC_ARG_VAR(FOOINC,[How to find FOO include files])
    
    if test "x${FOOLIBS}" != "x" ; then
       AC_DEFINE(HAVE_FOO, 1, [Define if FOO is in use.])
    fi

    You also could use (in the same file) AC_ARG_ENABLE for --enable-FOOBAR stuff.

  2. Edit $GCCTOP/gcc/Makefile.in, first by adding

    # How to find FOO
    FOOLIBS = @FOOLIBS@
    FOOINC = @FOOINC@

    to transmit the previous variables into the make, and also add your $(FOOLIBS) to LIBS (for libraries) and your $(FOOINC) to INCLUDES in this file.

  3. In the usual case, you do not need to edit $GCCTOP/Makefile.tpl to add communication between the different levels of configuration 7, or the topmost $GCCTOP/configure.in. But you add some code into $GCCTOP/gcc/configure.ac to enable the package and check for availability of the library:

    ## default FOO stuff
    foolibs=
    fooinc=
    ## the --with-foo stuff
    AC_ARG_WITH(foo, [  --with-foo=PATH        Specify prefix directory for installed FOO library])
    
    if test "x$with_foo" != x; then
      foolibs="-L$with_foo/lib"
      fooinc="-I$with_foo/include"
    fi

    and add into $GCCTOP/gcc/configure.ac code to test the linking of such a library (assuming it is initialized by foo_init() and needs #include <foo.h>), like

    ## checking for foo linking
    saved_CFLAGS="$CFLAGS"
    CFLAGS="$CFLAGS $fooinc $foolibs"
    AC_MSG_CHECKING([for FOO])
    AC_TRY_LINK([[#include|<foo.h>]],[
    foo_init (); ], [AC_MSG_RESULT([yes])], [AC_MSG_RESULT([no]); have_foo=no])
    CFLAGS="$saved_CFLAGS"

    Notice that the shell test is done with test not [ because square brackets are for m4 quotation in autoconf, and that LIBS and INCLUDES are extended for further libraries. You need also to tell autoconf about these flags by adding into $GCCTOP/gcc/configure.ac

    # autoconf flags for FOO
    AC_SUBST(foolibs)
    AC_SUBST(fooinc)
  4. Of course, your C code contributed inside $GCCTOP/gcc/ should compile and link without the FOO feature, hence #include <foo.h> and any calls to the FOO library should be wrapped by appropriate #if HAVE_FOO preprocessor directives, and you should offer an alternative (at least runtime errors when requesting a disabled feature).

  5. Don't forget to regenerate files in the source directory!
  6. It is important to document your new configuration options (since the --help flag at toplevel don't show the possible flags in the lwoer $GCCTOP/gcc/configure

thanks

To SebastianPop and to contributors on the mailing list


  1. While the source tree contains shell scripts named configure (e.g. gcc/configure), these scripts are generated from other (master) files within the source tree (1)

  2. The details are IMHO incredibly complex. I [BasileStarynkevitch] tend to attribute most of this complexity to historical factors -some of the generation tools didn't exist before- and to portability and cross-compilability concerns. (2)

  3. $GCCTOP/Makefile.in generates $BUILDIR/Makefile at configure time (3)

  4. libssp are run-time libraries for stack smashing protection, enabled by default (4)

  5. GMP is an arbitrary precision arithmetic library (5)

  6. For example, you might add the Posix real-time library RT (-lrt on modern GNU/Linux) for the feature PRECISETIMING to add millisecond timings into the compiler, using calls to [http://www.opengroup.org/pubs/online/7908799/xsh/clock_getres.html clock_gettime] from <time.h>, or add the [http://www.cs.unipr.it/ppl/ Parma Polyhedra Library] for middle-end optimisations. (6)

  7. The files $GCCTOP/configure and $GCCTOP/gcc/configure are generated and they communicate thru environment variables defined in $GCCTOP/Makefile.tpl (7)

None: Regenerating_GCC_Configuration (last edited 2011-07-14 08:40:52 by ManuelLópezIbáñez)