to prepend ‘g’ to most of the program names in a source tree,
excepting those like gdb
that already have one and those like
less
and lesskey
that aren’t GNU programs. (That is
assuming that you have a source tree containing those programs that is
set up to use this feature.)
One way to install multiple versions of some programs simultaneously is to append a version number to the name of one or both. For example, if you want to keep Autoconf version 1 around for awhile, you can configure Autoconf version 2 using --program-suffix=2 to install the programs as /usr/local/bin/autoconf2, /usr/local/bin/autoheader2, etc. Nevertheless, pay attention that only the binaries are renamed, therefore you’d have problems with the library files which might overlap.
Previous: Transformation Examples, Up: Transforming Program Names When Installing [Contents][Index]
Here is how to use the variable program_transform_name
in a
Makefile.in:
PROGRAMS = cp ls rm transform = @program_transform_name@ install: for p in $(PROGRAMS); do \ $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ sed '$(transform)'`; \ done uninstall: for p in $(PROGRAMS); do \ rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ done
It is guaranteed that program_transform_name
is never empty, and
that there are no useless separators. Therefore you may safely embed
program_transform_name
within a sed program using ‘;’:
transform = @program_transform_name@ transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/
Whether to do the transformations on documentation files (Texinfo or
man
) is a tricky question; there seems to be no perfect answer,
due to the several reasons for name transforming. Documentation is not
usually particular to a specific architecture, and Texinfo files do not
conflict with system documentation. But they might conflict with
earlier versions of the same files, and man
pages sometimes do
conflict with system documentation. As a compromise, it is probably
best to do name transformations on man
pages but not on Texinfo
manuals.
Previous: Transforming Program Names When Installing, Up: Site Configuration [Contents][Index]
Autoconf-generated configure
scripts allow your site to provide
default values for some configuration values. You do this by creating
site- and system-wide initialization files.
If the environment variable CONFIG_SITE
is set, configure
uses its value as a space-separated list of shell scripts to read;
it is recommended that these be absolute file names. Otherwise, it
reads the shell script prefix/share/config.site if it exists,
then prefix/etc/config.site if it exists. Thus,
settings in machine-specific files override those in machine-independent
ones in case of conflict.
Site files can be arbitrary shell scripts, but only certain kinds of
code are really appropriate to be in them. Because configure
reads any cache file after it has read any site files, a site file can
define a default cache file to be shared between all Autoconf-generated
configure
scripts run on that system (see Cache Files). If
you set a default cache file in a site file, it is a good idea to also
set the output variable CC
in that site file, because the cache
file is only valid for a particular compiler, but many systems have
several available.
You can examine or override the value set by a command line option to
configure
in a site file; options set shell variables that have
the same names as the options, with any dashes turned into underscores.
The exceptions are that --without- and --disable- options
are like giving the corresponding --with- or --enable-
option and the value ‘no’. Thus, --cache-file=localcache
sets the variable cache_file
to the value ‘localcache’;
--enable-warnings=no or --disable-warnings sets the variable
enable_warnings
to the value ‘no’; --prefix=/usr sets the
variable prefix
to the value ‘/usr’; etc.
Site files are also good places to set default values for other output
variables, such as CFLAGS
, if you need to give them non-default
values: anything you would normally do, repetitively, on the command
line. If you use non-default values for prefix or
exec_prefix (wherever you locate the site file), you can set them
in the site file if you specify it with the CONFIG_SITE
environment variable.
You can set some cache values in the site file itself. Doing this is
useful if you are cross-compiling, where it is impossible to check features
that require running a test program. You could “prime the cache” by
setting those values correctly for that system in
prefix/etc/config.site. To find out the names of the cache
variables you need to set, see the documentation of the respective
Autoconf macro. If the variables or their semantics are undocumented,
you may need to look for shell variables with ‘_cv_’ in their names
in the affected configure
scripts, or in the Autoconf M4
source code for those macros; but in that case, their name or semantics
may change in a future Autoconf version.
The cache file is careful to not override any variables set in the site
files. Similarly, you should not override command-line options in the
site files. Your code should check that variables such as prefix
and cache_file
have their default values (as set near the top of
configure
) before changing them.
Here is a sample file /usr/share/local/gnu/share/config.site. The
command ‘configure --prefix=/usr/share/local/gnu’ would read this
file (if CONFIG_SITE
is not set to a different file).
# /usr/share/local/gnu/share/config.site for configure # # Change some defaults. test "$prefix" = NONE && prefix=/usr/share/local/gnu test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var test "$localstatedir" = '${prefix}/var' && localstatedir=/var test "$runstatedir" = '${localstatedir}/run' && runstatedir=/run # Give Autoconf 2.x generated configure scripts a shared default # cache file for feature test results, architecture-specific. if test "$cache_file" = /dev/null; then cache_file="$prefix/var/config.cache" # A cache file is only valid for one C compiler. CC=gcc fi
Another use of config.site is for priming the directory variables
in a manner consistent with the Filesystem Hierarchy Standard
(FHS). Once the following file is installed at
/usr/share/config.site, a user can execute simply
./configure --prefix=/usr
to get all the directories chosen in
the locations recommended by FHS.
# /usr/share/config.site for FHS defaults when installing below /usr, # and the respective settings were not changed on the command line. if test "$prefix" = /usr; then test "$sysconfdir" = '${prefix}/etc' && sysconfdir=/etc test "$sharedstatedir" = '${prefix}/com' && sharedstatedir=/var test "$localstatedir" = '${prefix}/var' && localstatedir=/var fi
Likewise, on platforms where 64-bit libraries are built by default, then installed in /usr/local/lib64 instead of /usr/local/lib, it is appropriate to install /usr/local/share/config.site:
# /usr/local/share/config.site for platforms that prefer # the directory /usr/local/lib64 over /usr/local/lib. test "$libdir" = '${exec_prefix}/lib' && libdir='${exec_prefix}/lib64'
Next: config.status Invocation, Previous: Site Configuration, Up: Autoconf [Contents][Index]
configure
ScriptsBelow are instructions on how to configure a package that uses a
configure
script, suitable for inclusion as an INSTALL
file in the package. A plain-text version of INSTALL which you
may use comes with Autoconf.
configure
Invocation
Next: Compilers and Options, Up: Running configure
Scripts [Contents][Index]
Briefly, the shell command ‘./configure && make && make install’ should configure, build, and install this package. The following more-detailed instructions are generic; see the README file for instructions specific to this package. More recommendations for GNU packages can be found in Makefile Conventions in GNU Coding Standards.
The configure
shell script attempts to guess correct values
for various system-dependent variables used during compilation. It uses
those values to create a Makefile in each directory of the
package. It may also create one or more .h files containing
system-dependent definitions. Finally, it creates a shell script
config.status that you can run in the future to recreate the
current configuration, and a file config.log containing compiler
output (useful mainly for debugging configure
).
It can also use an optional file (typically called config.cache and enabled with --cache-file=config.cache or simply -C) that saves the results of its tests to speed up reconfiguring. Caching is disabled by default to prevent problems with accidental use of stale cache files.
If you need to do unusual things to compile the package, please try to
figure out how configure
could check whether to do them, and
mail diffs or instructions to the address given in the README so
they can be considered for the next release. If you are using the
cache, and at some point config.cache contains results you don’t
want to keep, you may remove or edit it.
The file configure.ac (or configure.in) is used to create
configure by a program called autoconf
. You need
configure.ac if you want to change it or regenerate
configure using a newer version of autoconf
.
The simplest way to compile this package is:
cd
to the directory containing the package’s source code and type
‘./configure’ to configure the package for your system.
Running configure
might take a while. While running, it prints some
messages telling which features it is checking for.
configure
created (so you can compile the package for a
different kind of computer), type ‘make distclean’. There is also
a ‘make maintainer-clean’ target, but that is intended mainly for
the package’s developers. If you use it, you may have to get all sorts
of other programs in order to regenerate files that came with the
distribution.
Next: Compiling For Multiple Architectures, Previous: Basic Installation, Up: Running configure
Scripts [Contents][Index]
Some systems require unusual options for compilation or linking that the
configure
script does not know about. Run ‘./configure
--help’ for details on some of the pertinent environment variables.
You can give configure
initial values for configuration
parameters by setting variables in the command line or in the environment.
Here is an example:
./configure CC=c99 CFLAGS=-g LIBS=-lposix
See Defining Variables, for more details.
Next: Installation Names, Previous: Compilers and Options, Up: Running configure
Scripts [Contents][Index]
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you can use GNU make
.
cd
to the directory where you want the object files and
executables to go and run the configure
script.
configure
automatically checks for the source code in the
directory that configure
is in and in ... This is
known as a VPATH build.
With a non-GNU make
,
it is safer to compile the package for one
architecture at a time in the source code directory. After you have
installed the package for one architecture, use ‘make distclean’
before reconfiguring for another architecture.
On MacOS X 10.5 and later systems, you can create libraries and executables that work on multiple system types—known as fat or universal binaries—by specifying multiple -arch options to the compiler but only a single -arch option to the preprocessor. Like this:
./configure CC="gcc -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ CXX="g++ -arch i386 -arch x86_64 -arch ppc -arch ppc64" \ CPP="gcc -E" CXXCPP="g++ -E"
This is not guaranteed to produce working output in all cases, you may
have to build one architecture at a time and combine the results
using the lipo
tool if you have problems.
Next: Optional Features, Previous: Compiling For Multiple Architectures, Up: Running configure
Scripts [Contents][Index]
By default, ‘make install’ installs the package’s commands under
/usr/local/bin, include files under /usr/local/include, etc.
You can specify an
installation prefix other than /usr/local by giving
configure
the option --prefix=prefix, where
prefix must be an absolute file name.
You can specify separate installation prefixes for architecture-specific
files and architecture-independent files. If you pass the option
--exec-prefix=prefix to configure
, the
package uses prefix as the prefix for installing programs and
libraries. Documentation and other data files still use the
regular prefix.
In addition, if you use an unusual directory layout you can give options like --bindir=dir to specify different values for particular kinds of files. Run ‘configure --help’ for a list of the directories you can set and what kinds of files go in them. In general, the default for these options is expressed in terms of ‘${prefix}’, so that specifying just --prefix will affect all of the other directory specifications that were not explicitly provided.
The most portable way to affect installation locations is to pass the
correct locations to configure
; however, many packages provide
one or both of the following shortcuts of passing variable assignments
to the ‘make install’ command line to change installation locations
without having to reconfigure or recompile.
The first method involves providing an override variable for each
affected directory. For example, ‘make install
prefix=/alternate/directory’ will choose an alternate location for all
directory configuration variables that were expressed in terms of
‘${prefix}’. Any directories that were specified during
configure
, but not in terms of ‘${prefix}’, must each be
overridden at install time for the entire
installation to be relocated. The approach of makefile variable
overrides for each directory variable is required by the GNU
Coding Standards, and ideally causes no recompilation. However, some
platforms have known limitations with the semantics of shared libraries
that end up requiring recompilation when using this method, particularly
noticeable in packages that use GNU Libtool.
The second method involves providing the ‘DESTDIR’ variable. For
example, ‘make install DESTDIR=/alternate/directory’ will prepend
‘/alternate/directory’ before all installation names. The approach
of ‘DESTDIR’ overrides is not required by the GNU Coding
Standards, and does not work on platforms that have drive letters. On
the other hand, it does better at avoiding recompilation issues, and
works well even when some directory options were not specified in terms
of ‘${prefix}’ at configure
time.
Next: Particular systems, Previous: Installation Names, Up: Running configure
Scripts [Contents][Index]
If the package supports it, you can cause programs to be installed with
an extra prefix or suffix on their names by giving configure
the option --program-prefix=PREFIX or
--program-suffix=SUFFIX.
Some packages pay attention to --enable-feature options
to configure
, where feature indicates an optional part
of the package. They may also pay attention to
--with-package options, where package is something
like ‘gnu-as’ or ‘x’ (for the X Window System). The
README should mention any --enable- and --with-
options that the package recognizes.
For packages that use the X Window System, configure
can
usually find the X include and library files automatically, but if it
doesn’t, you can use the configure
options
--x-includes=dir and --x-libraries=dir to
specify their locations.
Some packages offer the ability to configure how verbose the execution
of make
will be. For these packages, running
‘./configure --enable-silent-rules’ sets the default to minimal
output, which can be overridden with make V=1
; while running
‘./configure --disable-silent-rules’ sets the default to verbose,
which can be overridden with make V=0
.
Next: Specifying the System Type, Previous: Optional Features, Up: Running configure
Scripts [Contents][Index]
On HP-UX, the default C compiler is not ANSI C compatible. If GNU CC is not installed, it is recommended to use the following options in order to use an ANSI C compiler:
./configure CC="cc -Ae -D_XOPEN_SOURCE=500"
and if that doesn’t work, install pre-built binaries of GCC for HP-UX.
HP-UX make
updates targets which have the same timestamps as
their prerequisites, which makes it generally unusable when shipped
generated files such as configure
are involved. Use GNU
make
instead.
On OSF/1 a.k.a. Tru64, some versions of the default C compiler cannot
parse its <wchar.h>
header file. The option -nodtk can be
used as a workaround. If GNU CC is not installed, it is therefore
recommended to try
./configure CC="cc"
and if that doesn’t work, try
./configure CC="cc -nodtk"
On Solaris, don’t put /usr/ucb
early in your PATH
. This
directory contains several dysfunctional programs; working variants
of these programs are available in /usr/bin
. So, if you need
/usr/ucb
in your PATH
, put it after /usr/bin
.
On Haiku, software installed for all users goes in /boot/common, not /usr/local. It is recommended to use the following options:
./configure --prefix=/boot/common
Next: Sharing Defaults, Previous: Particular systems, Up: Running configure
Scripts [Contents][Index]
There may be some features configure
cannot figure out
automatically, but needs to determine by the type of machine the package
will run on. Usually, assuming the package is built to be run on the
same architectures, configure
can figure that out, but
if it prints a message saying it cannot guess the machine type, give it
the --build=type option. type can either be a
short name for the system type, such as ‘sun4’, or a canonical name
which has the form:
cpu-company-system
where system can have one of these forms:
os kernel-os
See the file config.sub for the possible values of each field. If config.sub isn’t included in this package, then this package doesn’t need to know the machine type.
If you are building compiler tools for cross-compiling, you should use the option --target=type to select the type of system they will produce code for.
If you want to use a cross compiler, that generates code for a platform different from the build platform, you should specify the host platform (i.e., that on which the generated programs will eventually be run) with --host=type.
Next: Defining Variables, Previous: Specifying the System Type, Up: Running configure
Scripts [Contents][Index]
If you want to set default values for configure
scripts to
share, you can create a site shell script called config.site that
gives default values for variables like CC
, cache_file
,
and prefix
. configure
looks for
prefix/share/config.site if it exists, then
prefix/etc/config.site if it exists. Or, you can set the
CONFIG_SITE
environment variable to the location of the site
script. A warning: not all configure
scripts look for a site
script.
Next: configure
Invocation, Previous: Sharing Defaults, Up: Running configure
Scripts [Contents][Index]
Variables not defined in a site shell script can be set in the
environment passed to configure
. However, some packages may
run configure again during the build, and the customized values of these
variables may be lost. In order to avoid this problem, you should set
them in the configure
command line, using ‘VAR=value’.
For example:
./configure CC=/usr/local2/bin/gcc
causes the specified gcc
to be used as the C compiler (unless it is
overridden in the site shell script).
Unfortunately, this technique does not work for CONFIG_SHELL
due
to an Autoconf limitation. Until the limitation is lifted, you can use
this workaround:
CONFIG_SHELL=/bin/bash ./configure CONFIG_SHELL=/bin/bash
Previous: Defining Variables, Up: Running configure
Scripts [Contents][Index]
configure
Invocationconfigure
recognizes the following options to control how it
operates.
Print a summary of all of the options to configure
, and exit.
Print a summary of the options unique to this package’s
configure
, and exit. The short
variant lists options
used only in the top level, while the recursive
variant lists
options also present in any nested packages.
Print the version of Autoconf used to generate the configure
script, and exit.
Enable the cache: use and save the results of the tests in file, traditionally config.cache. file defaults to /dev/null to disable caching.
Alias for --cache-file=config.cache.
Do not print messages saying which checks are being made. To suppress all normal output, redirect it to /dev/null (any error messages will still be shown).
Look for the package’s source code in directory dir. Usually
configure
can determine that directory automatically.
Use dir as the installation prefix. Installation Names for more details, including other options available for fine-tuning the installation locations.
Run the configure checks, but stop before creating any output files.
configure
also accepts some other, not widely useful, options.
Run ‘configure --help’ for more details.
Next: Obsolete Constructs, Previous: Running configure
Scripts, Up: Autoconf [Contents][Index]
The configure
script creates a file named config.status,
which actually configures, instantiates, the template files. It
also records the configuration options that were specified when the
package was last configured in case reconfiguring is needed.
Synopsis:
./config.status [option]… [tag]…
It configures each tag; if none are specified, all the templates
are instantiated. A tag refers to a file or other tag associated
with a configuration action, as specified by an AC_CONFIG_ITEMS
macro (see Performing Configuration Actions). The files must be specified
without their dependencies, as in
./config.status foobar
not
./config.status foobar:foo.in:bar.in
The supported options are:
Print a summary of the command line options, the list of the template files, and exit.
Print the version number of Autoconf and the configuration settings, and exit.
Print the configuration settings in reusable way, quoted for the shell, and exit. For example, for a debugging build that otherwise reuses the configuration from a different build directory build-dir of a package in src-dir, you could use the following:
args=`build-dir/config.status --config` eval src-dir/configure "$args" CFLAGS=-g --srcdir=src-dir
Note that it may be necessary to override a --srcdir setting that was saved in the configuration, if the arguments are used in a different build directory.
Do not print progress messages.
Don’t remove the temporary files.
Require that file be instantiated as if ‘AC_CONFIG_FILES(file:template)’ was used. Both file and template may be ‘-’ in which case the standard output and/or standard input, respectively, is used. If a template file name is relative, it is first looked for in the build tree, and then in the source tree. See Performing Configuration Actions, for more details.
This option and the following ones provide one way for separately
distributed packages to share the values computed by configure
.
Doing so can be useful if some of the packages need a superset of the
features that one of them, perhaps a common library, does. These
options allow a config.status file to create files other than the
ones that its configure.ac specifies, so it can be used for a
different package, or for extracting a subset of values. For example,
echo '@CC@' | ./config.status --file=-
provides the value of @CC@
on standard output.
Same as --file above, but with ‘AC_CONFIG_HEADERS’.
Ask config.status to update itself and exit (no instantiation).
This option is useful if you change configure
, so that the
results of some tests might be different from the previous run. The
--recheck option reruns configure
with the same arguments
you used before, plus the --no-create option, which prevents
configure
from running config.status and creating
Makefile and other files, and the --no-recursion option,
which prevents configure
from running other configure
scripts in subdirectories. (This is so other Make rules can
run config.status when it changes; see Automatic Remaking,
for an example).
config.status checks several optional environment variables that can alter its behavior:
The shell with which to run configure
. It must be
Bourne-compatible, and the absolute name of the shell should be passed.
The default is a shell that supports LINENO
if available, and
/bin/sh otherwise.
The file name to use for the shell script that records the
configuration. The default is ./config.status. This variable is
useful when one package uses parts of another and the configure
scripts shouldn’t be merged because they are maintained separately.
You can use ./config.status in your makefiles. For example, in the dependencies given above (see Automatic Remaking), config.status is run twice when configure.ac has changed. If that bothers you, you can make each run only regenerate the files for that rule:
config.h: stamp-h stamp-h: config.h.in config.status ./config.status config.h echo > stamp-h Makefile: Makefile.in config.status ./config.status Makefile
The calling convention of config.status has changed; see Obsolete config.status Invocation, for details.
 Most of the changes involve the macros, but in some cases the tools themselves, or even some concepts, are now considered obsolete.
You may completely skip this chapter if you are new to Autoconf. Its intention is mainly to help maintainers updating their packages by understanding how to move to more modern constructs.
autoupdate
to Modernize configure.acNext: acconfig.h, Up: Obsolete Constructs [Contents][Index]
config.status now supports arguments to specify the files to instantiate; see config.status Invocation, for more details. Before, environment variables had to be used.
The tags of the commands to execute. The default is the arguments given
to AC_OUTPUT
and AC_CONFIG_COMMANDS
in
configure.ac.
The files in which to perform ‘@variable@’ substitutions.
The default is the arguments given to AC_OUTPUT
and
AC_CONFIG_FILES
in configure.ac.
The files in which to substitute C #define
statements. The
default is the arguments given to AC_CONFIG_HEADERS
; if that
macro was not called, config.status ignores this variable.
The symbolic links to establish. The default is the arguments given to
AC_CONFIG_LINKS
; if that macro was not called,
config.status ignores this variable.
In config.status Invocation, using this old interface, the example would be:
config.h: stamp-h stamp-h: config.h.in config.status CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ CONFIG_HEADERS=config.h ./config.status echo > stamp-h Makefile: Makefile.in config.status CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ CONFIG_FILES=Makefile ./config.status
(If configure.ac does not call AC_CONFIG_HEADERS
, there is
no need to set CONFIG_HEADERS
in the make
rules. Equally
for CONFIG_COMMANDS
, etc.)
Next: Using autoupdate
to Modernize configure.ac, Previous: Obsolete config.status Invocation, Up: Obsolete Constructs [Contents][Index]
In order to produce config.h.in, autoheader
needs to
build or to find templates for each symbol. Modern releases of Autoconf
use AH_VERBATIM
and AH_TEMPLATE
(see Autoheader Macros), but in older releases a file, acconfig.h, contained the
list of needed templates. autoheader
copied comments and
#define
and #undef
statements from acconfig.h in
the current directory, if present. This file used to be mandatory if
you AC_DEFINE
any additional symbols.
Modern releases of Autoconf also provide AH_TOP
and
AH_BOTTOM
if you need to prepend/append some information to
config.h.in. Ancient versions of Autoconf had a similar feature:
if ./acconfig.h contains the string ‘@TOP@’,
autoheader
copies the lines before the line containing
‘@TOP@’ into the top of the file that it generates. Similarly,
if ./acconfig.h contains the string ‘@BOTTOM@’,
autoheader
copies the lines after that line to the end of the
file it generates. Either or both of those strings may be omitted. An
even older alternate way to produce the same effect in ancient versions
of Autoconf is to create the files file.top (typically
config.h.top) and/or file.bot in the current
directory. If they exist, autoheader
copies them to the
beginning and end, respectively, of its output.
In former versions of Autoconf, the files used in preparing a software package for distribution were:
configure.ac --. .------> autoconf* -----> configure +---+ [aclocal.m4] --+ `---. [acsite.m4] ---' | +--> [autoheader*] -> [config.h.in] [acconfig.h] ----. | +-----' [config.h.top] --+ [config.h.bot] --'
Using only the AH_
macros, configure.ac should be
self-contained, and should not depend upon acconfig.h etc.
Next: Obsolete Macros, Previous: acconfig.h, Up: Obsolete Constructs [Contents][Index]
autoupdate
to Modernize configure.acThe autoupdate
program updates a configure.ac file that
calls Autoconf macros by their old names to use the current macro names.
In version 2 of Autoconf, most of the macros were renamed to use a more
uniform and descriptive naming scheme. See Macro Names, for a
description of the new scheme. Although the old names still work
(see Obsolete Macros, for a list of the old macros and the corresponding
new names), you can make your configure.ac files more readable
and make it easier to use the current Autoconf documentation if you
update them to use the new macro names.
If given no arguments, autoupdate
updates configure.ac,
backing up the original version with the suffix ~ (or the value
of the environment variable SIMPLE_BACKUP_SUFFIX
, if that is
set). If you give autoupdate
an argument, it reads that file
instead of configure.ac and writes the updated file to the
standard output.
autoupdate
accepts the following options:
Print a summary of the command line options and exit.
Print the version number of Autoconf and exit.
Report processing steps.
Don’t remove the temporary files.
Force the update even if the file has not changed. Disregard the cache.
Also look for input files in dir. Multiple invocations accumulate. Directories are browsed from last to first.
Prepend directory dir to the search path. This is used to include the language-specific files before any third-party macros.
Next: Upgrading From Version 1, Previous: Using autoupdate
to Modernize configure.ac, Up: Obsolete Constructs [Contents][Index]
Several macros are obsoleted in Autoconf, for various reasons (typically they failed to quote properly, couldn’t be extended for more recent issues, etc.). They are still supported, but deprecated: their use should be avoided.
During the jump from Autoconf version 1 to version 2, most of the macros were renamed to use a more uniform and descriptive naming scheme, but their signature did not change. See Macro Names, for a description of the new naming scheme. Below, if there is just the mapping from old names to new names for these macros, the reader is invited to refer to the definition of the new macro for the signature and the description.
This macro is a platform-specific subset of
AC_USE_SYSTEM_EXTENSIONS
(see AC_USE_SYSTEM_EXTENSIONS).
Replaced by AC_FUNC_ALLOCA
(see AC_FUNC_ALLOCA).
Removed because of limited usefulness.
This macro is obsolete; it does nothing.
If the C compiler supports a working long double
type with more
range or precision than the double
type, define
HAVE_LONG_DOUBLE
.
You should use AC_TYPE_LONG_DOUBLE
or
AC_TYPE_LONG_DOUBLE_WIDER
instead. See Particular Type Checks.
Determine the system type and set output variables to the names of the canonical system types. See Getting the Canonical System Type, for details about the variables this macro sets.
The user is encouraged to use either AC_CANONICAL_BUILD
, or
AC_CANONICAL_HOST
, or AC_CANONICAL_TARGET
, depending on
the needs. Using AC_CANONICAL_TARGET
is enough to run the two
other macros (see Getting the Canonical System Type).
Replaced by AC_C_CHAR_UNSIGNED
(see AC_C_CHAR_UNSIGNED).
Autoconf, up to 2.13, used to provide this version of
AC_CHECK_TYPE
, deprecated because of its flaws. First, although
it is a member of the CHECK
clan, it does
more than just checking. Secondly, missing types are defined
using #define
, not typedef
, and this can lead to
problems in the case of pointer types.
This use of AC_CHECK_TYPE
is obsolete and discouraged; see
Generic Type Checks, for the description of the current macro.
If the type type is not defined, define it to be the C (or C++) builtin type default, e.g., ‘short int’ or ‘unsigned int’.
This macro is equivalent to:
AC_CHECK_TYPE([type], [], [AC_DEFINE_UNQUOTED([type], [default], [Define to `default' if <sys/types.h> does not define.])])
In order to keep backward compatibility, the two versions of
AC_CHECK_TYPE
are implemented, selected using these heuristics:
You are encouraged either to use a valid builtin type, or to use the
equivalent modern code (see above), or better yet, to use
AC_CHECK_TYPES
together with
#ifndef HAVE_LOFF_T typedef loff_t off_t; #endif
Same as
AC_MSG_NOTICE([checking feature-description…]
See AC_MSG_NOTICE.
This is an obsolete version of AC_TRY_COMPILE
itself replaced by
AC_COMPILE_IFELSE
(see Running the Compiler), with the
addition that it prints ‘checking for echo-text’ to the
standard output first, if echo-text is non-empty. Use
AC_MSG_CHECKING
and AC_MSG_RESULT
instead to print
messages (see Printing Messages).
Replaced by AC_C_CONST
(see AC_C_CONST).
Same as AC_C_CROSS
, which is obsolete too, and does nothing
:-)
.
Check for the Cygwin environment in which case the shell variable
CYGWIN
is set to ‘yes’. Don’t use this macro, the dignified
means to check the nature of the host is using AC_CANONICAL_HOST
(see Getting the Canonical System Type). As a matter of fact this macro is defined as:
AC_REQUIRE([AC_CANONICAL_HOST])[]dnl case $host_os in *cygwin* ) CYGWIN=yes;; * ) CYGWIN=no;; esac
Beware that the variable CYGWIN
has a special meaning when
running Cygwin, and should not be changed. That’s yet another reason
not to use this macro.
Same as:
AC_CHECK_DECLS([sys_siglist], [], [], [#include <signal.h> /* NetBSD declares sys_siglist in unistd.h. */ #ifdef HAVE_UNISTD_H # include <unistd.h> #endif ])
See AC_CHECK_DECLS.
Does nothing, now integrated in AC_PROG_LEX
(see AC_PROG_LEX).
Like calling AC_FUNC_CLOSEDIR_VOID
(see AC_FUNC_CLOSEDIR_VOID) and AC_HEADER_DIRENT
(see AC_HEADER_DIRENT),
but defines a different set of C preprocessor macros to indicate which
header file is found:
| Header | Old Symbol | New Symbol |
| dirent.h | DIRENT | HAVE_DIRENT_H |
| sys/ndir.h | SYSNDIR | HAVE_SYS_NDIR_H |
| sys/dir.h | SYSDIR | HAVE_SYS_DIR_H |
| ndir.h | NDIR | HAVE_NDIR_H |
If on DYNIX/ptx, add -lseq to output variable
LIBS
. This macro used to be defined as
AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"])
now it is just AC_FUNC_GETMNTENT
(see AC_FUNC_GETMNTENT).
Defined the output variable EXEEXT
based on the output of the
compiler, which is now done automatically. Typically set to empty
string if Posix and ‘.exe’ if a DOS variant.
Similar to AC_CYGWIN
but checks for the EMX environment on OS/2
and sets EMXOS2
. Don’t use this macro, the dignified means to
check the nature of the host is using AC_CANONICAL_HOST
(see Getting the Canonical System Type).
This is an obsolete version of AC_ARG_ENABLE
that does not
support providing a help string (see AC_ARG_ENABLE).
Replaced by AC_MSG_ERROR
(see AC_MSG_ERROR).
Replaced by AC_PATH_XTRA
(see AC_PATH_XTRA).
Replaced by m4_foreach_w
(see m4_foreach_w).
Replaced by AC_CHECK_FUNC
(see AC_CHECK_FUNC).
Do nothing. Formerly, this macro checked whether setvbuf
takes
the buffering type as its second argument and the buffer pointer as the
third, instead of the other way around, and defined
SETVBUF_REVERSED
. However, the last systems to have the problem
were those based on SVR2, which became obsolete in 1987, and the macro
is no longer needed.
If wait3
is found and fills in the contents of its third argument
(a ‘struct rusage *’), which HP-UX does not do, define
HAVE_WAIT3
.
These days portable programs should use waitpid
, not
wait3
, as wait3
has been removed from Posix.
Replaced by AC_PROG_GCC_TRADITIONAL
(see AC_PROG_GCC_TRADITIONAL).
Replaced by AC_TYPE_GETGROUPS
(see AC_TYPE_GETGROUPS).
Replaced by AC_FUNC_GETLOADAVG
(see AC_FUNC_GETLOADAVG).
This macro is a platform-specific subset of
AC_USE_SYSTEM_EXTENSIONS
(see AC_USE_SYSTEM_EXTENSIONS).
Replaced by AC_CHECK_FUNCS
(see AC_CHECK_FUNCS).
Replaced by AC_CHECK_HEADERS
(see AC_CHECK_HEADERS).
This macro is equivalent to calling AC_CHECK_LIB
with a
function argument of main
. In addition, library can
be written as any of ‘foo’, -lfoo, or ‘libfoo.a’. In
all of those cases, the compiler is passed -lfoo. However,
library cannot be a shell variable; it must be a literal name.
See AC_CHECK_LIB.
Replaced by AC_SYS_INTERPRETER
(see AC_SYS_INTERPRETER).
Replaced by AC_CHECK_HEADER
(see AC_CHECK_HEADER).
Replaced by AC_EGREP_HEADER
(see AC_EGREP_HEADER).
This macro used to check whether it was possible to include
time.h and sys/time.h in the same source file,
defining TIME_WITH_SYS_TIME
if so.
Nowadays, it is equivalent to ‘AC_CHECK_HEADERS([sys/time.h])’,
although it does still define TIME_WITH_SYS_TIME
for
compatibility’s sake. time.h is universally present, and the
systems on which sys/time.h conflicted with time.h are
obsolete.
Replaced by AS_HELP_STRING
(see AS_HELP_STRING).
Formerly AC_INIT
used to have a single argument, and was
equivalent to:
AC_INIT AC_CONFIG_SRCDIR(unique-file-in-source-dir)
See AC_INIT and AC_CONFIG_SRCDIR.
Replaced by AC_C_INLINE
(see AC_C_INLINE).
If the C type int
is 16 bits wide, define INT_16_BITS
.
Use ‘AC_CHECK_SIZEOF(int)’ instead (see AC_CHECK_SIZEOF).
If on IRIX (Silicon Graphics Unix), add -lsun to output
LIBS
. If you were using it to get getmntent
, use
AC_FUNC_GETMNTENT
instead. If you used it for the NIS versions
of the password and group functions, use ‘AC_CHECK_LIB(sun,
getpwnam)’. Up to Autoconf 2.13, it used to be
AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"])
now it is defined as
AC_FUNC_GETMNTENT AC_CHECK_LIB([sun], [getpwnam])
See AC_FUNC_GETMNTENT and AC_CHECK_LIB.
This macro adds -lcposix to output variable LIBS
if
necessary for Posix facilities. Sun dropped support for the obsolete
INTERACTIVE Systems Corporation Unix on 2006-07-23. New programs
need not use this macro. It is implemented as
AC_SEARCH_LIBS([strerror], [cposix])
(see AC_SEARCH_LIBS).
Select the language that is saved on the top of the stack, as set
by AC_LANG_SAVE
, remove it from the stack, and call
AC_LANG(language)
. See Language Choice, for the
preferred way to change languages.
Remember the current language (as set by AC_LANG
) on a stack.
The current language does not change. AC_LANG_PUSH
is preferred
(see AC_LANG_PUSH).
This is an obsolete version of AC_CONFIG_LINKS
(see AC_CONFIG_LINKS. An updated version of:
AC_LINK_FILES(config/$machine.h config/$obj_format.h, host.h object.h)
is:
AC_CONFIG_LINKS([host.h:config/$machine.h object.h:config/$obj_format.h])
Replaced by AC_PROG_LN_S
(see AC_PROG_LN_S).
Define LONG_64_BITS
if the C type long int
is 64 bits wide.
Use the generic macro ‘AC_CHECK_SIZEOF([long int])’ instead
(see AC_CHECK_SIZEOF).
If the C compiler supports a working long double
type with more
range or precision than the double
type, define
HAVE_LONG_DOUBLE
.
You should use AC_TYPE_LONG_DOUBLE
or
AC_TYPE_LONG_DOUBLE_WIDER
instead. See Particular Type Checks.
Replaced by
AC_SYS_LONG_FILE_NAMES
Replaced by AC_HEADER_MAJOR
(see AC_HEADER_MAJOR).
Used to define NEED_MEMORY_H
if the mem
functions were
defined in memory.h. Today it is equivalent to
‘AC_CHECK_HEADERS([memory.h])’ (see AC_CHECK_HEADERS). Adjust
your code to get the mem
functions from string.h instead.
Similar to AC_CYGWIN
but checks for the MinGW compiler
environment and sets MINGW32
. Don’t use this macro, the
dignified means to check the nature of the host is using
AC_CANONICAL_HOST
(see Getting the Canonical System Type).
This macro is a platform-specific subset of
AC_USE_SYSTEM_EXTENSIONS
(see AC_USE_SYSTEM_EXTENSIONS).
Replaced by AC_PROG_CC_C_O
(see AC_PROG_CC_C_O).
Replaced by AC_FUNC_MMAP
(see AC_FUNC_MMAP).
Replaced by AC_TYPE_MODE_T
(see AC_TYPE_MODE_T).
Defined the output variable OBJEXT
based on the output of the
compiler, after .c files have been excluded. Typically set to ‘o’
if Posix, ‘obj’ if a DOS variant.
Now the compiler checking macros handle
this automatically.
Make M4 print a message to the standard error output warning that
this-macro-name is obsolete, and giving the file and line number
where it was called. this-macro-name should be the name of the
macro that is calling AC_OBSOLETE
. If suggestion is given,
it is printed at the end of the warning message; for example, it can be
a suggestion for what to use instead of this-macro-name.
For instance
AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl
You are encouraged to use AU_DEFUN
instead, since it gives better
services to the user (see AU_DEFUN).
Replaced by AC_TYPE_OFF_T
(see AC_TYPE_OFF_T).
The use of AC_OUTPUT
with arguments is deprecated. This obsoleted
interface is equivalent to:
AC_CONFIG_FILES(file…) AC_CONFIG_COMMANDS([default], extra-cmds, init-cmds) AC_OUTPUT
See AC_CONFIG_FILES, AC_CONFIG_COMMANDS, and AC_OUTPUT.
Specify additional shell commands to run at the end of
config.status, and shell commands to initialize any variables
from configure
. This macro may be called multiple times. It is
obsolete, replaced by AC_CONFIG_COMMANDS
(see AC_CONFIG_COMMANDS).
Here is an unrealistic example:
fubar=27 AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], [fubar=$fubar]) AC_OUTPUT_COMMANDS([echo this is another, extra, bit], [echo init bit])
Aside from the fact that AC_CONFIG_COMMANDS
requires an
additional key, an important difference is that
AC_OUTPUT_COMMANDS
is quoting its arguments twice, unlike
AC_CONFIG_COMMANDS
. This means that AC_CONFIG_COMMANDS
can safely be given macro calls as arguments:
AC_CONFIG_COMMANDS(foo, [my_FOO()])
Conversely, where one level of quoting was enough for literal strings
with AC_OUTPUT_COMMANDS
, you need two with
AC_CONFIG_COMMANDS
. The following lines are equivalent:
AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]])
Replaced by AC_TYPE_PID_T
(see AC_TYPE_PID_T).
Replaced by AC_PREFIX_PROGRAM
(see AC_PREFIX_PROGRAM).
Now done by AC_PROG_CC
(see AC_PROG_CC).
Now done by AC_PROG_CC
(see AC_PROG_CC).
Now done by AC_PROG_CC
(see AC_PROG_CC).
Replaced by AC_CHECK_PROGS
(see AC_CHECK_PROGS).
Replaced by AC_PATH_PROGS
(see AC_PATH_PROGS).
Replaced by AC_CHECK_PROG
(see AC_CHECK_PROG).
Replaced by AC_EGREP_CPP
(see AC_EGREP_CPP).
Replaced by AC_PATH_PROG
(see AC_PATH_PROG).
Removed because of limited usefulness.
This macro was renamed AC_SYS_RESTARTABLE_SYSCALLS
. However,
these days portable programs should use sigaction
with
SA_RESTART
if they want restartable system calls. They should
not rely on HAVE_RESTARTABLE_SYSCALLS
, since nowadays whether a
system call is restartable is a dynamic issue, not a configuration-time
issue.
Replaced by AC_TYPE_SIGNAL
(see AC_TYPE_SIGNAL), which itself
is obsolete when assuming C89 or better.
Removed because of limited usefulness.
If on SCO Unix, add -lintl to output variable LIBS
. This
macro used to do this:
AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"])
Now it just calls AC_FUNC_STRFTIME
instead (see AC_FUNC_STRFTIME).
Replaced by
AC_FUNC_SETVBUF_REVERSED
Replaced by AC_PROG_MAKE_SET
(see AC_PROG_MAKE_SET).
Replaced by AC_CHECK_SIZEOF
(see AC_CHECK_SIZEOF).
Replaced by AC_TYPE_SIZE_T
(see AC_TYPE_SIZE_T).
Replaced by AC_HEADER_STAT
(see AC_HEADER_STAT).
Replaced by AC_HEADER_STDC
(see AC_HEADER_STDC), which
is itself obsolete. Nowadays it is safe to assume the facilities of C90
exist.
Replaced by AC_FUNC_STRCOLL
(see AC_FUNC_STRCOLL).
If struct stat
contains an st_blksize
member, define
HAVE_STRUCT_STAT_ST_BLKSIZE
. The former name,
HAVE_ST_BLKSIZE
is to be avoided, as its support will cease in
the future. This macro is obsoleted, and should be replaced by
AC_CHECK_MEMBERS([struct stat.st_blksize])
See AC_CHECK_MEMBERS.
If struct stat
contains an st_rdev
member, define
HAVE_STRUCT_STAT_ST_RDEV
. The former name for this macro,
HAVE_ST_RDEV
, is to be avoided as it will cease to be supported
in the future. Actually, even the new macro is obsolete and should be
replaced by:
AC_CHECK_MEMBERS([struct stat.st_rdev])
See AC_CHECK_MEMBERS.
Replaced by AC_CHECK_MEMBERS
(see AC_CHECK_MEMBERS).
Replaced by AC_STRUCT_ST_BLOCKS
(see AC_STRUCT_ST_BLOCKS).
Replaced by AC_CHECK_MEMBERS
(see AC_CHECK_MEMBERS).
If the system automatically restarts a system call that is interrupted
by a signal, define HAVE_RESTARTABLE_SYSCALLS
. This macro does
not check whether system calls are restarted in general—it checks whether a
signal handler installed with signal
(but not sigaction
)
causes system calls to be restarted. It does not check whether system calls
can be restarted when interrupted by signals that have no handler.
These days portable programs should use sigaction
with
SA_RESTART
if they want restartable system calls. They should
not rely on HAVE_RESTARTABLE_SYSCALLS
, since nowadays whether a
system call is restartable is a dynamic issue, not a configuration-time
issue.
This macro was renamed AC_DECL_SYS_SIGLIST
. However, even that
name is obsolete, as the same functionality is now achieved via
AC_CHECK_DECLS
(see AC_CHECK_DECLS).
This macro was renamed AC_TRY_CPP
, which in turn was replaced by
AC_PREPROC_IFELSE
(see AC_PREPROC_IFELSE).
This macro was renamed AC_TRY_RUN
, which in turn was replaced by
AC_RUN_IFELSE
(see AC_RUN_IFELSE).
Replaced by AC_STRUCT_TIMEZONE
(see AC_STRUCT_TIMEZONE).
Replaced by AC_HEADER_TIME
(see AC_HEADER_TIME), which is
itself obsolete; nowadays one need only do
‘AC_CHECK_HEADERS([sys/time.h])’.
Same as:
AC_COMPILE_IFELSE( [AC_LANG_PROGRAM([[includes]], [[function-body]])], [action-if-true], [action-if-false])
See Running the Compiler.
This macro double quotes both includes and function-body.
For C and C++, includes is any #include
statements needed
by the code in function-body (includes is ignored if
the currently selected language is Fortran or Fortran 77). The compiler
and compilation flags are determined by the current language
(see Language Choice).
Same as:
AC_PREPROC_IFELSE( [AC_LANG_SOURCE([[input]])], [action-if-true], [action-if-false])
This macro double quotes the input.
Same as:
AC_LINK_IFELSE( [AC_LANG_PROGRAM([[includes]], [[function-body]])], [action-if-true], [action-if-false])
See Running the Linker.
This macro double quotes both includes and function-body.
Depending on the current language (see Language Choice), create a test program to see whether a function whose body consists of function-body can be compiled and linked. If the file compiles and links successfully, run shell commands action-if-found, otherwise run action-if-not-found.
This macro double quotes both includes and function-body.
For C and C++, includes is any #include
statements needed
by the code in function-body (includes is ignored if
the currently selected language is Fortran or Fortran 77). The compiler
and compilation flags are determined by the current language
(see Language Choice), and in addition LDFLAGS
and
LIBS
are used for linking.
This macro is equivalent to
AC_LINK_IFELSE([AC_LANG_CALL([], [function])], [action-if-found], [action-if-not-found])
See Running the Linker.
Same as:
AC_RUN_IFELSE( [AC_LANG_SOURCE([[program]])], [action-if-true], [action-if-false], [action-if-cross-compiling])
If signal.h declares signal
as returning a pointer to a
function returning void
, define RETSIGTYPE
to be
void
; otherwise, define it to be int
. These days, it is
portable to assume C89, and that signal handlers return void
,
without needing to use this macro or RETSIGTYPE
.
When targeting older K&R C, it is possible to define signal handlers as
returning type RETSIGTYPE
, and omit a return statement:
RETSIGTYPE hup_handler () { … }
Replaced by AC_TYPE_UID_T
(see AC_TYPE_UID_T).
Same as ‘AC_CHECK_HEADERS([unistd.h])’ (see AC_CHECK_HEADERS),
which is one of the tests done as a side effect by
AC_INCLUDES_DEFAULT
(see Default Includes), so usually
unnecessary to write explicitly.
Define USG
if the BSD string functions (bcopy
,
bzero
, index
, rindex
, etc) are not defined
in strings.h. Modern code should assume string.h exists
and should use the ISO C string functions (memmove
, memset
,
strchr
, strrchr
, etc) unconditionally.
strings.h may be the only header that declares strcasecmp
,
strncasecmp
, and ffs
. AC_INCLUDES_DEFAULT
checks
for it (see Default Includes); test HAVE_STRINGS_H
.
Replaced by AC_FUNC_UTIME_NULL
(see AC_FUNC_UTIME_NULL).
If the cache file is inconsistent with the current host, target and build system types, it used to execute cmd or print a default error message. This is now handled by default.
Replaced by AC_MSG_RESULT
(see AC_MSG_RESULT).
Replaced by AC_FUNC_FORK
(see AC_FUNC_FORK).
Replaced by AC_FUNC_VPRINTF
(see AC_FUNC_VPRINTF).
This macro was renamed AC_FUNC_WAIT3
. However, these days
portable programs should use waitpid
, not wait3
, as
wait3
has been removed from Posix.
Replaced by AC_MSG_WARN
(see AC_MSG_WARN).
This is an obsolete version of AC_ARG_WITH
that does not
support providing a help string (see AC_ARG_WITH).
Replaced by AC_C_BIGENDIAN
(see AC_C_BIGENDIAN).
This macro used to add -lx to output variable LIBS
if on
Xenix. Also, if dirent.h is being checked for, added
-ldir to LIBS
. Now it is merely an alias of
AC_HEADER_DIRENT
instead, plus some code to detect whether
running XENIX on which you should not depend:
AC_MSG_CHECKING([for Xenix]) AC_EGREP_CPP([yes], [#if defined M_XENIX && !defined M_UNIX yes #endif], [AC_MSG_RESULT([yes]); XENIX=yes], [AC_MSG_RESULT([no]); XENIX=])
Don’t use this macro, the dignified means to check the nature of the
host is using AC_CANONICAL_HOST
(see Getting the Canonical System Type).
This macro was renamed AC_DECL_YYTEXT
, which in turn was
integrated into AC_PROG_LEX
(see AC_PROG_LEX).
Next: Upgrading From Version 2.13, Previous: Obsolete Macros, Up: Obsolete Constructs [Contents][Index]
Autoconf version 2 is mostly backward compatible with version 1.
However, it introduces better ways to do some things, and doesn’t
support some of the ugly things in version 1. So, depending on how
sophisticated your configure.ac files are, you might have to do
some manual work in order to upgrade to version 2. This chapter points
out some problems to watch for when upgrading. Also, perhaps your
configure
scripts could benefit from some of the new features in
version 2; the changes are summarized in the file NEWS in the
Autoconf distribution.
Next: Changed Makefiles, Up: Upgrading From Version 1 [Contents][Index]
If you have an aclocal.m4 installed with Autoconf (as opposed to
in a particular package’s source directory), you must rename it to
acsite.m4. See Using autoconf
to Create configure
.
If you distribute install.sh with your package, rename it to
install-sh so make
builtin rules don’t inadvertently
create a file called install from it. AC_PROG_INSTALL
looks for the script under both names, but it is best to use the new name.
If you were using config.h.top, config.h.bot, or
acconfig.h, you still can, but you have less clutter if you
use the AH_
macros. See Autoheader Macros.
Next: Changed Macros, Previous: Changed File Names, Up: Upgrading From Version 1 [Contents][Index]
Add ‘@CFLAGS@’, ‘@CPPFLAGS@’, and ‘@LDFLAGS@’ in
your Makefile.in files, so they can take advantage of the values
of those variables in the environment when configure
is run.
Doing this isn’t necessary, but it’s a convenience for users.
Also add ‘@configure_input@’ in a comment to each input file for
AC_OUTPUT
, so that the output files contain a comment saying
they were produced by configure
. Automatically selecting the
right comment syntax for all the kinds of files that people call
AC_OUTPUT
on became too much work.
Add config.log and config.cache to the list of files you
remove in distclean
targets.
If you have the following in Makefile.in:
prefix = /usr/local exec_prefix = $(prefix)
you must change it to:
prefix = @prefix@ exec_prefix = @exec_prefix@
The old behavior of replacing those variables without ‘@’ characters around them has been removed.
Next: Changed Results, Previous: Changed Makefiles, Up: Upgrading From Version 1 [Contents][Index]
Many of the macros were renamed in Autoconf version 2. You can still
use the old names, but the new ones are clearer, and it’s easier to find
the documentation for them. See Obsolete Macros, for a table showing the
new names for the old macros. Use the autoupdate
program to
convert your configure.ac to using the new macro names.
See Using autoupdate
to Modernize configure.ac.
Some macros have been superseded by similar ones that do the job better,
but are not call-compatible. If you get warnings about calling obsolete
macros while running autoconf
, you may safely ignore them, but
your configure
script generally works better if you follow
the advice that is printed about what to replace the obsolete macros with. In
particular, the mechanism for reporting the results of tests has
changed. If you were using echo
or AC_VERBOSE
(perhaps
via AC_COMPILE_CHECK
), your configure
script’s output
looks better if you switch to AC_MSG_CHECKING
and
AC_MSG_RESULT
. See Printing Messages. Those macros work best
in conjunction with cache variables. See Caching Results.
Next: Changed Macro Writing, Previous: Changed Macros, Up: Upgrading From Version 1 [Contents][Index]
If you were checking the results of previous tests by examining the
shell variable DEFS
, you need to switch to checking the values of
the cache variables for those tests. DEFS
no longer exists while
configure
is running; it is only created when generating output
files. This difference from version 1 is because properly quoting the
contents of that variable turned out to be too cumbersome and
inefficient to do every time AC_DEFINE
is called. See Cache Variable Names.
For example, here is a configure.ac fragment written for Autoconf version 1:
AC_HAVE_FUNCS(syslog) case "$DEFS" in *-DHAVE_SYSLOG*) ;; *) # syslog is not in the default libraries. See if it's in some other. saved_LIBS="$LIBS" for lib in bsd socket inet; do AC_CHECKING(for syslog in -l$lib) LIBS="-l$lib $saved_LIBS" AC_HAVE_FUNCS(syslog) case "$DEFS" in *-DHAVE_SYSLOG*) break ;; *) ;; esac LIBS="$saved_LIBS" done ;; esac
Here is a way to write it for version 2:
AC_CHECK_FUNCS([syslog]) if test "x$ac_cv_func_syslog" = xno; then # syslog is not in the default libraries. See if it's in some other. for lib in bsd socket inet; do AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) LIBS="-l$lib $LIBS"; break]) done fi
If you were working around bugs in AC_DEFINE_UNQUOTED
by adding
backslashes before quotes, you need to remove them. It now works
predictably, and does not treat quotes (except back quotes) specially.
See Setting Output Variables.
All of the Boolean shell variables set by Autoconf macros now use ‘yes’ for the true value. Most of them use ‘no’ for false, though for backward compatibility some use the empty string instead. If you were relying on a shell variable being set to something like 1 or ‘t’ for true, you need to change your tests.
Previous: Changed Results, Up: Upgrading From Version 1 [Contents][Index]
When defining your own macros, you should now use AC_DEFUN
instead of define
. AC_DEFUN
automatically calls
AC_PROVIDE
and ensures that macros called via AC_REQUIRE
do not interrupt other macros, to prevent nested ‘checking…’
messages on the screen. There’s no actual harm in continuing to use the
older way, but it’s less convenient and attractive. See Macro Definitions.
You probably looked at the macros that came with Autoconf as a guide for how to do things. It would be a good idea to take a look at the new versions of them, as the style is somewhat improved and they take advantage of some new features.
If you were doing tricky things with undocumented Autoconf internals (macros, variables, diversions), check whether you need to change anything to account for changes that have been made. Perhaps you can even use an officially supported technique in version 2 instead of kludging. Or perhaps not.
To speed up your locally written feature tests, add caching to them. See whether any of your tests are of general enough usefulness to encapsulate them into macros that you can share.
Previous: Upgrading From Version 1, Up: Obsolete Constructs [Contents][Index]
The introduction of the previous section (see Upgrading From Version 1) perfectly suits this section...
Autoconf version 2.50 is mostly backward compatible with version 2.13. However, it introduces better ways to do some things, and doesn’t support some of the ugly things in version 2.13. So, depending on how sophisticated your configure.ac files are, you might have to do some manual work in order to upgrade to version 2.50. This chapter points out some problems to watch for when upgrading. Also, perhaps your
configure
scripts could benefit from some of the new features in version 2.50; the changes are summarized in the file NEWS in the Autoconf distribution.
AC_LIBOBJ
vs. LIBOBJS
AC_ACT_IFELSE
vs. AC_TRY_ACT
Next: New Macros, Up: Upgrading From Version 2.13 [Contents][Index]
The most important changes are invisible to you: the implementation of most macros have completely changed. This allowed more factorization of the code, better error messages, a higher uniformity of the user’s interface etc. Unfortunately, as a side effect, some construct which used to (miraculously) work might break starting with Autoconf 2.50. The most common culprit is bad quotation.
For instance, in the following example, the message is not properly quoted:
AC_INIT AC_CHECK_HEADERS(foo.h, , AC_MSG_ERROR(cannot find foo.h, bailing out)) AC_OUTPUT
Autoconf 2.13 simply ignores it:
$ autoconf-2.13; ./configure --silent creating cache ./config.cache configure: error: cannot find foo.h $
while Autoconf 2.50 produces a broken configure:
$ autoconf-2.50; ./configure --silent configure: error: cannot find foo.h ./configure: exit: bad non-numeric arg `bailing' ./configure: exit: bad non-numeric arg `bailing' $
The message needs to be quoted, and the AC_MSG_ERROR
invocation
too!
AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AC_CHECK_HEADERS([foo.h], [], [AC_MSG_ERROR([cannot find foo.h, bailing out])]) AC_OUTPUT
Many many (and many more) Autoconf macros were lacking proper quotation,
including no less than… AC_DEFUN
itself!
$ cat configure.in AC_DEFUN([AC_PROG_INSTALL], [# My own much better version ]) AC_INIT AC_PROG_INSTALL AC_OUTPUT $ autoconf-2.13 autoconf: Undefined macros: ***BUG in Autoconf--please report*** AC_FD_MSG ***BUG in Autoconf--please report*** AC_EPI configure.in:1:AC_DEFUN([AC_PROG_INSTALL], configure.in:5:AC_PROG_INSTALL $ autoconf-2.50 $
Next: Hosts and Cross-Compilation, Previous: Changed Quotation, Up: Upgrading From Version 2.13 [Contents][Index]
While Autoconf was relatively dormant in the late 1990s, Automake
provided Autoconf-like macros for a while. Starting with Autoconf 2.50
in 2001, Autoconf provided
versions of these macros, integrated in the AC_
namespace,
instead of AM_
. But in order to ease the upgrading via
autoupdate
, bindings to such AM_
macros are provided.
Unfortunately older versions of Automake (e.g., Automake 1.4)
did not quote the names of these macros.
Therefore, when m4
finds something like
‘AC_DEFUN(AM_TYPE_PTRDIFF_T, …)’ in aclocal.m4,
AM_TYPE_PTRDIFF_T
is
expanded, replaced with its Autoconf definition.
Fortunately Autoconf catches pre-AC_INIT
expansions, and
complains, in its own words:
$ cat configure.ac AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AM_TYPE_PTRDIFF_T $ aclocal-1.4 $ autoconf aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion aclocal.m4:17: the top level autom4te: m4 failed with exit status: 1 $
Modern versions of Automake no longer define most of these macros, and properly quote the names of the remaining macros. If you must use an old Automake, do not depend upon macros from Automake as it is simply not its job to provide macros (but the one it requires itself):
$ cat configure.ac AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AM_TYPE_PTRDIFF_T $ rm aclocal.m4 $ autoupdate autoupdate: `configure.ac' is updated $ cat configure.ac AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AC_CHECK_TYPES([ptrdiff_t]) $ aclocal-1.4 $ autoconf $
Next: AC_LIBOBJ
vs. LIBOBJS
, Previous: New Macros, Up: Upgrading From Version 2.13 [Contents][Index]
Based on the experience of compiler writers, and after long public debates, many aspects of the cross-compilation chain have changed:
configure
,
configure
,
The relationship between build, host, and target have been cleaned up:
the chain of default is now simply: target defaults to host, host to
build, and build to the result of config.guess
. Nevertheless,
in order to ease the transition from 2.13 to 2.50, the following
transition scheme is implemented. Do not rely on it, as it will
be completely disabled in a couple of releases (we cannot keep it, as it
proves to cause more problems than it cures).
They all default to the result of running config.guess
, unless
you specify either --build or --host. In this case,
the default becomes the system type you specified. If you specify both,
and they’re different, configure
enters cross compilation
mode, so it doesn’t run any tests that require execution.
Hint: if you mean to override the result of config.guess
,
prefer --build over --host.
For backward compatibility, configure
accepts a system
type as an option by itself. Such an option overrides the
defaults for build, host, and target system types. The following
configure statement configures a cross toolchain that runs on
NetBSD/alpha but generates code for GNU Hurd/sparc,
which is also the build platform.
./configure --host=alpha-netbsd sparc-gnu
In Autoconf 2.13 and before, the variables build
, host
,
and target
had a different semantics before and after the
invocation of AC_CANONICAL_BUILD
etc. Now, the argument of
--build is strictly copied into build_alias
, and is left
empty otherwise. After the AC_CANONICAL_BUILD
, build
is
set to the canonicalized build type. To ease the transition, before,
its contents is the same as that of build_alias
. Do not
rely on this broken feature.
For consistency with the backward compatibility scheme exposed above, when --host is specified but --build isn’t, the build system is assumed to be the same as --host, and ‘build_alias’ is set to that value. Eventually, this historically incorrect behavior will go away.
The former scheme to enable cross-compilation proved to cause more harm
than good, in particular, it used to be triggered too easily, leaving
regular end users puzzled in front of cryptic error messages.
configure
could even enter cross-compilation mode only
because the compiler was not functional. This is mainly because
configure
used to try to detect cross-compilation, instead of
waiting for an explicit flag from the user.
Now, configure
enters cross-compilation mode if and only if
--host is passed.
That’s the short documentation. To ease the transition between 2.13 and its successors, a more complicated scheme is implemented. Do not rely on the following, as it will be removed in the near future.
If you specify --host, but not --build, when
configure
performs the first compiler test it tries to run
an executable produced by the compiler. If the execution fails, it
enters cross-compilation mode. This is fragile. Moreover, by the time
the compiler test is performed, it may be too late to modify the
build-system type: other tests may have already been performed.
Therefore, whenever you specify --host, be sure to specify
--build too.
./configure --build=x86_64-pc-linux-gnu --host=x86_64-w64-mingw64
enters cross-compilation mode. The former interface, which
consisted in setting the compiler to a cross-compiler without informing
configure
is obsolete. For instance, configure
fails if it can’t run the code generated by the specified compiler if you
configure as follows:
./configure CC=x86_64-w64-mingw64-gcc
Next: AC_ACT_IFELSE
vs. AC_TRY_ACT
, Previous: Hosts and Cross-Compilation, Up: Upgrading From Version 2.13 [Contents][Index]
AC_LIBOBJ
vs. LIBOBJS
Up to Autoconf 2.13, the replacement of functions was triggered via the
variable LIBOBJS
. Since Autoconf 2.50, the macro
AC_LIBOBJ
should be used instead (see Generic Function Checks).
Starting at Autoconf 2.53, the use of LIBOBJS
is an error.
This change is mandated by the unification of the GNU Build System
components. In particular, the various fragile techniques used to parse
a configure.ac are all replaced with the use of traces. As a
consequence, any action must be traceable, which obsoletes critical
variable assignments. Fortunately, LIBOBJS
was the only problem,
and it can even be handled gracefully (read, “without your having to
change something”).
There were two typical uses of LIBOBJS
: asking for a replacement
function, and adjusting LIBOBJS
for Automake and/or Libtool.
As for function replacement, the fix is immediate: use
AC_LIBOBJ
. For instance:
LIBOBJS="$LIBOBJS fnmatch.o" LIBOBJS="$LIBOBJS malloc.$ac_objext"
should be replaced with:
AC_LIBOBJ([fnmatch]) AC_LIBOBJ([malloc])
When used with Automake 1.10 or newer, a suitable value for
LIBOBJDIR
is set so that the LIBOBJS
and LTLIBOBJS
can be referenced from any Makefile.am. Even without Automake,
arranging for LIBOBJDIR
to be set correctly enables
referencing LIBOBJS
and LTLIBOBJS
in another directory.
The LIBOBJDIR
feature is experimental.
Previous: AC_LIBOBJ
vs. LIBOBJS
, Up: Upgrading From Version 2.13 [Contents][Index]
AC_ACT_IFELSE
vs. AC_TRY_ACT
Since Autoconf 2.50, internal codes uses AC_PREPROC_IFELSE
,
AC_COMPILE_IFELSE
, AC_LINK_IFELSE
, and
AC_RUN_IFELSE
on one hand and AC_LANG_SOURCE
,
and AC_LANG_PROGRAM
on the other hand instead of the deprecated
AC_TRY_CPP
, AC_TRY_COMPILE
, AC_TRY_LINK
, and
AC_TRY_RUN
. The motivations where:
AC_TRY_COMPILE
etc. were double
quoting their arguments;
In addition to the change of syntax, the philosophy has changed too: while emphasis was put on speed at the expense of accuracy, today’s Autoconf promotes accuracy of the testing framework at, ahem…, the expense of speed.
As a perfect example of what is not to be done, here is how to
find out whether a header file contains a particular declaration, such
as a typedef, a structure, a structure member, or a function. Use
AC_EGREP_HEADER
instead of running grep
directly on the
header file; on some systems the symbol might be defined in another
header file that the file you are checking includes.
As a (bad) example, here is how you should not check for C preprocessor
symbols, either defined by header files or predefined by the C
preprocessor: using AC_EGREP_CPP
:
AC_EGREP_CPP(yes, [#ifdef _AIX yes #endif ], is_aix=yes, is_aix=no)
The above example, properly written would (i) use
AC_LANG_PROGRAM
, and (ii) run the compiler:
AC_COMPILE_IFELSE([AC_LANG_PROGRAM( [[#ifndef _AIX error: This isn't AIX! #endif ]])], [is_aix=yes], [is_aix=no])
Next: Frequent Autoconf Questions, with answers, Previous: Obsolete Constructs, Up: Autoconf [Contents][Index]
N.B.: This section describes a feature which is still stabilizing. Although we believe that Autotest is useful as-is, this documentation describes an interface which might change in the future: do not depend upon Autotest without subscribing to the Autoconf mailing lists.
It is paradoxical that portable projects depend on nonportable tools to run their test suite. Autoconf by itself is the paragon of this problem: although it aims at perfectly portability, up to 2.13 its test suite was using DejaGNU, a rich and complex testing framework, but which is far from being standard on Posix systems. Worse yet, it was likely to be missing on the most fragile platforms, the very platforms that are most likely to torture Autoconf and exhibit deficiencies.
To circumvent this problem, many package maintainers have developed their own testing framework, based on simple shell scripts whose sole outputs are exit status values describing whether the test succeeded. Most of these tests share common patterns, and this can result in lots of duplicated code and tedious maintenance.
Following exactly the same reasoning that yielded to the inception of Autoconf, Autotest provides a test suite generation framework, based on M4 macros building a portable shell script. The suite itself is equipped with automatic logging and tracing facilities which greatly diminish the interaction with bug reporters, and simple timing reports.
Autoconf itself has been using Autotest for years, and we do attest that it has considerably improved the strength of the test suite and the quality of bug reports. Other projects are known to use some generation of Autotest, such as Bison, GNU Wdiff, GNU Tar, each of them with different needs, and this usage has validated Autotest as a general testing framework.
Nonetheless, compared to DejaGNU, Autotest is inadequate for interactive tool testing, which is probably its main limitation.
testsuite
Scriptstestsuite
ScriptsNext: Autotest Logs, Up: Using an Autotest Test Suite [Contents][Index]
testsuite
ScriptsGenerating testing or validation suites using Autotest is rather easy.
The whole validation suite is held in a file to be processed through
autom4te
, itself using GNU M4 under the hood, to
produce a stand-alone Bourne shell script which then gets distributed.
Neither autom4te
nor GNU M4 are needed at
the installer’s end.
Each test of the validation suite should be part of some test group. A test group is a sequence of interwoven tests that ought to be executed together, usually because one test in the group creates data files that a later test in the same group needs to read. Complex test groups make later debugging more tedious. It is much better to keep only a few tests per test group. Ideally there is only one test per test group.
For all but the simplest packages, some file such as testsuite.at does not fully hold all test sources, as these are often easier to maintain in separate files. Each of these separate files holds a single test group, or a sequence of test groups all addressing some common functionality in the package. In such cases, testsuite.at merely initializes the validation suite, and sometimes does elementary health checking, before listing include statements for all other test files. The special file package.m4, containing the identification of the package, is automatically included if found.
A convenient alternative consists in moving all the global issues
(local Autotest macros, elementary health checking, and AT_INIT
invocation) into the file local.at
, and making
testsuite.at be a simple list of m4_include
s of sub test
suites. In such case, generating the whole test suite or pieces of it
is only a matter of choosing the autom4te
command line
arguments.
The validation scripts that Autotest produces are by convention called
testsuite
. When run, testsuite
executes each test
group in turn, producing only one summary line per test to say if that
particular test succeeded or failed. At end of all tests, summarizing
counters get printed. One debugging directory is left for each test
group which failed, if any: such directories are named
testsuite.dir/nn, where nn is the sequence number of
the test group, and they include:
testsuite
Scripts). The automatic generation
of debugging scripts has the purpose of easing the chase for bugs.
AT_DATA
AT_CHECK_EUNIT
In the ideal situation, none of the tests fail, and consequently no debugging directory is left behind for validation.
It often happens in practice that individual tests in the validation
suite need to get information coming out of the configuration process.
Some of this information, common for all validation suites, is provided
through the file atconfig, automatically created by
AC_CONFIG_TESTDIR
. For configuration information which your
testing environment specifically needs, you might prepare an optional
file named atlocal.in, instantiated by AC_CONFIG_FILES
.
The configuration process produces atconfig and atlocal
out of these two input files, and these two produced files are
automatically read by the testsuite script.
Here is a diagram showing the relationship between files.
Files used in preparing a software package for distribution:
[package.m4] -->. \ subfile-1.at ->. [local.at] ---->+ ... \ \ subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite ... / subfile-n.at ->'
Files used in configuring a software package:
.--> atconfig / [atlocal.in] --> config.status* --< \ `--> [atlocal]
Files created during test suite execution:
atconfig -->. .--> testsuite.log \ / >-- testsuite* --< / \ [atlocal] ->' `--> [testsuite.dir]
Previous: testsuite
Scripts, Up: Using an Autotest Test Suite [Contents][Index]
When run, the test suite creates a log file named after itself, e.g., a
test suite named testsuite
creates testsuite.log. It
contains a lot of information, usually more than maintainers actually
need, but therefore most of the time it contains all that is needed:
A bad but unfortunately widespread habit consists of
setting environment variables before the command, such as in
‘CC=my-home-grown-cc ./testsuite’. The test suite does not
know this change, hence (i) it cannot report it to you, and (ii)
it cannot preserve the value of CC
for subsequent runs.
Autoconf faced exactly the same problem, and solved it by asking
users to pass the variable definitions as command line arguments.
Autotest requires this rule, too, but has no means to enforce it; the log
then contains a trace of the variables that were changed by the user.
The topmost lines of all the ChangeLog files found in the source hierarchy. This is especially useful when bugs are reported against development versions of the package, since the version string does not provide sufficient information to know the exact state of the sources the user compiled. Of course, this relies on the use of a ChangeLog.
Running a test suite in a cross-compile environment is not an easy task, since it would mean having the test suite run on a machine build, while running programs on a machine host. It is much simpler to run both the test suite and the programs on host, but then, from the point of view of the test suite, there remains a single environment, host = build. The log contains relevant information on the state of the build machine, including some important environment variables.
The absolute file name and answers to --version of the tested
programs (see Writing testsuite.at, AT_TESTED
).
The contents of config.log, as created by configure
,
are appended. It contains the configuration flags and a detailed report
on the configuration itself.
Next: Running testsuite
Scripts, Previous: Using an Autotest Test Suite, Up: Generating Test Suites with Autotest [Contents][Index]
The testsuite.at is a Bourne shell script making use of special
Autotest M4 macros. It often contains a call to AT_INIT
near
its beginning followed by one call to m4_include
per source file
for tests. Each such included file, or the remainder of
testsuite.at if include files are not used, contain a sequence of
test groups. Each test group begins with a call to AT_SETUP
,
then an arbitrary number of shell commands or calls to AT_CHECK
,
and then completes with a call to AT_CLEANUP
. Multiple test
groups can be categorized by a call to AT_BANNER
.
All of the public Autotest macros have all-uppercase names in the namespace ‘^AT_’ to prevent them from accidentally conflicting with other text; Autoconf also reserves the namespace ‘^_AT_’ for internal macros. All shell variables used in the testsuite for internal purposes have mostly-lowercase names starting with ‘at_’. Autotest also uses here-document delimiters in the namespace ‘^_AT[A-Z]’, and makes use of the file system namespace ‘^at-’.
Since Autoconf is built on top of M4sugar (see Programming in M4sugar) and M4sh (see Programming in M4sh), you must also be aware of those namespaces (‘^_?\(m4\|AS\)_’). In general, you should not use the namespace of a package that does not own the macro or shell code you are writing.
Initialize Autotest. Giving a name to the test suite is
encouraged if your package includes several test suites. Before this
macro is called, AT_PACKAGE_STRING
and
AT_PACKAGE_BUGREPORT
must be defined, which are used to display
information about the testsuite to the user. Typically, these macros
are provided by a file package.m4 built by make
(see Making testsuite
Scripts), in order to inherit the package
name, version, and bug reporting address from configure.ac.
State that, in addition to the Free Software Foundation’s copyright on the Autotest macros, parts of your test suite are covered by copyright-notice.
The copyright-notice shows up in both the head of
testsuite
and in ‘testsuite --version’.
Accept options from the space-separated list options, a list that
has leading dashes removed from the options. Long options will be
prefixed with ‘--’, single-character options with ‘-’. The
first word in this list is the primary option, any others are
assumed to be short-hand aliases. The variable associated with it
is at_arg_option
, with any dashes in option replaced
with underscores.
If the user passes --option to the testsuite
,
the variable will be set to ‘:’. If the user does not pass the
option, or passes --no-option, then the variable will be
set to ‘false’.
action-if-given is run each time the option is encountered; here,
the variable at_optarg
will be set to ‘:’ or ‘false’ as
appropriate. at_optarg
is actually just a copy of
at_arg_option
.
action-if-not-given will be run once after option parsing is complete and if no option from options was used.
help-text is added to the end of the list of options shown in
testsuite --help
(see AS_HELP_STRING).
It is recommended that you use a package-specific prefix to options names in order to avoid clashes with future Autotest built-in options.
Accept options with arguments from the space-separated list
options, a list that has leading dashes removed from the options.
Long options will be prefixed with ‘--’, single-character options
with ‘-’. The first word in this list is the primary option,
any others are assumed to be short-hand aliases. The variable associated
with it is at_arg_option
, with any dashes in option
replaced with underscores.
If the user passes --option=arg or
--option arg to the testsuite
, the
variable will be set to ‘arg’.
action-if-given is run each time the option is encountered; here,
the variable at_optarg
will be set to ‘arg’.
at_optarg
is actually just a copy of at_arg_option
.
action-if-not-given will be run once after option parsing is complete and if no option from options was used.
help-text is added to the end of the list of options shown in
testsuite --help
(see AS_HELP_STRING).
It is recommended that you use a package-specific prefix to options names in order to avoid clashes with future Autotest built-in options.
Enable colored test results by default when the output is connected to a terminal.
Log the file name and answer to --version of each program in space-separated list executables. Several invocations register new executables, in other words, don’t fear registering one program several times.
Autotest test suites rely on PATH
to find the tested program.
This avoids the need to generate absolute names of the various tools, and
makes it possible to test installed programs. Therefore, knowing which
programs are being exercised is crucial to understanding problems in
the test suite itself, or its occasional misuses. It is a good idea to
also subscribe foreign programs you depend upon, to avoid incompatible
diagnostics.
executables is implicitly wrapped in shell double quotes, but it
will still use shell variable expansion (‘$’), command substitution
(‘`’), and backslash escaping (‘\’). In particular, the
EXEEXT
variable is available if it is passed to the testsuite
via atlocal or atconfig.
Execute shell-code in the main testsuite process, after initializing the test suite and processing command-line options, but before running any tests. If this macro is used several times, all of the shell-codes will be executed, in the order they appeared in testsuite.at.
One reason to use AT_PREPARE_TESTS
is when the programs under
test are sensitive to environment variables: you can unset all these
variables or reset them to safe values in shell-code.
shell-code is only executed if at least one test is going to be
run. In particular, it will not be executed if any of the --help,
--version, --list, or --clean options are
given to testsuite
(see Running testsuite
Scripts).
Execute shell-code in each test group’s subshell, at the point of
the AT_SETUP
that starts the test group.
Define a shell function that will be available to the code for each test
group. Its name will be ath_fn_name
, and its body will be
code. (The prefix prevents name conflicts with shell functions
defined by M4sh and Autotest.)
args should describe the function’s arguments and description what it does; these are used only for documentation comments in the generated testsuite script.
This macro identifies the start of a category of related test groups. When the resulting testsuite is invoked with more than one test group to run, its output will include a banner containing test-category-name prior to any tests run from that category. The banner should be no more than about 40 or 50 characters. A blank banner indicates uncategorized tests; an empty line will be inserted after tests from an earlier category, effectively ending that category.
This macro starts a group of related tests, all to be executed in the same subshell. It accepts a single argument, which holds a few words (no more than about 30 or 40 characters) quickly describing the purpose of the test group being started. test-group-name must not expand to unbalanced quotes, although quadrigraphs can be used.
Associate the space-separated list of keywords to the enclosing
test group. This makes it possible to run “slices” of the test suite.
For instance, if some of your test groups exercise some ‘foo’
feature, then using ‘AT_KEYWORDS(foo)’ lets you run
‘./testsuite -k foo’ to run exclusively these test groups. The
test-group-name of the test group is automatically recorded to
AT_KEYWORDS
.
Several invocations within a test group accumulate new keywords. In other words, don’t fear registering the same keyword several times in a test group.
If the current test group fails, log the contents of file. Several identical calls within one test group have no additional effect.
Make the test group fail and skip the rest of its execution, if
shell-condition is true. shell-condition is a shell expression
such as a test
command. Tests before AT_FAIL_IF
will be executed and may still cause the test group to be skipped.
You can instantiate this macro many times from within the same test group.
You should use this macro only for very simple failure conditions. If the
shell-condition could emit any kind of output you should instead
use AT_CHECK
like
AT_CHECK([if shell-condition; then exit 99; fi])
so that such output is properly recorded in the testsuite.log file.
Determine whether the test should be skipped because it requires
features that are unsupported on the machine under test.
shell-condition is a shell expression such as a test
command. Tests before AT_SKIP_IF
will be executed
and may still cause the test group to fail. You can instantiate this
macro many times from within the same test group.
You should use this macro only for very simple skip conditions. If the
shell-condition could emit any kind of output you should instead
use AT_CHECK
like
AT_CHECK([if shell-condition; then exit 77; fi])
so that such output is properly recorded in the testsuite.log file.
Determine whether the test is expected to fail because it is a known
bug (for unsupported features, you should skip the test).
shell-condition is a shell expression such as a test
command; you can instantiate this macro many times from within the
same test group, and one of the conditions is enough to turn
the test into an expected failure.
End the current test group.
Initialize an input data file with given contents. Of course, the contents have to be properly quoted between square brackets to protect against included commas or spurious M4 expansion. contents must be empty or end with a newline. file must be a single shell word that expands into a single file name.
The difference between AT_DATA
and AT_DATA_UNQUOTED
is
that only the latter performs shell variable expansion (‘$’),
command substitution (‘`’), and backslash escaping (‘\’)
on contents.
Perform a test, by running the shell commands in a subshell. commands is output as-is, so shell expansions are honored. These commands are expected to have a final exit status of status, and to produce output as described by stdout and stderr (see below).
This macro must be invoked in between AT_SETUP
and AT_CLEANUP
.
If commands exit with unexpected status 77, then the rest of the test group is skipped. If commands exit with unexpected status 99, then the test group is immediately failed; this is called a hard failure. Otherwise, the test is considered to have succeeeded if all of the status, stdout, and stderr expectations were met.
If run-if-fail is nonempty, it provides extra shell commands to
run when the test fails; if run-if-pass is nonempty, it provides
extra shell commands to run when the test succeeds. These commands are
not run in a subshell, and they are not run when the test group
is skipped (exit code 77) or hard-failed (exit code 99). They may
change whether the test group is considered to have succeeded, by
modifying the shell variable at_failed
; set it to :
to
indicate that the test group has failed, or false
to indicate
that it has succeeded.
The exit status of commands is available to run-if-fail and
run-if-pass commands in the at_status
shell variable. The
output from commands is also available, in the files named by the
at_stdout
and at_stderr
variables.
If status is the literal ‘ignore’, then the exit status of
commands is not checked, except for the special cases of 77 (skip)
and 99 (hard failure). The existence of hard failures allows one to
mark a test as an expected failure with AT_XFAIL_IF
because a
feature has not yet been implemented, but to still distinguish between
gracefully handling the missing feature and dumping core.
If the value of the stdout or stderr parameter is one of the literals in the following table, then the test treats the output according to the rules of that literal.
The content of the output is ignored, but still captured in the test group log (if the testsuite is run with the -v option, the test group log is displayed as the test is run; if the test group later fails, the test group log is also copied into the overall testsuite log). This action is valid for both stdout and stderr.
The content of the output is ignored, and nothing is captured in the log
files. If commands are likely to produce binary output (including
long lines) or large amounts of output, then logging the output can make
it harder to locate details related to subsequent tests within the
group, and could potentially corrupt terminal display of a user running
testsuite -v
. This action is valid for both stdout and
stderr.
Only valid as the stdout parameter. Capture the content of
standard output in both a file named stdout and the test group log.
Subsequent commands in the test group can then post-process the file.
This action is often used when it is desired to use grep
to
look for a substring in the output, or when the output must be
post-processed to normalize error messages into a common form.
Only valid as the stderr parameter. Capture the content of standard error in both a file named stderr and the test group log.
Like ‘stdout’ or ‘stderr’, except that the captured output is not duplicated into the test group log. This action is particularly useful for an intermediate check that produces large amounts of data, which will be followed by another check that filters down to the relevant data, as it makes it easier to locate details in the log.
Only valid as the stdout parameter. Compare standard output with the previously created file expout, and list any differences in the testsuite log.
Only valid as the stderr parameter. Compare standard error with the previously created file experr, and list any differences in the testsuite log.
Otherwise, the values of the stdout and stderr parameters are treated as text that must exactly match the output given by commands on standard output and standard error (including an empty parameter for no output); any differences are captured in the testsuite log and the test is failed (unless an unexpected exit status of 77 skipped the test instead).
AT_CHECK_UNQUOTED
performs shell variable expansion (‘$’),
command substitution (‘`’), and backslash escaping (‘\’) on
comparison text given in the stdout and stderr parameters;
AT_CHECK
does not. There is no difference in the interpretation
of commands.
Initialize and execute an Erlang module named module that performs tests following the test-spec EUnit test specification. test-spec must be a valid EUnit test specification, as defined in the EUnit Reference Manual. erlflags are optional command-line options passed to the Erlang interpreter to execute the test Erlang module. Typically, erlflags defines at least the paths to directories containing the compiled Erlang modules under test, as ‘-pa path1 path2 ...’.
For example, the unit tests associated with Erlang module ‘testme’, which compiled code is in subdirectory src, can be performed with:
AT_CHECK_EUNIT([testme_testsuite], [{module, testme}], [-pa "${abs_top_builddir}/src"])
This macro must be invoked in between AT_SETUP
and AT_CLEANUP
.
Variables ERL
, ERLC
, and (optionally) ERLCFLAGS
must be defined as the path of the Erlang interpreter, the path of the
Erlang compiler, and the command-line flags to pass to the compiler,
respectively. Those variables should be configured in
configure.ac using the AC_ERLANG_PATH_ERL
and
AC_ERLANG_PATH_ERLC
macros, and the configured values of those
variables are automatically defined in the testsuite. If ERL
or
ERLC
is not defined, the test group is skipped.
If the EUnit library cannot be found, i.e. if module eunit
cannot
be loaded, the test group is skipped. Otherwise, if test-spec is
an invalid EUnit test specification, the test group fails. Otherwise,
if the EUnit test passes, shell commands run-if-pass are executed
or, if the EUnit test fails, shell commands run-if-fail are
executed and the test group fails.
Only the generated test Erlang module is automatically compiled and executed. If test-spec involves testing other Erlang modules, e.g. module ‘testme’ in the example above, those modules must be already compiled.
If the testsuite is run in verbose mode and with the --verbose option, EUnit is also run in verbose mode to output more details about individual unit tests.
Next: Making testsuite
Scripts, Previous: Writing testsuite.at, Up: Generating Test Suites with Autotest [Contents][Index]
testsuite
ScriptsAutotest test suites support the following options:
Display the list of options and exit successfully.
Display the version of the test suite and exit successfully.
Change the current directory to dir before creating any files. Useful for running the testsuite in a subdirectory from a top-level Makefile.
Run n tests in parallel, if possible. If n is not given, run all given tests in parallel. Note that there should be no space before the argument to -j, as -j number denotes the separate arguments -j and number, see below.
In parallel mode, the standard input device of the testsuite script is not available to commands inside a test group. Furthermore, banner lines are not printed, and the summary line for each test group is output after the test group completes. Summary lines may appear unordered. If verbose and trace output are enabled (see below), they may appear intermixed from concurrently running tests.
Parallel mode requires the mkfifo
command to work, and will be
silently disabled otherwise.
Remove all the files the test suite might have created and exit. Meant
for clean
Make targets.
List all the tests (or only the selection), including their possible keywords.
By default all tests are performed (or described with --list) silently in the default environment, but the environment, set of tests, and verbosity level can be tuned:
Set the environment variable to value. Use this rather than ‘FOO=foo ./testsuite’ as debugging scripts would then run in a different environment.
The variable AUTOTEST_PATH
specifies the testing path to prepend
to PATH
. Relative directory names (not starting with
‘/’) are considered to be relative to the top level of the
package being built. All directories are made absolute, first
starting from the top level build tree, then from the
source tree. For instance ‘./testsuite
AUTOTEST_PATH=tests:bin’ for a /src/foo-1.0 source package built
in /tmp/foo results in ‘/tmp/foo/tests:/tmp/foo/bin’ and
then ‘/src/foo-1.0/tests:/src/foo-1.0/bin’ being prepended to
PATH
.
Add the corresponding test groups, with obvious semantics, to the selection.
Add to the selection the test groups with title or keywords (arguments
to AT_SETUP
or AT_KEYWORDS
) that match all keywords
of the comma separated list keywords, case-insensitively. Use
‘!’ immediately before the keyword to invert the selection for this
keyword. By default, the keywords match whole words; enclose them in
‘.*’ to also match parts of words.
For example, running
./testsuite -k 'autoupdate,.*FUNC.*'
selects all tests tagged ‘autoupdate’ and with tags containing ‘FUNC’ (as in ‘AC_CHECK_FUNC’, ‘AC_FUNC_ALLOCA’, etc.), while
./testsuite -k '!autoupdate' -k '.*FUNC.*'
selects all tests not tagged ‘autoupdate’ or with tags containing ‘FUNC’.
If any test fails, immediately abort testing. This implies --debug: post test group clean up, and top-level logging are inhibited. This option is meant for the full test suite, it is not really useful for generated debugging scripts. If the testsuite is run in parallel mode using --jobs, then concurrently running tests will finish before exiting.
Force more verbosity in the detailed output of what is being done. This is the default for debugging scripts.
Enable colored test results. Without an argument, or with ‘always’,
test results will be colored.  Otherwise, if either the macro AT_COLOR_TESTS
is used by
the testsuite author, or the argument ‘auto’ is given, then test
results are colored if standard output is connected to a terminal.
Do not remove the files after a test group was performed—but they are still removed before, therefore using this option is sane when running several test groups. Create debugging scripts. Do not overwrite the top-level log (in order to preserve a supposedly existing full log file). This is the default for debugging scripts, but it can also be useful to debug the testsuite itself.
Add to the selection all test groups that failed or passed unexpectedly during the last non-debugging test run.
Trigger shell tracing of the test groups.
Besides these options accepted by every Autotest testsuite, the
testsuite author might have added package-specific options
via the AT_ARG_OPTION
and AT_ARG_OPTION_ARG
macros
(see Writing testsuite.at); refer to testsuite --help
and
the package documentation for details.
Previous: Running testsuite
Scripts, Up: Generating Test Suites with Autotest [Contents][Index]
testsuite
ScriptsFor putting Autotest into movement, you need some configuration and makefile machinery. We recommend, at least if your package uses deep or shallow hierarchies, that you use tests/ as the name of the directory holding all your tests and their makefile. Here is a check list of things to do, followed by an example, taking into consideration whether you are also using Automake.
AT_PACKAGE_STRING
, the
full signature of the package, and AT_PACKAGE_BUGREPORT
, the
address to which bug reports should be sent. For sake of completeness,
we suggest that you also define AT_PACKAGE_NAME
,
AT_PACKAGE_TARNAME
, AT_PACKAGE_VERSION
, and
AT_PACKAGE_URL
.
See Initializing configure
, for a description of these variables.
Be sure to distribute package.m4 and to put it into the source
hierarchy: the test suite ought to be shipped! See below for an example.
AC_CONFIG_TESTDIR
in your configure.ac.
An Autotest test suite is to be configured in directory. This
macro causes directory/atconfig to be created by
config.status
and sets the default AUTOTEST_PATH
to
test-path (see Running testsuite
Scripts).
AC_CONFIG_FILES
command includes substitution for
tests/atlocal.
AUTOM4TE
variable to be set.
The following example demonstrates the above checklist, first by assuming that you are using Automake (see below for tweaks to make to get the same results without Automake). Begin by adding the following lines to your configure.ac:
# Initialize the test suite. AC_CONFIG_TESTDIR([tests]) AC_CONFIG_FILES([tests/Makefile tests/atlocal]) AM_MISSING_PROG([AUTOM4TE], [autom4te])
Next, add the following lines to your tests/Makefile.am, in order to link ‘make check’ with a validation suite.
# The ':;' works around a Bash 3.2 bug when the output is not writable. $(srcdir)/package.m4: $(top_srcdir)/configure.ac :;{ \ echo '# Signature of the current package.' && \ echo 'm4_define([AT_PACKAGE_NAME],' && \ echo ' [$(PACKAGE_NAME)])' && \ echo 'm4_define([AT_PACKAGE_TARNAME],' && \ echo ' [$(PACKAGE_TARNAME)])' && \ echo 'm4_define([AT_PACKAGE_VERSION],' && \ echo ' [$(PACKAGE_VERSION)])' && \ echo 'm4_define([AT_PACKAGE_STRING],' && \ echo ' [$(PACKAGE_STRING)])' && \ echo 'm4_define([AT_PACKAGE_BUGREPORT],' && \ echo ' [$(PACKAGE_BUGREPORT)])'; \ echo 'm4_define([AT_PACKAGE_URL],' && \ echo ' [$(PACKAGE_URL)])'; \ } >'$(srcdir)/package.m4' EXTRA_DIST = testsuite.at $(srcdir)/package.m4 $(TESTSUITE) atlocal.in TESTSUITE = $(srcdir)/testsuite check-local: atconfig atlocal $(TESTSUITE) $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) installcheck-local: atconfig atlocal $(TESTSUITE) $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ $(TESTSUITEFLAGS) clean-local: test ! -f '$(TESTSUITE)' || \ $(SHELL) '$(TESTSUITE)' --clean AUTOTEST = $(AUTOM4TE) --language=autotest $(TESTSUITE): $(srcdir)/testsuite.at $(srcdir)/package.m4 $(AUTOTEST) -I '$(srcdir)' -o<EMAIL_ADDRESS><EMAIL_ADDRESS>mv<EMAIL_ADDRESS>$@
Note that the built testsuite is distributed; this is necessary because
users might not have Autoconf installed, and thus would not be able to
rebuild it. Likewise, the use of Automake’s AM_MISSING_PROG
will
arrange for the definition of $AUTOM4TE
within the Makefile to
provide the user with
a nicer error message if they modify a source file to the testsuite, and
accidentally trigger the rebuild rules.
You might want to list explicitly the dependencies, i.e., the list of the files testsuite.at includes.
If you don’t use Automake, you should make the following tweaks. In
your configure.ac, replace the AM_MISSING_PROG
line above
with AC_PATH_PROG([AUTOM4TE], [autom4te], [false])
. You are
welcome to also try using the missing
script from the Automake
project instead of false
, to try to get a nicer error message
when the user modifies prerequisites but did not have Autoconf
installed, but at that point you may be better off using Automake.
Then, take the code suggested above for tests/Makefile.am and
place it in your tests/Makefile.in instead. Add code to your
tests/Makefile.in to ensure that $(EXTRA_DIST)
files are
distributed, as well as adding the following additional lines to prepare
the set of needed Makefile variables:
subdir = tests PACKAGE_NAME = @PACKAGE_NAME@ PACKAGE_TARNAME = @PACKAGE_TARNAME@ PACKAGE_VERSION = @PACKAGE_VERSION@ PACKAGE_STRING = @PACKAGE_STRING@ PACKAGE_BUGREPORT = @PACKAGE_BUGREPORT@ PACKAGE_URL = @PACKAGE_URL@ AUTOM4TE = @AUTOM4TE@ atconfig: $(top_builddir)/config.status cd $(top_builddir) && \ $(SHELL) ./config.status $(subdir)/$@ atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status cd $(top_builddir) && \ $(SHELL) ./config.status $(subdir)/$@
Using the above example (with or without Automake), and assuming you were careful to not initialize ‘TESTSUITEFLAGS’ within your makefile, you can now fine-tune test suite execution at runtime by altering this variable, for example:
make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g'
Next: History of Autoconf, Previous: Generating Test Suites with Autotest, Up: Autoconf [Contents][Index]
Several questions about Autoconf come up occasionally. Here some of them are addressed.
configure
Scripts#define
Installation Directories?configure
scriptsconfigure
ScriptsWhat are the restrictions on distributing configure
scripts that Autoconf generates? How does that affect my
programs that use them?
There are no restrictions on how the configuration scripts that Autoconf produces may be distributed or used. In Autoconf version 1, they were covered by the GNU General Public License. We still encourage software authors to distribute their work under terms like those of the GPL, but doing so is not required to use Autoconf.
Of the other files that might be used with configure
,
config.h.in is under whatever copyright you use for your
configure.ac. config.sub and config.guess have an
exception to the GPL when they are used with an Autoconf-generated
configure
script, which permits you to distribute them under the
same terms as the rest of your package. install-sh is from the X
Consortium and is not copyrighted.
Next: How Can I Bootstrap?, Previous: Distributing configure
Scripts, Up: Frequent Autoconf Questions, with answers [Contents][Index]
Why does Autoconf require GNU M4?
Many M4 implementations have hard-coded limitations on the size and number of macros that Autoconf exceeds. They also lack several builtin macros that it would be difficult to get along without in a sophisticated application like Autoconf, including:
m4_builtin m4_indir m4_bpatsubst __file__ __line__
Autoconf requires version 1.4.6 or later of GNU M4.
Since only software maintainers need to use Autoconf, and since GNU M4 is simple to configure and install, it seems reasonable to require GNU M4 to be installed also. Many maintainers of GNU and other free software already have most of the GNU utilities installed, since they prefer them.
Next: Why Not Imake?, Previous: Why Require GNU M4?, Up: Frequent Autoconf Questions, with answers [Contents][Index]
If Autoconf requires GNU M4 and GNU M4 has an Autoconf
configure
script, how do I bootstrap? It seems like a chicken
and egg problem!
This is a misunderstanding. Although GNU M4 does come with a
configure
script produced by Autoconf, Autoconf is not required
in order to run the script and install GNU M4. Autoconf is only
required if you want to change the M4 configure
script, which few
people have to do (mainly its maintainer).
Next: How Do I #define
Installation Directories?, Previous: How Can I Bootstrap?, Up: Frequent Autoconf Questions, with answers [Contents][Index]
Why not use Imake instead of configure
scripts?
Several people have written addressing this question, so adaptations of their explanations are included here.
The following answer is based on one written by Richard Pixley:
Autoconf generated scripts frequently work on machines that it has never been set up to handle before. That is, it does a good job of inferring a configuration for a new system. Imake cannot do this.
Imake uses a common database of host specific data. For X11, this makes sense because the distribution is made as a collection of tools, by one central authority who has control over the database.
GNU tools are not released this way. Each GNU tool has a maintainer; these maintainers are scattered across the world. Using a common database would be a maintenance nightmare. Autoconf may appear to be this kind of database, but in fact it is not. Instead of listing host dependencies, it lists program requirements.
If you view the GNU suite as a collection of native tools, then the problems are similar. But the GNU development tools can be configured as cross tools in almost any host+target permutation. All of these configurations can be installed concurrently. They can even be configured to share host independent files across hosts. Imake doesn’t address these issues.
Imake templates are a form of standardization. The GNU coding standards address the same issues without necessarily imposing the same restrictions.
Here is some further explanation, written by Per Bothner:
One of the advantages of Imake is that it is easy to generate large makefiles using the ‘#include’ and macro mechanisms of
cpp
. However,cpp
is not programmable: it has limited conditional facilities, and no looping. Andcpp
cannot inspect its environment.All of these problems are solved by using
sh
instead ofcpp
. The shell is fully programmable, has macro substitution, can execute (or source) other shell scripts, and can inspect its environment.
Paul Eggert elaborates more:
With Autoconf, installers need not assume that Imake itself is already installed and working well. This may not seem like much of an advantage to people who are accustomed to Imake. But on many hosts Imake is not installed or the default installation is not working well, and requiring Imake to install a package hinders the acceptance of that package on those hosts. For example, the Imake template and configuration files might not be installed properly on a host, or the Imake build procedure might wrongly assume that all source files are in one big directory tree, or the Imake configuration might assume one compiler whereas the package or the installer needs to use another, or there might be a version mismatch between the Imake expected by the package and the Imake supported by the host. These problems are much rarer with Autoconf, where each package comes with its own independent configuration processor.
Also, Imake often suffers from unexpected interactions between
make
and the installer’s C preprocessor. The fundamental problem here is that the C preprocessor was designed to preprocess C programs, not makefiles. This is much less of a problem with Autoconf, which uses the general-purpose preprocessor M4, and where the package’s author (rather than the installer) does the preprocessing in a standard way.
Finally, Mark Eichin notes:
Imake isn’t all that extensible, either. In order to add new features to Imake, you need to provide your own project template, and duplicate most of the features of the existing one. This means that for a sophisticated project, using the vendor-provided Imake templates fails to provide any leverage—since they don’t cover anything that your own project needs (unless it is an X11 program).
On the other side, though:
The one advantage that Imake has over
configure
: Imakefile files tend to be much shorter (likewise, less redundant) than Makefile.in files. There is a fix to this, however—at least for the Kerberos V5 tree, we’ve modified things to call in common post.in and pre.in makefile fragments for the entire tree. This means that a lot of common things don’t have to be duplicated, even though they normally are inconfigure
setups.
Next: What is autom4te.cache?, Previous: Why Not Imake?, Up: Frequent Autoconf Questions, with answers [Contents][Index]
#define
Installation Directories?My program needs library files, installed in datadir
and
similar. If I use
AC_DEFINE_UNQUOTED([DATADIR], [$datadir], [Define to the read-only architecture-independent data directory.])
I get
#define DATADIR "${prefix}/share"
As already explained, this behavior is on purpose, mandated by the GNU Coding Standards, see Installation Directory Variables. There are several means to achieve a similar goal:
AC_DEFINE
but use your makefile to pass the
actual value of datadir
via compilation flags.
See Installation Directory Variables, for the details.
CPPFLAGS
:
CPPFLAGS = -DDATADIR='"$(datadir)"' @CPPFLAGS@
If you are using Automake, you should use AM_CPPFLAGS
instead:
AM_CPPFLAGS = -DDATADIR='"$(datadir)"'
Alternatively, create a dedicated header file:
DISTCLEANFILES = myprog-paths.h myprog-paths.h: Makefile echo '#define DATADIR "$(datadir)"' >$@
The Gnulib module ‘configmake’ provides such a header with all the standard directory variables defined, see configmake in GNU Gnulib.
AC_DEFINE
but have configure
compute the literal
value of datadir
and others. Many people have wrapped macros to
automate this task; for an example, see the macro AC_DEFINE_DIR
from
the Autoconf Macro
Archive.
This solution does not conform to the GNU Coding Standards.
prefix
, and try to
find prefix
at runtime, this way your package is relocatable.
Next: Header Present But Cannot Be Compiled, Previous: How Do I #define
Installation Directories?, Up: Frequent Autoconf Questions, with answers [Contents][Index]
What is this directory autom4te.cache? Can I safely remove it?
In the GNU Build System, configure.ac plays a central
role and is read by many tools: autoconf
to create
configure, autoheader
to create config.h.in,
automake
to create Makefile.in, autoscan
to
check the completeness of configure.ac, autoreconf
to
check the GNU Build System components that are used. To
“read configure.ac” actually means to compile it with M4,
which can be a long process for complex configure.ac.
This is why all these tools, instead of running directly M4, invoke
autom4te
(see Invoking autom4te
) which, while answering to
a specific demand, stores additional information in
autom4te.cache for future runs. For instance, if you run
autoconf
, behind the scenes, autom4te
also
stores information for the other tools, so that when you invoke
autoheader
or automake
etc., reprocessing
configure.ac is not needed. The speed up is frequently 30%,
and is increasing with the size of configure.ac.
But it is and remains being simply a cache: you can safely remove it.
Can I permanently get rid of it?
The creation of this cache can be disabled from
~/.autom4te.cfg, see Customizing autom4te
, for more
details. You should be aware that disabling the cache slows down the
Autoconf test suite by 40%. The more GNU Build System
components are used, the more the cache is useful; for instance
running ‘autoreconf -f’ on the Core Utilities is twice slower without
the cache although --force implies that the cache is
not fully exploited, and eight times slower than without
--force.
Next: Expanded Before Required, Previous: What is autom4te.cache?, Up: Frequent Autoconf Questions, with answers [Contents][Index]
The most important guideline to bear in mind when checking for
features is to mimic as much as possible the intended use.
Unfortunately, old versions of AC_CHECK_HEADER
and
AC_CHECK_HEADERS
failed to follow this idea, and called
the preprocessor, instead of the compiler, to check for headers. As a
result, incompatibilities between headers went unnoticed during
configuration, and maintainers finally had to deal with this issue
elsewhere.
The transition began with Autoconf 2.56. As of Autoconf 2.64 both
checks are performed, and configure
complains loudly if the
compiler and the preprocessor do not agree. However, only the compiler
result is considered. As of Autoconf 2.70, only the compiler check is
performed.
Consider the following example:
$ cat number.h typedef int number; $ cat pi.h const number pi = 3; $ cat configure.ac AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AC_CHECK_HEADERS([pi.h]) $ autoconf -Wall $ ./configure CPPFLAGS='-I.' checking for gcc... gcc checking whether the C compiler works... yes checking for C compiler default output file name... a.out checking for suffix of executables... checking whether we are cross compiling... no checking for suffix of object files... o checking whether the compiler supports GNU C... yes checking whether gcc accepts -g... yes checking for gcc option to enable C11 features... -std=gnu11 checking for sys/types.h... yes checking for sys/stat.h... yes checking for strings.h... yes checking for inttypes.h... yes checking for stdint.h... yes checking for unistd.h... yes checking for pi.h... no
The proper way to handle this case is using the fourth argument (see Generic Header Checks):
$ cat configure.ac AC_INIT([Example], [1.0]<EMAIL_ADDRESS>AC_CHECK_HEADERS([number.h pi.h], [], [], [[#ifdef HAVE_NUMBER_H # include <number.h> #endif ]]) $ autoconf -Wall $ ./configure CPPFLAGS='-I.' checking for gcc... gcc checking whether the C compiler works... yes checking for C compiler default output file name... a.out checking for suffix of executables... checking whether we are cross compiling... no checking for suffix of object files... o checking whether the compiler supports GNU C... yes checking whether gcc accepts -g... yes checking for gcc option to enable C11 features... -std=gnu11 checking for number.h... yes checking for pi.h... yes
See Particular Header Checks, for a list of headers with their prerequisites.
Next: Debugging configure
scripts, Previous: Header Present But Cannot Be Compiled, Up: Frequent Autoconf Questions, with answers [Contents][Index]
Older versions of Autoconf silently built files with incorrect ordering between dependent macros if an outer macro first expanded, then later indirectly required, an inner macro. Starting with Autoconf 2.64, this situation no longer generates out-of-order code, but results in duplicate output and a syntax warning:
$ cat configure.ac ⇒AC_DEFUN([TESTA], [[echo in A ⇒if test -n "$SEEN_A" ; then echo duplicate ; fi ⇒SEEN_A=:]]) ⇒AC_DEFUN([TESTB], [AC_REQUIRE([TESTA])[echo in B ⇒if test -z "$SEEN_A" ; then echo bug ; fi]]) ⇒AC_DEFUN([TESTC], [AC_REQUIRE([TESTB])[echo in C]]) ⇒AC_DEFUN([OUTER], [[echo in OUTER] ⇒TESTA ⇒TESTC]) ⇒AC_INIT ⇒OUTER ⇒AC_OUTPUT $ autoconf ⇒configure.ac:11: warning: AC_REQUIRE: ⇒ `TESTA' was expanded before it was required ⇒configure.ac:4: TESTB is expanded from... ⇒configure.ac:6: TESTC is expanded from... ⇒configure.ac:7: OUTER is expanded from... ⇒configure.ac:11: the top level
To avoid this warning, decide what purpose the macro in question serves.
If it only needs to be expanded once (for example, if it provides
initialization text used by later macros), then the simplest fix is to
change the macro to be declared with AC_DEFUN_ONCE
(see One-Shot Macros), although this only works in Autoconf 2.64 and
newer. A more portable fix is to change all
instances of direct calls to instead go through AC_REQUIRE
(see Prerequisite Macros). If, instead, the macro is parameterized
by arguments or by the current definition of other macros in the m4
environment, then the macro should always be directly expanded instead
of required.
For another case study, consider this example trimmed down from an actual package. Originally, the package contained shell code and multiple macro invocations at the top level of configure.ac:
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([…])]) foobar= AC_PROG_CC FOO
but that was getting complex, so the author wanted to offload some of the text into a new macro in another file included via aclocal.m4. The naïve approach merely wraps the text in a new macro:
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([…])]) AC_DEFUN([BAR], [ foobar= AC_PROG_CC FOO ]) BAR
With older versions of Autoconf, the setting of ‘foobar=’ occurs
before the single compiler check, as the author intended. But with
Autoconf 2.64, this issues the “expanded before it was required”
warning for AC_PROG_CC
, and outputs two copies of the compiler
check, one before ‘foobar=’, and one after. To understand why this
is happening, remember that the use of AC_COMPILE_IFELSE
includes
a call to AC_REQUIRE([AC_PROG_CC])
under the hood. According to
the documented semantics of AC_REQUIRE
, this means that
AC_PROG_CC
must occur before the body of the outermost
AC_DEFUN
, which in this case is BAR
, thus preceding the
use of ‘foobar=’. The older versions of Autoconf were broken with
regards to the rules of AC_REQUIRE
, which explains why the code
changed from one over to two copies of AC_PROG_CC
when upgrading
autoconf. In other words, the author was unknowingly relying on a bug
exploit to get the desired results, and that exploit broke once the bug
was fixed.
So, what recourse does the author have, to restore their intended
semantics of setting ‘foobar=’ prior to a single compiler check,
regardless of whether Autoconf 2.63 or 2.64 is used? One idea is to
remember that only AC_DEFUN
is impacted by AC_REQUIRE
;
there is always the possibility of using the lower-level
m4_define
:
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([…])]) m4_define([BAR], [ foobar= AC_PROG_CC FOO ]) BAR
This works great if everything is in the same file. However, it does
not help in the case where the author wants to have aclocal
find the definition of BAR
from its own file, since
aclocal
requires the use of AC_DEFUN
. In this case, a
better fix is to recognize that if BAR
also uses
AC_REQUIRE
, then there will no longer be direct expansion prior
to a subsequent require. Then, by creating yet another helper macro,
the author can once again guarantee a single invocation of
AC_PROG_CC
, which will still occur after foobar=
. The
author can also use AC_BEFORE
to make sure no other macro
appearing before BAR
has triggered an unwanted expansion of
AC_PROG_CC
.
AC_DEFUN([FOO], [AC_COMPILE_IFELSE([…])]) AC_DEFUN([BEFORE_CC], [ foobar= ]) AC_DEFUN([BAR], [ AC_BEFORE([$0], [AC_PROG_CC])dnl AC_REQUIRE([BEFORE_CC])dnl AC_REQUIRE([AC_PROG_CC])dnl FOO ]) BAR
Previous: Expanded Before Required, Up: Frequent Autoconf Questions, with answers [Contents][Index]
configure
scriptsWhile in general, configure
scripts generated by Autoconf
strive to be fairly portable to various systems, compilers, shells, and
other tools, it may still be necessary to debug a failing test, broken
script or makefile, or fix or override an incomplete, faulty, or erroneous
test, especially during macro development. Failures can occur at all levels,
in M4 syntax or semantics, shell script issues, or due to bugs in the
test or the tools invoked by configure
. Together with the
rather arcane error message that m4
and make
may
produce when their input contains syntax errors, this can make debugging
rather painful.
Nevertheless, here is a list of hints and strategies that may help:
autoconf
fails, common causes for error include:
Typically, it helps to go back to the last working version of the input
and compare the differences for each of these errors. Another
possibility is to sprinkle pairs of m4_traceon
and
m4_traceoff
judiciously in the code, either without a parameter
or listing some macro names and watch m4
expand its input
verbosely (see Debugging via autom4te).
autoconf
succeeds but the generated
configure
script has invalid shell syntax. You can detect this
case by running ‘bash -n configure’ or ‘sh -n configure’.
If this command fails, the same tips apply, as if autoconf
had
failed.
configure
script execution may be done by sprinkling
pairs of set -x
and set +x
into the shell script before
and after the region that contains a bug. Running the whole script with
‘shell -vx ./configure 2>&1 | tee log-file’ with a decent
shell may work, but produces lots of output. Here, it can help to
search for markers like ‘checking for’ a particular test in the
log-file.
configure
tests produce invalid results for your system,
it may be necessary to override them:
make
run time with some care (see make macro=value
and Submakes). Since this
normally won’t cause configure
to be run again with these
changed settings, it may fail if the changed variable would have caused
different test results from configure
, so this may work only
for simple differences.
configure
command line (see Compilers and Options, see Defining Variables,
see Particular systems).
configure
command line as above, or through a primed cache or
site file (see Cache Files, see Setting Site Defaults). The name of a
cache variable is documented with a test macro or may be inferred from
Cache Variable Names; the precise semantics of undocumented
variables are often internal details, subject to change.
configure
may produce invalid results because
of uncaught programming errors, in your package or in an upstream
library package. For example, when AC_CHECK_LIB
fails to find a
library with a specified function, always check config.log. This
will reveal the exact error that produced the failing result: the
library linked by AC_CHECK_LIB
probably has a fatal bug.
Conversely, as macro author, you can make it easier for users of your macro:
make
variables to factorize and allow
override of settings at make
run time,
configure
tests,
Next: GNU Free Documentation License, Previous: Frequent Autoconf Questions, with answers, Up: Autoconf [Contents][Index]
This chapter was written by the original author, David MacKenzie.
You may be wondering, Why was Autoconf originally written? How did it get into its present form? (Why does it look like gorilla spit?) If you’re not wondering, then this chapter contains no information useful to you, and you might as well skip it. If you are wondering, then let there be light...
Next: Exodus, Up: History of Autoconf [Contents][Index]
In June 1991 I was maintaining many of the GNU utilities for the
Free Software Foundation. As they were ported to more platforms and
more programs were added, the number of -D options that users
had to select in the makefile (around 20) became burdensome.
Especially for me—I had to test each new release on a bunch of
different systems. So I wrote a little shell script to guess some of
the correct settings for the fileutils package, and released it as part
of fileutils 2.0. That configure
script worked well enough that
the next month I adapted it (by hand) to create similar configure
scripts for several other GNU utilities packages. Brian Berliner
also adapted one of my scripts for his CVS revision control system.
Later that summer, I learned that Richard Stallman and Richard Pixley
were developing similar scripts to use in the GNU compiler tools;
so I adapted my configure
scripts to support their evolving
interface: using the file name Makefile.in as the templates;
adding ‘+srcdir’, the first option (of many); and creating
config.status files.
Next: Leviticus, Previous: Genesis, Up: History of Autoconf [Contents][Index]
As I got feedback from users, I incorporated many improvements, using
Emacs to search and replace, cut and paste, similar changes in each of
the scripts. As I adapted more GNU utilities packages to use
configure
scripts, updating them all by hand became impractical.
Rich Murphey, the maintainer of the GNU graphics utilities, sent me
mail saying that the configure
scripts were great, and asking if
I had a tool for generating them that I could send him. No, I thought,
but I should! So I started to work out how to generate them. And the
journey from the slavery of hand-written configure
scripts to the
abundance and ease of Autoconf began.
Cygnus configure
, which was being developed at around that time,
is table driven; it is meant to deal mainly with a discrete number of
system types with a small number of mainly unguessable features (such as
details of the object file format). The automatic configuration system
that Brian Fox had developed for Bash takes a similar approach. For
general use, it seems to me a hopeless cause to try to maintain an
up-to-date database of which features each variant of each operating
system has. It’s easier and more reliable to check for most features on
the fly—especially on hybrid systems that people have hacked on
locally or that have patches from vendors installed.
I considered using an architecture similar to that of Cygnus
configure
, where there is a single configure
script that
reads pieces of configure.in when run. But I didn’t want to have
to distribute all of the feature tests with every package, so I settled
on having a different configure
made from each
configure.in by a preprocessor. That approach also offered more
control and flexibility.
I looked briefly into using the Metaconfig package, by Larry Wall,
Harlan Stenn, and Raphael Manfredi, but I decided not to for several
reasons. The Configure
scripts it produces are interactive,
which I find quite inconvenient; I didn’t like the ways it checked for
some features (such as library functions); I didn’t know that it was
still being maintained, and the Configure
scripts I had
seen didn’t work on many modern systems (such as System V R4 and NeXT);
it wasn’t flexible in what it could do in response to a feature’s
presence or absence; I found it confusing to learn; and it was too big
and complex for my needs (I didn’t realize then how much Autoconf would
eventually have to grow).
I considered using Perl to generate my style of configure
scripts, but decided that M4 was better suited to the job of simple
textual substitutions: it gets in the way less, because output is
implicit. Plus, everyone already has it. (Initially I didn’t rely on
the GNU extensions to M4.) Also, some of my friends at the
University of Maryland had recently been putting M4 front ends on
several programs, including tvtwm
, and I was interested in trying
out a new language.
Next: Numbers, Previous: Exodus, Up: History of Autoconf [Contents][Index]
Since my configure
scripts determine the system’s capabilities
automatically, with no interactive user intervention, I decided to call
the program that generates them Autoconfig. But with a version number
tacked on, that name would be too long for old Unix file systems,
so I shortened it to Autoconf.
In the fall of 1991 I called together a group of fellow questers after the Holy Grail of portability (er, that is, alpha testers) to give me feedback as I encapsulated pieces of my handwritten scripts in M4 macros and continued to add features and improve the techniques used in the checks. Prominent among the testers were François Pinard, who came up with the idea of making an Autoconf shell script to run M4 and check for unresolved macro calls; Richard Pixley, who suggested running the compiler instead of searching the file system to find include files and symbols, for more accurate results; Karl Berry, who got Autoconf to configure TeX and added the macro index to the documentation; and Ian Lance Taylor, who added support for creating a C header file as an alternative to putting -D options in a makefile, so he could use Autoconf for his UUCP package. The alpha testers cheerfully adjusted their files again and again as the names and calling conventions of the Autoconf macros changed from release to release. They all contributed many specific checks, great ideas, and bug fixes.
Next: Deuteronomy, Previous: Leviticus, Up: History of Autoconf [Contents][Index]
In July 1992, after months of alpha testing, I released Autoconf 1.0,
and converted many GNU packages to use it. I was surprised by how
positive the reaction to it was. More people started using it than I
could keep track of, including people working on software that wasn’t
part of the GNU Project (such as TCL, FSP, and Kerberos V5).
Autoconf continued to improve rapidly, as many people using the
configure
scripts reported problems they encountered.
Autoconf turned out to be a good torture test for M4 implementations. Unix M4 started to dump core because of the length of the macros that Autoconf defined, and several bugs showed up in GNU M4 as well. Eventually, we realized that we needed to use some features that only GNU M4 has. 4.3BSD M4, in particular, has an impoverished set of builtin macros; the System V version is better, but still doesn’t provide everything we need.
More development occurred as people put Autoconf under more stresses