Go to the first, previous, next, last section, table of contents.



Files

As was seen in the previous chapter, the GNU configure and build system uses a number of different files. The developer must write a few files. The others are generated by various tools.

The system is rather flexible, and can be used in many different ways. In describing the files that it uses, I will describe the common case, and mention some other cases that may arise.

Developer Files

This section describes the files written or generated by the developer of a package.

Developer Files Picture

Here is a picture of the files which are written by the developer, the generated files which would be included with a complete source distribution, and the tools which create those files. The file names are in rectangles with square corners and the tool names are in rectangles with rounded corners (e.g., `autoheader' is the name of a tool, not the name of a file).

Written Developer Files

The following files would be written by the developer.

`configure.in'
This is the configuration script. This script contains invocations of autoconf macros. It may also contain ordinary shell script code. This file will contain feature tests for portability issues. The last thing in the file will normally be an `AC_OUTPUT' macro listing which files to create when the builder runs the configure script. This file is always required when using the GNU configure system. See section Write configure.in.
`Makefile.am'
This is the automake input file. It describes how the code should be built. It consists of definitions of automake variables. It may also contain ordinary Makefile targets. This file is only needed when using automake (newer tools normally use automake, but there are still older tools which have not been converted, in which the developer writes `Makefile.in' directly). See section Write Makefile.am.
`acconfig.h'
When the configure script creates a portability header file, by using `AM_CONFIG_HEADER' (or, if not using automake, `AC_CONFIG_HEADER'), this file is used to describe macros which are not recognized by the `autoheader' command. This is normally a fairly uninteresting file, consisting of a collection of `#undef' lines with comments. Normally any call to `AC_DEFINE' in `configure.in' will require a line in this file. See section Write acconfig.h.
`acinclude.m4'
This file is not always required. It defines local autoconf macros. These macros may then be used in `configure.in'. If you don't need any local autoconf macros, then you don't need this file at all. In fact, in general, you never need local autoconf macros, since you can put everything in `configure.in', but sometimes a local macro is convenient. Newer tools may omit `acinclude.m4', and instead use a subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS = -I m4' in `Makefile.am' to force `aclocal' to look there for macro definitions. The macro definitions are then placed in separate files in that directory. The `acinclude.m4' file is only used when using automake; in older tools, the developer writes `aclocal.m4' directly, if it is needed.

Generated Developer Files

The following files would be generated by the developer.

When using automake, these files are normally not generated manually after the first time. Instead, the generated `Makefile' contains rules to automatically rebuild the files as required. When `AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in Cygnus code), the automatic rebuilding rules will only be defined if you configure using the `--enable-maintainer-mode' option.

When using automatic rebuilding, it is important to ensure that all the various tools have been built and installed on your `PATH'. Using automatic rebuilding is highly recommended, so much so that I'm not going to explain what you have to do if you don't use it.

`configure'
This is the configure script which will be run when building the package. This is generated by `autoconf' from `configure.in' and `aclocal.m4'. This is a shell script.
`Makefile.in'
This is the file which the configure script will turn into the `Makefile' at build time. This file is generated by `automake' from `Makefile.am'. If you aren't using automake, you must write this file yourself. This file is pretty much a normal `Makefile', with some configure substitutions for certain variables.
`aclocal.m4'
This file is created by the `aclocal' program, based on the contents of `configure.in' and `acinclude.m4' (or, as noted in the description of `acinclude.m4' above, on the contents of an `m4' subdirectory). This file contains definitions of autoconf macros which `autoconf' will use when generating the file `configure'. These autoconf macros may be defined by you in `acinclude.m4' or they may be defined by other packages such as automake, libtool or gettext. If you aren't using automake, you will normally write this file yourself; in that case, if `configure.in' uses only standard autoconf macros, this file will not be needed at all.
`config.in'
This file is created by `autoheader' based on `acconfig.h' and `configure.in'. At build time, the configure script will define some of the macros in it to create `config.h', which may then be included by your program. This permits your C code to use preprocessor conditionals to change its behaviour based on the characteristics of the host system. This file may also be called `config.h.in'.
`stamp.h-in'
This rather uninteresting file, which I omitted from the picture, is generated by `automake'. It always contains the string `timestamp'. It is used as a timestamp file indicating whether `config.in' is up to date. Using a timestamp file means that `config.in' can be marked as up to date without actually changing its modification time. This is useful since `config.in' depends upon `configure.in', but it is easy to change `configure.in' in a way which does not affect `config.in'.

Build Files

This section describes the files which are created at configure and build time. These are the files which somebody who builds the package will see.

Of course, the developer will also build the package. The distinction between developer files and build files is not that the developer does not see the build files, but that somebody who only builds the package does not have to worry about the developer files.

Build Files Picture

Here is a picture of the files which will be created at build time. `config.status' is both a created file and a shell script which is run to create other files, and the picture attempts to show that.

Build Files Description

This is a description of the files which are created at build time.

`config.status'
The first step in building a package is to run the `configure' script. The `configure' script will create the file `config.status', which is itself a shell script. When you first run `configure', it will automatically run `config.status'. An `Makefile' derived from an automake generated `Makefile.in' will contain rules to automatically run `config.status' again when necessary to recreate certain files if their inputs change.
`Makefile'
This is the file which make will read to build the program. The `config.status' script will transform `Makefile.in' into `Makefile'.
`config.h'
This file defines C preprocessor macros which C code can use to adjust its behaviour on different systems. The `config.status' script will transform `config.in' into `config.h'.
`config.cache'
This file did not fit neatly into the picture, and I omitted it. It is used by the `configure' script to cache results between runs. This can be an important speedup. If you modify `configure.in' in such a way that the results of old tests should change (perhaps you have added a new library to `LDFLAGS'), then you will have to remove `config.cache' to force the tests to be rerun. The autoconf manual explains how to set up a site specific cache file. This can speed up running `configure' scripts on your system.
`stamp.h'
This file, which I omitted from the picture, is similar to `stamp-h.in'. It is used as a timestamp file indicating whether `config.h' is up to date. This is useful since `config.h' depends upon `config.status', but it is easy for `config.status' to change in a way which does not affect `config.h'.

Support Files

The GNU configure and build system requires several support files to be included with your distribution. You do not normally need to concern yourself with these. If you are using the Cygnus tree, most are already present. Otherwise, they will be installed with your source by `automake' (with the `--add-missing' option) and `libtoolize'.

You don't have to put the support files in the top level directory. You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR' macro in `configure.in' to tell `automake' and the `configure' script where they are.

In this section, I describe the support files, so that you can know what they are and why they are there.

`ABOUT-NLS'
Added by automake if you are using gettext. This is a documentation file about the gettext project.
`ansi2knr.c'
Used by an automake generated `Makefile' if you put `ansi2knr' in `AUTOMAKE_OPTIONS' in `Makefile.am'. This permits compiling ANSI C code with a K&R C compiler.
`ansi2knr.1'
The man page which goes with `ansi2knr.c'.
`config.guess'
A shell script which determines the configuration name for the system on which it is run.
`config.sub'
A shell script which canonicalizes a configuration name entered by a user.
`elisp-comp'
Used to compile Emacs LISP files.
`install-sh'
A shell script which installs a program. This is used if the configure script can not find an install binary.
`ltconfig'
Used by libtool. This is a shell script which configures libtool for the particular system on which it is used.
`ltmain.sh'
Used by libtool. This is the actual libtool script which is used, after it is configured by `ltconfig' to build a library.
`mdate-sh'
A shell script used by an automake generated `Makefile' to pretty print the modification time of a file. This is used to maintain version numbers for texinfo files.
`missing'
A shell script used if some tool is missing entirely. This is used by an automake generated `Makefile' to avoid certain sorts of timestamp problems.
`mkinstalldirs'
A shell script which creates a directory, including all parent directories. This is used by an automake generated `Makefile' during installation.
`texinfo.tex'
Required if you have any texinfo files. This is used when converting Texinfo files into DVI using `texi2dvi' and TeX.
`ylwrap'
A shell script used by an automake generated `Makefile' to run programs like `bison', `yacc', `flex', and `lex'. These programs default to producing output files with a fixed name, and the `ylwrap' script runs them in a subdirectory to avoid file name conflicts when using a parallel make program.


Go to the first, previous, next, last section, table of contents.