大家好，又见面了，我是你们的朋友全栈君。
1 Introduction
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 Posix-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 Posix variants. There is no need to maintain files that list the features supported by each release of each variant of Posix.
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.
Those who do not understand Autoconf are condemned to reinvent it, poorly. The primary goal of Autoconf is making the user’s life easier; making the maintainer’s life easier is only a secondary goal. Put another way, the primary goal is not to make the generation of configure automatic for package maintainers (although patches along that front are welcome, since package maintainers form the user base of Autoconf); rather, the goal is to make configure painless, portable, and predictable for the end user of each autoconfiscated package. And to this degree, Autoconf is highly successful at its goal — most complaints to the Autoconf list are about difficulties in writing Autoconf input, and not in the behavior of the resulting configure. Even packages that don’t use Autoconf will generally provide a configure script, and the most common complaint about these alternative home-grown scripts is that they fail to meet one or more of the GNU Coding Standards (see Configuration) that users have come to expect from Autoconf-generated configure scripts.
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 The GNU Build System, for more information.
Autoconf imposes some restrictions on the names of macros used with #if in C programs (see Preprocessor Symbol Index).
Autoconf requires GNU M4 version 1.4.6 or later in order to generate the scripts. It uses features that some versions of M4, including GNU M4 1.3, do not have. Autoconf works better with GNU M4 version 1.4.14 or later, though this is not required.
See Autoconf 1, for information about upgrading from version 1. See History, for the story of Autoconf’s development. See FAQ, 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. Past suggestions are archived.
Mail bug reports to the Autoconf Bugs mailing list. Past bug reports are archived.
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 git; see the Autoconf Summary for details, or view the actual repository. Anonymous CVS access is also available, see README for more details. Patches relative to the current git version can be sent for review to the Autoconf Patches mailing list, with discussion on prior patches archived; and all commits are posted in the read-only Autoconf Commit mailing list, which is also archived.
Because of its mission, the Autoconf package itself 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.
Next: Making configure Scripts, Previous: Introduction, Up: Top
2 The GNU Build System
Autoconf solves an important problem—reliable discovery of system-specific build and runtime 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.
- Automake: Escaping makefile hell
- Gnulib: The GNU portability library
- Libtool: Building libraries portably
- Pointers: More info on the GNU build system
Next: Gnulib, Up: The GNU Build System
2.1 Automake
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 its numerous limitations. Its lack of support for automatic dependency tracking, recursive builds in subdirectories, reliable timestamps (e.g., for network file systems), 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 builds the hello program, and make install installs it in /usr/local/bin (or whatever prefix was given to configure, if not /usr/local).
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…
Next: Libtool, Previous: Automake, Up: The GNU Build System
2.2 Gnulib
GNU software has a well-deserved reputation for running on many different types of systems. While our primary goal is to write software for the GNU system, many users and developers have been introduced to us through the systems that they were already using.
Gnulib is a central location for common GNU code, intended to be shared among free software packages. Its components are typically shared at the source level, rather than being a library that gets built, installed, and linked against. The idea is to copy files from Gnulib into your own source tree. There is no distribution tarball; developers should just grab source modules from the repository. The source files are available online, under various licenses, mostly GNU GPL or GNU LGPL.
Gnulib modules typically contain C source code along with Autoconf macros used to configure the source code. For example, the Gnulib stdbool module implements a stdbool.h header that nearly conforms to C99, even on old-fashioned hosts that lack stdbool.h. This module contains a source file for the replacement header, along with an Autoconf macro that arranges to use the replacement header on old-fashioned systems.
Next: Pointers, Previous: Gnulib, Up: The GNU Build System
2.3 Libtool
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 Make 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 without Automake, 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.
Previous: Libtool, Up: The GNU Build System
2.4 Pointers
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 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 is a piece of cake.)
There are a number of places that you can go to for more information on the GNU build tools.
- Web
The project home pages for Autoconf, Automake, Gnulib, and Libtool.
- Automake Manual
See Automake, for more information on Automake.
- Books
The book GNU Autoconf, Automake and Libtool1 describes the complete GNU build environment. You can also find the entire book on-line.
Next: Setup, Previous: The GNU Build System, Up: Top
3 Making 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:
- one or more Makefile files, usually one in each subdirectory of the package (see Makefile Substitutions);
- optionally, a C header file, the name of which is configurable, containing
#definedirectives (see Configuration Headers); - a shell script called config.status that, when run, recreates the files listed above (see config.status Invocation);
- an optional shell script normally called config.cache (created when using ‘configure –config-cache’) that saves the results of running many of the tests (see Cache Files);
- a file called config.log containing any messages produced by compilers, to help debugging if 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 can 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, when using just Autoconf:
your source files --> [autoscan*] --> [configure.scan] --> configure.ac
configure.ac --.
| .------> autoconf* -----> configure
[aclocal.m4] --+---+
| `-----> [autoheader*] --> [config.h.in]
[acsite.m4] ---'
Makefile.in
Additionally, if you use Automake, the following additional productions come into play:
[acinclude.m4] --.
|
[local macros] --+--> aclocal* --> aclocal.m4
|
configure.ac ----'
configure.ac --.
+--> automake* --> Makefile.in
Makefile.am ---'
Files used in configuring a software package:
.-------------> [config.cache]
configure* ------------+-------------> config.log
|
[config.h.in] -. v .-> [config.h] -.
+--> config.status* -+ +--> make*
Makefile.in ---' `-> Makefile ---'
- Writing Autoconf Input: What to put in an Autoconf input file
- autoscan Invocation: Semi-automatic configure.ac writing
- ifnames Invocation: Listing the conditionals in source code
- autoconf Invocation: How to create configuration scripts
- autoreconf Invocation: Remaking multiple configure scripts
Next: autoscan Invocation, Up: Making configure Scripts
3.1 Writing configure.ac
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 Existing Tests, for their descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see Writing Tests, for information about them. For especially tricky or specialized features, configure.ac might need to contain some hand-crafted shell commands; see Portable Shell Programming. The autoscan program can give you a good start in writing configure.ac (see autoscan Invocation, 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.
- Shell Script Compiler: Autoconf as solution of a problem
- Autoconf Language: Programming in Autoconf
- Autoconf Input Layout: Standard organization of configure.ac
Next: Autoconf Language, Up: Writing Autoconf Input
3.1.1 A Shell Script Compiler
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, even in 2008, where shells without any function support are far and few between, there are pitfalls to avoid when making use of them. Also, finding a Bourne shell that accepts shell functions is not trivial, even though there is almost always one on interesting porting targets.
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 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.
Next: Autoconf Input Layout, Previous: Shell Script Compiler, Up: Writing Autoconf Input
3.1.2 The Autoconf Language
The Autoconf language differs from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have 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 white space between the macro name and the open parenthesis.
AC_INIT ([oops], [1.0]) # incorrect
AC_INIT([hello], [1.0]) # good
Arguments should be enclosed within the quote characters ‘[’ and ‘]’, and be separated by commas. Any leading blanks or newlines in arguments are ignored, unless they are quoted. You should always quote an argument that might contain a macro name, comma, parenthesis, or a leading blank or newline. This rule applies recursively for every macro call, including macros called from other macros. For more details on quoting rules, see Programming in M4.
For instance:
AC_CHECK_HEADER([stdio.h],
[AC_DEFINE([HAVE_STDIO_H], [1],
[Define to 1 if you 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], 1,
[Define to 1 if you have <stdio.h>.])],
[AC_MSG_ERROR([sorry, can't do anything for you])])
because ‘1’ cannot contain a macro call. Here, the argument of AC_MSG_ERROR must be quoted; otherwise, its comma would be interpreted as an argument separator. Also, the second and third arguments of ‘AC_CHECK_HEADER’ must be quoted, since they contain macro calls. The three arguments ‘HAVE_STDIO_H’, ‘stdio.h’, and ‘Define to 1 if you have <stdio.h>.’ do not need quoting, but if you unwisely defined a macro with a name like ‘Define’ or ‘stdio’ then they would need quoting. Cautious Autoconf users would keep the quotes, but many Autoconf users find such precautions annoying, and would rewrite the example as follows:
AC_CHECK_HEADER(stdio.h,
[AC_DEFINE(HAVE_STDIO_H, 1,
[Define to 1 if you have <stdio.h>.])],
[AC_MSG_ERROR([sorry, can't do anything for you])])
This is safe, so long as you adopt good naming conventions and do not define macros with names like ‘HAVE_STDIO_H’, ‘stdio’, or ‘h’. Though it is also safe here to omit the quotes around ‘Define to 1 if you have <stdio.h>.’ this is not recommended, as message strings are more likely to inadvertently contain commas.
The following example is wrong and dangerous, as it is underquoted:
AC_CHECK_HEADER(stdio.h,
AC_DEFINE(HAVE_STDIO_H, 1,
Define to 1 if you 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. For example, these two approaches in configure.ac (quoting just the potential problems, or quoting the entire line) will protect your script in case autoconf ever adds a macro AC_DC:
echo "Hard rock was here! --[AC_DC]"
[echo "Hard rock was here! --AC_DC"]
which results in this text in configure:
echo "Hard rock was here! --AC_DC"
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, either around just the problematic portions, or over the entire argument:
AC_MSG_WARN([[AC_DC] stinks --Iron Maiden])
AC_MSG_WARN([[AC_DC stinks --Iron Maiden]])
However, the above example triggers a warning about a possibly unexpanded macro when running autoconf, because it collides with the namespace of macros reserved for the Autoconf language. To be really safe, you can use additional escaping (either a quadrigraph, or creative shell constructs) to silence that particular warning:
echo "Hard rock was here! --AC""_DC"
AC_MSG_WARN([[AC@&t@_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(AC_LANG_SOURCE([char b[10];]), [],
[AC_MSG_ERROR([you lose])])
is incorrect: here, the first argument of AC_LANG_SOURCE is ‘char b[10];’ and is expanded once, which results in ‘char b10;’; and the AC_LANG_SOURCE is also expanded prior to being passed to AC_COMPILE_IFELSE. (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; likewise, the intermediate AC_LANG_SOURCE macro should be quoted once so that it is only expanded after the rest of the body of AC_COMPILE_IFELSE is in place:
AC_COMPILE_IFELSE([AC_LANG_SOURCE([[char b[10];]])], [],
[AC_MSG_ERROR([you lose])])
Voilà, you actually produce ‘char b[10];’ this time!
On the other hand, descriptions (e.g., the last parameter of AC_DEFINE or AS_HELP_STRING) are not literals—they are subject to line breaking, for example—and should not be double quoted. Even if these descriptions are short and are not actually broken, double quoting them yields weird results.
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.
Previous: Autoconf Language, Up: Writing Autoconf Input
3.1.3 Standard configure.ac Layout
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 Output). 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 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
AC_INIT(package, version, bug-report-address)
information on the package
checks for programs
checks for libraries
checks for header files
checks for types
checks for structures
checks for compiler characteristics
checks for library functions
checks for system services
AC_CONFIG_FILES([file...])
AC_OUTPUT
Next: ifnames Invocation, Previous: Writing Autoconf Input, Up: Making configure Scripts
3.2 Using 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 probably needs 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 Configuration Headers). You might also have to change or add some #if directives to your program in order to make it work with Autoconf (see ifnames Invocation, 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 contains 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, one or more blanks, and the Autoconf macro to output if that symbol is encountered. Lines starting with ‘#’ are comments.
autoscan accepts the following options:
–help
-h
Print a summary of the command line options and exit.
–version
-V
Print the version number of Autoconf and exit.
–verbose
-v
Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous.
–debug
-d
Don’t remove temporary files.
–include=dir
-I dir
Append dir to the include path. Multiple invocations accumulate.
–prepend-include=dir
-B dir
Prepend dir to the include path. Multiple invocations accumulate.
Next: autoconf Invocation, Previous: autoscan Invocation, Up: Making configure Scripts
3.3 Using 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 autoscan Invocation).
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:
–help
-h
Print a summary of the command line options and exit.
–version
-V
Print the version number of Autoconf and exit.
Next: autoreconf Invocation, Previous: ifnames Invocation, Up: Making configure Scripts
3.4 Using 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 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:
–help
-h
Print a summary of the command line options and exit.
–version
-V
Print the version number of Autoconf and exit.
–verbose
-v
Report processing steps.
–debug
-d
Don’t remove the temporary files.
–force
-f
Remake configure even if newer than its input files.
–include=dir
-I dir
Append dir to the include path. Multiple invocations accumulate.
–prepend-include=dir
-B dir
Prepend dir to the include path. Multiple invocations accumulate.
–output=file
-o file
Save output (script or trace) to file. The file – stands for the standard output.
–warnings=category
-W category
Report the warnings related to category (which can actually be a comma separated list). See Reporting Messages, macro AC_DIAGNOSE, for a comprehensive list of categories. Special values include:
‘all’
report all the warnings
‘none’
report none
‘error’
treats warnings as errors
‘no-category’
disable warnings falling into category
Warnings about ‘syntax’ are enabled by default, and the environment variable WARNINGS, a comma separated list of categories, is honored as well. Passing -W category actually behaves as if you had passed –warnings syntax,$WARNINGS,category. To disable the defaults and WARNINGS, and then enable warnings about obsolete constructs, 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 autom4te Invocation, for some examples.
–trace=macro[:format]
-t macro[:format]
Do not create the 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 autom4te Invocation, for details on the format.
–initialization
-i
By default, –trace does not trace the initialization of the Autoconf macros (typically the 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
Previous: autoconf Invocation, Up: Making configure Scripts
3.5 Using 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 Subdirectories). By default, it only remakes those files that are older than their sources. The environment variables AUTOM4TE, AUTOCONF, AUTOHEADER, AUTOMAKE, ACLOCAL, AUTOPOINT, LIBTOOLIZE, M4, and MAKE may be used to override the invocation of the respective tools.
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 Automatic Remaking, for Make rules to automatically rebuild 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.
Gettext supplies the autopoint command to add translation infrastructure to a source package. If you use autopoint, your configure.ac should invoke both AM_GNU_GETTEXT and AM_GNU_GETTEXT_VERSION(gettext-version). See Invoking the autopoint Program, for further details.
autoreconf accepts the following options:
–help
-h
Print a summary of the command line options and exit.
–version
-V
Print the version number of Autoconf and exit.
–verbose
-v
Print the name of each directory autoreconf examines and the commands it runs. If given two or more times, pass –verbose to subordinate tools that support it.
–debug
-d
Don’t remove the temporary files.
–force
-f
Remake even configure scripts and configuration headers that are newer than their input files (configure.ac and, if present, aclocal.m4).
–install
-i
Install the missing auxiliary files in the package. By default, files are copied; this can be changed with –symlink.
If deemed appropriate, this option triggers calls to ‘automake –add-missing’, ‘libtoolize’, ‘autopoint’, etc.
–no-recursive
Do not rebuild files in subdirectories to configure (see Subdirectories, macro AC_CONFIG_SUBDIRS).
–symlink
-s
When used with –install, install symbolic links to the missing auxiliary files instead of copying them.
–make
-m
When the directories were configured, update the configuration by running ‘./config.status –recheck && ./config.status’, and then run ‘make’.
–include=dir
-I dir
Append dir to the include path. Multiple invocations accumulate. Passed on to aclocal, autoconf and autoheader internally.
–prepend-include=dir
-B dir
Prepend dir to the include path. Multiple invocations accumulate. Passed on to autoconf and autoheader internally.
–warnings=category
-W category
Report the warnings related to category (which can actually be a comma separated list).
‘cross’
related to cross compilation issues.
‘obsolete’
report the uses of obsolete constructs.
‘portability’
portability issues
‘syntax’
dubious syntactic constructs.
‘all’
report all the warnings
‘none’
report none
‘error’
treats warnings as errors
‘no-category’
disable warnings falling into category
Warnings about ‘syntax’ are enabled by default, and the environment variable WARNINGS, a comma separated list of categories, is honored as well. Passing -W category actually behaves as if you had passed –warnings syntax,$WARNINGS,category. To disable the defaults and WARNINGS, and then enable warnings about obsolete constructs, use -W none,obsolete.
If you want autoreconf to pass flags that are not listed here on to aclocal, set ACLOCAL_AMFLAGS in your Makefile.am. Due to a limitation in the Autoconf implementation these flags currently must be set on a single line in Makefile.am, without any backslash-newlines.
Next: Existing Tests, Previous: Making configure Scripts, Up: Top
4 Initialization and Output Files
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.
- Initializing configure: Option processing etc.
- Versioning: Dealing with Autoconf versions
- Notices: Copyright, version numbers in configure
- Input: Where Autoconf should find files
- Output: Outputting results from the configuration
- Configuration Actions: Preparing the output based on results
- Configuration Files: Creating output files
- Makefile Substitutions: Using output variables in makefiles
- Configuration Headers: Creating a configuration header file
- Configuration Commands: Running arbitrary instantiation commands
- Configuration Links: Links depending on the configuration
- Subdirectories: Configuring independent packages together
- Default Prefix: Changing the default installation prefix
Next: Versioning, Up: Setup
4.1 Initializing configure
Every configure script must call AC_INIT before doing anything else that produces output. Calls to silent macros, such as AC_DEFUN, may also occur prior to AC_INIT, although these are generally used via aclocal.m4, since that is implicitly included before the start of configure.ac. The only other required macro is AC_OUTPUT (see Output).
— Macro: AC_INIT (package, version, [bug-report], [tarname], [url])
Process any command-line arguments and perform initialization and verification.
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 ‘-’. If provided, url should be the home page for the package.
The arguments of
AC_INITmust be static, i.e., there should not be any shell computation, quotes, or newlines, but they can be computed by M4. This is because the package information strings are expanded at M4 time into several contexts, and must give the same text at shell time whether used in single-quoted strings, double-quoted strings, quoted here-documents, or unquoted here-documents. It is permissible to usem4_esyscmdorm4_esyscmd_sfor computing a version string that changes with every commit to a version control system (in fact, Autoconf does just that, for all builds of the development tree made between releases).The following M4 macros (e.g.,
AC_PACKAGE_NAME), output variables (e.g.,PACKAGE_NAME), and preprocessor symbols (e.g.,PACKAGE_NAME), are defined byAC_INIT:
AC_PACKAGE_NAME,PACKAGE_NAME
AC_PACKAGE_TARNAME,PACKAGE_TARNAMEExactly tarname, possibly generated from package.
AC_PACKAGE_VERSION,PACKAGE_VERSION
AC_PACKAGE_STRING,PACKAGE_STRING
AC_PACKAGE_BUGREPORT,PACKAGE_BUGREPORTExactly bug-report, if one was provided. Typically an email address, or URL to a bug management web page.
AC_PACKAGE_URL,PACKAGE_URLExactly url, if one was provided. If url was empty, but package begins with ‘GNU ’, then this defaults to ‘http://www.gnu.org/software/tarname/’, otherwise, no URL is assumed.
If your configure script does its own option processing, it should inspect ‘$@’ or ‘$*’ immediately after calling AC_INIT, because other Autoconf macros liberally use the set command to process strings, and this has the side effect of updating ‘$@’ and ‘$*’. However, we suggest that you use standard macros like AC_ARG_ENABLE instead of attempting to implement your own option processing. See Site Configuration.
Next: Notices, Previous: Initializing configure, Up: Setup
4.2 Dealing with Autoconf versions
The following optional macros can be used to help choose the minimum version of Autoconf that can successfully compile a given configure.ac.
Ensure that a recent enough version of Autoconf is being used. If the version of Autoconf being used to create configure is earlier than version, print an error message to the standard error output and exit with failure (exit status is 63). For example:
AC_PREREQ([2.69])This macro may be used before
AC_INIT.
This macro was introduced in Autoconf 2.62. It identifies the version of Autoconf that is currently parsing the input file, in a format suitable for
m4_version_compare(see m4_version_compare); in other words, for this release of Autoconf, its value is ‘2.69’. One potential use of this macro is for writing conditional fallbacks based on when a feature was added to Autoconf, rather than usingAC_PREREQto require the newer version of Autoconf. However, remember that the Autoconf philosophy favors feature checks over version checks.You should not expand this macro directly; use ‘m4_defn([AC_AUTOCONF_VERSION])’ instead. This is because some users might have a beta version of Autoconf installed, with arbitrary letters included in its version string. This means it is possible for the version string to contain the name of a defined macro, such that expanding
AC_AUTOCONF_VERSIONwould trigger the expansion of that macro during rescanning, and change the version string to be different than what you intended to check.
Next: Input, Previous: Versioning, Up: Setup
4.3 Notices in configure
The following macros manage version numbers for configure scripts. Using them is optional.
— Macro: AC_COPYRIGHT (copyright-notice)
State that, in addition to the Free Software Foundation’s copyright on the Autoconf macros, parts of your configure are covered by the copyright-notice.
The copyright-notice shows up in both the head of configure and in ‘configure –version’.
— Macro: AC_REVISION (revision-info)
Copy revision stamp revision-info into the 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.30 $])produces this in configure:
#!/bin/sh # From configure.ac Revision: 1.30
Next: Output, Previous: Notices, Up: Setup
4.4 Finding configure Input
— Macro: AC_CONFIG_SRCDIR (unique-file-in-source-dir)
unique-file-in-source-dir is some file that is in the package’s source directory; 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 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.
— Macro: AC_CONFIG_AUX_DIR (dir)
Use the auxiliary build tools (e.g., install-sh, config.sub, config.guess, Cygnus 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_INSTALLdoes 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.The auxiliary directory is commonly named build-aux. If you need portability to DOS variants, do not name the auxiliary directory aux. See File System Conventions.
— Macro: AC_REQUIRE_AUX_FILE (file)
Declares that file is expected in the directory defined above. In Autoconf proper, this macro does nothing: its sole purpose is to be traced by third-party tools to produce a list of expected auxiliary files. For instance it is called by macros like
AC_PROG_INSTALL(see Particular Programs) orAC_CANONICAL_BUILD(see Canonicalizing) to register the auxiliary files they need.
Similarly, packages that use aclocal should declare where local macros can be found using AC_CONFIG_MACRO_DIR.
— Macro: AC_CONFIG_MACRO_DIR (dir)
Specify dir as the location of additional local Autoconf macros. This macro is intended for use by future versions of commands like autoreconf that trace macro calls. It should be called directly from configure.ac so that tools that install macros for aclocal can find the macros’ declarations.
Note that if you use aclocal from Automake to generate aclocal.m4, you must also set
ACLOCAL_AMFLAGS = -Idir in your top-level Makefile.am. Due to a limitation in the Autoconf implementation of autoreconf, these include directives currently must be set on a single line in Makefile.am, without any backslash-newlines.
Next: Configuration Actions, Previous: Input, Up: Setup
4.5 Outputting Files
Every Autoconf script, e.g., configure.ac, should finish by calling AC_OUTPUT. That is the macro that generates and runs config.status, which in turn creates the makefiles and any other files resulting from configuration. This is the only required macro besides AC_INIT (see Input).
Generate config.status and launch it. Call this macro once, at the end of configure.ac.
config.status performs all the configuration actions: all the output files (see Configuration Files, macro
AC_CONFIG_FILES), header files (see Configuration Headers, macroAC_CONFIG_HEADERS), commands (see Configuration Commands, macroAC_CONFIG_COMMANDS), links (see Configuration Links, macroAC_CONFIG_LINKS), subdirectories to configure (see Subdirectories, macroAC_CONFIG_SUBDIRS) are honored.The location of your
AC_OUTPUTinvocation is the exact point where configuration actions are taken: any code afterwards is executed by configure once config.status was run. If you want to bind actions to config.status itself (independently of whether configure is being run), see Running Arbitrary Configuration Commands.
Historically, the usage of AC_OUTPUT was somewhat different. See 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.
If the Make command,
$MAKEif set or else ‘make’, predefines$(MAKE), define output variableSET_MAKEto be empty. Otherwise, defineSET_MAKEto a macro definition that sets$(MAKE), such as ‘MAKE=make’. CallsAC_SUBSTforSET_MAKE.
If you use this macro, place a line like this in each Makefile.in that runs MAKE on other directories:
@SET_MAKE@
Next: Configuration Files, Previous: Output, Up: Setup
4.6 Performing Configuration Actions
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_ITEMS(tag..., [commands], [init-cmds])
where the arguments are:
tag…
A blank-or-newline-separated list of tags, which are typically the names of the files to instantiate.
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_ITEMS([$my_foos])
and use this instead:
... && AC_CONFIG_ITEMS([fooo])
... && AC_CONFIG_ITEMS([foooo])
The macros AC_CONFIG_FILES and AC_CONFIG_HEADERS use special tag values: they may have the form ‘output’ or ‘output:inputs’. The file output is instantiated from its templates, inputs (defaulting to ‘output.in’).
‘AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk])’, for example, asks for the creation of the file Makefile that contains 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 config.status Invocation, for more details.
The inputs may be absolute or relative file names. In the latter case they are first looked for in the build tree, and then in the source tree. Input files should be text files, and a line length below 2000 bytes should be safe.
commands
Shell commands output literally into config.status, and associated with a tag that the user can use to tell config.status which commands to run. The commands are run each time a tag request is given to config.status, typically each time the file tag is created.
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
The name of the top source directory, assuming that the working directory is the top build directory. This is what the configure option –srcdir sets.
ac_top_srcdir
The name of the top source directory, assuming that the working directory is the current build directory.
ac_top_build_prefix
The name of the top build directory, assuming that the working directory is the current build directory. It can be empty, or else ends with a slash, so that you may concatenate it.
ac_srcdir
The name of the corresponding source directory, assuming that the working directory is the current build directory.
tmp
The name of a temporary directory within the build tree, which you can use if you need to create additional temporary files. The directory is cleaned up when config.status is done or interrupted. Please use package-specific file name prefixes to avoid clashing with files that config.status may use internally.
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_build_prefix='../../'
# Concatenation of $ac_top_build_prefix and srcdir
ac_top_srcdir='../../../package'
# Concatenation of $ac_top_srcdir and deep/dir
ac_srcdir='../../../package/deep/dir'
independently of ‘in/in.in’.
init-cmds
Shell commands output unquoted near the beginning of config.status, and executed each time config.status runs (regardless of the tag). Because they are unquoted, for example, ‘$var’ is output as the value of 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 tag values, of course!
Next: Makefile Substitutions, Previous: Configuration Actions, Up: Setup
4.7 Creating Configuration Files
Be sure to read the previous section, Configuration Actions.
— Macro: AC_CONFIG_FILES (file…, [cmds], [init-cmds])
Make
AC_OUTPUTcreate 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 Configuration Actions. See Makefile Substitutions, for more information on using output variables. See 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, makefiles are created this way, but other files, such as .gdbinit, can be specified as well.Typical calls to
AC_CONFIG_FILESlook 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 DOS variants, or to prepend and/or append boilerplate to the file.
Next: Configuration Headers, Previous: Configuration Files, Up: Setup
4.8 Substitutions in Makefiles
Each subdirectory in a distribution that contains something to be compiled or installed should come with a file Makefile.in, from which configure creates a file Makefile in that directory. To create Makefile, configure performs a simple variable substitution, replacing occurrences of ‘@variable@’ in Makefile.in with the value that configure has determined for that variable. Variables that are substituted into output files in this way are called output variables. They are ordinary shell variables that are set in configure. To make configure substitute a particular variable into the output files, the macro AC_SUBST must be called with that variable name as an argument. Any occurrences of ‘@variable@’ for other variables are left unchanged. See Setting Output Variables, for more information on creating output variables with AC_SUBST.
A software package that uses a configure script should be distributed with a file Makefile.in, but no makefile; that way, the user has to properly configure the package for the local system before compiling it.
See Makefile Conventions, for more information on what to put in makefiles.
- Preset Output Variables: Output variables that are always set
- Installation Directory Variables: Other preset output variables
- Changed Directory Variables: Warnings about datarootdir
- Build Directories: Supporting multiple concurrent compiles
- Automatic Remaking: Makefile rules for configuring
Next: Installation Directory Variables, Up: Makefile Substitutions
4.8.1 Preset Output Variables
Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. See Output Variable Index, for a complete list of output variables. See Installation Directory Variables, for the list of the preset ones related to installation directories. Below are listed the other preset ones, many of which are precious variables (see Setting Output Variables, AC_ARG_VAR).
The preset variables which are available during config.status (see Configuration Actions) may also be used during configure tests. For example, it is permissible to reference ‘$srcdir’ when constructing a list of directories to pass via option -I during a compiler feature check. When used in this manner, coupled with the fact that configure is always run from the top build directory, it is sufficient to use just ‘$srcdir’ instead of ‘$top_srcdir’.
Debugging and optimization options for the C compiler. If it is not set in the environment when configure runs, the default value is set when you call
AC_PROG_CC(or empty if you don’t). configure uses this variable when compiling or linking programs to test for C features.If a compiler option affects only the behavior of the preprocessor (e.g., -Dname), it should be put into
CPPFLAGSinstead. If it affects only the linker (e.g., -Ldirectory), it should be put intoLDFLAGSinstead. If it affects only the compiler proper,CFLAGSis the natural home for it. If an option affects multiple phases of the compiler, though, matters get tricky. One approach to put such options directly intoCC, e.g.,CC='gcc -m64'. Another is to put them into bothCPPFLAGSandLDFLAGS, but not intoCFLAGS.However, remember that some Makefile variables are reserved by the GNU Coding Standards for the use of the “user”—the person building the package. For instance,
CFLAGSis one such variable.Sometimes package developers are tempted to set user variables such as
CFLAGSbecause it appears to make their job easier. However, the package itself should never set a user variable, particularly not to include switches that are required for proper compilation of the package. Since these variables are documented as being for the package builder, that person rightfully expects to be able to override any of these variables at build time. If the package developer needs to add switches without interfering with the user, the proper way to do that is to introduce an additional variable. Automake makes this easy by introducingAM_CFLAGS(see Flag Variables Ordering), but the concept is the same even if Automake is not used.
A comment saying that the file was generated automatically by configure and giving the name of the input file.
AC_OUTPUTadds a comment line containing this variable to the top of every makefile it creates. For other files, you should reference this variable in a comment at the top of each input file. For example, an input shell script should begin like this:#!/bin/sh # @configure_input@The presence of that line also reminds people editing the file that it needs to be processed by configure in order to be used.
Preprocessor options for the C, C++, Objective C, and Objective C++ preprocessors and compilers. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when preprocessing or compiling programs to test for C, C++, Objective C, and Objective C++ features.
This variable’s contents should contain options like -I, -D, and -U that affect only the behavior of the preprocessor. Please see the explanation of
CFLAGSfor what you can do if an option affects other phases of the compiler as well.Currently, configure always links as part of a single invocation of the compiler that also preprocesses and compiles, so it uses this variable also when linking programs. However, it is unwise to depend on this behavior because the GNU Coding Standards do not require it and many packages do not use
CPPFLAGSwhen linking programs.See Special Chars in Variables, for limitations that
CPPFLAGSmight run into.
Debugging and optimization options for the C++ compiler. It acts like
CFLAGS, but for C++ instead of C.
-D options to pass to the C compiler. If
AC_CONFIG_HEADERSis called, configure replaces ‘@DEFS@’ with -DHAVE_CONFIG_H instead (see Configuration Headers). This variable is not defined while configure is performing its tests, only when creating the output files. See Setting Output Variables, for how to check the results of previous tests.
— Variable: ECHO_C
— Variable: ECHO_N
— Variable: ECHO_T
How does one suppress the trailing newline from echo for question-answer message pairs? These variables provide a way:
echo $ECHO_N "And the winner is... $ECHO_C" sleep 100000000000 echo "${ECHO_T}dead."Some old and uncommon echo implementations offer no means to achieve this, in which case
ECHO_Tis set to tab. You might not want to use it.
Debugging and optimization options for the Erlang compiler. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when compiling programs to test for Erlang features.
Debugging and optimization options for the Fortran compiler. If it is not set in the environment when configure runs, the default value is set when you call
AC_PROG_FC(or empty if you don’t). configure uses this variable when compiling or linking programs to test for Fortran features.
Debugging and optimization options for the Fortran 77 compiler. If it is not set in the environment when configure runs, the default value is set when you call
AC_PROG_F77(or empty if you don’t). configure uses this variable when compiling or linking programs to test for Fortran 77 features.
Options for the linker. If it is not set in the environment when configure runs, the default value is empty. configure uses this variable when linking programs to test for C, C++, Objective C, Objective C++, Fortran, and Go features.
This variable’s contents should contain options like -s and -L that affect only the behavior of the linker. Please see the explanation of
CFLAGSfor what you can do if an option also affects other phases of the compiler.Don’t use this variable to pass library names (-l) to the linker; use
LIBSinstead.
-l options to pass to the linker. The default value is empty, but some Autoconf macros may prepend extra libraries to this variable if those libraries are found and provide necessary functions, see Libraries. configure uses this variable when linking programs to test for C, C++, Objective C, Objective C++, Fortran, and Go features.
Debugging and optimization options for the Objective C compiler. It acts like
CFLAGS, but for Objective C instead of C.
Debugging and optimization options for the Objective C++ compiler. It acts like
CXXFLAGS, but for Objective C++ instead of C++.
Debugging and optimization options for the Go compiler. It acts like
CFLAGS, but for Go instead of C.
The relative name of the top level of the current build tree. In the top-level directory, this is the same as
builddir.
The relative name of the top level of the current build tree with final slash if nonempty. This is the same as
top_builddir, except that it contains zero or more runs of../, so it should not be appended with a slash for concatenation. This helps for make implementations that otherwise do not treat ./file and file as equal in the toplevel build directory.
The name of the directory that contains the source code for that makefile.
The name of the top-level source code directory for the package. In the top-level directory, this is the same as
srcdir.
Next: Changed Directory Variables, Previous: Preset Output Variables, Up: Makefile Substitutions
4.8.2 Installation Directory Variables
The following variables specify the directories for package installation, see Variables for Installation Directories, for more information. Each variable corresponds to an argument of configure; trailing slashes are stripped so that expressions such as ‘${prefix}/lib’ expand with only one slash between directory names. See the end of this section for details on when and how to use these variables.
The directory for installing idiosyncratic read-only architecture-independent data.
The root of the directory tree for read-only architecture-independent data files.
The directory for installing documentation files (other than Info and man).
The directory for installing documentation files in DVI format.
The installation prefix for architecture-dependent files. By default it’s the same as
prefix. You should avoid installing anything directly toexec_prefix. However, the default value for directories containing architecture-dependent files should be relative toexec_prefix.
The directory for installing executables that other programs run.
The directory for installing locale-dependent but architecture-independent data, such as message catalogs. This directory usually has a subdirectory per locale.
The directory for installing modifiable single-machine data.
The top-level directory for installing documentation in man format.
The directory for installing C header files for non-GCC compilers.
The common installation prefix for all files. If
exec_prefixis defined to a different value,prefixis used only for architecture-independent files.
The directory for installing executables that system administrators run.
The directory for installing modifiable architecture-independent data.
Most of these variables have values that rely on prefix or exec_prefix. It is deliberate that the directory output variables keep them unexpanded: typically ‘@datarootdir@’ is replaced by ‘${prefix}/share’, not ‘/usr/local/share’, and ‘@datadir@’ is replaced by ‘${datarootdir}’.
This behavior is mandated by the GNU Coding Standards, so that when the user runs:
‘make’
she can still specify a different prefix from the one specified to configure, in which case, if needed, the package should hard code dependencies corresponding to the make-specified prefix.
‘make install’
she can specify a different installation location, in which case the package must still depend on the location which was compiled in (i.e., never recompile when ‘make install’ is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there.
In order to support these features, it is essential that datarootdir remains defined as ‘${prefix}/share’, so that its value can be expanded based on the current value of prefix.
A corollary is that you should not use these variables except in makefiles. For instance, instead of trying to evaluate datadir in configure and hard-coding it in makefiles using e.g., ‘AC_DEFINE_UNQUOTED([DATADIR], [“$datadir”], [Data directory.])’, you should add -DDATADIR=’$(datadir)’ to your makefile’s definition of CPPFLAGS (AM_CPPFLAGS if you are also using Automake).
Similarly, you should not rely on AC_CONFIG_FILES to replace bindir and friends in your shell scripts and other files; instead, let make manage their replacement. For instance Autoconf ships templates of its shell scripts ending with ‘.in’, and uses a makefile snippet similar to the following to build scripts like autoheader and autom4te:
edit = sed \
-e 's|@bindir[@]|$(bindir)|g' \
-e 's|@pkgdatadir[@]|$(pkgdatadir)|g' \
-e 's|@prefix[@]|$(prefix)|g'
autoheader autom4te: Makefile
rm -f $@ $@.tmp
srcdir=''; \
test -f ./$@.in || srcdir=$(srcdir)/; \
$(edit) $${srcdir}$@.in >$@.tmp
chmod +x $@.tmp
chmod a-w $@.tmp
mv $@.tmp $@
autoheader: $(srcdir)/autoheader.in
autom4te: $(srcdir)/autom4te.in
Some details are noteworthy:
‘@bindir[@]’
The brackets prevent configure from replacing ‘@bindir@’ in the Sed expression itself. Brackets are preferable to a backslash here, since Posix says ‘\@’ is not portable.
‘$(bindir)’
Don’t use ‘@bindir@’! Use the matching makefile variable instead.
‘$(pkgdatadir)’
The example takes advantage of the variable ‘$(pkgdatadir)’ provided by Automake; it is equivalent to ‘$(datadir)/$(PACKAGE)’.
‘/’
Don’t use ‘/’ in the Sed expressions that replace file names since most likely the variables you use, such as ‘$(bindir)’, contain ‘/’. Use a shell metacharacter instead, such as ‘|’.
special characters
File names, file name components, and the value of VPATH should not contain shell metacharacters or white space. See Special Chars in Variables.
dependency on Makefile
Since edit uses values that depend on the configuration specific values (prefix, etc.) and not only on VERSION and so forth, the output depends on Makefile, not configure.ac.
‘$@’
The main rule is generic, and uses ‘$@’ extensively to avoid the need for multiple copies of the rule.
Separated dependencies and single suffix rules
You can’t use them! The above snippet cannot be (portably) rewritten as:
autoconf autoheader: Makefile
.in:
rm -f $@ $@.tmp
$(edit) $< >$@.tmp
chmod +x $@.tmp
mv $@.tmp $@
See Single Suffix Rules, for details.
‘$(srcdir)’
Be sure to specify the name of the source directory, otherwise the package won’t support separated builds.
For the more specific installation of Erlang libraries, the following variables are defined:
— Variable: ERLANG_INSTALL_LIB_DIR
The common parent directory of Erlang library installation directories. This variable is set by calling the
AC_ERLANG_SUBST_INSTALL_LIB_DIRmacro in configure.ac.
— Variable: ERLANG_INSTALL_LIB_DIR_library
The installation directory for Erlang library library. This variable is set by using the ‘AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR’ macro in configure.ac.
See Erlang Libraries, for details.
Next: Build Directories, Previous: Installation Directory Variables, Up: Makefile Substitutions
4.8.3 Changed Directory Variables
In Autoconf 2.60, the set of directory variables has changed, and the defaults of some variables have been adjusted (see Installation Directory Variables) to changes in the GNU Coding Standards. Notably, datadir, infodir, and mandir are now expressed in terms of datarootdir. If you are upgrading from an earlier Autoconf version, you may need to adjust your files to ensure that the directory variables are substituted correctly (see Defining Directories), and that a definition of datarootdir is in place. For example, in a Makefile.in, adding
datarootdir = @datarootdir@
is usually sufficient. If you use Automake to create Makefile.in, it will add this for you.
To help with the transition, Autoconf warns about files that seem to use datarootdir without defining it. In some cases, it then expands the value of $datarootdir in substitutions of the directory variables. The following example shows such a warning:
$ cat configure.ac
AC_INIT
AC_CONFIG_FILES([Makefile])
AC_OUTPUT
$ cat Makefile.in
prefix = @prefix@
datadir = @datadir@
$ autoconf
$ configure
configure: creating ./config.status
config.status: creating Makefile
config.status: WARNING:
Makefile.in seems to ignore the --datarootdir setting
$ cat Makefile
prefix = /usr/local
datadir = ${prefix}/share
Usually one can easily change the file to accommodate both older and newer Autoconf releases:
$ cat Makefile.in
prefix = @prefix@
datarootdir = @datarootdir@
datadir = @datadir@
$ configure
configure: creating ./config.status
config.status: creating Makefile
$ cat Makefile
prefix = /usr/local
datarootdir = ${prefix}/share
datadir = ${datarootdir}
In some cases, however, the checks may not be able to detect that a suitable initialization of datarootdir is in place, or they may fail to detect that such an initialization is necessary in the output file. If, after auditing your package, there are still spurious configure warnings about datarootdir, you may add the line
AC_DEFUN([AC_DATAROOTDIR_CHECKED])
to your configure.ac to disable the warnings. This is an exception to the usual rule that you should not define a macro whose name begins with AC_ (see Macro Names).
Next: Automatic Remaking, Previous: Changed Directory Variables, Up: Makefile Substitutions
4.8.4 Build Directories
You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory.
To support doing this, make uses the VPATH variable to find the files that are in the source directory. GNU Make can do this. Most other recent make programs can do this as well, though they may have difficulties and it is often simpler to recommend GNU make (see VPATH and Make). Older make programs do not support VPATH; when using them, the source code must be in the same directory as the object files.
If you are using GNU Automake, the remaining details in this section are already covered for you, based on the contents of your Makefile.am. But if you are using Autoconf in isolation, then supporting VPATH requires the following in your Makefile.in:
srcdir = @srcdir@
VPATH = @srcdir@
Do not set VPATH to the value of another variable (see Variables listed in VPATH.
configure substitutes the correct value for srcdir when it produces Makefile.
Do not use the make variable $<, which expands to the file name of the file in the source directory (found with VPATH), except in implicit rules. (An implicit rule is one such as ‘.c.o’, which tells how to create a .o file from a .c file.) Some versions of make do not set $< in explicit rules; they expand it to an empty value.
Instead, Make command lines should always refer to source files by prefixing them with ‘$(srcdir)/’. For example:
time.info: time.texinfo
$(MAKEINFO) '$(srcdir)/time.texinfo'
Previous: Build Directories, Up: Makefile Substitutions
待续…
发布者：全栈程序员-用户IM，转载请注明出处：https://javaforall.cn/135980.html原文链接：https://javaforall.cn
【正版授权，激活自己账号】： Jetbrains全家桶Ide使用，1年售后保障，每天仅需1毛
【官方授权 正版激活】： 官方授权 正版激活 支持Jetbrains家族下所有IDE 使用个人JB账号...
