| [Top] | [Contents] | [Index] | [ ? ] |
1. Introduction Autoconf's purpose, strengths, and weaknesses 2. The GNU Build System A set of tools for portable software packages 3. Making configureScriptsHow to organize and produce Autoconf scripts 4. Initialization and Output Files Initialization and output 5. Existing Tests Macros that check for particular features 6. Writing Tests How to write new feature checks 7. Results of Tests What to do with results from feature checks 8. Programming in M4 Layers on top of which Autoconf is written 9. Writing Autoconf Macros Adding new macros to Autoconf 10. Portable Shell Programming Shell script portability pitfalls 11. Manual Configuration Selecting features that can't be guessed 12. Site Configuration Local defaults for configure13. Running configureScriptsHow to use the Autoconf output 14. Recreating a Configuration Recreating a configuration 15. Obsolete Constructs Kept for backward compatibility 16. Generating Test Suites with Autotest Creating portable test suites 17. Frequent Autoconf Questions, with answers 18. History of Autoconf A. Copying This Manual How to make copies of this manual B. Indices Indices of symbols, concepts, etc.
-- The Detailed Node Listing ---
The GNU Build System
2.1 Automake Escaping Makefile hell 2.2 Libtool Building libraries portably 2.3 Pointers More info on the GNU build system
MakingconfigureScripts
3.1 Writing `configure.ac' What to put in an Autoconf input file 3.2 Using autoscanto Create `configure.ac'Semi-automatic `configure.ac' writing 3.3 Using ifnamesto List ConditionalsListing the conditionals in source code 3.4 Using autoconfto CreateconfigureHow to create configuration scripts 3.5 Using autoreconfto UpdateconfigureScriptsRemaking multiple configurescripts
Writing `configure.ac'
3.1.1 A Shell Script Compiler Autoconf as solution of a problem 3.1.2 The Autoconf Language Programming in Autoconf 3.1.3 Standard `configure.ac' Layout Standard organization of `configure.ac'
Initialization and Output Files
4.1 Initializing configureOption processing etc. 4.2 Notices in configureCopyright, version numbers in configure4.3 Finding configureInputWhere Autoconf should find files 4.4 Outputting Files Outputting results from the configuration 4.5 Performing Configuration Actions Preparing the output based on results 4.6 Creating Configuration Files Creating output files 4.7 Substitutions in Makefiles Using output variables in `Makefile's 4.8 Configuration Header Files Creating a configuration header file 4.9 Running Arbitrary Configuration Commands Running arbitrary instantiation commands 4.10 Creating Configuration Links Links depending on the configuration 4.11 Configuring Other Packages in Subdirectories Configuring independent packages together 4.12 Default Prefix Changing the default installation prefix
Substitutions in Makefiles
4.7.1 Preset Output Variables Output variables that are always set 4.7.2 Installation Directory Variables Other preset output variables 4.7.3 Build Directories Supporting multiple concurrent compiles 4.7.4 Automatic Remaking Makefile rules for configuring
Configuration Header Files
4.8.1 Configuration Header Templates Input for the configuration headers 4.8.2 Using autoheaderto Create `config.h.in'How to create configuration templates 4.8.3 Autoheader Macros How to specify CPP templates
Existing Tests
5.1 Common Behavior Macros' standard schemes 5.2 Alternative Programs Selecting between alternative programs 5.3 Files Checking for the existence of files 5.4 Library Files Library archives that might be missing 5.5 Library Functions C library functions that might be missing 5.6 Header Files Header files that might be missing 5.7 Declarations Declarations that may be missing 5.8 Structures Structures or members that might be missing 5.9 Types Types that might be missing 5.10 Compilers and Preprocessors Checking for compiling programs 5.11 System Services Operating system services 5.12 UNIX Variants Special kludges for specific UNIX variants
Common Behavior
5.1.1 Standard Symbols Symbols defined by the macros 5.1.2 Default Includes Includes used by the generic macros
Alternative Programs
5.2.1 Particular Program Checks Special handling to find certain programs 5.2.2 Generic Program and File Checks How to find other programs
Library Functions
5.5.1 Portability of C Functions Pitfalls with usual functions 5.5.2 Particular Function Checks Special handling to find certain functions 5.5.3 Generic Function Checks How to find other functions
Header Files
5.6.1 Portability of Headers Collected knowledge on common headers 5.6.2 Particular Header Checks Special handling to find certain headers 5.6.3 Generic Header Checks How to find other headers
Declarations
5.7.1 Particular Declaration Checks Macros to check for certain declarations 5.7.2 Generic Declaration Checks How to find other declarations
Structures
5.8.1 Particular Structure Checks Macros to check for certain structure members 5.8.2 Generic Structure Checks How to find other structure members
Types
5.9.1 Particular Type Checks Special handling to find certain types 5.9.2 Generic Type Checks How to find other types
Compilers and Preprocessors
5.10.1 Specific Compiler Characteristics Some portability issues 5.10.2 Generic Compiler Characteristics Language independent tests 5.10.3 C Compiler Characteristics Checking its characteristics 5.10.4 C++ Compiler Characteristics Likewise 5.10.5 Fortran 77 Compiler Characteristics Likewise
Writing Tests
6.1 Language Choice Selecting which language to use for testing 6.2 Writing Test Programs Forging source files for compilers 6.3 Running the Preprocessor Detecting preprocessor symbols 6.4 Running the Compiler Detecting language or header features 6.5 Running the Linker Detecting library features 6.6 Checking Run Time Behavior Testing for run-time features 6.7 Systemology A zoology of operating systems 6.8 Multiple Cases Tests for several possible values
Writing Test Programs
6.2.1 Guidelines for Test Programs General rules for writing test programs 6.2.2 Test Functions Avoiding pitfalls in test programs 6.2.3 Generating Sources Source program boilerplate
Results of Tests
7.1 Defining C Preprocessor Symbols Defining C preprocessor symbols 7.2 Setting Output Variables Replacing variables in output files 7.3 Caching Results Speeding up subsequent configureruns7.4 Printing Messages Notifying configureusers
Caching Results
7.3.1 Cache Variable Names Shell variables used in caches 7.3.2 Cache Files Files configureuses for caching7.3.3 Cache Checkpointing Loading and saving the cache file
Programming in M4
8.1 M4 Quotation Protecting macros from unwanted expansion 8.2 Using autom4teThe Autoconf executables backbone 8.3 Programming in M4sugar Convenient pure M4 macros 8.4 Programming in M4sh Common shell Constructs
M4 Quotation
8.1.1 Active Characters Characters that change the behavior of M4 8.1.2 One Macro Call Quotation and one macro call 8.1.3 Quotation and Nested Macros Macros calling macros 8.1.4 changequoteis EvilWorse than INTERCAL: M4 + changequote 8.1.5 Quadrigraphs Another way to escape special characters 8.1.6 Quotation Rule Of Thumb One parenthesis, one quote
Usingautom4te
8.2.1 Invoking autom4teA GNU M4 wrapper 8.2.2 Customizing autom4teCustomizing the Autoconf package
Programming in M4sugar
8.3.1 Redefined M4 Macros M4 builtins changed in M4sugar 8.3.2 Evaluation Macros More quotation and evaluation control 8.3.3 Forbidden Patterns Catching unexpanded macros
Writing Autoconf Macros
9.1 Macro Definitions Basic format of an Autoconf macro 9.2 Macro Names What to call your new macros 9.3 Reporting Messages Notifying autoconfusers9.4 Dependencies Between Macros What to do when macros depend on other macros 9.5 Obsoleting Macros Warning about old ways of doing things 9.6 Coding Style Writing Autoconf macros à la Autoconf
Dependencies Between Macros
9.4.1 Prerequisite Macros Ensuring required information 9.4.2 Suggested Ordering Warning about possible ordering problems
Portable Shell Programming
10.1 Shellology A zoology of shells 10.2 Here-Documents Quirks and tricks 10.3 File Descriptors FDs and redirections 10.4 File System Conventions File- and pathnames 10.5 Shell Substitutions Variable and command expansions 10.6 Assignments Varying side effects of assignments 10.7 Special Shell Variables Variables you should not change 10.8 Limitations of Shell Builtins Portable use of not so portable /bin/sh 10.9 Limitations of Usual Tools Portable use of portable tools 10.10 Limitations of Make Portable Makefiles
Manual Configuration
11.1 Specifying the System Type Specifying the system type 11.2 Getting the Canonical System Type Getting the canonical system type 11.3 Using the System Type What to do with the system type
Site Configuration
12.1 Working With External Software Working with other optional software 12.2 Choosing Package Options Selecting optional features 12.3 Making Your Help Strings Look Pretty Formatting help string 12.4 Configuring Site Details Configuring site details 12.5 Transforming Program Names When Installing Changing program names when installing 12.6 Setting Site Defaults Giving configurelocal defaults
Transforming Program Names When Installing
12.5.1 Transformation Options configureoptions to transform names12.5.2 Transformation Examples Sample uses of transforming names 12.5.3 Transformation Rules `Makefile' uses of transforming names
RunningconfigureScripts
13.1 Basic Installation Instructions for typical cases 13.2 Compilers and Options Selecting compilers and optimization 13.3 Compiling For Multiple Architectures Compiling for multiple architectures at once 13.4 Installation Names Installing in different directories 13.5 Optional Features Selecting optional features 13.6 Specifying the System Type Specifying the system type 13.7 Sharing Defaults Setting site-wide defaults for configure13.8 Defining Variables Specifying the compiler etc. 13.9 configureInvocationChanging how configureruns
Obsolete Constructs
15.1 Obsolete `config.status' Invocation Different calling convention 15.2 `acconfig.h' Additional entries in `config.h.in' 15.3 Using autoupdateto Modernize `configure.ac'Automatic update of `configure.ac' 15.4 Obsolete Macros Backward compatibility macros 15.5 Upgrading From Version 1 Tips for upgrading your files 15.6 Upgrading From Version 2.13 Some fresher tips
Upgrading From Version 1
15.5.1 Changed File Names Files you might rename 15.5.2 Changed Makefiles New things to put in `Makefile.in' 15.5.3 Changed Macros Macro calls you might replace 15.5.4 Changed Results Changes in how to check test results 15.5.5 Changed Macro Writing Better ways to write your own macros
Upgrading From Version 2.13
15.6.1 Changed Quotation Broken code which used to work 15.6.2 New Macros Interaction with foreign macros 15.6.3 Hosts and Cross-Compilation Bugward compatibility kludges 15.6.4 AC_LIBOBJvs.LIBOBJSLIBOBJS is a forbidden token 15.6.5 AC_FOO_IFELSEvs.AC_TRY_FOOA more generic scheme for testing sources
Generating Test Suites with Autotest
16.1 Using an Autotest Test Suite Autotest and the user 16.2 Writing `testsuite.at' Autotest macros 16.3 Running testsuiteScriptsRunning testsuitescripts16.4 Making testsuiteScriptsUsing autom4te to create testsuite
Using an Autotest Test Suite
16.1.1 testsuiteScriptsThe concepts of Autotest 16.1.2 Autotest Logs Their contents
Frequent Autoconf Questions, with answers
17.1 Distributing configureScriptsDistributing configurescripts17.2 Why Require GNU M4? Why not use the standard M4? 17.3 How Can I Bootstrap? Autoconf and GNU M4 require each other? 17.4 Why Not Imake? Why GNU uses configureinstead of Imake17.5 How Do I #defineInstallation Directories?Passing datadirto program17.6 What is `autom4te.cache'? What is it? Can I remove it?
History of Autoconf
18.1 Genesis Prehistory and naming of configure18.2 Exodus The plagues of M4 and Perl 18.3 Leviticus The priestly code of portability arrives 18.4 Numbers Growth and contributors 18.5 Deuteronomy Approaching the promises of easy configuration
Copying This Manual
A.1 GNU Free Documentation License License for copying this manual
Indices
B.1 Environment Variable Index Index of environment variables used B.2 Output Variable Index Index of variables set in output files B.3 Preprocessor Symbol Index Index of C preprocessor symbols defined B.4 Autoconf Macro Index Index of Autoconf macros B.5 M4 Macro Index Index of M4, M4sugar, and M4sh macros B.6 Autotest Macro Index Index of Autotest macros B.7 Program and Function Index Index of those with portability problems B.8 Concept Index General index
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
A physicist, an engineer, and a computer scientist were discussing the nature of God. ``Surely a Physicist,'' said the physicist, ``because early in the Creation, God made Light; and you know, Maxwell's equations, the dual nature of electromagnetic waves, the relativistic consequences...'' ``An Engineer!,'' said the engineer, ``because before making Light, God split the Chaos into Land and Water; it takes a hell of an engineer to handle that big amount of mud, and orderly separation of solids from liquids...'' The computer scientist shouted: ``And the Chaos, where do you think it was coming from, hmm?'' ---Anonymous
Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf.
The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they individually test for the presence of each feature that the software package they are for might need. (Before each check, they print a one-line message stating what they are checking for, so the user doesn't get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common UNIX variants. There is no need to maintain files that list the features supported by each release of each variant of UNIX.
For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code.
The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them.
Autoconf does not solve all problems related to making portable software packages--for a more complete solution, it should be used in concert with other GNU build tools like Automake and Libtool. These other tools take on jobs like the creation of a portable, recursive `Makefile' with all of the standard targets, linking of shared libraries, and so on. See section 2. The GNU Build System, for more information.
Autoconf imposes some restrictions on the names of macros used with
#if in C programs (see section B.3 Preprocessor Symbol Index).
Autoconf requires GNU M4 in order to generate the scripts. It uses features that some UNIX versions of M4, including GNU M4 1.3, do not have. You must use version 1.4 or later of GNU M4.
See section 15.5 Upgrading From Version 1, for information about upgrading from version 1. See section 18. History of Autoconf, for the story of Autoconf's development. See section 17. Frequent Autoconf Questions, with answers, for answers to some common questions about Autoconf.
See the Autoconf web page for up-to-date information, details on the mailing lists, pointers to a list of known bugs, etc.
Mail suggestions to the Autoconf mailing list.
Bug reports should be preferably submitted to the Autoconf Gnats database, or sent to the Autoconf Bugs mailing list. If possible, first check that your bug is not already solved in current development versions, and that it has not been reported yet. Be sure to include all the needed information and a short `configure.ac' that demonstrates the problem.
Autoconf's development tree is accessible via CVS; see the Autoconf web page for details. There is also a CVSweb interface to the Autoconf development tree. Patches relative to the current CVS version can be sent for review to the Autoconf Patches mailing list.
Because of its mission, Autoconf includes only a set of often-used macros that have already demonstrated their usefulness. Nevertheless, if you wish to share your macros, or find existing ones, see the Autoconf Macro Archive, which is kindly run by Peter Simons.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Autoconf solves an important problem--reliable discovery of system-specific build and run-time information--but this is only one piece of the puzzle for the development of portable software. To this end, the GNU project has developed a suite of integrated utilities to finish the job Autoconf started: the GNU build system, whose most important components are Autoconf, Automake, and Libtool. In this chapter, we introduce you to those tools, point you to sources of more information, and try to convince you to use the entire GNU build system for your software.
2.1 Automake Escaping Makefile hell 2.2 Libtool Building libraries portably 2.3 Pointers More info on the GNU build system
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The ubiquity of make means that a `Makefile' is almost the
only viable way to distribute automatic build rules for software, but
one quickly runs into make's numerous limitations. Its lack of
support for automatic dependency tracking, recursive builds in
subdirectories, reliable timestamps (e.g., for network filesystems), and
so on, mean that developers must painfully (and often incorrectly)
reinvent the wheel for each project. Portability is non-trivial, thanks
to the quirks of make on many systems. On top of all this is the
manual labor required to implement the many standard targets that users
have come to expect (make install, make distclean,
make uninstall, etc.). Since you are, of course, using Autoconf,
you also have to insert repetitive code in your Makefile.in to
recognize @CC@, @CFLAGS@, and other substitutions
provided by configure. Into this mess steps Automake.
Automake allows you to specify your build needs in a Makefile.am
file with a vastly simpler and more powerful syntax than that of a plain
Makefile, and then generates a portable Makefile.in for
use with Autoconf. For example, the Makefile.am to build and
install a simple "Hello world" program might look like:
bin_PROGRAMS = hello hello_SOURCES = hello.c |
The resulting Makefile.in (~400 lines) automatically supports all
the standard targets, the substitutions provided by Autoconf, automatic
dependency tracking, VPATH building, and so on. make will
build the hello program, and make install will install it
in `/usr/local/bin' (or whatever prefix was given to
configure, if not `/usr/local').
Automake may require that additional tools be present on the
developer's machine. For example, the Makefile.in that
the developer works with may not be portable (e.g., it might use special
features of your compiler to automatically generate dependency
information). Running make dist, however, produces a
`hello-1.0.tar.gz' package (or whatever the program/version is)
with a Makefile.in that will work on any system.
The benefits of Automake increase for larger packages (especially ones with subdirectories), but even for small programs the added convenience and portability can be substantial. And that's not all....
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Very often, one wants to build not only programs, but libraries, so that other programs can benefit from the fruits of your labor. Ideally, one would like to produce shared (dynamically linked) libraries, which can be used by multiple programs without duplication on disk or in memory and can be updated independently of the linked programs. Producing shared libraries portably, however, is the stuff of nightmares--each system has its own incompatible tools, compiler flags, and magic incantations. Fortunately, GNU provides a solution: Libtool.
Libtool handles all the requirements of building shared libraries for
you, and at this time seems to be the only way to do so with any
portability. It also handles many other headaches, such as: the
interaction of Makefile rules with the variable suffixes of
shared libraries, linking reliably with shared libraries before they are
installed by the superuser, and supplying a consistent versioning system
(so that different versions of a library can be installed or upgraded
without breaking binary compatibility). Although Libtool, like
Autoconf, can be used on its own, it is most simply utilized in
conjunction with Automake--there, Libtool is used automatically
whenever shared libraries are needed, and you need not know its syntax.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Developers who are used to the simplicity of make for small
projects on a single system might be daunted at the prospect of
learning to use Automake and Autoconf. As your software is
distributed to more and more users, however, you will otherwise
quickly find yourself putting lots of effort into reinventing the
services that the GNU build tools provide, and making the
same mistakes that they once made and overcame. (Besides, since
you're already learning Autoconf, Automake will be a piece of cake.)
There are a number of places that you can go to for more information on the GNU build tools.
The home pages for Autoconf, Automake, and Libtool.
See section `Automake' in GNU Automake, for more information on Automake.
The book GNU Autoconf, Automake and Libtool(1) describes the complete GNU build environment. You can also find the entire book on-line at "The Goat Book" home page.
The Autoconf Developer Page maintains links to a number of Autoconf/Automake tutorials online, and also links to the Autoconf Macro Archive.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
configure Scripts
The configuration scripts that Autoconf produces are by convention
called configure. When run, configure creates several
files, replacing configuration parameters in them with appropriate
values. The files that configure creates are:
#define directives (see section 4.8 Configuration Header Files);
configure makes a mistake.
To create a configure script with Autoconf, you need to write an
Autoconf input file `configure.ac' (or `configure.in') and run
autoconf on it. If you write your own feature tests to
supplement those that come with Autoconf, you might also write files
called `aclocal.m4' and `acsite.m4'. If you use a C header
file to contain #define directives, you might also run
autoheader, and you will distribute the generated file
`config.h.in' with the package.
Here is a diagram showing how the files that can be used in
configuration are produced. Programs that are executed are suffixed by
`*'. Optional files are enclosed in square brackets (`[]').
autoconf and autoheader also read the installed Autoconf
macro files (by reading `autoconf.m4').
Files used in preparing a software package for distribution:
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
configure.ac --.
| .------> autoconf* -----> configure
[aclocal.m4] --+---+
| `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'
Makefile.in -------------------------------> Makefile.in
|
Files used in configuring a software package:
.-------------> [config.cache]
configure* ------------+-------------> config.log
|
[config.h.in] -. v .-> [config.h] -.
+--> config.status* -+ +--> make*
Makefile.in ---' `-> Makefile ---'
|
3.1 Writing `configure.ac' What to put in an Autoconf input file 3.2 Using autoscanto Create `configure.ac'Semi-automatic `configure.ac' writing 3.3 Using ifnamesto List ConditionalsListing the conditionals in source code 3.4 Using autoconfto CreateconfigureHow to create configuration scripts 3.5 Using autoreconfto UpdateconfigureScriptsRemaking multiple configurescripts
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
To produce a configure script for a software package, create a
file called `configure.ac' that contains invocations of the
Autoconf macros that test the system features your package needs or can
use. Autoconf macros already exist to check for many features; see
5. Existing Tests, for their descriptions. For most other features,
you can use Autoconf template macros to produce custom checks; see
6. Writing Tests, for information about them. For especially tricky
or specialized features, `configure.ac' might need to contain some
hand-crafted shell commands; see 10. Portable Shell Programming. The
autoscan program can give you a good start in writing
`configure.ac' (see section 3.2 Using autoscan to Create `configure.ac', for more information).
Previous versions of Autoconf promoted the name `configure.in',
which is somewhat ambiguous (the tool needed to process this file is not
described by its extension), and introduces a slight confusion with
`config.h.in' and so on (for which `.in' means "to be
processed by configure"). Using `configure.ac' is now
preferred.
3.1.1 A Shell Script Compiler Autoconf as solution of a problem 3.1.2 The Autoconf Language Programming in Autoconf 3.1.3 Standard `configure.ac' Layout Standard organization of `configure.ac'
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Just as for any other computer language, in order to properly program `configure.ac' in Autoconf you must understand what problem the language tries to address and how it does so.
The problem Autoconf addresses is that the world is a mess. After all,
you are using Autoconf in order to have your package compile easily on
all sorts of different systems, some of them being extremely hostile.
Autoconf itself bears the price for these differences: configure
must run on all those systems, and thus configure must limit itself
to their lowest common denominator of features.
Naturally, you might then think of shell scripts; who needs
autoconf? A set of properly written shell functions is enough to
make it easy to write configure scripts by hand. Sigh!
Unfortunately, shell functions do not belong to the least common
denominator; therefore, where you would like to define a function and
use it ten times, you would instead need to copy its body ten times.
So, what is really needed is some kind of compiler, autoconf,
that takes an Autoconf program, `configure.ac', and transforms it
into a portable shell script, configure.
How does autoconf perform this task?
There are two obvious possibilities: creating a brand new language or
extending an existing one. The former option is very attractive: all
sorts of optimizations could easily be implemented in the compiler and
many rigorous checks could be performed on the Autoconf program
(e.g., rejecting any non-portable construct). Alternatively, you can
extend an existing language, such as the sh (Bourne shell)
language.
Autoconf does the latter: it is a layer on top of sh. It was
therefore most convenient to implement autoconf as a macro
expander: a program that repeatedly performs macro expansions on
text input, replacing macro calls with macro bodies and producing a pure
sh script in the end. Instead of implementing a dedicated
Autoconf macro expander, it is natural to use an existing
general-purpose macro language, such as M4, and implement the extensions
as a set of M4 macros.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The Autoconf language is very different from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have very different syntactic status, in Autoconf their status is rigorously the same. Therefore, we need a means to distinguish literal strings from text to be expanded: quotation.
When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments should be enclosed within the M4 quote characters `[' and `]', and be separated by commas. Any leading spaces in arguments are ignored, unless they are quoted. You may safely leave out the quotes when the argument is simple text, but always quote complex arguments such as other macro calls. This rule applies recursively for every macro call, including macros called from other macros.
For instance:
AC_CHECK_HEADER([stdio.h],
[AC_DEFINE([HAVE_STDIO_H])],
[AC_MSG_ERROR([Sorry, can't do anything for you])])
|
is quoted properly. You may safely simplify its quotation to:
AC_CHECK_HEADER(stdio.h,
[AC_DEFINE(HAVE_STDIO_H)],
[AC_MSG_ERROR([Sorry, can't do anything for you])])
|
Notice that the argument of AC_MSG_ERROR is still quoted;
otherwise, its comma would have been interpreted as an argument separator.
The following example is wrong and dangerous, as it is underquoted:
AC_CHECK_HEADER(stdio.h,
AC_DEFINE(HAVE_STDIO_H),
AC_MSG_ERROR([Sorry, can't do anything for you]))
|
In other cases, you may have to use text that also resembles a macro call. You must quote that text even when it is not passed as a macro argument:
echo "Hard rock was here! --[AC_DC]" |
which will result in
echo "Hard rock was here! --AC_DC" |
When you use the same text in a macro argument, you must therefore have an extra quotation level (since one is stripped away by the macro substitution). In general, then, it is a good idea to use double quoting for all literal string arguments:
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) |
You are now able to understand one of the constructs of Autoconf that has been continually misunderstood... The rule of thumb is that whenever you expect macro expansion, expect quote expansion; i.e., expect one level of quotes to be lost. For instance:
AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])]) |
is incorrect: here, the first argument of AC_COMPILE_IFELSE is
`char b[10];' and will be expanded once, which results in
`char b10;'. (There was an idiom common in Autoconf's past to
address this issue via the M4 changequote primitive, but do not
use it!) Let's take a closer look: the author meant the first argument
to be understood as a literal, and therefore it must be quoted twice:
AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) |
Voilà, you actually produce `char b[10];' this time!
The careful reader will notice that, according to these guidelines, the
"properly" quoted AC_CHECK_HEADER example above is actually
lacking three pairs of quotes! Nevertheless, for the sake of readability,
double quotation of literals is used only where needed in this manual.
Some macros take optional arguments, which this documentation represents as [arg] (not to be confused with the quote characters). You may just leave them empty, or use `[]' to make the emptiness of the argument explicit, or you may simply omit the trailing commas. The three lines below are equivalent:
AC_CHECK_HEADERS(stdio.h, [], [], []) AC_CHECK_HEADERS(stdio.h,,,) AC_CHECK_HEADERS(stdio.h) |
It is best to put each macro call on its own line in
`configure.ac'. Most of the macros don't add extra newlines; they
rely on the newline after the macro call to terminate the commands.
This approach makes the generated configure script a little
easier to read by not inserting lots of blank lines. It is generally
safe to set shell variables on the same line as a macro call, because
the shell allows assignments without intervening newlines.
You can include comments in `configure.ac' files by starting them with the `#'. For example, it is helpful to begin `configure.ac' files with a line like this:
# Process this file with autoconf to produce a configure script. |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The order in which `configure.ac' calls the Autoconf macros is not
important, with a few exceptions. Every `configure.ac' must
contain a call to AC_INIT before the checks, and a call to
AC_OUTPUT at the end (see section 4.4 Outputting Files). Additionally, some macros
rely on other macros having been called first, because they check
previously set values of some variables to decide what to do. These
macros are noted in the individual descriptions (see section 5. Existing Tests), and they also warn you when configure is created if they
are called out of order.
To encourage consistency, here is a suggested order for calling the Autoconf macros. Generally speaking, the things near the end of this list are those that could depend on things earlier in it. For example, library functions could be affected by types and libraries.
Autoconf requirements |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
autoscan to Create `configure.ac'
The autoscan program can help you create and/or maintain a
`configure.ac' file for a software package. autoscan
examines source files in the directory tree rooted at a directory given
as a command line argument, or the current directory if none is given.
It searches the source files for common portability problems and creates
a file `configure.scan' which is a preliminary `configure.ac'
for that package, and checks a possibly existing `configure.ac' for
completeness.
When using autoscan to create a `configure.ac', you
should manually examine `configure.scan' before renaming it to
`configure.ac'; it will probably need some adjustments.
Occasionally, autoscan outputs a macro in the wrong order
relative to another macro, so that autoconf produces a warning;
you need to move such macros manually. Also, if you want the package to
use a configuration header file, you must add a call to
AC_CONFIG_HEADERS (see section 4.8 Configuration Header Files). You might
also have to change or add some #if directives to your program in
order to make it work with Autoconf (see section 3.3 Using ifnames to List Conditionals, for
information about a program that can help with that job).
When using autoscan to maintain a `configure.ac', simply
consider adding its suggestions. The file `autoscan.log' will
contain detailed information on why a macro is requested.
autoscan uses several data files (installed along with Autoconf)
to determine which macros to output when it finds particular symbols in
a package's source files. These data files all have the same format:
each line consists of a symbol, whitespace, and the Autoconf macro to
output if that symbol is encountered. Lines starting with `#' are
comments.
autoscan accepts the following options:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
ifnames to List Conditionals
ifnames can help you write `configure.ac' for a software
package. It prints the identifiers that the package already uses in C
preprocessor conditionals. If a package has already been set up to have
some portability, ifnames can thus help you figure out what its
configure needs to check for. It may help fill in some gaps in a
`configure.ac' generated by autoscan (see section 3.2 Using autoscan to Create `configure.ac').
ifnames scans all of the C source files named on the command line
(or the standard input, if none are given) and writes to the standard
output a sorted list of all the identifiers that appear in those files
in #if, #elif, #ifdef, or #ifndef
directives. It prints each identifier on a line, followed by a
space-separated list of the files in which that identifier occurs.
ifnames accepts the following options:
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
autoconf to Create configure
To create configure from `configure.ac', run the
autoconf program with no arguments. autoconf processes
`configure.ac' with the M4 macro processor, using the
Autoconf macros. If you give autoconf an argument, it reads that
file instead of `configure.ac' and writes the configuration script
to the standard output instead of to configure. If you give
autoconf the argument `-', it reads from the standard
input instead of `configure.ac' and writes the configuration script
to the standard output.
The Autoconf macros are defined in several files. Some of the files are
distributed with Autoconf; autoconf reads them first. Then it
looks for the optional file `acsite.m4' in the directory that
contains the distributed Autoconf macro files, and for the optional file
`aclocal.m4' in the current directory. Those files can contain
your site's or the package's own Autoconf macro definitions
(see section 9. Writing Autoconf Macros, for more information). If a macro is
defined in more than one of the files that autoconf reads, the
last definition it reads overrides the earlier ones.
autoconf accepts the following options:
AC_DIAGNOSE, for a comprehensive list of categories. Special
values include:
Warnings about `syntax' are enabled by default, and the environment
variable WARNINGS, a comma separated list of categories, is
honored. Passing `-W category' will actually behave as if
you had passed `--warnings=syntax,$WARNINGS,category'. If
you want to disable the defaults and WARNINGS, but (for example)
enable the warnings about obsolete constructs, you would use `-W
none,obsolete'.
Because autoconf uses autom4te behind the scenes, it
displays a back trace for errors, but not for warnings; if you want
them, just pass `-W error'. See section 8.2.1 Invoking autom4te, for some
examples.
configure script, but list the calls to
macro according to the format. Multiple `--trace'
arguments can be used to list several macros. Multiple `--trace'
arguments for a single macro are not cumulative; instead, you should
just make format as long as needed.
The format is a regular string, with newlines if desired, and
several special escape codes. It defaults to `$f:$l:$n:$%'; see
8.2.1 Invoking autom4te, for details on the format.
AC_DEFUN definitions). This
results in a noticeable speedup, but can be disabled by this option.
It is often necessary to check the content of a `configure.ac' file, but parsing it yourself is extremely fragile and error-prone. It is suggested that you rely upon `--trace' to scan `configure.ac'. For instance, to find the list of variables that are substituted, use:
$ autoconf -t AC_SUBST configure.ac:2:AC_SUBST:ECHO_C configure.ac:2:AC_SUBST:ECHO_N configure.ac:2:AC_SUBST:ECHO_T More traces deleted |
The example below highlights the difference between `$@', `$*', and $%.
$ cat configure.ac AC_DEFINE(This, is, [an [example]]) $ autoconf -t 'AC_DEFINE:@: $@ *: $* $: $%' @: [This],[is],[an [example]] *: This,is,an [example] $: This:is:an [example] |
The format gives you a lot of freedom:
$ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";'
$ac_subst{"ECHO_C"} = "configure.ac:2";
$ac_subst{"ECHO_N"} = "configure.ac:2";
$ac_subst{"ECHO_T"} = "configure.ac:2";
More traces deleted
|
A long separator can be used to improve the readability of complex structures, and to ease their parsing (for instance when no single character is suitable as a separator):
$ autoconf -t 'AM_MISSING_PROG:${|:::::|}*'
ACLOCAL|:::::|aclocal|:::::|$missing_dir
AUTOCONF|:::::|autoconf|:::::|$missing_dir
AUTOMAKE|:::::|automake|:::::|$missing_dir
More traces deleted
|
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
autoreconf to Update configure Scripts
Installing the various components of the GNU Build System can be
tedious: running autopoint for Gettext, automake for
`Makefile.in' etc. in each directory. It may be needed either
because some tools such as automake have been updated on your
system, or because some of the sources such as `configure.ac' have
been updated, or finally, simply in order to install the GNU Build
System in a fresh tree.
autoreconf runs autoconf, autoheader,
aclocal, automake, libtoolize, and
autopoint (when appropriate) repeatedly to update the
GNU Build System in the specified directories and their
subdirectories (see section 4.11 Configuring Other Packages in Subdirectories). By default, it only remakes
those files that are older than their sources.
If you install a new version of some tool, you can make
autoreconf remake all of the files by giving it the
`--force' option.
See section 4.7.4 Automatic Remaking, for `Makefile' rules to automatically
remake configure scripts when their source files change. That
method handles the timestamps of configuration header templates
properly, but does not pass `--autoconf-dir=dir' or
`--localdir=dir'.
autoreconf accepts the following options:
autoreconf runs
autoconf (and autoheader, if appropriate).
This option triggers calls to `automake --add-missing', `libtoolize', `autopoint', etc.
Warnings about `syntax' are enabled by default, and the environment
variable WARNINGS, a comma separated list of categories, is
honored. Passing `-W category' will actually behave as if
you had passed `--warnings=syntax,$WARNINGS,category'. If
you want to disable the defaults and WARNINGS, but (for example)
enable the warnings about obsolete constructs, you would use `-W
none,obsolete'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Autoconf-generated configure scripts need some information about
how to initialize, such as how to find the package's source files and
about the output files to produce. The following sections describe the
initialization and the creation of output files.
4.1 Initializing configureOption processing etc. 4.2 Notices in configureCopyright, version numbers in configure4.3 Finding configureInputWhere Autoconf should find files 4.4 Outputting Files Outputting results from the configuration 4.5 Performing Configuration Actions Preparing the output based on results 4.6 Creating Configuration Files Creating output files 4.7 Substitutions in Makefiles Using output variables in `Makefile's 4.8 Configuration Header Files Creating a configuration header file 4.9 Running Arbitrary Configuration Commands Running arbitrary instantiation commands 4.10 Creating Configuration Links Links depending on the configuration 4.11 Configuring Other Packages in Subdirectories Configuring independent packages together 4.12 Default Prefix Changing the default installation prefix
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
configure
Every configure script must call AC_INIT before doing
anything else. The only other required macro is AC_OUTPUT
(see section 4.4 Outputting Files).
Set the name of the package and its version. These are
typically used in `--version' support, including that of
configure. The optional argument bug-report should be
the email to which users should send bug reports. The package
tarname differs from package: the latter designates the full
package name (e.g., `GNU Autoconf'), while the former is meant for
distribution tar ball names (e.g., `autoconf'). It defaults to
package with `GNU ' stripped, lower-cased, and all characters
other than alphanumerics and underscores are changed to `-'.
It is preferable that the arguments of AC_INIT be static, i.e.,
there should not be any shell computation, but they can be computed by
M4.
The following M4 macros (e.g., AC_PACKAGE_NAME), output variables
(e.g., PACKAGE_NAME), and preprocessor symbols (e.g.,
PACKAGE_NAME) are defined by AC_INIT:
AC_PACKAGE_NAME, PACKAGE_NAME
AC_PACKAGE_TARNAME, PACKAGE_TARNAME
AC_PACKAGE_VERSION, PACKAGE_VERSION
AC_PACKAGE_STRING, PACKAGE_STRING
AC_PACKAGE_BUGREPORT, PACKAGE_BUGREPORT
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
configure
The following macros manage version numbers for configure
scripts. Using them is optional.
configure is earlier
than version, print an error message to the standard error output
and do not create configure. For example:
AC_PREREQ(2.57) |
This macro is the only macro that may be used before AC_INIT, but
for consistency, you are invited not to do so.
configure are covered by the
copyright-notice.
The copyright-notice will show up in both the head of
configure and in `configure --version'.
configure
script, with any dollar signs or double-quotes removed. This macro lets
you put a revision stamp from `configure.ac' into configure
without RCS or CVS changing it when you check in
configure. That way, you can determine easily which revision of
`configure.ac' a particular configure corresponds to.
For example, this line in `configure.ac':
AC_REVISION($Revision: 1.1 $) |
produces this in configure:
#! /bin/sh # From configure.ac Revision: 1.30 |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
configure Input configure checks for this file's existence to
make sure that the directory that it is told contains the source code in
fact does. Occasionally people accidentally specify the wrong directory
with `--srcdir'; this is a safety check. See section 13.9 configure Invocation, for more information.
Packages that do manual configuration or use the install program
might need to tell configure where to find some other shell
scripts by calling AC_CONFIG_AUX_DIR, though the default places
it looks are correct for most cases.
configure,
Automake and Libtool scripts etc.) that are in directory dir.
These are auxiliary files used in configuration. dir can be
either absolute or relative to `srcdir'. The default is
`srcdir' or `srcdir/..' or
`srcdir/../..', whichever is the first that contains
`install-sh'. The other files are not checked for, so that using
AC_PROG_INSTALL does not automatically require distributing the
other auxiliary files. It checks for `install.sh' also, but that
name is obsolete because some make have a rule that creates
`install' from it if there is no `Makefile'.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Every Autoconf script, e.g., `configure.ac', should finish by
calling AC_OUTPUT. That is the macro that generates
`config.status', which will create the `Makefile's and any
other files resulting from configuration. This is the only required
macro besides AC_INIT (see section 4.3 Finding configure Input).
`config.status' will perform all the configuration actions: all the
output files (see 4.6 Creating Configuration Files, macro
AC_CONFIG_FILES), header files (see 4.8 Configuration Header Files,
macro AC_CONFIG_HEADERS), commands (see 4.9 Running Arbitrary Configuration Commands, macro AC_CONFIG_COMMANDS), links (see
4.10 Creating Configuration Links, macro AC_CONFIG_LINKS), subdirectories
to configure (see 4.11 Configuring Other Packages in Subdirectories, macro AC_CONFIG_SUBDIRS)
are honored.
Historically, the usage of AC_OUTPUT was somewhat different.
See section 15.4 Obsolete Macros, for a description of the arguments that
AC_OUTPUT used to support.
If you run make in subdirectories, you should run it using the
make variable MAKE. Most versions of make set
MAKE to the name of the make program plus any options it
was given. (But many do not include in it the values of any variables
set on the command line, so those are not passed on automatically.)
Some old versions of make do not set this variable. The
following macro allows you to use it even with those versions.
make predefines the Make variable MAKE, define
output variable SET_MAKE to be empty. Otherwise, define
SET_MAKE to contain `MAKE=make'. Calls AC_SUBST for
SET_MAKE.
If you use this macro, place a line like this in each `Makefile.in'
that runs MAKE on other directories:
@SET_MAKE@ |
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
`configure' is designed so that it appears to do everything itself, but there is actually a hidden slave: `config.status'. `configure' is in charge of examining your system, but it is `config.status' that actually takes the proper actions based on the results of `configure'. The most typical task of `config.status' is to instantiate files.
This section describes the common behavior of the four standard
instantiating macros: AC_CONFIG_FILES, AC_CONFIG_HEADERS,
AC_CONFIG_COMMANDS and AC_CONFIG_LINKS. They all
have this prototype:
AC_CONFIG_FOOS(tag..., [commands], [init-cmds]) |
where the arguments are:
You are encouraged to use literals as tags. In particular, you should avoid
... && my_foos="$my_foos fooo" ... && my_foos="$my_foos foooo" AC_CONFIG_FOOS($my_foos) |
and use this instead:
... && AC_CONFIG_FOOS(fooo) ... && AC_CONFIG_FOOS(foooo) |
The macros AC_CONFIG_FILES and AC_CONFIG_HEADERS use
special tags: they may have the form `output' or
`output:inputs'. The file output is instantiated
from its templates, inputs (defaulting to `output.in').
For instance `AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' asks for the creation of `Makefile' that will be the expansion of the output variables in the concatenation of `boiler/top.mk' and `boiler/bot.mk'.
The special value `-' might be used to denote the standard output when used in output, or the standard input when used in the inputs. You most probably don't need to use this in `configure.ac', but it is convenient when using the command line interface of `./config.status', see 14. Recreating a Configuration, for more details.
The inputs may be absolute or relative filenames. In the latter case they are first looked for in the build tree, and then in the source tree.
The variables set during the execution of configure are
not available here: you first need to set them via the
init-cmds. Nonetheless the following variables are precomputed:
srcdir
configure's option `--srcdir' sets.
ac_top_srcdir
ac_top_builddir
ac_srcdir
The current directory refers to the directory (or pseudo-directory) containing the input part of tags. For instance, running
AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...]) |
with `--srcdir=../package' produces the following values:
# Argument of --srcdir srcdir='../package' # Reversing deep/dir ac_top_builddir='../../' # Concatenation of $ac_top_builddir and srcdir ac_top_srcdir='../../../package' # Concatenation of $ac_top_srcdir and deep/dir ac_srcdir='../../../package/deep/dir' |
independently of `in/in.in'.
var. init-cmds
is typically used by `configure' to give `config.status' some
variables it needs to run the commands.
You should be extremely cautious in your variable names: all the init-cmds share the same name space and may overwrite each other in unpredictable ways. Sorry....
All these macros can be called multiple times, with different tags, of course!
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Be sure to read the previous section, 4.5 Performing Configuration Actions.
AC_OUTPUT create each `file' by copying an input
file (by default `file.in'), substituting the output variable
values.
This macro is one of the instantiating macros; see 4.5 Performing Configuration Actions. See section 4.7 Substitutions in Makefiles, for more information on using
output variables. See section 7.2 Setting Output Variables, for more information
on creating them. This macro creates the directory that the file is in
if it doesn't exist. Usually, `Makefile's are created this way,
but other files, such as `.gdbinit', can be specified as well.
Typical calls to AC_CONFIG_FILES look like this:
AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) |
You can override an input file name by appending to file a colon-separated list of input files. Examples:
AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk]
[lib/Makefile:boiler/lib.mk])
|
Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file.
| [ < ] |