Go to the first, previous, next, last section, table of contents.
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.
This section describes the files written or generated by the developer
of a package.
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).
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.
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'.
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.
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.
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'.
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.