START-INFO-DIR-ENTRY * Autoconf: (autoconf). Create source code configuration scripts END-INFO-DIR-ENTRY START-INFO-DIR-ENTRY * autoscan: (autoconf)autoscan Invocation. Semi-automatic `configure.ac' writing * ifnames: (autoconf)ifnames Invocation. Listing the conditionals in source code * autoconf: (autoconf)autoconf Invocation. How to create configuration scripts * autoreconf: (autoconf)autoreconf Invocation. Remaking multiple `configure' scripts * configure: (autoconf)configure Invocation. Configuring a package * config.status: (autoconf)config.status Invocation. Recreating a configuration * testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite END-INFO-DIR-ENTRY Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie. This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and an `m4' macro package. Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License". Autoconf ******** This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and the GNU M4 macro package. This is edition 2.53, for Autoconf version 2.53. 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 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. *Note The GNU build system::, for more information. Autoconf imposes some restrictions on the names of macros used with `#if' in C programs (*note 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. *Note Autoconf 1::, for information about upgrading from version 1. *Note History::, for the story of Autoconf's development. *Note Questions::, for answers to some common questions about Autoconf. See the Autoconf web page(1) 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(2), 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(3). 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(4), which is kindly run by Peter Simons . ---------- Footnotes ---------- (1) Autoconf web page, . (2) Autoconf Gnats database, . (3) CVSweb interface to the Autoconf development tree, . (4) Autoconf Macro Archive, . 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 ======== 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... Libtool ======= 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 to 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. 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 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. - Web The home pages for Autoconf(1), Automake(2), and Libtool(3). - Automake Manual *Note Automake: (automake)Top, for more information on Automake. - Books The book `GNU Autoconf, Automake and Libtool'(4) describes the complete GNU build environment. You can also find the entire book on-line at "The Goat Book" home page(5). - Tutorials and Examples The Autoconf Developer Page(6) maintains links to a number of Autoconf/Automake tutorials online, and also links to the Autoconf Macro Archive(7). ---------- Footnotes ---------- (1) Autoconf, . (2) Automake, . (3) Libtool, . (4) `GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902. (5) "The Goat Book" home page, . (6) Autoconf Developer Page, . (7) Autoconf Macro Archive, . 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, one in each subdirectory of the package (*note Makefile Substitutions::); - optionally, a C header file, the name of which is configurable, containing `#define' directives (*note Configuration Headers::); - a shell script called `config.status' that, when run, will recreate the files listed above (*note 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 (*note 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 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 ---' 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 *Note Existing Tests::, for their descriptions. For most other features, you can use Autoconf template macros to produce custom checks; see *Note Writing Tests::, for information about them. For especially tricky or specialized features, `configure.ac' might need to contain some hand-crafted shell commands; see *Note Portable Shell::. The `autoscan' program can give you a good start in writing `configure.ac' (*note autoscan Invocation::, for more information). Previous versions of Autoconf promoted the name `configure.in', which is somewhat ambiguous (the tool needed to produce 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. 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, 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. The Autoconf Language --------------------- 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])]) Voila`, 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. 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 (*note 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 (*note 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' 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 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' (*note Configuration Headers::). You might also have to change or add some `#if' directives to your program in order to make it work with Autoconf (*note 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' 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: `--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. `--include=DIR' `-I DIR' Also look for input files in DIR. Multiple invocations accumulate. Directories are browsed from last to first. 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' (*note 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. 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 (*note 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' Also look for input files in DIR. Multiple invocations accumulate. Directories are browsed from last to first. `--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). *Note 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. `autoconf -W CATEGORY' will actually behave as if you had run: autoconf --warnings=syntax,$WARNINGS,CATEGORY If you want to disable `autoconf''s defaults and `WARNINGS', but (for example) enable the warnings about obsolete constructs, you would use `-W none,obsolete'. `autoconf' displays a back trace for errors, but not for warnings; if you want them, just pass `-W error'. For instance, on this `configure.ac': AC_DEFUN([INNER], [AC_TRY_RUN([exit (0)])]) AC_DEFUN([OUTER], [INNER]) AC_INIT OUTER you get: $ autoconf -Wcross configure.ac:8: warning: AC_TRY_RUN called without default \ to allow cross compiling $ autoconf -Wcross,error configure.ac:8: error: AC_TRY_RUN called without default \ to allow cross compiling acgeneral.m4:3044: AC_TRY_RUN is expanded from... configure.ac:2: INNER is expanded from... configure.ac:5: OUTER is expanded from... configure.ac:8: the top level `--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 below 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'. The FORMAT of `--trace' can use the following special escapes: `$$' The character `$'. `$f' The filename from which MACRO is called. `$l' The line number from which MACRO is called. `$d' The depth of the MACRO call. This is an M4 technical detail that you probably don't want to know about. `$n' The name of the MACRO. `$NUM' The NUMth argument of the call to MACRO. `$@' `$SEP@' `${SEPARATOR}@' All the arguments passed to MACRO, separated by the character SEP or the string SEPARATOR (`,' by default). Each argument is quoted, i.e. enclosed in a pair of square brackets. `$*' `$SEP*' `${SEPARATOR}*' As above, but the arguments are not quoted. `$%' `$SEP%' `${SEPARATOR}%' As above, but the arguments are not quoted, all new line characters in the arguments are smashed, and the default separator is `:'. The escape `$%' produces single-line trace outputs (unless you put newlines in the `separator'), while `$@' and `$*' do not. 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 its 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 Using `autoreconf' to Update `configure' Scripts ================================================ Installing the various components of the GNU Build System can be tedious: running `gettextize', `automake' 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. It runs `autoconf', `autoheader', `aclocal', `automake', `libtoolize', and `gettextize' (when appropriate) repeatedly to update the GNU Build System in specified directories, and their subdirectories (*note Subdirectories::). By default, it only remakes those files that are older than their sources. If you install a new version of some tools, you can make `autoreconf' remake _all_ of the files by giving it the `--force' option. *Note 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: `--help' `-h' Print a summary of the command line options and exit. `--version' `-V' Print the version number of Autoconf and exit. `--verbose' Print the name of each directory where `autoreconf' runs `autoconf' (and `autoheader', if appropriate). `--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' Copy missing auxiliary files. This option is similar to the option `--add-missing' in `automake'. `--symlink' `-s' Instead of copying missing auxiliary files, install symbolic links. `--include=DIR' `-I DIR' Also look for input files in DIR. Multiple invocations accumulate. Directories are browsed from last to first. 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 initialization and the creation of output files. Initializing `configure' ======================== Every `configure' script must call `AC_INIT' before doing anything else. The only other required macro is `AC_OUTPUT' (*note Output::). - Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT], [TARNAME]) Process any command-line arguments and perform various initializations and verifications. 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 latter is meant for distribution tar ball names (e.g., `autoconf'). It defaults to PACKAGE once `GNU ' strip, lower cased, and all non alphanumeric character mapped onto `-'. It is preferable that these arguments 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 then defined: `AC_PACKAGE_NAME', `PACKAGE_NAME' Exactly PACKAGE. `AC_PACKAGE_TARNAME', `PACKAGE_TARNAME' Exactly TARNAME. `AC_PACKAGE_VERSION', `PACKAGE_VERSION' Exactly VERSION. `AC_PACKAGE_STRING', `PACKAGE_STRING' Exactly `PACKAGE VERSION'. `AC_PACKAGE_BUGREPORT', `PACKAGE_BUGREPORT' Exactly BUG-REPORT. Notices in `configure' ====================== The following macros manage version numbers for `configure' scripts. Using them is optional. - Macro: AC_PREREQ (VERSION) 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 do not create `configure'. For example: AC_PREREQ(2.53) This macro is the only macro that may be used before `AC_INIT', but for consistency, you are invited not to do so. - 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 will show 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 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. *Note 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_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'. Outputting Files ================ Every Autoconf script, e.g., `configure.ac', should finish by calling `AC_OUTPUT'. It is the macro that generates `config.status', which will create the `Makefile's and any other files resulting from configuration. The only required macro is `AC_INIT' (*note Input::). - Macro: AC_OUTPUT Generate `config.status' and launch it. Call this macro once, at the end of `configure.ac'. `config.status' will take all the configuration actions: all the output files (see *Note Configuration Files::, macro `AC_CONFIG_FILES'), header files (see *Note Configuration Headers::, macro `AC_CONFIG_HEADERS'), commands (see *Note Configuration Commands::, macro `AC_CONFIG_COMMANDS'), links (see *Note Configuration Links::, macro `AC_CONFIG_LINKS'), subdirectories to configure (see *Note Subdirectories::, macro `AC_CONFIG_SUBDIRS') are honored. Historically, the usage of `AC_OUTPUT' was somewhat different. *Note Obsolete Macros::, for a description of the arguments that `AC_OUTPUT' used to support. If you run `make' on 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. - Macro: AC_PROG_MAKE_SET If `make' predefines the variable `MAKE', define output variable `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to contain `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. To use this macro, place a line like this in each `Makefile.in' that runs `MAKE' on other directories: @SET_MAKE@ Taking 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_FOOS(TAG..., [COMMANDS], [INIT-CMDS]) where the arguments are: TAG... A whitespace-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_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 *Note config.status Invocation::, 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. COMMANDS Shell commands output literally into `config.status', and associated with a tag that the user can use to tell `config.status' which the 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 variable 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 path from the top build directory to the top source directory. This is what `configure''s option `--srcdir' sets. `ac_top_srcdir' The path from the current build directory to the top source directory. `ac_top_builddir' The path from the current build directory to the top build directory. It can be empty, or else ends with a slash, so that you may concatenate it. `ac_srcdir' The path from the current build directory to the corresponding source directory. 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'. 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' will be 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 TAGs, of course! Creating Configuration Files ============================ Be sure to read the previous section, *Note Configuration Actions::. - Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS]) Make `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 *Note Configuration Actions::. *Note Makefile Substitutions::, for more information on using output variables. *Note 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. 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' will create a `Makefile' in that directory. To create a `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. *Note 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. *Note Makefile Conventions: (standards)Makefile Conventions, for more information on what to put in `Makefile's. 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. *Note Output Variable Index::, for a complete list of output variables. *Note Installation Directory Variables::, for the list of the preset ones related to installation directories. Below are listed the other preset ones. They all are precious variables (*note Setting Output Variables::, `AC_ARG_VAR'). - Variable: CFLAGS 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 programs to test for C features. - Variable: configure_input A comment saying that the file was generated automatically by `configure' and giving the name of the input file. `AC_OUTPUT' adds 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. - Variable: CPPFLAGS Header file search directory (`-IDIR') and any other miscellaneous options for the C and 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 compiling or preprocessing programs to test for C and C++ features. - Variable: CXXFLAGS 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_CXX' (or empty if you don't). `configure' uses this variable when compiling programs to test for C++ features. - Variable: DEFS `-D' options to pass to the C compiler. If `AC_CONFIG_HEADERS' is called, `configure' replaces `@DEFS@' with `-DHAVE_CONFIG_H' instead (*note Configuration Headers::). This variable is not defined while `configure' is performing its tests, only when creating the output files. *Note 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_T' is set to tab. You might not want to use it. - Variable: FFLAGS 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 programs to test for Fortran 77 features. - Variable: LDFLAGS Stripping (`-s'), path (`-L'), and any other miscellaneous options for the linker. Don't use this variable to pass library names (`-l') to the linker, use `LIBS' instead. 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++ and Fortran 77 features. - Variable: LIBS `-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 *Note Libraries::. `configure' uses this variable when linking programs to test for C, C++ and Fortran 77 features. - Variable: builddir Rigorously equal to `.'. Added for symmetry only. - Variable: abs_builddir Absolute path of `builddir'. - Variable: top_builddir The relative path to the top-level of the current build tree. In the top-level directory, this is the same as `srcbuild'. - Variable: abs_top_builddir Absolute path of `top_builddir'. - Variable: srcdir The relative path to the directory that contains the source code for that `Makefile'. - Variable: abs_srcdir Absolute path of `srcdir'. - Variable: top_srcdir The relative path to the top-level source code directory for the package. In the top-level directory, this is the same as `srcdir'. - Variable: abs_top_srcdir Absolute path of `top_srcdir'. Installation Directory Variables -------------------------------- The following variables specify the directories where the package will be installed, see *Note Variables for Installation Directories: (standards)Directory Variables, for more information. See the end of this section for details on when and how to use these variables. - Variable: bindir The directory for installing executables that users run. - Variable: datadir The directory for installing read-only architecture-independent data. - Variable: exec_prefix The installation prefix for architecture-dependent files. By default it's the same as PREFIX. You should avoid installing anything directly to EXEC_PREFIX. However, the default value for directories containing architecture-dependent files should be relative to EXEC_PREFIX. - Variable: includedir The directory for installing C header files. - Variable: infodir The directory for installing documentation in Info format. - Variable: libdir The directory for installing object code libraries. - Variable: libexecdir The directory for installing executables that other programs run. - Variable: localstatedir The directory for installing modifiable single-machine data. - Variable: mandir The top-level directory for installing documentation in man format. - Variable: oldincludedir The directory for installing C header files for non-gcc compilers. - Variable: prefix The common installation prefix for all files. If EXEC_PREFIX is defined to a different value, PREFIX is used only for architecture-independent files. - Variable: sbindir The directory for installing executables that system administrators run. - Variable: sharedstatedir The directory for installing modifiable architecture-independent data. - Variable: sysconfdir The directory for installing read-only single-machine 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 `@datadir@' will be replaced by `${prefix}/share', not `/usr/local/share'. 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 shall 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 `datadir' remains being defined as `${prefix}/share' to depend upon 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 hardcoding it in Makefiles using e.g. `AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add `-DDATADIR="$(datadir)"' to your `CPPFLAGS'. Similarly you should not rely on `AC_OUTPUT_FILES' to replace `datadir' and friends in your shell scripts and other files, rather let `make' manage their replacement. For instance Autoconf ships templates of its shell scripts ending with `.sh', and uses this Makefile snippet: .sh: rm -f $@ $@.tmp sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp chmod +x $@.tmp mv $@.tmp $@ Three things are noteworthy: `@datadir\@' The backslash prevents `configure' from replacing `@datadir@' in the sed expression itself. `$(pkgdatadir)' Don't use `@pkgdatadir@'! Use the matching makefile variable instead. `,' Don't use `/' in the sed expression(s) since most probably the variables you use, such as `$(pkgdatadir)', will contain some. 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' and most other recent `make' programs can do this. Older `make' programs do not support `VPATH'; when using them, the source code must be in the same directory as the object files. To support `VPATH', each `Makefile.in' should contain two lines that look like: srcdir = @srcdir@ VPATH = @srcdir@ Do not set `VPATH' to the value of another variable, for example `VPATH = $(srcdir)', because some versions of `make' do not do variable substitutions on the value of `VPATH'. `configure' substitutes in 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, `Makefile' command lines should always refer to source files by prefixing them with `$(srcdir)/'. For example: time.info: time.texinfo $(MAKEINFO) $(srcdir)/time.texinfo Automatic Remaking ------------------ You can put rules like the following in the top-level `Makefile.in' for a package to automatically update the configuration information when you change the configuration files. This example includes all of the optional files, such as `aclocal.m4' and those related to configuration header files. Omit from the `Makefile.in' rules for any of these files that your package does not use. The `$(srcdir)/' prefix is included because of limitations in the `VPATH' mechanism. The `stamp-' files are necessary because the timestamps of `config.h.in' and `config.h' will not be changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file `stamp-h.in' your package's distribution, so `make' will consider `config.h.in' up to date. Don't use `touch' (*note Limitations of Usual Tools::), rather use `echo' (using `date' would cause needless differences, hence CVS conflicts etc.). $(srcdir)/configure: configure.ac aclocal.m4 cd $(srcdir) && autoconf # autoheader might not change config.h.in, so touch a stamp file. $(srcdir)/config.h.in: stamp-h.in $(srcdir)/stamp-h.in: configure.ac aclocal.m4 cd $(srcdir) && autoheader echo timestamp > $(srcdir)/stamp-h.in config.h: stamp-h stamp-h: config.h.in config.status ./config.status Makefile: Makefile.in config.status ./config.status config.status: configure ./config.status --recheck (Be careful if you copy these lines directly into your Makefile, as you will need to convert the indented lines to start with the tab character.) In addition, you should use `AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h])' so `config.status' will ensure that `config.h' is considered up to date. *Note Output::, for more information about `AC_OUTPUT'. *Note config.status Invocation::, for more examples of handling configuration-related dependencies. Configuration Header Files ========================== When a package tests more than a few C preprocessor symbols, the command lines to pass `-D' options to the compiler can get quite long. This causes two problems. One is that the `make' output is hard to visually scan for errors. More seriously, the command lines can exceed the length limits of some operating systems. As an alternative to passing `-D' options to the compiler, `configure' scripts can create a C header file containing `#define' directives. The `AC_CONFIG_HEADERS' macro selects this kind of output. It should be called right after `AC_INIT'. The package should `#include' the configuration header file before any other header files, to prevent inconsistencies in declarations (for example, if it redefines `const'). Use `#include ' instead of `#include "config.h"', and pass the C compiler a `-I.' option (or `-I..'; whichever directory contains `config.h'). That way, even if the source directory is configured itself (perhaps to make a distribution), other build directories can also be configured without finding the `config.h' from the source directory. - Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS]) This macro is one of the instantiating macros, see *Note Configuration Actions::. Make `AC_OUTPUT' create the file(s) in the whitespace-separated list HEADER containing C preprocessor `#define' statements, and replace `@DEFS@' in generated files with `-DHAVE_CONFIG_H' instead of the value of `DEFS'. The usual name for HEADER is `config.h'. If HEADER already exists and its contents are identical to what `AC_OUTPUT' would put in it, it is left alone. Doing this allows some changes in configuration without needlessly causing object files that depend on the header file to be recompiled. Usually the input file is named `HEADER.in'; however, you can override the input file name by appending to HEADER, a colon-separated list of input files. Examples: AC_CONFIG_HEADERS([config.h:config.hin]) AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post]) Doing this allows you to keep your file names acceptable to MS-DOS, or to prepend and/or append boilerplate to the file. *Note Configuration Actions::, for more details on HEADER. Configuration Header Templates ------------------------------ Your distribution should contain a template file that looks as you want the final header file to look, including comments, with `#undef' statements which are used as hooks. For example, suppose your `configure.ac' makes these calls: AC_CONFIG_HEADERS([conf.h]) AC_CHECK_HEADERS([unistd.h]) Then you could have code like the following in `conf.h.in'. On systems that have `unistd.h', `configure' will `#define' `HAVE_UNISTD_H' to 1. On other systems, the whole line will be commented out (in case the system predefines that symbol). /* Define as 1 if you have unistd.h. */ #undef HAVE_UNISTD_H You can then decode the configuration header using the preprocessor directives: #include #if HAVE_UNISTD_H # include #else /* We are in trouble. */ #endif The use of old form templates, with `#define' instead of `#undef' is strongly discouraged. Since it is a tedious task to keep a template header up to date, you may use `autoheader' to generate it, see *Note autoheader Invocation::. Using `autoheader' to Create `config.h.in' ------------------------------------------ The `autoheader' program can create a template file of C `#define' statements for `configure' to use. If `configure.ac' invokes `AC_CONFIG_HEADERS(FILE)', `autoheader' creates `FILE.in'; if multiple file arguments are given, the first one is used. Otherwise, `autoheader' creates `config.h.in'. In order to do its job, `autoheader' needs you to document all of the symbols that you might use; i.e., there must be at least one `AC_DEFINE' or one `AC_DEFINE_UNQUOTED' using its third argument for each symbol (*note Defining Symbols::). An additional constraint is that the first argument of `AC_DEFINE' must be a literal. Note that all symbols defined by Autoconf's built-in tests are already documented properly; you only need to document those that you define yourself. You might wonder why `autoheader' is needed: after all, why would `configure' need to "patch" a `config.h.in' to produce a `config.h' instead of just creating `config.h' from scratch? Well, when everything rocks, the answer is just that we are wasting our time maintaining `autoheader': generating `config.h' directly is all that is needed. When things go wrong, however, you'll be thankful for the existence of `autoheader'. The fact that the symbols are documented is important in order to _check_ that `config.h' makes sense. The fact that there is a well defined list of symbols that should be `#define''d (or not) is also important for people who are porting packages to environments where `configure' cannot be run: they just have to _fill in the blanks_. But let's come back to the point: `autoheader''s invocation... If you give `autoheader' an argument, it uses that file instead of `configure.ac' and writes the header file to the standard output instead of to `config.h.in'. If you give `autoheader' an argument of `-', it reads the standard input instead of `configure.ac' and writes the header file to the standard output. `autoheader' 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 the template file even if newer than its input files. `--include=DIR' `-I DIR' Also look for input files in DIR. Multiple invocations accumulate. Directories are browsed from last to first. `--warnings=CATEGORY' `-W CATEGORY' Report the warnings related to CATEGORY (which can actually be a comma separated list). Current categories include: `obsolete' report the uses of obsolete constructs `all' report all the warnings `none' report none `error' treats warnings as errors `no-CATEGORY' disable warnings falling into CATEGORY Autoheader Macros ----------------- `autoheader' scans `configure.ac' and figures out which C preprocessor symbols it might define. It knows how to generate templates for symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS' etc., but if you `AC_DEFINE' any additional symbol, you must define a template for it. If there are missing templates, `autoheader' fails with an error message. The simplest way to create a template for a SYMBOL is to supply the DESCRIPTION argument to an `AC_DEFINE(SYMBOL)'; see *Note Defining Symbols::. You may also use one of the following macros. - Macro: AH_VERBATIM (KEY, TEMPLATE) Tell `autoheader' to include the TEMPLATE as-is in the header template file. This TEMPLATE is associated with the KEY, which is used to sort all the different templates and guarantee their uniqueness. It should be the symbol that can be `AC_DEFINE''d. For example: AH_VERBATIM([_GNU_SOURCE], [/* Enable GNU extensions on systems that have them. */ #ifndef _GNU_SOURCE # define _GNU_SOURCE #endif]) - Macro: AH_TEMPLATE (KEY, DESCRIPTION) Tell `autoheader' to generate a template for KEY. This macro generates standard templates just like `AC_DEFINE' when a DESCRIPTION is given. For example: AH_TEMPLATE([CRAY_STACKSEG_END], [Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. This function is required for alloca.c support on those systems.]) will generate the following template, with the description properly justified. /* Define to one of _getb67, GETB67, getb67 for Cray-2 and Cray-YMP systems. This function is required for alloca.c support on those systems. */ #undef CRAY_STACKSEG_END - Macro: AH_TOP (TEXT) Include TEXT at the top of the header template file. - Macro: AH_BOTTOM (TEXT) Include TEXT at the bottom of the header template file. Running Arbitrary Configuration Commands ======================================== You execute arbitrary commands either before, during and after `config.status' is run. The three following macros accumulate the commands to run when they are called multiple times. `AC_CONFIG_COMMANDS' replaces the obsolete macro `AC_OUTPUT_COMMANDS', see *Note Obsolete Macros::, for details. - Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS]) Specify additional shell commands to run at the end of `config.status', and shell commands to initialize any variables from `configure'. Associate the commands to the TAG. Since typically the CMDS create a file, TAG should naturally be the name of that file. This macro is one of the instantiating macros, see *Note Configuration Actions::. Here is an unrealistic example: fubar=42 AC_CONFIG_COMMANDS([fubar], [echo this is extra $fubar, and so on.], [fubar=$fubar]) Here is a better one: AC_CONFIG_COMMANDS([time-stamp], [date >time-stamp]) - Macro: AC_CONFIG_COMMANDS_PRE (CMDS) Execute the CMDS right before creating `config.status'. A typical use is computing values derived from variables built during the execution of `configure': AC_CONFIG_COMMANDS_PRE( [LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` AC_SUBST(LTLIBOBJS)]) - Macro: AC_CONFIG_COMMANDS_POST (CMDS) Execute the CMDS right after creating `config.status'. Creating Configuration Links ============================ You may find it convenient to create links whose destinations depend upon results of tests. One can use `AC_CONFIG_COMMANDS' but the creation of relative symbolic links can be delicate when the package is built in another directory than its sources. - Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS]) Make `AC_OUTPUT' link each of the existing files SOURCE to the corresponding link name DEST. Makes a symbolic link if possible, otherwise a hard link. The DEST and SOURCE names should be relative to the top level source or build directory. This macro is one of the instantiating macros, see *Note Configuration Actions::. For example, this call: AC_CONFIG_LINKS(host.h:config/$machine.h object.h:config/$obj_format.h) creates in the current directory `host.h' as a link to `SRCDIR/config/$machine.h', and `object.h' as a link to `SRCDIR/config/$obj_format.h'. The tempting value `.' for DEST is invalid: it makes it impossible for `config.status' to guess the links to establish. One can then run: ./config.status host.h object.h to create the links. Configuring Other Packages in Subdirectories ============================================ In most situations, calling `AC_OUTPUT' is sufficient to produce `Makefile's in subdirectories. However, `configure' scripts that control more than one independent package can use `AC_CONFIG_SUBDIRS' to run `configure' scripts for other packages in subdirectories. - Macro: AC_CONFIG_SUBDIRS (DIR ...) Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the given whitespace-separated list. Each DIR should be a literal, i.e., please do not use: if test "$package_foo_enabled" = yes; then $my_subdirs="$my_subdirs foo" fi AC_CONFIG_SUBDIRS($my_subdirs) because this prevents `./configure --help=recursive' from displaying the options of the package `foo'. Rather, you should write: if test "$package_foo_enabled" = yes; then AC_CONFIG_SUBDIRS(foo) fi If a given DIR is not found, an error is reported: if the subdirectory is optional, write: if test -d $srcdir/foo; then AC_CONFIG_SUBDIRS(foo) fi If a given DIR contains `configure.gnu', it is run instead of `configure'. This is for packages that might use a non-autoconf script `Configure', which can't be called through a wrapper `configure' since it would be the same file on case-insensitive filesystems. Likewise, if a DIR contains `configure.ac' but no `configure', the Cygnus `configure' script found by `AC_CONFIG_AUX_DIR' is used. The subdirectory `configure' scripts are given the same command line options that were given to this `configure' script, with minor changes if needed, which include: - adjusting a relative path for the cache file; - adjusting a relative path for the source directory; - propagating the current value of `$prefix', including if it was defaulted, and if default values of the top level and of sub directory `configure' differ. This macro also sets the output variable `subdirs' to the list of directories `DIR ...'. `Makefile' rules can use this variable to determine which subdirectories to recurse into. This macro may be called multiple times. Default Prefix ============== By default, `configure' sets the prefix for files it installs to `/usr/local'. The user of `configure' can select a different prefix using the `--prefix' and `--exec-prefix' options. There are two ways to change the default: when creating `configure', and when running it. Some software packages might want to install in a directory besides `/usr/local' by default. To accomplish that, use the `AC_PREFIX_DEFAULT' macro. - Macro: AC_PREFIX_DEFAULT (PREFIX) Set the default installation prefix to PREFIX instead of `/usr/local'. It may be convenient for users to have `configure' guess the installation prefix from the location of a related program that they have already installed. If you wish to do that, you can call `AC_PREFIX_PROGRAM'. - Macro: AC_PREFIX_PROGRAM (PROGRAM) If the user did not specify an installation prefix (using the `--prefix' option), guess a value for it by looking for PROGRAM in `PATH', the way the shell does. If PROGRAM is found, set the prefix to the parent of the directory containing PROGRAM; otherwise leave the prefix specified in `Makefile.in' unchanged. For example, if PROGRAM is `gcc' and the `PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'. Existing Tests ************** These macros test for particular system features that packages might need or want to use. If you need to test for a kind of feature that none of these macros check for, you can probably do it by calling primitive test macros with appropriate arguments (*note Writing Tests::). These tests print messages telling the user which feature they're checking for, and what they find. They cache their results for future `configure' runs (*note Caching Results::). Some of these macros set output variables. *Note Makefile Substitutions::, for how to get their values. The phrase "define NAME" is used below as a shorthand to mean "define C preprocessor symbol NAME to the value 1". *Note Defining Symbols::, for how to get those symbol definitions into your program. Common Behavior =============== Much effort has been expended to make Autoconf easy to learn. The most obvious way to reach this goal is simply to enforce standard interfaces and behaviors, avoiding exceptions as much as possible. Because of history and inertia, unfortunately, there are still too many exceptions in Autoconf; nevertheless, this section describes some of the common rules. Standard Symbols ---------------- All the generic macros that `AC_DEFINE' a symbol as a result of their test transform their ARGUMENTs to a standard alphabet. First, ARGUMENT is converted to upper case and any asterisks (`*') are each converted to `P'. Any remaining characters that are not alphanumeric are converted to underscores. For instance, AC_CHECK_TYPES(struct $Expensive*) will define the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds. Default Includes ---------------- Several tests depend upon a set of header files. Since these headers are not universally available, tests actually have to provide a set of protected includes, such as: #if TIME_WITH_SYS_TIME # include # include #else # if HAVE_SYS_TIME_H # include # else # include # endif #endif Unless you know exactly what you are doing, you should avoid using unconditional includes, and check the existence of the headers you include beforehand (*note Header Files::). Most generic macros provide the following default set of includes: #include #if HAVE_SYS_TYPES_H # include #endif #if HAVE_SYS_STAT_H # include #endif #if STDC_HEADERS # include # include #else # if HAVE_STDLIB_H # include # endif #endif #if HAVE_STRING_H # if !STDC_HEADERS && HAVE_MEMORY_H # include # endif # include #endif #if HAVE_STRINGS_H # include #endif #if HAVE_INTTYPES_H # include #else # if HAVE_STDINT_H # include # endif #endif #if HAVE_UNISTD_H # include #endif If the default includes are used, then Autoconf will automatically check for the presence of these headers and their compatibility, i.e., you don't need to run `AC_HEADERS_STDC', nor check for `stdlib.h' etc. These headers are checked for in the same order as they are included. For instance, on some systems `string.h' and `strings.h' both exist, but conflict. Then `HAVE_STRING_H' will be defined, but `HAVE_STRINGS_H' won't. Alternative Programs ==================== These macros check for the presence or behavior of particular programs. They are used to choose between several alternative programs and to decide what to do once one has been chosen. If there is no macro specifically defined to check for a program you need, and you don't need to check for any special properties of it, then you can use one of the general program-check macros. Particular Program Checks ------------------------- These macros check for particular programs--whether they exist, and in some cases whether they support certain features. - Macro: AC_PROG_AWK Check for `gawk', `mawk', `nawk', and `awk', in that order, and set output variable `AWK' to the first one that is found. It tries `gawk' first because that is reported to be the best implementation. - Macro: AC_PROG_INSTALL Set output variable `INSTALL' to the path of a BSD compatible `install' program, if one is found in the current `PATH'. Otherwise, set `INSTALL' to `DIR/install-sh -c', checking the directories specified to `AC_CONFIG_AUX_DIR' (or its default directories) to determine DIR (*note Output::). Also set the variables `INSTALL_PROGRAM' and `INSTALL_SCRIPT' to `${INSTALL}' and `INSTALL_DATA' to `${INSTALL} -m 644'. This macro screens out various instances of `install' known not to work. It prefers to find a C program rather than a shell script, for speed. Instead of `install-sh', it can also use `install.sh', but that name is obsolete because some `make' programs have a rule that creates `install' from it if there is no `Makefile'. Autoconf comes with a copy of `install-sh' that you can use. If you use `AC_PROG_INSTALL', you must include either `install-sh' or `install.sh' in your distribution, or `configure' will produce an error message saying it can't find them--even if the system you're on has a good `install' program. This check is a safety measure to prevent you from accidentally leaving that file out, which would prevent your package from installing on systems that don't have a BSD-compatible `install' program. If you need to use your own installation program because it has features not found in standard `install' programs, there is no reason to use `AC_PROG_INSTALL'; just put the file name of your program into your `Makefile.in' files. - Macro: AC_PROG_LEX If `flex' is found, set output variable `LEX' to `flex' and `LEXLIB' to `-lfl', if that library is in a standard place. Otherwise set `LEX' to `lex' and `LEXLIB' to `-ll'. Define `YYTEXT_POINTER' if `yytext' is a `char *' instead of a `char []'. Also set output variable `LEX_OUTPUT_ROOT' to the base of the file name that the lexer generates; usually `lex.yy', but sometimes something else. These results vary according to whether `lex' or `flex' is being used. You are encouraged to use Flex in your sources, since it is both more pleasant to use than plain Lex and the C source it produces is portable. In order to ensure portability, however, you must either provide a function `yywrap' or, if you don't use it (e.g., your scanner has no `#include'-like feature), simply include a `%noyywrap' statement in the scanner's source. Once this done, the scanner is portable (unless _you_ felt free to use nonportable constructs) and does not depend on any library. In this case, and in this case only, it is suggested that you use this Autoconf snippet: AC_PROG_LEX if test "$LEX" != flex; then LEX="$SHELL $missing_dir/missing flex" AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) AC_SUBST(LEXLIB, '') fi The shell script `missing' can be found in the Automake distribution. To ensure backward compatibility, Automake's `AM_PROG_LEX' invokes (indirectly) this macro twice, which will cause an annoying but benign "`AC_PROG_LEX' invoked multiple times" warning. Future versions of Automake will fix this issue, meanwhile, just ignore this message. - Macro: AC_PROG_LN_S If `ln -s' works on the current file system (the operating system and file system support symbolic links), set the output variable `LN_S' to `ln -s'; otherwise, if `ln' works, set `LN_S' to `ln' and otherwise set it to `cp -p'. If you make a link a directory other than the current directory, its meaning depends on whether `ln' or `ln -s' is used. To safely create links using `$(LN_S)', either find out which form is used and adjust the arguments, or always invoke `ln' in the directory where the link is to be created. In other words, it does not work to do: $(LN_S) foo /x/bar Instead, do: (cd /x && $(LN_S) foo bar) - Macro: AC_PROG_RANLIB Set output variable `RANLIB' to `ranlib' if `ranlib' is found, and otherwise to `:' (do nothing). - Macro: AC_PROG_YACC If `bison' is found, set output variable `YACC' to `bison -y'. Otherwise, if `byacc' is found, set `YACC' to `byacc'. Otherwise set `YACC' to `yacc'. Generic Program and File Checks ------------------------------- These macros are used to find programs not covered by the "particular" test macros. If you need to check the behavior of a program as well as find out whether it is present, you have to write your own test for it (*note Writing Tests::). By default, these macros use the environment variable `PATH'. If you need to check for a program that might not be in the user's `PATH', you can pass a modified path to use instead, like this: AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], [$PATH:/usr/libexec:/usr/sbin:/usr/etc:etc]) You are strongly encouraged to declare the VARIABLE passed to `AC_CHECK_PROG' etc. as precious, *Note Setting Output Variables::, `AC_ARG_VAR', for more details. - Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND, [VALUE-IF-NOT-FOUND], [PATH], [REJECT]) Check whether program PROG-TO-CHECK-FOR exists in `PATH'. If it is found, set VARIABLE to VALUE-IF-FOUND, otherwise to VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an absolute file name) even if it is the first found in the search path; in that case, set VARIABLE using the absolute file name of the PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was already set, do nothing. Calls `AC_SUBST' for VARIABLE. - Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Check for each program in the whitespace-separated list PROGS-TO-CHECK-FOR exists on the `PATH'. If it is found, set VARIABLE to the name of that program. Otherwise, continue checking the next program in the list. If none of the programs in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not changed. Calls `AC_SUBST' for VARIABLE. - Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a prefix of the host type as determined by `AC_CANONICAL_HOST', followed by a dash (*note Canonicalizing::). For example, if the user runs `configure --host=i386-gnu', then this call: AC_CHECK_TOOL(RANLIB, ranlib, :) sets `RANLIB' to `i386-gnu-ranlib' if that program exists in `PATH', or otherwise to `ranlib' if that program exists in `PATH', or to `:' if neither program exists. - Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Like `AC_CHECK_TOOL', each of the tools in the list PROGS-TO-CHECK-FOR are checked with a prefix of the host type as determined by `AC_CANONICAL_HOST', followed by a dash (*note Canonicalizing::). If none of the tools can be found with a prefix, then the first one without a prefix is used. If a tool is found, set VARIABLE to the name of that program. If none of the tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not changed. Calls `AC_SUBST' for VARIABLE. - Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Like `AC_CHECK_PROG', but set VARIABLE to the entire path of PROG-TO-CHECK-FOR if found. - Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, set VARIABLE to the entire path of the program found. - Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH]) Like `AC_CHECK_TOOL', but set VARIABLE to the entire path of the program if it is found. Files ===== You might also need to check for the existence of files. Before using these macros, ask yourself whether a run time test might not be a better solution. Be aware that, like most Autoconf macros, they test a feature of the host machine, and therefore, they die when cross-compiling. - Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) Check whether file FILE exists on the native system. If it is found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given. - Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) Executes `AC_CHECK_FILE' once for each file listed in FILES. Additionally, defines `HAVE_FILE' (*note Standard Symbols::) for each file found. Library Files ============= The following macros check for the presence of certain C, C++ or Fortran 77 library archive files. - Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) Depending on the current language(*note Language Choice::), try to ensure that the C, C++, or Fortran 77 function FUNCTION is available by checking whether a test program can be linked with the library LIBRARY to get the function. LIBRARY is the base name of the library; e.g., to check for `-lmp', use `mp' as the LIBRARY argument. ACTION-IF-FOUND is a list of shell commands to run if the link with the library succeeds; ACTION-IF-NOT-FOUND is a list of shell commands to run if the link fails. If ACTION-IF-FOUND is not specified, the default action will prepend `-lLIBRARY' to `LIBS' and define `HAVE_LIBLIBRARY' (in all capitals). This macro is intended to support building of `LIBS' in a right-to-left (least-dependent to most-dependent) fashion such that library dependencies are satisfied as a natural side-effect of consecutive tests. Some linkers are very sensitive to library ordering so the order in which `LIBS' is generated is important to reliable detection of libraries. If linking with LIBRARY results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the OTHER-LIBRARIES argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that LIBRARY is present, because linking the test program will always fail with unresolved symbols. The OTHER-LIBRARIES argument should be limited to cases where it is desirable to test for one library in the presence of another that is not already in `LIBS'. - Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) Search for a library defining FUNCTION if it's not already available. This equates to calling `AC_TRY_LINK_FUNC' first with no libraries, then for each library listed in SEARCH-LIBS. Add `-lLIBRARY' to `LIBS' for the first library found to contain FUNCTION, and run ACTION-IF-FOUND. If the function is not found, run ACTION-IF-NOT-FOUND. If linking with LIBRARY results in unresolved symbols that would be resolved by linking with additional libraries, give those libraries as the OTHER-LIBRARIES argument, separated by spaces: e.g. `-lXt -lX11'. Otherwise, this macro will fail to detect that FUNCTION is present, because linking the test program will always fail with unresolved symbols. Library Functions ================= The following macros check for particular C library functions. If there is no macro specifically defined to check for a function you need, and you don't need to check for any special properties of it, then you can use one of the general function-check macros. Portability of C Functions -------------------------- Most usual functions can either be missing, or be buggy, or be limited on some architectures. This section tries to make an inventory of these portability issues. By definition, this list will always require additions. Please help us keeping it as complete as possible. `snprintf' The ISO C99 standard says that if the output array isn't big enough and if no other errors occur, `snprintf' and `vsnprintf' truncate the output and return the number of bytes that ought to have been produced. Some older systems return the truncated length (e.g., GNU C Library 2.0.x or IRIX 6.5), some a negative value (e.g., earlier GNU C Library versions), and some the buffer length without truncation (e.g., 32-bit Solaris 7). Also, some buggy older systems ignore the length and overrun the buffer (e.g., 64-bit Solaris 7). `sprintf' The ISO C standard says `sprintf' and `vsprintf' return the number of bytes written, but on some old systems (SunOS 4 for instance) they return the buffer pointer instead. `sscanf' On various old systems, e.g. HP-UX 9, `sscanf' requires that its input string is writable (though it doesn't actually change it). This can be a problem when using `gcc' since it normally puts constant strings in read-only memory (*note Incompatibilities of GCC: (gcc)Incompatibilities.). Apparently in some cases even having format strings read-only can be a problem. `strnlen' AIX 4.3 provides a broken version which produces funny results: strnlen ("foobar", 0) = 0 strnlen ("foobar", 1) = 3 strnlen ("foobar", 2) = 2 strnlen ("foobar", 3) = 1 strnlen ("foobar", 4) = 0 strnlen ("foobar", 5) = 6 strnlen ("foobar", 6) = 6 strnlen ("foobar", 7) = 6 strnlen ("foobar", 8) = 6 strnlen ("foobar", 9) = 6 `unlink' The POSIX spec says that `unlink' causes the given files to be removed only after there are no more open file handles for it. Not all OS's support this behaviour though. So even on systems that provide `unlink', you cannot portably assume it is OK to call it on files that are open. For example, on Windows 9x and ME, such a call would fail; on DOS it could even lead to file system corruption, as the file might end up being written to after the OS has removed it. `va_copy' The ISO C99 standard provides `va_copy' for copying `va_list' variables. It may be available in older environments too, though possibly as `__va_copy' (eg. `gcc' in strict C89 mode). These can be tested with `#ifdef'. A fallback to `memcpy (&dst, &src, sizeof(va_list))' will give maximum portability. `va_list' `va_list' is not necessarily just a pointer. It can be a `struct' (eg. `gcc' on Alpha), which means `NULL' is not portable. Or it can be an array (eg. `gcc' in some PowerPC configurations), which means as a function parameter it can be effectively call-by-reference and library routines might modify the value back in the caller (eg. `vsnprintf' in the GNU C Library 2.1). Signed `>>' Normally the C `>>' right shift of a signed type replicates the high bit, giving a so-called "arithmetic" shift. But care should be taken since the ISO C standard doesn't require that behaviour. On those few processors without a native arithmetic shift (for instance Cray vector systems) zero bits may be shifted in, the same as a shift of an unsigned type. Particular Function Checks -------------------------- These macros check for particular C functions--whether they exist, and in some cases how they respond when given certain arguments. - Macro: AC_FUNC_ALLOCA Check how to get `alloca'. Tries to get a builtin version by checking for `alloca.h' or the predefined C preprocessor macros `__GNUC__' and `_AIX'. If this macro finds `alloca.h', it defines `HAVE_ALLOCA_H'. If those attempts fail, it looks for the function in the standard C library. If any of those methods succeed, it defines `HAVE_ALLOCA'. Otherwise, it sets the output variable `ALLOCA' to `alloca.o' and defines `C_ALLOCA' (so programs can periodically call `alloca(0)' to garbage collect). This variable is separate from `LIBOBJS' so multiple programs can share the value of `ALLOCA' without needing to create an actual library, in case only some of them use the code in `LIBOBJS'. This macro does not try to get `alloca' from the System V R3 `libPW' or the System V R4 `libucb' because those libraries contain some incompatible functions that cause trouble. Some versions do not even contain `alloca' or contain a buggy version. If you still want to use their `alloca', use `ar' to extract `alloca.o' from them instead of compiling `alloca.c'. Source files that use `alloca' should start with a piece of code like the following, to declare it properly. In some versions of AIX, the declaration of `alloca' must precede everything else except for comments and preprocessor directives. The `#pragma' directive is indented so that pre-ANSI C compilers will ignore it, rather than choke on it. /* AIX requires this to be the first thing in the file. */ #ifndef __GNUC__ # if HAVE_ALLOCA_H # include # else # ifdef _AIX #pragma alloca # else # ifndef alloca /* predefined by HP cc +Olibcalls */ char *alloca (); # endif # endif # endif #endif - Macro: AC_FUNC_CHOWN If the `chown' function is available and works (in particular, it should accept `-1' for `uid' and `gid'), define `HAVE_CHOWN'. - Macro: AC_FUNC_CLOSEDIR_VOID If the `closedir' function does not return a meaningful value, define `CLOSEDIR_VOID'. Otherwise, callers ought to check its return value for an error indicator. - Macro: AC_FUNC_ERROR_AT_LINE If the `error_at_line' function is not found, require an `AC_LIBOBJ' replacement of `error'. - Macro: AC_FUNC_FNMATCH If the `fnmatch' function is available and works (unlike the one on Solaris 2.4), define `HAVE_FNMATCH'. - Macro: AC_FUNC_FORK This macro checks for the `fork' and `vfork' functions. If a working `fork' is found, define `HAVE_WORKING_FORK'. This macro checks whether `fork' is just a stub by trying to run it. If `vfork.h' is found, define `HAVE_VFORK_H'. If a working `vfork' is found, define `HAVE_WORKING_VFORK'. Otherwise, define `vfork' to be `fork' for backward compatibility with previous versions of `autoconf'. This macro checks for several known errors in implementations of `vfork' and considers the system to not have a working `vfork' if it detects any of them. It is not considered to be an implementation error if a child's invocation of `signal' modifies the parent's signal handler, since child processes rarely change their signal handlers. Since this macro defines `vfork' only for backward compatibility with previous versions of `autoconf' you're encouraged to define it yourself in new code: #if !HAVE_WORKING_VFORK # define vfork fork #endif - Macro: AC_FUNC_FSEEKO If the `fseeko' function is available, define `HAVE_FSEEKO'. Define `_LARGEFILE_SOURCE' if necessary. - Macro: AC_FUNC_GETGROUPS If the `getgroups' function is available and works (unlike on Ultrix 4.3, where `getgroups (0, 0)' always fails), define `HAVE_GETGROUPS'. Set `GETGROUPS_LIBS' to any libraries needed to get that function. This macro runs `AC_TYPE_GETGROUPS'. - Macro: AC_FUNC_GETLOADAVG Check how to get the system load averages. If the system has the `getloadavg' function, define `HAVE_GETLOADAVG', and set `GETLOADAVG_LIBS' to any libraries needed to get that function. Also add `GETLOADAVG_LIBS' to `LIBS'. Otherwise, require an `AC_LIBOBJ' replacement (`getloadavg.c') of `getloadavg', and possibly define several other C preprocessor macros and output variables: 1. Define `C_GETLOADAVG'. 2. Define `SVR4', `DGUX', `UMAX', or `UMAX4_3' if on those systems. 3. If `nlist.h' is found, define `NLIST_STRUCT'. 4. If `struct nlist' has an `n_un.n_name' member, define `HAVE_STRUCT_NLIST_N_UN_N_NAME'. The obsolete symbol `NLIST_NAME_UNION' is still defined, but do not depend upon it. 5. Programs may need to be installed setgid (or setuid) for `getloadavg' to work. In this case, define `GETLOADAVG_PRIVILEGED', set the output variable `NEED_SETGID' to `true' (and otherwise to `false'), and set `KMEM_GROUP' to the name of the group that should own the installed program. - Macro: AC_FUNC_GETMNTENT Check for `getmntent' in the `sun', `seq', and `gen' libraries, for Irix 4, PTX, and Unixware, respectively. Then, if `getmntent' is available, define `HAVE_GETMNTENT'. - Macro: AC_FUNC_GETPGRP Define `GETPGRP_VOID' if it is an error to pass 0 to `getpgrp'; this is the POSIX.1 behavior. On older BSD systems, you must pass 0 to `getpgrp', as it takes an argument and behaves like POSIX.1's `getpgid'. #if GETPGRP_VOID pid = getpgrp (); #else pid = getpgrp (0); #endif This macro does not check whether `getpgrp' exists at all; if you need to work in that situation, first call `AC_CHECK_FUNC' for `getpgrp'. - Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK If `link' is a symbolic link, then `lstat' should treat `link/' the same as `link/.'. However, many older `lstat' implementations incorrectly ignore trailing slashes. It is safe to assume that if `lstat' incorrectly ignores trailing slashes, then other symbolic-link-aware functions like `unlink' and `unlink' also incorrectly ignore trailing slashes. If `lstat' behaves properly, define `LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an `AC_LIBOBJ' replacement of `lstat'. - Macro: AC_FUNC_MALLOC If the `malloc' works correctly (`malloc (0)' returns a valid pointer), define `HAVE_MALLOC'. - Macro: AC_FUNC_MEMCMP If the `memcmp' function is not available, or does not work on 8-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 bytes or more and with at least one buffer not starting on a 4-byte boundary (such as the one on NeXT x86 OpenStep), require an `AC_LIBOBJ' replacement for `memcmp'. - Macro: AC_FUNC_MKTIME If the `mktime' function is not available, or does not work correctly, require an `AC_LIBOBJ' replacement for `mktime'. - Macro: AC_FUNC_MMAP If the `mmap' function exists and works correctly, define `HAVE_MMAP'. Only checks private fixed mapping of already-mapped memory. - Macro: AC_FUNC_OBSTACK If the obstacks are found, define `HAVE_OBSTACK', else require an `AC_LIBOBJ' replacement for `obstack'. - Macro: AC_FUNC_SELECT_ARGTYPES Determines the correct type to be passed for each of the `select' function's arguments, and defines those types in `SELECT_TYPE_ARG1', `SELECT_TYPE_ARG234', and `SELECT_TYPE_ARG5' respectively. `SELECT_TYPE_ARG1' defaults to `int', `SELECT_TYPE_ARG234' defaults to `int *', and `SELECT_TYPE_ARG5' defaults to `struct timeval *'. - Macro: AC_FUNC_SETPGRP If `setpgrp' takes no argument (the POSIX.1 version), define `SETPGRP_VOID'. Otherwise, it is the BSD version, which takes two process IDs as arguments. This macro does not check whether `setpgrp' exists at all; if you need to work in that situation, first call `AC_CHECK_FUNC' for `setpgrp'. - Macro: AC_FUNC_STAT - Macro: AC_FUNC_LSTAT Determine whether `stat' or `lstat' have the bug that it succeeds when given the zero-length file name argument. The `stat' and `lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this. If it does, then define `HAVE_STAT_EMPTY_STRING_BUG' (or `HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an `AC_LIBOBJ' replacement of it. - Macro: AC_FUNC_SETVBUF_REVERSED If `setvbuf' takes the buffering type as its second argument and the buffer pointer as the third, instead of the other way around, define `SETVBUF_REVERSED'. - Macro: AC_FUNC_STRCOLL If the `strcoll' function exists and works correctly, define `HAVE_STRCOLL'. This does a bit more than `AC_CHECK_FUNCS(strcoll)', because some systems have incorrect definitions of `strcoll' that should not be used. - Macro: AC_FUNC_STRTOD If the `strtod' function does not exist or doesn't work correctly, ask for an `AC_LIBOBJ' replacement of `strtod'. In this case, because `strtod.c' is likely to need `pow', set the output variable `POW_LIB' to the extra library needed. - Macro: AC_FUNC_STRERROR_R If `strerror_r' is available, define `HAVE_STRERROR_R', and if it is declared, define `HAVE_DECL_STRERROR_R'. If it returns a `char *' message, define `STRERROR_R_CHAR_P'; otherwise it returns an `int' error number. The Thread-Safe Functions option of POSIX-200X requires `strerror_r' to return `int', but many systems (including, for example, version 2.2.4 of the GNU C Library) return a `char *' value that is not necessarily equal to the buffer argument. - Macro: AC_FUNC_STRFTIME Check for `strftime' in the `intl' library, for SCO UNIX. Then, if `strftime' is available, define `HAVE_STRFTIME'. - Macro: AC_FUNC_STRNLEN Check for a working `strnlen', and ask for its replacement. Some architectures are know to provide broken versions of `strnlen', such as AIX 4.3. - Macro: AC_FUNC_UTIME_NULL If `utime(FILE, NULL)' sets FILE's timestamp to the present, define `HAVE_UTIME_NULL'. - Macro: AC_FUNC_VPRINTF If `vprintf' is found, define `HAVE_VPRINTF'. Otherwise, if `_doprnt' is found, define `HAVE_DOPRNT'. (If `vprintf' is available, you may assume that `vfprintf' and `vsprintf' are also available.) Generic Function Checks ----------------------- These macros are used to find functions not covered by the "particular" test macros. If the functions might be in libraries other than the default C library, first call `AC_CHECK_LIB' for those libraries. If you need to check the behavior of a function as well as find out whether it is present, you have to write your own test for it (*note Writing Tests::). - Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) If C function FUNCTION is available, run shell commands ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want to define a symbol if the function is available, consider using `AC_CHECK_FUNCS' instead. This macro checks for functions with C linkage even when `AC_LANG(C++)' has been called, since C is more standardized than C++. (*note Language Choice::, for more information about selecting the language for checks.) - Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) For each FUNCTION in the whitespace-separated argument list, define `HAVE_FUNCTION' (in all capitals) if it is available. If ACTION-IF-FOUND is given, it is additional shell code to execute when one of the functions is found. You can give it a value of `break' to break out of the loop on the first match. If ACTION-IF-NOT-FOUND is given, it is executed when one of the functions is not found. Autoconf follows a philosophy that was formed over the years by those who have struggled for portability: isolate the portability issues in specific files, and then program as if you were in a POSIX environment. Some functions may be missing or unfixable, and your package must be ready to replace them. Use the first three of the following macros to specify a function to be replaced, and the last one (`AC_REPLACE_FUNCS') to check for and replace the function if needed. - Macro: AC_LIBOBJ (FUNCTION) Specify that `FUNCTION.c' must be included in the executables to replace a missing or broken implementation of FUNCTION. Technically, it adds `FUNCTION.$ac_objext' to the output variable `LIBOBJS' and calls `AC_LIBSOURCE' for `FUNCTION.c'. You should not directly change `LIBOBJS', since this is not traceable. - Macro: AC_LIBSOURCE (FILE) Specify that FILE might be needed to compile the project. If you need to know what files might be needed by a `configure.ac', you should trace `AC_LIBSOURCE'. FILE must be a literal. This macro is called automatically from `AC_LIBOBJ', but you must call it explicitly if you pass a shell variable to `AC_LIBOBJ'. In that case, since shell variables cannot be traced statically, you must pass to `AC_LIBSOURCE' any possible files that the shell variable might cause `AC_LIBOBJ' to need. For example, if you want to pass a variable `$foo_or_bar' to `AC_LIBOBJ' that holds either `"foo"' or `"bar"', you should do: AC_LIBSOURCE(foo.c) AC_LIBSOURCE(bar.c) AC_LIBOBJ($foo_or_bar) There is usually a way to avoid this, however, and you are encouraged to simply call `AC_LIBOBJ' with literal arguments. Note that this macro replaces the obsolete `AC_LIBOBJ_DECL', with slightly different semantics: the old macro took the function name, e.g. `foo', as its argument rather than the file name. - Macro: AC_LIBSOURCES (FILES) Like `AC_LIBSOURCE', but accepts one or more FILES in a comma-separated M4 list. Thus, the above example might be rewritten: AC_LIBSOURCES([foo.c, bar.c]) AC_LIBOBJ($foo_or_bar) - Macro: AC_REPLACE_FUNCS (FUNCTION...) Like `AC_CHECK_FUNCS', but uses `AC_LIBOBJ(FUNCTION)' as ACTION-IF-NOT-FOUND. You can declare your replacement function by enclosing the prototype in `#if !HAVE_FUNCTION'. If the system has the function, it probably declares it in a header file you should be including, so you shouldn't redeclare it lest your declaration conflict. Header Files ============ The following macros check for the presence of certain C header files. If there is no macro specifically defined to check for a header file you need, and you don't need to check for any special properties of it, then you can use one of the general header-file check macros. Particular Header Checks ------------------------ These macros check for particular system header files--whether they exist, and in some cases whether they declare certain symbols. - Macro: AC_HEADER_DIRENT Check for the following header files. For the first one that is found and defines `DIR', define the listed C preprocessor macro: `dirent.h' `HAVE_DIRENT_H' `sys/ndir.h' `HAVE_SYS_NDIR_H' `sys/dir.h' `HAVE_SYS_DIR_H' `ndir.h' `HAVE_NDIR_H' The directory-library declarations in your source code should look something like the following: #if HAVE_DIRENT_H # include # define NAMLEN(dirent) strlen((dirent)->d_name) #else # define dirent direct # define NAMLEN(dirent) (dirent)->d_namlen # if HAVE_SYS_NDIR_H # include # endif # if HAVE_SYS_DIR_H # include # endif # if HAVE_NDIR_H # include # endif #endif Using the above declarations, the program would declare variables to be of type `struct dirent', not `struct direct', and would access the length of a directory entry name by passing a pointer to a `struct dirent' to the `NAMLEN' macro. This macro also checks for the SCO Xenix `dir' and `x' libraries. - Macro: AC_HEADER_MAJOR If `sys/types.h' does not define `major', `minor', and `makedev', but `sys/mkdev.h' does, define `MAJOR_IN_MKDEV'; otherwise, if `sys/sysmacros.h' does, define `MAJOR_IN_SYSMACROS'. - Macro: AC_HEADER_STAT If the macros `S_ISDIR', `S_ISREG' et al. defined in `sys/stat.h' do not work properly (returning false positives), define `STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl UTS and Motorola System V/88. - Macro: AC_HEADER_STDC Define `STDC_HEADERS' if the system has ANSI C header files. Specifically, this macro checks for `stdlib.h', `stdarg.h', `string.h', and `float.h'; if the system has those, it probably has the rest of the ANSI C header files. This macro also checks whether `string.h' declares `memchr' (and thus presumably the other `mem' functions), whether `stdlib.h' declare `free' (and thus presumably `malloc' and other related functions), and whether the `ctype.h' macros work on characters with the high bit set, as ANSI C requires. Use `STDC_HEADERS' instead of `__STDC__' to determine whether the system has ANSI-compliant header files (and probably C library functions) because many systems that have GCC do not have ANSI C header files. On systems without ANSI C headers, there is so much variation that it is probably easier to declare the functions you use than to figure out exactly what the system header files declare. Some systems contain a mix of functions ANSI and BSD; some are mostly ANSI but lack `memmove'; some define the BSD functions as macros in `string.h' or `strings.h'; some have only the BSD functions but `string.h'; some declare the memory functions in `memory.h', some in `string.h'; etc. It is probably sufficient to check for one string function and one memory function; if the library has the ANSI versions of those then it probably has most of the others. If you put the following in `configure.ac': AC_HEADER_STDC AC_CHECK_FUNCS(strchr memcpy) then, in your code, you can put declarations like this: #if STDC_HEADERS # include #else # if !HAVE_STRCHR # define strchr index # define strrchr rindex # endif char *strchr (), *strrchr (); # if !HAVE_MEMCPY # define memcpy(d, s, n) bcopy ((s), (d), (n)) # define memmove(d, s, n) bcopy ((s), (d), (n)) # endif #endif If you use a function like `memchr', `memset', `strtok', or `strspn', which have no BSD equivalent, then macros won't suffice; you must provide an implementation of each function. An easy way to incorporate your implementations only when needed (since the ones in system C libraries may be hand optimized) is to, taking `memchr' for example, put it in `memchr.c' and use `AC_REPLACE_FUNCS(memchr)'. - Macro: AC_HEADER_SYS_WAIT If `sys/wait.h' exists and is compatible with POSIX.1, define `HAVE_SYS_WAIT_H'. Incompatibility can occur if `sys/wait.h' does not exist, or if it uses the old BSD `union wait' instead of `int' to store a status value. If `sys/wait.h' is not POSIX.1 compatible, then instead of including it, define the POSIX.1 macros with their usual interpretations. Here is an example: #include #if HAVE_SYS_WAIT_H # include #endif #ifndef WEXITSTATUS # define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) #endif #ifndef WIFEXITED # define WIFEXITED(stat_val) (((stat_val) & 255) == 0) #endif `_POSIX_VERSION' is defined when `unistd.h' is included on POSIX.1 systems. If there is no `unistd.h', it is definitely not a POSIX.1 system. However, some non-POSIX.1 systems do have `unistd.h'. The way to check if the system supports POSIX.1 is: #if HAVE_UNISTD_H # include # include #endif #ifdef _POSIX_VERSION /* Code for POSIX.1 systems. */ #endif - Macro: AC_HEADER_TIME If a program may include both `time.h' and `sys/time.h', define `TIME_WITH_SYS_TIME'. On some older systems, `sys/time.h' includes `time.h', but `time.h' is not protected against multiple inclusion, so programs should not explicitly include both files. This macro is useful in programs that use, for example, `struct timeval' or `struct timezone' as well as `struct tm'. It is best used in conjunction with `HAVE_SYS_TIME_H', which can be checked for using `AC_CHECK_HEADERS(sys/time.h)'. #if TIME_WITH_SYS_TIME # include # include #else # if HAVE_SYS_TIME_H # include # else # include # endif #endif - Macro: AC_HEADER_TIOCGWINSZ If the use of `TIOCGWINSZ' requires `', then define `GWINSZ_IN_SYS_IOCTL'. Otherwise `TIOCGWINSZ' can be found in `'. Use: #if HAVE_TERMIOS_H # include #endif #if GWINSZ_IN_SYS_IOCTL # include #endif Generic Header Checks --------------------- These macros are used to find system header files not covered by the "particular" test macros. If you need to check the contents of a header as well as find out whether it is present, you have to write your own test for it (*note Writing Tests::). - Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) If the system header file HEADER-FILE is usable, execute shell commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. If you just want to define a symbol if the header file is available, consider using `AC_CHECK_HEADERS' instead. The meaning of "usable" depends upon the content of INCLUDES: if INCLUDES is empty check whether HEADER-FILE can be _preprocessed_ without error. if INCLUDE is set Check whether INCLUDES #include can be _compiled_ without error. You may use `AC_CHECK_HEADER' (and `AC_CHECK_HEADERS') to check whether two headers are compatible. You may pass any kind of dummy content for INCLUDES, such as a single space, a comment, to check whether HEADER-FILE compiles with success. - Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) For each given system header file HEADER-FILE in the whitespace-separated argument list that exists, define `HAVE_HEADER-FILE' (in all capitals). If ACTION-IF-FOUND is given, it is additional shell code to execute when one of the header files is found. You can give it a value of `break' to break out of the loop on the first match. If ACTION-IF-NOT-FOUND is given, it is executed when one of the header files is not found. Be sure to read the documentation of `AC_CHECK_HEADER' to understand the influence of INCLUDES. Declarations ============ The following macros check for the declaration of variables and functions. If there is no macro specifically defined to check for a symbol you need, then you can use the general macros (*note Generic Declarations::) or, for more complex tests, you may use `AC_TRY_COMPILE' (*note Examining Syntax::). Particular Declaration Checks ----------------------------- The following macros check for certain declarations. - Macro: AC_DECL_SYS_SIGLIST Define `SYS_SIGLIST_DECLARED' if the variable `sys_siglist' is declared in a system header file, either `signal.h' or `unistd.h'. Generic Declaration Checks -------------------------- These macros are used to find declarations not covered by the "particular" test macros. - Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) If SYMBOL (a function or a variable) is not declared in INCLUDES and a declaration is needed, run the shell commands ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND. If no INCLUDES are specified, the default includes are used (*note Default Includes::). This macro actually tests whether it is valid to use SYMBOL as an r-value, not if it is really declared, because it is much safer to avoid introducing extra declarations when they are not needed. - Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) For each of the SYMBOLS (_comma_-separated list), define `HAVE_DECL_SYMBOL' (in all capitals) to `1' if SYMBOL is declared, otherwise to `0'. If ACTION-IF-NOT-FOUND is given, it is additional shell code to execute when one of the function declarations is needed, otherwise ACTION-IF-FOUND is executed. This macro uses an m4 list as first argument: AC_CHECK_DECLS(strdup) AC_CHECK_DECLS([strlen]) AC_CHECK_DECLS([malloc, realloc, calloc, free]) Unlike the other `AC_CHECK_*S' macros, when a SYMBOL is not declared, `HAVE_DECL_SYMBOL' is defined to `0' instead of leaving `HAVE_DECL_SYMBOL' undeclared. When you are _sure_ that the check was performed, use `HAVE_DECL_SYMBOL' just like any other result of Autoconf: #if !HAVE_DECL_SYMBOL extern char *symbol; #endif If the test may have not been performed, however, because it is safer _not_ to declare a symbol than to use a declaration that conflicts with the system's one, you should use: #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC char *malloc (size_t *s); #endif You fall into the second category only in extreme situations: either your files may be used without being configured, or they are used during the configuration. In most cases the traditional approach is enough. Structures ========== The following macros check for the presence of certain members in C structures. If there is no macro specifically defined to check for a member you need, then you can use the general structure-member macro (*note Generic Structures::) or, for more complex tests, you may use `AC_TRY_COMPILE' (*note Examining Syntax::). Particular Structure Checks --------------------------- The following macros check for certain structures or structure members. - Macro: AC_STRUCT_ST_BLKSIZE If `struct stat' contains an `st_blksize' member, define `HAVE_STRUCT_STAT_ST_BLKSIZE'. The former name, `HAVE_ST_BLKSIZE' is to be avoided, as its support will cease in the future. This macro is obsoleted, and should be replaced by AC_CHECK_MEMBERS([struct stat.st_blksize]) - Macro: AC_STRUCT_ST_BLOCKS If `struct stat' contains an `st_blocks' member, define `HAVE_STRUCT STAT_ST_BLOCKS'. Otherwise, require an `AC_LIBOBJ' replacement of `fileblocks'. The former name, `HAVE_ST_BLOCKS' is to be avoided, as its support will cease in the future. - Macro: AC_STRUCT_ST_RDEV If `struct stat' contains an `st_rdev' member, define `HAVE_STRUCT_STAT_ST_RDEV'. The former name for this macro, `HAVE_ST_RDEV', is to be avoided as it will cease to be supported in the future. Actually, even the new macro is obsolete, and should be replaced by: AC_CHECK_MEMBERS([struct stat.st_rdev]) - Macro: AC_STRUCT_TM If `time.h' does not define `struct tm', define `TM_IN_SYS_TIME', which means that including `sys/time.h' had better define `struct tm'. - Macro: AC_STRUCT_TIMEZONE Figure out how to get the current timezone. If `struct tm' has a `tm_zone' member, define `HAVE_STRUCT_TM_TM_ZONE' (and the obsoleted `HAVE_TM_ZONE'). Otherwise, if the external array `tzname' is found, define `HAVE_TZNAME'. Generic Structure Checks ------------------------ These macros are used to find structure members not covered by the "particular" test macros. - Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) Check whether MEMBER is a member of the aggregate AGGREGATE. If no INCLUDES are specified, the default includes are used (*note Default Includes::). AC_CHECK_MEMBER(struct passwd.pw_gecos,, [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], [#include ]) You can use this macro for sub-members: AC_CHECK_MEMBER(struct top.middle.bot) - Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) Check for the existence of each `AGGREGATE.MEMBER' of MEMBERS using the previous macro. When MEMBER belongs to AGGREGATE, define `HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and dots replaced by underscores). This macro uses m4 lists: AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) Types ===== The following macros check for C types, either builtin or typedefs. If there is no macro specifically defined to check for a type you need, and you don't need to check for any special properties of it, then you can use a general type-check macro. Particular Type Checks ---------------------- These macros check for particular C types in `sys/types.h', `stdlib.h' and others, if they exist. - Macro: AC_TYPE_GETGROUPS Define `GETGROUPS_T' to be whichever of `gid_t' or `int' is the base type of the array argument to `getgroups'. - Macro: AC_TYPE_MODE_T Equivalent to `AC_CHECK_TYPE(mode_t, int)'. - Macro: AC_TYPE_OFF_T Equivalent to `AC_CHECK_TYPE(off_t, long)'. - Macro: AC_TYPE_PID_T Equivalent to `AC_CHECK_TYPE(pid_t, int)'. - Macro: AC_TYPE_SIGNAL If `signal.h' declares `signal' as returning a pointer to a function returning `void', define `RETSIGTYPE' to be `void'; otherwise, define it to be `int'. Define signal handlers as returning type `RETSIGTYPE': RETSIGTYPE hup_handler () { ... } - Macro: AC_TYPE_SIZE_T Equivalent to `AC_CHECK_TYPE(size_t, unsigned)'. - Macro: AC_TYPE_UID_T If `uid_t' is not defined, define `uid_t' to be `int' and `gid_t' to be `int'. Generic Type Checks ------------------- These macros are used to check for types not covered by the "particular" test macros. - Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) Check whether TYPE is defined. It may be a compiler builtin type or defined by the INCLUDES (*note Default Includes::). - Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes']) For each TYPE of the TYPES that is defined, define `HAVE_TYPE' (in all capitals). If no INCLUDES are specified, the default includes are used (*note Default Includes::). If ACTION-IF-FOUND is given, it is additional shell code to execute w