Differences between revisions 63 and 65 (spanning 2 versions)
Revision 63 as of 2006-11-16 21:53:55
Size: 14927
Editor: xdsl-84-44-158-175
Comment: typos; say what is 2.13 and what is 2.59 generated; plan for 2.60 move
Revision 65 as of 2006-12-14 16:50:12
Size: 15130
Deletions are marked like this. Additions are marked like this.
Line 20: Line 20:

There are two level of configuration. See [http://gcc.gnu.org/ml/gcc/2006-12/msg00360.html this thread]
Line 140: Line 142:
CFLAGS="$CFLAGS $ltdlinc $ltdllibs"
AC_MSG_CHECKING([for ltdl])
CFLAGS="$CFLAGS $fooinc $foolibs"
Line 147: Line 149:
Line 149: Line 152:
}}} Notice that the shell test is done with ''test'' not `[` because square brackets are for m4 quotation in autoconf. You need also to tell autoconf about these flags with {{{# autoconf flags for FOO }}} 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 with {{{# autoconf flags for FOO

Regenerating GCC Configuration

This page is not about how to configure GCC when building it: build-time configuration is documented [http://gcc.gnu.org/install/configure.html here (how to configure)] and [http://gcc.gnu.org/onlinedocs/gccint/Configure-Terms.html#Configure-Terms here (configure terms)] and [http://gcc.gnu.org/onlinedocs/gccint/Host-Config.html#Host-Config 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 configureFootNote(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) scripts from their master source. I BasileStarynkevitch am also seeking [http://gcc.gnu.org/ml/gcc/2006-10/msg00610.html advice] and welcome changes!

The configure shell scripts inside the source tree are usually generated FootNote(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.). 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. [http://www.gnu.org/software/autoconf/ Autoconf] is an extensible package of M4 macros that produce shell scripts to automatically configure software source code packages. [http://sources.redhat.com/automake/ Automake] (with aclocal) is a tool (written in Perl) for automatically generating Makefiles. See also the [http://sources.redhat.com/autobook/ autobook] (from which some sentences are borrowed here) and [http://www-src.lip6.fr/homepages/Alexandre.Duret-Lutz/autotools.html this (newer)] or [http://inti.sourceforge.net/tutorial/libinti/autotoolsproject.html this (older)] tutorial. [http://www.gnu.org/software/libtool/ 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 [http://www.gnu.org/software/autogen/ 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 is still generated by [ftp://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.13.tar.gz autoconf 2.13] while the others are generated by [ftp://ftp.gnu.org/pub/gnu/autoconf/autoconf-2.59.tar.gz autoconf 2.59] (a move to 2.60 is planned).

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

There are two level of configuration. See [http://gcc.gnu.org/ml/gcc/2006-12/msg00360.html this thread]

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
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.in by autoconf 2.13. Multilib support also uses $GCCTOP/config-ml.in but you rarely need to edit $GCCTOP/config-ml.in

The toplevel $GCCTOP/Makefile.in FootNote(`$GCCTOP/Makefile.in` generates `$BUILDIR/Makefile` at configure time) 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 topmost configure.in in the source directory, and use the AC_ARG_ENABLE macro of autoconf; this [http://www.gnu.org/software/autoconf/manual/html_node/Package-Options.html macro] takes a feature name, a help string, and optional enabling/disabling and default shell code. For example the libssp feature FootNote(libssp are run-time libraries for stack smashing protection, enabled by default) is handled in the topmost configure.in with

[  --enable-libssp        Builds libssp directory],

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 [http://www.gnu.org/software/autoconf/manual/html_node/External-Software.html macro] takes a package name, a help string, and optional enabling/disabling and default shell code. For instance the gmp package FootNote([http://www.swox.com/gmp/ GMP] is an arbitrary precision arithmetic library) 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_* [http://www.gnu.org/software/autoconf/manual/html_node/Particular-Functions.html 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 [http://www.gnu.org/software/autoconf/manual/html_node/Generic-Functions.html 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. */

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

# include <unistd.h>

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


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 [http://gcc.gnu.org/ml/gcc/2006-10/msg00610.html 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

autogen Makefile.def

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

cd $GCCTOP/gcc

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.

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 FOOBARFootNote(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.); 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.])

    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.

  1. Edit $GCCTOP/Makefile.tpl to add communication between the different levels of configuration FootNote(The files `$GCCTOP/configure` and `$GCCTOP/gcc/configure` are generated and they communicate thru environment variables defined in `$GCCTOP/Makefile.tpl`), by adding to HOST_EXPORTS the following

      FOOLIBS="$(HOST_FOOLIBS)"; export FOOLIBS; \
      FOOINC="$(HOST_FOOINC)"; export FOOINC; \
    and later in the file {{{# Where to find FOO

HOST_FOOLIBS = @foolibs@ HOST_FOOINC = @fooinc@}}}

  1. Add into the topmost $GCCTOP/configure.in code to enable the package and check for availability of the library:

    ## default FOO stuff
    ## 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

    and add 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])

if test x"$have_foo" = xyes; then

  • LIBS="$LIBS $foolibs" INCLUDES="$INCLUDES $fooinc"

fi 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 with {{{# autoconf flags for FOO AC_SUBST(foolibs) AC_SUBST(fooinc)}}}

  1. 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).

  2. Don't forget to regenerate files in the source directory!


To SebastianPop and to contributors on the mailing list

None: Regenerating_GCC_Configuration (last edited 2019-10-28 12:19:24 by tschwinge)