Table of Contents ***************** Autoconf 1 Introduction 2 The GNU Build System 2.1 Automake 2.2 Gnulib 2.3 Libtool 2.4 Pointers 3 Making `configure' Scripts 3.1 Writing `configure.ac' 3.1.1 A Shell Script Compiler 3.1.2 The Autoconf Language 3.1.3 Standard `configure.ac' Layout 3.2 Using `autoscan' to Create `configure.ac' 3.3 Using `ifnames' to List Conditionals 3.4 Using `autoconf' to Create `configure' 3.5 Using `autoreconf' to Update `configure' Scripts 4 Initialization and Output Files 4.1 Initializing `configure' 4.2 Dealing with Autoconf versions 4.3 Notices in `configure' 4.4 Finding `configure' Input 4.5 Outputting Files 4.6 Performing Configuration Actions 4.7 Creating Configuration Files 4.8 Substitutions in Makefiles 4.8.1 Preset Output Variables 4.8.2 Installation Directory Variables 4.8.3 Changed Directory Variables 4.8.4 Build Directories 4.8.5 Automatic Remaking 4.9 Configuration Header Files 4.9.1 Configuration Header Templates 4.9.2 Using `autoheader' to Create `config.h.in' 4.9.3 Autoheader Macros 4.10 Running Arbitrary Configuration Commands 4.11 Creating Configuration Links 4.12 Configuring Other Packages in Subdirectories 4.13 Default Prefix 5 Existing Tests 5.1 Common Behavior 5.1.1 Standard Symbols 5.1.2 Default Includes 5.2 Alternative Programs 5.2.1 Particular Program Checks 5.2.2 Generic Program and File Checks 5.3 Files 5.4 Library Files 5.5 Library Functions 5.5.1 Portability of C Functions 5.5.2 Particular Function Checks 5.5.3 Generic Function Checks 5.6 Header Files 5.6.1 Portability of Headers 5.6.2 Particular Header Checks 5.6.3 Generic Header Checks 5.7 Declarations 5.7.1 Particular Declaration Checks 5.7.2 Generic Declaration Checks 5.8 Structures 5.8.1 Particular Structure Checks 5.8.2 Generic Structure Checks 5.9 Types 5.9.1 Particular Type Checks 5.9.2 Generic Type Checks 5.10 Compilers and Preprocessors 5.10.1 Specific Compiler Characteristics 5.10.2 Generic Compiler Characteristics 5.10.3 C Compiler Characteristics 5.10.4 C++ Compiler Characteristics 5.10.5 Objective C Compiler Characteristics 5.10.6 Erlang Compiler and Interpreter Characteristics 5.10.7 Fortran Compiler Characteristics 5.11 System Services 5.12 Posix Variants 5.13 Erlang Libraries 6 Writing Tests 6.1 Language Choice 6.2 Writing Test Programs 6.2.1 Guidelines for Test Programs 6.2.2 Test Functions 6.2.3 Generating Sources 6.3 Running the Preprocessor 6.4 Running the Compiler 6.5 Running the Linker 6.6 Checking Runtime Behavior 6.7 Systemology 6.8 Multiple Cases 7 Results of Tests 7.1 Defining C Preprocessor Symbols 7.2 Setting Output Variables 7.3 Special Characters in Output Variables 7.4 Caching Results 7.4.1 Cache Variable Names 7.4.2 Cache Files 7.4.3 Cache Checkpointing 7.5 Printing Messages 8 Programming in M4 8.1 M4 Quotation 8.1.1 Active Characters 8.1.2 One Macro Call 8.1.3 Quoting and Parameters 8.1.4 Quotation and Nested Macros 8.1.5 `changequote' is Evil 8.1.6 Quadrigraphs 8.1.7 Quotation Rule Of Thumb 8.2 Using `autom4te' 8.2.1 Invoking `autom4te' 8.2.2 Customizing `autom4te' 8.3 Programming in M4sugar 8.3.1 Redefined M4 Macros 8.3.2 Diagnostic messages from M4sugar 8.3.3 Diversion support 8.3.4 Conditional constructs 8.3.5 Looping constructs 8.3.6 Evaluation Macros 8.3.7 String manipulation in M4 8.3.8 Arithmetic computation in M4 8.3.9 Set manipulation in M4 8.3.10 Forbidden Patterns 8.4 Programming in M4sh 8.5 File Descriptor Macros 9 Writing Autoconf Macros 9.1 Macro Definitions 9.2 Macro Names 9.3 Reporting Messages 9.4 Dependencies Between Macros 9.4.1 Prerequisite Macros 9.4.2 Suggested Ordering 9.4.3 One-Shot Macros 9.5 Obsoleting Macros 9.6 Coding Style 10 Portable Shell Programming 10.1 Shellology 10.2 Here-Documents 10.3 File Descriptors 10.4 File System Conventions 10.5 Shell Pattern Matching 10.6 Shell Substitutions 10.7 Assignments 10.8 Parentheses in Shell Scripts 10.9 Slashes in Shell Scripts 10.10 Special Shell Variables 10.11 Shell Functions 10.12 Limitations of Shell Builtins 10.13 Limitations of Usual Tools 11 Portable Make Programming 11.1 `$<' in Ordinary Make Rules 11.2 Failure in Make Rules 11.3 Special Characters in Make Macro Names 11.4 Backslash-Newline-Newline in Make Macro Values 11.5 Backslash-Newline in Make Comments 11.6 Long Lines in Makefiles 11.7 `make macro=value' and Submakes 11.8 The Make Macro MAKEFLAGS 11.9 The Make Macro `SHELL' 11.10 Comments in Make Rules 11.11 The `obj/' Subdirectory and Make 11.12 Exit Status of `make -k' 11.13 `VPATH' and Make 11.13.1 `VPATH' and Double-colon Rules 11.13.2 `$<' Not Supported in Explicit Rules 11.13.3 Automatic Rule Rewriting 11.13.4 Tru64 `make' Creates Prerequisite Directories Magically 11.13.5 Make Target Lookup 11.14 Single Suffix Rules and Separated Dependencies 11.15 Timestamp Resolution and Make 12 Portable C and C++ Programming 12.1 Varieties of Unportability 12.2 Integer Overflow 12.2.1 Basics of Integer Overflow 12.2.2 Examples of Code Assuming Wraparound Overflow 12.2.3 Optimizations That Break Wraparound Arithmetic 12.2.4 Practical Advice for Signed Overflow Issues 12.2.5 Signed Integer Division and Integer Overflow 12.3 Preprocessor Arithmetic 12.4 Properties of Null Pointers 12.5 Buffer Overruns and Subscript Errors 12.6 Volatile Objects 12.7 Floating Point Portability 12.8 Exiting Portably 13 Manual Configuration 13.1 Specifying the System Type 13.2 Getting the Canonical System Type 13.3 Using the System Type 14 Site Configuration 14.1 Controlling Help Output 14.2 Working With External Software 14.3 Choosing Package Options 14.4 Making Your Help Strings Look Pretty 14.5 Controlling Checking of `configure' Options 14.6 Configuring Site Details 14.7 Transforming Program Names When Installing 14.7.1 Transformation Options 14.7.2 Transformation Examples 14.7.3 Transformation Rules 14.8 Setting Site Defaults 15 Running `configure' Scripts 15.1 Basic Installation 15.2 Compilers and Options 15.3 Compiling For Multiple Architectures 15.4 Installation Names 15.5 Optional Features 15.6 Particular systems 15.7 Specifying the System Type 15.8 Sharing Defaults 15.9 Defining Variables 15.10 `configure' Invocation 16 config.status Invocation 17 Obsolete Constructs 17.1 Obsolete `config.status' Invocation 17.2 `acconfig.h' 17.3 Using `autoupdate' to Modernize `configure.ac' 17.4 Obsolete Macros 17.5 Upgrading From Version 1 17.5.1 Changed File Names 17.5.2 Changed Makefiles 17.5.3 Changed Macros 17.5.4 Changed Results 17.5.5 Changed Macro Writing 17.6 Upgrading From Version 2.13 17.6.1 Changed Quotation 17.6.2 New Macros 17.6.3 Hosts and Cross-Compilation 17.6.4 `AC_LIBOBJ' vs. `LIBOBJS' 17.6.5 `AC_FOO_IFELSE' vs. `AC_TRY_FOO' 18 Generating Test Suites with Autotest 18.1 Using an Autotest Test Suite 18.1.1 `testsuite' Scripts 18.1.2 Autotest Logs 18.2 Writing `testsuite.at' 18.3 Running `testsuite' Scripts 18.4 Making `testsuite' Scripts 19 Frequent Autoconf Questions, with answers 19.1 Distributing `configure' Scripts 19.2 Why Require GNU M4? 19.3 How Can I Bootstrap? 19.4 Why Not Imake? 19.5 How Do I `#define' Installation Directories? 19.6 What is `autom4te.cache'? 19.7 Header Present But Cannot Be Compiled 20 History of Autoconf 20.1 Genesis 20.2 Exodus 20.3 Leviticus 20.4 Numbers 20.5 Deuteronomy Appendix A GNU Free Documentation License Appendix B Indices B.1 Environment Variable Index B.2 Output Variable Index B.3 Preprocessor Symbol Index B.4 Autoconf Macro Index B.5 M4 Macro Index B.6 Autotest Macro Index B.7 Program and Function Index B.8 Concept Index Autoconf ******** This manual (9 September 2008) is for GNU Autoconf (version 2.63), a package for creating scripts to configure source code packages using templates and an M4 macro package. Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008 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.2 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License." (a) The FSF's Back-Cover Text is: "You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom." 1 Introduction ************** A physicist, an engineer, and a computer scientist were discussing the nature of God. "Surely a Physicist," said the physicist, "because early in the Creation, God made Light; and you know, Maxwell's equations, the dual nature of electromagnetic waves, the relativistic consequences...." "An Engineer!," said the engineer, "because before making Light, God split the Chaos into Land and Water; it takes a hell of an engineer to handle that big amount of mud, and orderly separation of solids from liquids...." The computer scientist shouted: "And the Chaos, where do you think it was coming from, hmm?" --Anonymous Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of Posix-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf. The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they individually test for the presence of each feature that the software package they are for might need. (Before each check, they print a one-line message stating what they are checking for, so the user doesn't get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common Posix variants. There is no need to maintain files that list the features supported by each release of each variant of Posix. For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code. Those who do not understand Autoconf are condemned to reinvent it, poorly. The primary goal of Autoconf is making the _user's_ life easier; making the _maintainer's_ life easier is only a secondary goal. Put another way, the primary goal is not to make the generation of `configure' automatic for package maintainers (although patches along that front are welcome, since package maintainers form the user base of Autoconf); rather, the goal is to make `configure' painless, portable, and predictable for the end user of each "autoconfiscated" package. And to this degree, Autoconf is highly successful at its goal -- most complaints to the Autoconf list are about difficulties in writing Autoconf input, and not in the behavior of the resulting `configure'. Even packages that don't use Autoconf will generally provide a `configure' script, and the most common complaint about these alternative home-grown scripts is that they fail to meet one or more of the GNU Coding Standards that users have come to expect from Autoconf-generated `configure' scripts. The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them. Autoconf does not solve all problems related to making portable software packages--for a more complete solution, it should be used in concert with other GNU build tools like Automake and Libtool. These other tools take on jobs like the creation of a portable, recursive makefile with all of the standard targets, linking of shared libraries, and so on. *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 version 1.4.5 or later in order to generate the scripts. It uses features that some versions of M4, including GNU M4 1.3, do not have. Autoconf works better with GNU M4 version 1.4.11 or later, though this is not required. *Note Autoconf 1::, for information about upgrading from version 1. *Note History::, for the story of Autoconf's development. *Note FAQ::, for answers to some common questions about Autoconf. See the Autoconf web page (http://www.gnu.org/software/autoconf/) for up-to-date information, details on the mailing lists, pointers to a list of known bugs, etc. Mail suggestions to the Autoconf mailing list . Past suggestions are archived (http://lists.gnu.org/archive/html/autoconf/). Mail bug reports to the Autoconf Bugs mailing list . Past bug reports are archived (http://lists.gnu.org/archive/html/bug-autoconf/). If possible, first check that your bug is not already solved in current development versions, and that it has not been reported yet. Be sure to include all the needed information and a short `configure.ac' that demonstrates the problem. Autoconf's development tree is accessible via `git'; see the Autoconf Summary (http://savannah.gnu.org/projects/autoconf/) for details, or view the actual repository (http://git.sv.gnu.org/gitweb/?p=autoconf.git). Anonymous CVS access is also available, see `README' for more details. Patches relative to the current `git' version can be sent for review to the Autoconf Patches mailing list , with discussion on prior patches archived (http://lists.gnu.org/archive/html/autoconf-patches/); and all commits are posted in the read-only Autoconf Commit mailing list , which is also archived (http://lists.gnu.org/archive/html/autoconf-commit/). Because of its mission, the Autoconf package itself includes only a set of often-used macros that have already demonstrated their usefulness. Nevertheless, if you wish to share your macros, or find existing ones, see the Autoconf Macro Archive (http://autoconf-archive.cryp.to/), which is kindly run by Peter Simons . 2 The GNU Build System ********************** Autoconf solves an important problem--reliable discovery of system-specific build and runtime information--but this is only one piece of the puzzle for the development of portable software. To this end, the GNU project has developed a suite of integrated utilities to finish the job Autoconf started: the GNU build system, whose most important components are Autoconf, Automake, and Libtool. In this chapter, we introduce you to those tools, point you to sources of more information, and try to convince you to use the entire GNU build system for your software. 2.1 Automake ============ The ubiquity of `make' means that a makefile is almost the only viable way to distribute automatic build rules for software, but one quickly runs into its numerous limitations. Its lack of support for automatic dependency tracking, recursive builds in subdirectories, reliable timestamps (e.g., for network file systems), and so on, mean that developers must painfully (and often incorrectly) reinvent the wheel for each project. Portability is non-trivial, thanks to the quirks of `make' on many systems. On top of all this is the manual labor required to implement the many standard targets that users have come to expect (`make install', `make distclean', `make uninstall', etc.). Since you are, of course, using Autoconf, you also have to insert repetitive code in your `Makefile.in' to recognize `@CC@', `@CFLAGS@', and other substitutions provided by `configure'. Into this mess steps "Automake". Automake allows you to specify your build needs in a `Makefile.am' file with a vastly simpler and more powerful syntax than that of a plain makefile, and then generates a portable `Makefile.in' for use with Autoconf. For example, the `Makefile.am' to build and install a simple "Hello world" program might look like: bin_PROGRAMS = hello hello_SOURCES = hello.c The resulting `Makefile.in' (~400 lines) automatically supports all the standard targets, the substitutions provided by Autoconf, automatic dependency tracking, `VPATH' building, and so on. `make' builds the `hello' program, and `make install' installs it in `/usr/local/bin' (or whatever prefix was given to `configure', if not `/usr/local'). The benefits of Automake increase for larger packages (especially ones with subdirectories), but even for small programs the added convenience and portability can be substantial. And that's not all.... 2.2 Gnulib ========== GNU software has a well-deserved reputation for running on many different types of systems. While our primary goal is to write software for the GNU system, many users and developers have been introduced to us through the systems that they were already using. Gnulib is a central location for common GNU code, intended to be shared among free software packages. Its components are typically shared at the source level, rather than being a library that gets built, installed, and linked against. The idea is to copy files from Gnulib into your own source tree. There is no distribution tarball; developers should just grab source modules from the repository. The source files are available online, under various licenses, mostly GNU GPL or GNU LGPL. Gnulib modules typically contain C source code along with Autoconf macros used to configure the source code. For example, the Gnulib `stdbool' module implements a `stdbool.h' header that nearly conforms to C99, even on old-fashioned hosts that lack `stdbool.h'. This module contains a source file for the replacement header, along with an Autoconf macro that arranges to use the replacement header on old-fashioned systems. 2.3 Libtool =========== Often, one wants to build not only programs, but libraries, so that other programs can benefit from the fruits of your labor. Ideally, one would like to produce _shared_ (dynamically linked) libraries, which can be used by multiple programs without duplication on disk or in memory and can be updated independently of the linked programs. Producing shared libraries portably, however, is the stuff of nightmares--each system has its own incompatible tools, compiler flags, and magic incantations. Fortunately, GNU provides a solution: "Libtool". Libtool handles all the requirements of building shared libraries for you, and at this time seems to be the _only_ way to do so with any portability. It also handles many other headaches, such as: the interaction of Make rules with the variable suffixes of shared libraries, linking reliably with shared libraries before they are installed by the superuser, and supplying a consistent versioning system (so that different versions of a library can be installed or upgraded without breaking binary compatibility). Although Libtool, like Autoconf, can be used without Automake, it is most simply utilized in conjunction with Automake--there, Libtool is used automatically whenever shared libraries are needed, and you need not know its syntax. 2.4 Pointers ============ Developers who are used to the simplicity of `make' for small projects on a single system might be daunted at the prospect of learning to use Automake and Autoconf. As your software is distributed to more and more users, however, you otherwise quickly find yourself putting lots of effort into reinventing the services that the GNU build tools provide, and making the same mistakes that they once made and overcame. (Besides, since you're already learning Autoconf, Automake is a piece of cake.) There are a number of places that you can go to for more information on the GNU build tools. - Web The project home pages for Autoconf (http://www.gnu.org/software/autoconf/), Automake (http://www.gnu.org/software/automake/), Gnulib (http://www.gnu.org/software/gnulib/), and Libtool (http://www.gnu.org/software/libtool/). - Automake Manual *Note Automake: (automake)Top, for more information on Automake. - Books The book `GNU Autoconf, Automake and Libtool'(1) describes the complete GNU build environment. You can also find the entire book on-line (http://sources.redhat.com/autobook/). ---------- Footnotes ---------- (1) `GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally New Riders), 2000, ISBN 1578701902. 3 Making `configure' Scripts **************************** The configuration scripts that Autoconf produces are by convention called `configure'. When run, `configure' creates several files, replacing configuration parameters in them with appropriate values. The files that `configure' creates are: - one or more `Makefile' files, usually one in each subdirectory of the package (*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, recreates 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 can distribute the generated file `config.h.in' with the package. Here is a diagram showing how the files that can be used in configuration are produced. Programs that are executed are suffixed by `*'. Optional files are enclosed in square brackets (`[]'). `autoconf' and `autoheader' also read the installed Autoconf macro files (by reading `autoconf.m4'). Files used in preparing a software package for distribution: your source files --> [autoscan*] --> [configure.scan] --> configure.ac configure.ac --. | .------> autoconf* -----> configure [aclocal.m4] --+---+ | `-----> [autoheader*] --> [config.h.in] [acsite.m4] ---' Makefile.in -------------------------------> Makefile.in Files used in configuring a software package: .-------------> [config.cache] configure* ------------+-------------> config.log | [config.h.in] -. v .-> [config.h] -. +--> config.status* -+ +--> make* Makefile.in ---' `-> Makefile ---' 3.1 Writing `configure.ac' ========================== 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 process this file is not described by its extension), and introduces a slight confusion with `config.h.in' and so on (for which `.in' means "to be processed by `configure'"). Using `configure.ac' is now preferred. 3.1.1 A Shell Script Compiler ----------------------------- 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. Even in 2007, where shells without any function support are far and few between, there are pitfalls to avoid when making use of them. So, what is really needed is some kind of compiler, `autoconf', that takes an Autoconf program, `configure.ac', and transforms it into a portable shell script, `configure'. How does `autoconf' perform this task? There are two obvious possibilities: creating a brand new language or extending an existing one. The former option is attractive: all sorts of optimizations could easily be implemented in the compiler and many rigorous checks could be performed on the Autoconf program (e.g., rejecting any non-portable construct). Alternatively, you can extend an existing language, such as the `sh' (Bourne shell) language. Autoconf does the latter: it is a layer on top of `sh'. It was therefore most convenient to implement `autoconf' as a macro expander: a program that repeatedly performs "macro expansions" on text input, replacing macro calls with macro bodies and producing a pure `sh' script in the end. Instead of implementing a dedicated Autoconf macro expander, it is natural to use an existing general-purpose macro language, such as M4, and implement the extensions as a set of M4 macros. 3.1.2 The Autoconf Language --------------------------- The Autoconf language differs from many other computer languages because it treats actual code the same as plain text. Whereas in C, for instance, data and instructions have different syntactic status, in Autoconf their status is rigorously the same. Therefore, we need a means to distinguish literal strings from text to be expanded: quotation. When calling macros that take arguments, there must not be any white space between the macro name and the open parenthesis. Arguments should be enclosed within the M4 quote characters `[' and `]', and be separated by commas. Any leading blanks or newlines in arguments are ignored, unless they are quoted. You should always quote an argument that might contain a macro name, comma, parenthesis, or a leading blank or newline. This rule applies recursively for every macro call, including macros called from other macros. For instance: AC_CHECK_HEADER([stdio.h], [AC_DEFINE([HAVE_STDIO_H], [1], [Define to 1 if you have .])], [AC_MSG_ERROR([Sorry, can't do anything for you])]) is quoted properly. You may safely simplify its quotation to: AC_CHECK_HEADER([stdio.h], [AC_DEFINE([HAVE_STDIO_H], 1, [Define to 1 if you have .])], [AC_MSG_ERROR([Sorry, can't do anything for you])]) because `1' cannot contain a macro call. Here, the argument of `AC_MSG_ERROR' must be quoted; otherwise, its comma would be interpreted as an argument separator. Also, the second and third arguments of `AC_CHECK_HEADER' must be quoted, since they contain macro calls. The three arguments `HAVE_STDIO_H', `stdio.h', and `Define to 1 if you have .' do not need quoting, but if you unwisely defined a macro with a name like `Define' or `stdio' then they would need quoting. Cautious Autoconf users would keep the quotes, but many Autoconf users find such precautions annoying, and would rewrite the example as follows: AC_CHECK_HEADER(stdio.h, [AC_DEFINE(HAVE_STDIO_H, 1, [Define to 1 if you have .])], [AC_MSG_ERROR([Sorry, can't do anything for you])]) This is safe, so long as you adopt good naming conventions and do not define macros with names like `HAVE_STDIO_H', `stdio', or `h'. Though it is also safe here to omit the quotes around `Define to 1 if you have .' this is not recommended, as message strings are more likely to inadvertently contain commas. The following example is wrong and dangerous, as it is underquoted: AC_CHECK_HEADER(stdio.h, AC_DEFINE(HAVE_STDIO_H, 1, Define to 1 if you have .), 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 results 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 is 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! On the other hand, descriptions (e.g., the last parameter of `AC_DEFINE' or `AS_HELP_STRING') are not literals--they are subject to line breaking, for example--and should not be double quoted. Even if these descriptions are short and are not actually broken, double quoting them yields weird results. Some macros take optional arguments, which this documentation represents as [ARG] (not to be confused with the quote characters). You may just leave them empty, or use `[]' to make the emptiness of the argument explicit, or you may simply omit the trailing commas. The three lines below are equivalent: AC_CHECK_HEADERS([stdio.h], [], [], []) AC_CHECK_HEADERS([stdio.h],,,) AC_CHECK_HEADERS([stdio.h]) It is best to put each macro call on its own line in `configure.ac'. Most of the macros don't add extra newlines; they rely on the newline after the macro call to terminate the commands. This approach makes the generated `configure' script a little easier to read by not inserting lots of blank lines. It is generally safe to set shell variables on the same line as a macro call, because the shell allows assignments without intervening newlines. You can include comments in `configure.ac' files by starting them with the `#'. For example, it is helpful to begin `configure.ac' files with a line like this: # Process this file with autoconf to produce a configure script. 3.1.3 Standard `configure.ac' Layout ------------------------------------ The order in which `configure.ac' calls the Autoconf macros is not important, with a few exceptions. Every `configure.ac' must contain a call to `AC_INIT' before the checks, and a call to `AC_OUTPUT' at the end (*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' 3.2 Using `autoscan' to Create `configure.ac' ============================================= The `autoscan' program can help you create and/or maintain a `configure.ac' file for a software package. `autoscan' examines source files in the directory tree rooted at a directory given as a command line argument, or the current directory if none is given. It searches the source files for common portability problems and creates a file `configure.scan' which is a preliminary `configure.ac' for that package, and checks a possibly existing `configure.ac' for completeness. When using `autoscan' to create a `configure.ac', you should manually examine `configure.scan' before renaming it to `configure.ac'; it probably needs some adjustments. Occasionally, `autoscan' outputs a macro in the wrong order relative to another macro, so that `autoconf' produces a warning; you need to move such macros manually. Also, if you want the package to use a configuration header file, you must add a call to `AC_CONFIG_HEADERS' (*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' contains detailed information on why a macro is requested. `autoscan' uses several data files (installed along with Autoconf) to determine which macros to output when it finds particular symbols in a package's source files. These data files all have the same format: each line consists of a symbol, one or more blanks, and the Autoconf macro to output if that symbol is encountered. Lines starting with `#' are comments. `autoscan' accepts the following options: `--help' `-h' Print a summary of the command line options and exit. `--version' `-V' Print the version number of Autoconf and exit. `--verbose' `-v' Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous. `--debug' `-d' Don't remove temporary files. `--include=DIR' `-I DIR' Append DIR to the include path. Multiple invocations accumulate. `--prepend-include=DIR' `-B DIR' Prepend DIR to the include path. Multiple invocations accumulate. 3.3 Using `ifnames' to List Conditionals ======================================== `ifnames' can help you write `configure.ac' for a software package. It prints the identifiers that the package already uses in C preprocessor conditionals. If a package has already been set up to have some portability, `ifnames' can thus help you figure out what its `configure' needs to check for. It may help fill in some gaps in a `configure.ac' generated by `autoscan' (*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. 3.4 Using `autoconf' to Create `configure' ========================================== To create `configure' from `configure.ac', run the `autoconf' program with no arguments. `autoconf' processes `configure.ac' with the M4 macro processor, using the Autoconf macros. If you give `autoconf' an argument, it reads that file instead of `configure.ac' and writes the configuration script to the standard output instead of to `configure'. If you give `autoconf' the argument `-', it reads from the standard input instead of `configure.ac' and writes the configuration script to the standard output. The Autoconf macros are defined in several files. Some of the files are distributed with Autoconf; `autoconf' reads them first. Then it looks for the optional file `acsite.m4' in the directory that contains the distributed Autoconf macro files, and for the optional file `aclocal.m4' in the current directory. Those files can contain your site's or the package's own Autoconf macro definitions (*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' Append DIR to the include path. Multiple invocations accumulate. `--prepend-include=DIR' `-B DIR' Prepend DIR to the include path. Multiple invocations accumulate. `--output=FILE' `-o FILE' Save output (script or trace) to FILE. The file `-' stands for the standard output. `--warnings=CATEGORY' `-W CATEGORY' Report the warnings related to CATEGORY (which can actually be a comma separated list). *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 as well. Passing `-W CATEGORY' actually behaves as if you had passed `--warnings syntax,$WARNINGS,CATEGORY'. If you want to disable the defaults and `WARNINGS', but (for example) enable the warnings about obsolete constructs, you would use `-W none,obsolete'. Because `autoconf' uses `autom4te' behind the scenes, it displays a back trace for errors, but not for warnings; if you want them, just pass `-W error'. *Note autom4te Invocation::, for some examples. `--trace=MACRO[:FORMAT]' `-t MACRO[:FORMAT]' Do not create the `configure' script, but list the calls to MACRO according to the FORMAT. Multiple `--trace' arguments can be used to list several macros. Multiple `--trace' arguments for a single macro are not cumulative; instead, you should just make FORMAT as long as needed. The FORMAT is a regular string, with newlines if desired, and several special escape codes. It defaults to `$f:$l:$n:$%'; see *Note autom4te Invocation::, for details on the FORMAT. `--initialization' `-i' By default, `--trace' does not trace the initialization of the Autoconf macros (typically the `AC_DEFUN' definitions). This results in a noticeable speedup, but can be disabled by this option. It is often necessary to check the content of a `configure.ac' file, but parsing it yourself is extremely fragile and error-prone. It is suggested that you rely upon `--trace' to scan `configure.ac'. For instance, to find the list of variables that are substituted, use: $ autoconf -t AC_SUBST configure.ac:2:AC_SUBST:ECHO_C configure.ac:2:AC_SUBST:ECHO_N configure.ac:2:AC_SUBST:ECHO_T More traces deleted The example below highlights the difference between `$@', `$*', and `$%'. $ cat configure.ac AC_DEFINE(This, is, [an [example]]) $ autoconf -t 'AC_DEFINE:@: $@ *: $* %: $%' @: [This],[is],[an [example]] *: This,is,an [example] %: This:is:an [example] The FORMAT gives you a lot of freedom: $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' $ac_subst{"ECHO_C"} = "configure.ac:2"; $ac_subst{"ECHO_N"} = "configure.ac:2"; $ac_subst{"ECHO_T"} = "configure.ac:2"; More traces deleted A long SEPARATOR can be used to improve the readability of complex structures, and to ease their parsing (for instance when no single character is suitable as a separator): $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' ACLOCAL|:::::|aclocal|:::::|$missing_dir AUTOCONF|:::::|autoconf|:::::|$missing_dir AUTOMAKE|:::::|automake|:::::|$missing_dir More traces deleted 3.5 Using `autoreconf' to Update `configure' Scripts ==================================================== Installing the various components of the GNU Build System can be tedious: running `autopoint' for Gettext, `automake' for `Makefile.in' etc. in each directory. It may be needed either because some tools such as `automake' have been updated on your system, or because some of the sources such as `configure.ac' have been updated, or finally, simply in order to install the GNU Build System in a fresh tree. `autoreconf' runs `autoconf', `autoheader', `aclocal', `automake', `libtoolize', and `autopoint' (when appropriate) repeatedly to update the GNU Build System in the specified directories and their subdirectories (*note Subdirectories::). By default, it only remakes those files that are older than their sources. The environment variables `AUTOCONF', `AUTOHEADER', `AUTOMAKE', `ACLOCAL', `AUTOPOINT', `LIBTOOLIZE', `M4', and `MAKE' may be used to override the invocation of the respective tools. If you install a new version of some tool, you can make `autoreconf' remake _all_ of the files by giving it the `--force' option. *Note Automatic Remaking::, for Make rules to automatically rebuild `configure' scripts when their source files change. That method handles the timestamps of configuration header templates properly, but does not pass `--autoconf-dir=DIR' or `--localdir=DIR'. Gettext supplies the `autopoint' command to add translation infrastructure to a source package. If you use `autopoint', your `configure.ac' should invoke both `AM_GNU_GETTEXT' and `AM_GNU_GETTEXT_VERSION(GETTEXT-VERSION)'. *Note Invoking the `autopoint' Program: (gettext)autopoint Invocation, for further details. `autoreconf' accepts the following options: `--help' `-h' Print a summary of the command line options and exit. `--version' `-V' Print the version number of Autoconf and exit. `--verbose' `-V' Print the name of each directory `autoreconf' examines and the commands it runs. If given two or more times, pass `--verbose' to subordinate tools that support it. `--debug' `-d' Don't remove the temporary files. `--force' `-f' Remake even `configure' scripts and configuration headers that are newer than their input files (`configure.ac' and, if present, `aclocal.m4'). `--install' `-i' Install the missing auxiliary files in the package. By default, files are copied; this can be changed with `--symlink'. If deemed appropriate, this option triggers calls to `automake --add-missing', `libtoolize', `autopoint', etc. `--no-recursive' Do not rebuild files in subdirectories to configure (see *Note Subdirectories::, macro `AC_CONFIG_SUBDIRS'). `--symlink' `-s' When used with `--install', install symbolic links to the missing auxiliary files instead of copying them. `--make' `-m' When the directories were configured, update the configuration by running `./config.status --recheck && ./config.status', and then run `make'. `--include=DIR' `-I DIR' Append DIR to the include path. Multiple invocations accumulate. Passed on to `autoconf' and `autoheader' internally. `--prepend-include=DIR' `-B DIR' Prepend DIR to the include path. Multiple invocations accumulate. Passed on to `autoconf' and `autoheader' internally. `--warnings=CATEGORY' `-W CATEGORY' Report the warnings related to CATEGORY (which can actually be a comma separated list). `cross' related to cross compilation issues. `obsolete' report the uses of obsolete constructs. `portability' portability issues `syntax' dubious syntactic constructs. `all' report all the warnings `none' report none `error' treats warnings as errors `no-CATEGORY' disable warnings falling into CATEGORY Warnings about `syntax' are enabled by default, and the environment variable `WARNINGS', a comma separated list of categories, is honored as well. Passing `-W CATEGORY' actually behaves as if you had passed `--warnings syntax,$WARNINGS,CATEGORY'. If you want to disable the defaults and `WARNINGS', but (for example) enable the warnings about obsolete constructs, you would use `-W none,obsolete'. If you want `autoreconf' to pass flags that are not listed here on to `aclocal', set `ACLOCAL_AMFLAGS' in your `Makefile.am'. Due to a limitation in the Autoconf implementation these flags currently must be set on a single line in `Makefile.am', without any backslash-newlines. 4 Initialization and Output Files ********************************* Autoconf-generated `configure' scripts need some information about how to initialize, such as how to find the package's source files and about the output files to produce. The following sections describe the initialization and the creation of output files. 4.1 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 former is meant for distribution tar ball names (e.g., `autoconf'). It defaults to PACKAGE with `GNU ' stripped, lower-cased, and all characters other than alphanumerics and underscores are changed to `-'. It is preferable that the arguments of `AC_INIT' be static, i.e., there should not be any shell computation, but they can be computed by M4. The following M4 macros (e.g., `AC_PACKAGE_NAME'), output variables (e.g., `PACKAGE_NAME'), and preprocessor symbols (e.g., `PACKAGE_NAME'), are defined by `AC_INIT': `AC_PACKAGE_NAME', `PACKAGE_NAME' 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. If your `configure' script does its own option processing, it should inspect `$@' or `$*' immediately after calling `AC_INIT', because other Autoconf macros liberally use the `set' command to process strings, and this has the side effect of updating `$@' and `$*'. However, we suggest that you use standard macros like `AC_ARG_ENABLE' instead of attempting to implement your own option processing. *Note Site Configuration::. 4.2 Dealing with Autoconf versions ================================== The following optional macros can be used to help choose the minimum version of Autoconf that can successfully compile a given `configure.ac'. -- 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 exit with failure (exit status is 63). For example: AC_PREREQ([2.63]) 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_AUTOCONF_VERSION This macro was introduced in Autoconf 2.62. It identifies the version of Autoconf that is currently parsing the input file, in a format suitable for `m4_version_compare' (*note m4_version_compare::); in other words, for this release of Autoconf, its value is `2.63'. One potential use of this macro is for writing conditional fallbacks based on when a feature was added to Autoconf, rather than using `AC_PREREQ' to require the newer version of Autoconf. However, remember that the Autoconf philosophy favors feature checks over version checks. You should not expand this macro directly; use `m4_defn([AC_AUTOCONF_VERSION])' instead. This is because some users might have a beta version of Autoconf installed, with arbitrary letters included in its version string. This means it is possible for the version string to contain the name of a defined macro, such that expanding `AC_AUTOCONF_VERSION' would trigger the expansion of that macro during rescanning, and change the version string to be different than what you intended to check. 4.3 Notices in `configure' ========================== The following macros manage version numbers for `configure' scripts. Using them is optional. -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE) State that, in addition to the Free Software Foundation's copyright on the Autoconf macros, parts of your `configure' are covered by the COPYRIGHT-NOTICE. The COPYRIGHT-NOTICE shows up in both the head of `configure' and in `configure --version'. -- Macro: AC_REVISION (REVISION-INFO) Copy revision stamp REVISION-INFO into the `configure' script, with any dollar signs or double-quotes removed. This macro lets you put a revision stamp from `configure.ac' into `configure' without RCS or CVS changing it when you check in `configure'. That way, you can determine easily which revision of `configure.ac' a particular `configure' corresponds to. For example, this line in `configure.ac': AC_REVISION([$Revision: 1.30 $]) produces this in `configure': #!/bin/sh # From configure.ac Revision: 1.30 4.4 Finding `configure' Input ============================= -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR) UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's source directory; `configure' checks for this file's existence to make sure that the directory that it is told contains the source code in fact does. Occasionally people accidentally specify the wrong directory with `--srcdir'; this is a safety check. *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. The auxiliary directory is commonly named `build-aux'. If you need portability to DOS variants, do not name the auxiliary directory `aux'. *Note File System Conventions::. -- Macro: AC_REQUIRE_AUX_FILE (FILE) Declares that FILE is expected in the directory defined above. In Autoconf proper, this macro does nothing: its sole purpose is to be traced by third-party tools to produce a list of expected auxiliary files. For instance it is called by macros like `AC_PROG_INSTALL' (*note Particular Programs::) or `AC_CANONICAL_BUILD' (*note Canonicalizing::) to register the auxiliary files they need. Similarly, packages that use `aclocal' should declare where local macros can be found using `AC_CONFIG_MACRO_DIR'. -- Macro: AC_CONFIG_MACRO_DIR (DIR) Specify DIR as the location of additional local Autoconf macros. This macro is intended for use by future versions of commands like `autoreconf' that trace macro calls. It should be called directly from `configure.ac' so that tools that install macros for `aclocal' can find the macros' declarations. Note that if you use `aclocal' from Automake to generate `aclocal.m4', you must also set `ACLOCAL_AMFLAGS = -I DIR' in your top-level `Makefile.am'. Due to a limitation in the Autoconf implementation of `autoreconf', these include directives currently must be set on a single line in `Makefile.am', without any backslash-newlines. 4.5 Outputting Files ==================== Every Autoconf script, e.g., `configure.ac', should finish by calling `AC_OUTPUT'. That is the macro that generates and runs `config.status', which in turn creates the makefiles and any other files resulting from configuration. This is the only required macro besides `AC_INIT' (*note Input::). -- Macro: AC_OUTPUT Generate `config.status' and launch it. Call this macro once, at the end of `configure.ac'. `config.status' performs all the configuration actions: all the output files (see *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. The location of your `AC_OUTPUT' invocation is the exact point where configuration actions are taken: any code afterwards is executed by `configure' once `config.status' was run. If you want to bind actions to `config.status' itself (independently of whether `configure' is being run), see *Note Running Arbitrary Configuration Commands: Configuration Commands. 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' in subdirectories, you should run it using the `make' variable `MAKE'. Most versions of `make' set `MAKE' to the name of the `make' program plus any options it was given. (But many do not include in it the values of any variables set on the command line, so those are not passed on automatically.) Some old versions of `make' do not set this variable. The following macro allows you to use it even with those versions. -- Macro: AC_PROG_MAKE_SET If the Make command, `$MAKE' if set or else `make', predefines `$(MAKE)', define output variable `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to a macro definition that sets `$(MAKE)', such as `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. If you use this macro, place a line like this in each `Makefile.in' that runs `MAKE' on other directories: @SET_MAKE@ 4.6 Performing Configuration Actions ==================================== `configure' is designed so that it appears to do everything itself, but there is actually a hidden slave: `config.status'. `configure' is in charge of examining your system, but it is `config.status' that actually takes the proper actions based on the results of `configure'. The most typical task of `config.status' is to _instantiate_ files. This section describes the common behavior of the four standard instantiating macros: `AC_CONFIG_FILES', `AC_CONFIG_HEADERS', `AC_CONFIG_COMMANDS' and `AC_CONFIG_LINKS'. They all have this prototype: AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS]) where the arguments are: TAG... A blank-or-newline-separated list of tags, which are typically the names of the files to instantiate. You are encouraged to use literals as TAGS. In particular, you should avoid ... && my_foos="$my_foos fooo" ... && my_foos="$my_foos foooo" AC_CONFIG_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 TAG values: they may have the form `OUTPUT' or `OUTPUT:INPUTS'. The file OUTPUT is instantiated from its templates, INPUTS (defaulting to `OUTPUT.in'). `AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]', for example, asks for the creation of the file `Makefile' that contains the expansion of the output variables in the concatenation of `boiler/top.mk' and `boiler/bot.mk'. The special value `-' might be used to denote the standard output when used in OUTPUT, or the standard input when used in the INPUTS. You most probably don't need to use this in `configure.ac', but it is convenient when using the command line interface of `./config.status', see *Note config.status Invocation::, for more details. The INPUTS may be absolute or relative file names. In the latter case they are first looked for in the build tree, and then in the source tree. 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 variables set during the execution of `configure' are _not_ available here: you first need to set them via the INIT-CMDS. Nonetheless the following variables are precomputed: `srcdir' The name of the top source directory, assuming that the working directory is the top build directory. This is what the `configure' option `--srcdir' sets. `ac_top_srcdir' The name of the top source directory, assuming that the working directory is the current build directory. `ac_top_build_prefix' The name of the top build directory, assuming that the working directory is the current build directory. It can be empty, or else ends with a slash, so that you may concatenate it. `ac_srcdir' The name of the corresponding source directory, assuming that the working directory is the current build directory. The "current" directory refers to the directory (or pseudo-directory) containing the input part of TAGS. For instance, running AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [...], [...]) with `--srcdir=../package' produces the following values: # Argument of --srcdir srcdir='../package' # Reversing deep/dir ac_top_build_prefix='../../' # Concatenation of $ac_top_build_prefix and srcdir ac_top_srcdir='../../../package' # Concatenation of $ac_top_srcdir and deep/dir ac_srcdir='../../../package/deep/dir' independently of `in/in.in'. INIT-CMDS Shell commands output _unquoted_ near the beginning of `config.status', and executed each time `config.status' runs (regardless of the tag). Because they are unquoted, for example, `$var' is output as the value of `var'. INIT-CMDS is typically used by `configure' to give `config.status' some variables it needs to run the COMMANDS. You should be extremely cautious in your variable names: all the INIT-CMDS share the same name space and may overwrite each other in unpredictable ways. Sorry.... All these macros can be called multiple times, with different TAG values, of course! 4.7 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, makefiles 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 DOS variants, or to prepend and/or append boilerplate to the file. 4.8 Substitutions in Makefiles ============================== Each subdirectory in a distribution that contains something to be compiled or installed should come with a file `Makefile.in', from which `configure' creates a file `Makefile' in that directory. To create `Makefile', `configure' performs a simple variable substitution, replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value that `configure' has determined for that variable. Variables that are substituted into output files in this way are called "output variables". They are ordinary shell variables that are set in `configure'. To make `configure' substitute a particular variable into the output files, the macro `AC_SUBST' must be called with that variable name as an argument. Any occurrences of `@VARIABLE@' for other variables are left unchanged. *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 makefiles. 4.8.1 Preset Output Variables ----------------------------- Some output variables are preset by the Autoconf macros. Some of the Autoconf macros set additional output variables, which are mentioned in the descriptions for those macros. *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 or linking programs to test for C features. If a compiler option affects only the behavior of the preprocessor (e.g., `-D NAME'), it should be put into `CPPFLAGS' instead. If it affects only the linker (e.g., `-L DIRECTORY'), it should be put into `LDFLAGS' instead. If it affects only the compiler proper, `CFLAGS' is the natural home for it. If an option affects multiple phases of the compiler, though, matters get tricky. One approach to put such options directly into `CC', e.g., `CC='gcc -m64''. Another is to put them into both `CPPFLAGS' and `LDFLAGS', but not into `CFLAGS'. -- 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 Preprocessor options for the C, C++, and Objective C preprocessors and compilers. If it is not set in the environment when `configure' runs, the default value is empty. `configure' uses this variable when preprocessing or compiling programs to test for C, C++, and Objective C features. This variable's contents should contain options like `-I', `-D', and `-U' that affect only the behavior of the preprocessor. Please see the explanation of `CFLAGS' for what you can do if an option affects other phases of the compiler as well. Currently, `configure' always links as part of a single invocation of the compiler that also preprocesses and compiles, so it uses this variable also when linking programs. However, it is unwise to depend on this behavior because the GNU coding standards do not require it and many packages do not use `CPPFLAGS' when linking programs. *Note Special Chars in Variables::, for limitations that `CPPFLAGS' might run into. -- Variable: CXXFLAGS Debugging and optimization options for the C++ compiler. It acts like `CFLAGS', but for C++ instead of C. -- 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: ERLCFLAGS Debugging and optimization options for the Erlang compiler. If it is not set in the environment when `configure' runs, the default value is empty. `configure' uses this variable when compiling programs to test for Erlang features. -- Variable: FCFLAGS Debugging and optimization options for the Fortran compiler. If it is not set in the environment when `configure' runs, the default value is set when you call `AC_PROG_FC' (or empty if you don't). `configure' uses this variable when compiling or linking programs to test for Fortran features. -- 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 or linking programs to test for Fortran 77 features. -- Variable: LDFLAGS Options for the linker. If it is not set in the environment when `configure' runs, the default value is empty. `configure' uses this variable when linking programs to test for C, C++, Objective C, and Fortran features. This variable's contents should contain options like `-s' and `-L' that affect only the behavior of the linker. Please see the explanation of `CFLAGS' for what you can do if an option also affects other phases of the compiler. Don't use this variable to pass library names (`-l') to the linker; use `LIBS' instead. -- 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 features. -- Variable: OBJCFLAGS Debugging and optimization options for the Objective C compiler. It acts like `CFLAGS', but for Objective C instead of C. -- Variable: builddir Rigorously equal to `.'. Added for symmetry only. -- Variable: abs_builddir Absolute name of `builddir'. -- Variable: top_builddir The relative name of the top level of the current build tree. In the top-level directory, this is the same as `builddir'. -- Variable: top_build_prefix The relative name of the top level of the current build tree with final slash if nonemtpy. This is the same as `top_builddir', except that it contains of zero of more runs of `../', so it should not be appended with a slash for concatenation. This helps for `make' implementations that otherwise do not treat `./file' and `file' as equal in the toplevel build directory. -- Variable: abs_top_builddir Absolute name of `top_builddir'. -- Variable: srcdir The name of the directory that contains the source code for that makefile. -- Variable: abs_srcdir Absolute name of `srcdir'. -- Variable: top_srcdir The name of 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 name of `top_srcdir'. 4.8.2 Installation Directory Variables -------------------------------------- The following variables specify the directories for package installation, see *Note Variables for Installation Directories: (standards)Directory Variables, for more information. Each variable corresponds to an argument of `configure'; trailing slashes are stripped so that expressions such as `${prefix}/lib' expand with only one slash between directory names. See the end of this section for details on when and how to use these variables. -- Variable: bindir The directory for installing executables that users run. -- Variable: datadir The directory for installing idiosyncratic read-only architecture-independent data. -- Variable: datarootdir The root of the directory tree for read-only architecture-independent data files. -- Variable: docdir The directory for installing documentation files (other than Info and man). -- Variable: dvidir The directory for installing documentation files in DVI format. -- 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: htmldir The directory for installing HTML documentation. -- 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: localedir The directory for installing locale-dependent but architecture-independent data, such as message catalogs. This directory usually has a subdirectory per locale. -- 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: pdfdir The directory for installing PDF documentation. -- 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: psdir The directory for installing PostScript documentation. -- 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 `@datarootdir@' is replaced by `${prefix}/share', not `/usr/local/share', and `@datadir@' is replaced by `${datarootdir}'. This behavior is mandated by the GNU coding standards, so that when the user runs: `make' she can still specify a different prefix from the one specified to `configure', in which case, if needed, the package should hard code dependencies corresponding to the make-specified prefix. `make install' she can specify a different installation location, in which case the package _must_ still depend on the location which was compiled in (i.e., never recompile when `make install' is run). This is an extremely important feature, as many people may decide to install all the files of a package grouped together, and then install links from the final locations to there. In order to support these features, it is essential that `datarootdir' remains 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 hard-coding it in makefiles using e.g., `AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])', you should add `-DDATADIR='$(datadir)'' to your makefile's definition of `CPPFLAGS' (`AM_CPPFLAGS' if you are also using Automake). Similarly, you should not rely on `AC_CONFIG_FILES' to replace `datadir' and friends in your shell scripts and other files; instead, let `make' manage their replacement. For instance Autoconf ships templates of its shell scripts ending with `.in', and uses a makefile snippet similar to the following to build scripts like `autoheader' and `autom4te': edit = sed \ -e 's|@datadir[@]|$(pkgdatadir)|g' \ -e 's|@prefix[@]|$(prefix)|g' autoheader autom4te: Makefile rm -f $@ $@.tmp $(edit) '$(srcdir)/$@.in' >$@.tmp chmod +x $@.tmp chmod a-w $@.tmp mv $@.tmp $@ autoheader: $(srcdir)/autoheader.in autom4te: $(srcdir)/autom4te.in Some details are noteworthy: `@datadir[@]' The brackets prevent `configure' from replacing `@datadir@' in the Sed expression itself. Brackets are preferable to a backslash here, since Posix says `\@' is not portable. `$(pkgdatadir)' Don't use `@pkgdatadir@'! Use the matching makefile variable instead. `/' Don't use `/' in the Sed expressions that replace file names since most likely the variables you use, such as `$(pkgdatadir)', contain `/'. Use a shell metacharacter instead, such as `|'. special characters File names, file name components, and the value of `VPATH' should not contain shell metacharacters or white space. *Note Special Chars in Variables::. dependency on `Makefile' Since `edit' uses values that depend on the configuration specific values (`prefix', etc.) and not only on `VERSION' and so forth, the output depends on `Makefile', not `configure.ac'. `$@' The main rule is generic, and uses `$@' extensively to avoid the need for multiple copies of the rule. Separated dependencies and single suffix rules You can't use them! The above snippet cannot be (portably) rewritten as: autoconf autoheader: Makefile .in: rm -f $@ $@.tmp $(edit) $< >$@.tmp chmod +x $@.tmp mv $@.tmp $@ *Note Single Suffix Rules::, for details. `$(srcdir)' Be sure to specify the name of the source directory, otherwise the package won't support separated builds. For the more specific installation of Erlang libraries, the following variables are defined: -- Variable: ERLANG_INSTALL_LIB_DIR The common parent directory of Erlang library installation directories. This variable is set by calling the `AC_ERLANG_SUBST_INSTALL_LIB_DIR' macro in `configure.ac'. -- Variable: ERLANG_INSTALL_LIB_DIR_LIBRARY The installation directory for Erlang library LIBRARY. This variable is set by calling the `AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(LIBRARY, VERSION' macro in `configure.ac'. *Note Erlang Libraries::, for details. 4.8.3 Changed Directory Variables --------------------------------- In Autoconf 2.60, the set of directory variables has changed, and the defaults of some variables have been adjusted (*note Installation Directory Variables::) to changes in the GNU Coding Standards. Notably, `datadir', `infodir', and `mandir' are now expressed in terms of `datarootdir'. If you are upgrading from an earlier Autoconf version, you may need to adjust your files to ensure that the directory variables are substituted correctly (*note Defining Directories::), and that a definition of `datarootdir' is in place. For example, in a `Makefile.in', adding datarootdir = @datarootdir@ is usually sufficient. If you use Automake to create `Makefile.in', it will add this for you. To help with the transition, Autoconf warns about files that seem to use `datarootdir' without defining it. In some cases, it then expands the value of `$datarootdir' in substitutions of the directory variables. The following example shows such a warning: $ cat configure.ac AC_INIT AC_CONFIG_FILES([Makefile]) AC_OUTPUT $ cat Makefile.in prefix = @prefix@ datadir = @datadir@ $ autoconf $ configure configure: creating ./config.status config.status: creating Makefile config.status: WARNING: Makefile.in seems to ignore the --datarootdir setting $ cat Makefile prefix = /usr/local datadir = ${prefix}/share Usually one can easily change the file to accommodate both older and newer Autoconf releases: $ cat Makefile.in prefix = @prefix@ datarootdir = @datarootdir@ datadir = @datadir@ $ configure configure: creating ./config.status config.status: creating Makefile $ cat Makefile prefix = /usr/local datarootdir = ${prefix}/share datadir = ${datarootdir} In some cases, however, the checks may not be able to detect that a suitable initialization of `datarootdir' is in place, or they may fail to detect that such an initialization is necessary in the output file. If, after auditing your package, there are still spurious `configure' warnings about `datarootdir', you may add the line AC_DEFUN([AC_DATAROOTDIR_CHECKED]) to your `configure.ac' to disable the warnings. This is an exception to the usual rule that you should not define a macro whose name begins with `AC_' (*note Macro Names::). 4.8.4 Build Directories ----------------------- You can support compiling a software package for several architectures simultaneously from the same copy of the source code. The object files for each architecture are kept in their own directory. To support doing this, `make' uses the `VPATH' variable to find the files that are in the source directory. GNU Make can do this. Most other recent `make' programs can do this as well, though they may have difficulties and it is often simpler to recommend GNU `make' (*note VPATH and Make::). Older `make' programs do not support `VPATH'; when using them, the source code must be in the same directory as the object files. If you are using GNU Automake, the remaining details in this section are already covered for you, based on the contents of your `Makefile.am'. But if you are using Autoconf in isolation, then supporting `VPATH' requires the following in your `Makefile.in': srcdir = @srcdir@ VPATH = @srcdir@ Do not set `VPATH' to the value of another variable, for example `VPATH = $(srcdir)', because some versions of `make' do not do variable substitutions on the value of `VPATH'. `configure' substitutes the correct value for `srcdir' when it produces `Makefile'. Do not use the `make' variable `$<', which expands to the file name of the file in the source directory (found with `VPATH'), except in implicit rules. (An implicit rule is one such as `.c.o', which tells how to create a `.o' file from a `.c' file.) Some versions of `make' do not set `$<' in explicit rules; they expand it to an empty value. Instead, Make command lines should always refer to source files by prefixing them with `$(srcdir)/'. For example: time.info: time.texinfo $(MAKEINFO) '$(srcdir)/time.texinfo' 4.8.5 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' are not 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 that `make' considers `config.h.in' up to date. Don't use `touch' (*note Limitations of Usual Tools::); instead, 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 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' ensures 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. 4.9 Configuration Header Files ============================== When a package contains more than a few tests that define 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. Though it can be called anywhere between `AC_INIT' and `AC_OUTPUT', it is customary to call it 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'). To provide for VPATH builds, remember to pass the C compiler a `-I.' option (or `-I..'; whichever directory contains `config.h'). Even if you use `#include "config.h"', the preprocessor searches only the directory of the currently read file, i.e., the source directory, not the build directory. With the appropriate `-I' option, you can use `#include '. Actually, it's a good habit to use it, because in the rare case when the source directory contains another `config.h', the build directory should be searched first. -- 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 blank-or-newline-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 making some changes in the 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. For example, you might need to make the input file name acceptable to DOS variants: AC_CONFIG_HEADERS([config.h:config.hin]) -- Macro: AH_HEADER This macro is defined as the name of the first declared config header and undefined if no config headers have been declared up to this point. A third-party macro may, for example, require use of a config header without invoking AC_CONFIG_HEADERS twice, like this: AC_CONFIG_COMMANDS_PRE( [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) *Note Configuration Actions::, for more details on HEADER. 4.9.1 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'. The `conf.h' created by `configure' defines `HAVE_UNISTD_H' to 1, if and only if the system has `unistd.h'. /* Define as 1 if you have unistd.h. */ #undef HAVE_UNISTD_H The format of the template file is stricter than what the C preprocessor is required to accept. A directive line should contain only whitespace, `#undef', and `HAVE_UNISTD_H'. The use of `#define' instead of `#undef', or of comments on the same line as `#undef', is strongly discouraged. Each hook should only be listed once. Other preprocessor lines, such as `#ifdef' or `#include', are copied verbatim from the template into the generated header. 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::. During the instantiation of the header, each `#undef' line in the template file for each symbol defined by `AC_DEFINE' is changed to an appropriate `#define'. If the corresponding `AC_DEFINE' has not been executed during the `configure' run, the `#undef' line is commented out. (This is important, e.g., for `_POSIX_SOURCE': on many systems, it can be implicitly defined by the compiler, and undefining it in the header would then break compilation of subsequent headers.) Currently, _all_ remaining `#undef' lines in the header template are commented out, whether or not there was a corresponding `AC_DEFINE' for the macro name; but this behavior is not guaranteed for future releases of Autoconf. Generally speaking, since you should not use `#define', and you cannot guarantee whether a `#undef' directive in the header template will be converted to a `#define' or commented out in the generated header file, the template file cannot be used for conditional definition effects. Consequently, if you need to use the construct #ifdef THIS # define THAT #endif you must place it outside of the template. If you absolutely need to hook it to the config header itself, please put the directives to a separate file, and `#include' that file from the config header template. If you are using `autoheader', you would probably use `AH_BOTTOM' to append the `#include' directive. 4.9.2 Using `autoheader' to Create `config.h.in' ------------------------------------------------ The `autoheader' program can create a template file of C `#define' statements for `configure' to use. It searches for the first invocation of `AC_CONFIG_HEADERS' in `configure' sources to determine the name of the template. (If the first call of `AC_CONFIG_HEADERS' specifies more than one input file name, `autoheader' uses the first one.) It is recommended that only one input file is used. If you want to append a boilerplate code, it is preferable to use `AH_BOTTOM([#include ])'. File `conf_post.h' is not processed during the configuration then, which make things clearer. Analogically, `AH_TOP' can be used to prepend a boilerplate code. In order to do its job, `autoheader' needs you to document all of the symbols that you might use. Typically this is done via an `AC_DEFINE' or `AC_DEFINE_UNQUOTED' call whose first argument is a literal symbol and whose third argument describes the symbol (*note Defining Symbols::). Alternatively, you can use `AH_TEMPLATE' (*note Autoheader Macros::), or you can supply a suitable input file for a subsequent configuration header file. Symbols defined by Autoconf's builtin tests are already documented properly; you need to document only 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 defined (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: the invocation of `autoheader'... 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' Append DIR to the include path. Multiple invocations accumulate. `--prepend-include=DIR' `-B DIR' Prepend DIR to the include path. Multiple invocations accumulate. `--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 4.9.3 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 template for a SYMBOL is created by `autoheader' from the DESCRIPTION argument to an `AC_DEFINE'; see *Note Defining Symbols::. For special needs, you can use the following macros. -- 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.]) generates 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_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 a symbol that can be defined via `AC_DEFINE'. -- 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. Please note that TEXT gets included "verbatim" to the template file, not to the resulting config header, so it can easily get mangled when the template is processed. There is rarely a need for something other than AH_BOTTOM([#include ]) 4.10 Running Arbitrary Configuration Commands ============================================= You can execute arbitrary commands 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 with TAG. Since typically the CMDS create a file, TAG should naturally be the name of that file. If needed, the directory hosting TAG is created. 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([timestamp], [date >timestamp]) The following two macros look similar, but in fact they are not of the same breed: they are executed directly by `configure', so you cannot use `config.status' to rerun them. -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS) Execute the CMDS right before creating `config.status'. This macro presents the last opportunity to call `AC_SUBST', `AC_DEFINE', or `AC_CONFIG_FOOS' macros. -- Macro: AC_CONFIG_COMMANDS_POST (CMDS) Execute the CMDS right after creating `config.status'. 4.11 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 a directory different from the source directory. -- 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 if possible, otherwise a copy. 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. 4.12 Configuring Other Packages in Subdirectories ================================================= In most situations, calling `AC_OUTPUT' is sufficient to produce makefiles 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 blank-or-newline-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'. Instead, 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 file systems. Likewise, if a DIR contains `configure.in' 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 name for the cache file; - adjusting a relative name for the source directory; - propagating the current value of `$prefix', including if it was defaulted, and if the default values of the top level and of the subdirectory `configure' differ. This macro also sets the output variable `subdirs' to the list of directories `DIR ...'. Make rules can use this variable to determine which subdirectories to recurse into. This macro may be called multiple times. 4.13 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 other than `/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, else default the prefix as described above (`/usr/local' or `AC_PREFIX_DEFAULT'). For example, if PROGRAM is `gcc' and the `PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'. 5 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 the C preprocessor symbol NAME to the value 1". *Note Defining Symbols::, for how to get those symbol definitions into your program. 5.1 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. 5.1.1 Standard Symbols ---------------------- All the generic macros that `AC_DEFINE' a symbol as a result of their test transform their ARGUMENT values 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*]) defines the symbol `HAVE_STRUCT__EXPENSIVEP' if the check succeeds. 5.1.2 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: #ifdef TIME_WITH_SYS_TIME # include # include #else # ifdef 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 use the following macro to provide the default set of includes: -- Macro: AC_INCLUDES_DEFAULT ([INCLUDE-DIRECTIVES]) Expand to INCLUDE-DIRECTIVES if defined, otherwise to: #include #ifdef HAVE_SYS_TYPES_H # include #endif #ifdef HAVE_SYS_STAT_H # include #endif #ifdef STDC_HEADERS # include # include #else # ifdef HAVE_STDLIB_H # include # endif #endif #ifdef HAVE_STRING_H # if !defined STDC_HEADERS && defined HAVE_MEMORY_H # include # endif # include #endif #ifdef HAVE_STRINGS_H # include #endif #ifdef HAVE_INTTYPES_H # include #endif #ifdef HAVE_STDINT_H # include #endif #ifdef HAVE_UNISTD_H # include #endif If the default includes are used, then check for the presence of these headers and their compatibility, i.e., you don't need to run `AC_HEADER_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' is defined, not `HAVE_STRINGS_H'. 5.2 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. 5.2.1 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_GREP Look for the best available `grep' or `ggrep' that accepts the longest input lines possible, and that supports multiple `-e' options. Set the output variable `GREP' to whatever is chosen. *Note Limitations of Usual Tools::, for more information about portability problems with the `grep' command family. -- Macro: AC_PROG_EGREP Check whether `$GREP -E' works, or else look for the best available `egrep' or `gegrep' that accepts the longest input lines possible. Set the output variable `EGREP' to whatever is chosen. -- Macro: AC_PROG_FGREP Check whether `$GREP -F' works, or else look for the best available `fgrep' or `gfgrep' that accepts the longest input lines possible. Set the output variable `FGREP' to whatever is chosen. -- Macro: AC_PROG_INSTALL Set output variable `INSTALL' to the name 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'. `@INSTALL@' is special, as its value may vary for different configuration files. 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. Further, this macro requires `install' to be able to install multiple files into a target directory in a single invocation. 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; otherwise `configure' produces 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_MKDIR_P Set output variable `MKDIR_P' to a program that ensures that for each argument, a directory named by this argument exists, creating it and its parent directories if needed, and without race conditions when two instances of the program attempt to make the same directory at nearly the same time. This macro uses the `mkdir -p' command if possible. Otherwise, it falls back on invoking `install-sh' with the `-d' option, so your package should contain `install-sh' as described under `AC_PROG_INSTALL'. An `install-sh' file that predates Autoconf 2.60 or Automake 1.10 is vulnerable to race conditions, so if you want to support parallel installs from different packages into the same directory you need to make sure you have an up-to-date `install-sh'. In particular, be careful about using `autoreconf -if' if your Automake predates Automake 1.10. This macro is related to the `AS_MKDIR_P' macro (*note Programming in M4sh::), but it sets an output variable intended for use in other files, whereas `AS_MKDIR_P' is intended for use in scripts like `configure'. Also, `AS_MKDIR_P' does not accept options, but `MKDIR_P' supports the `-m' option, e.g., a makefile might invoke `$(MKDIR_P) -m 0 dir' to create an inaccessible directory, and conversely a makefile should use `$(MKDIR_P) -- $(FOO)' if FOO might yield a value that begins with `-'. Finally, `AS_MKDIR_P' does not check for race condition vulnerability, whereas `AC_PROG_MKDIR_P' does. `@MKDIR_P@' is special, as its value may vary for different configuration 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' defaults to `char *' instead of to `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 causes an annoying but benign "`AC_PROG_LEX' invoked multiple times" warning. Future versions of Automake will fix this issue; meanwhile, just ignore this message. As part of running the test, this macro may delete any file in the configuration directory named `lex.yy.c' or `lexyy.c'. -- 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 in 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_SED Set output variable `SED' to a Sed implementation that conforms to Posix and does not have arbitrary length limits. Report an error if no acceptable Sed is found. *Note Limitations of Usual Tools::, for more information about portability problems with Sed. -- 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'. 5.2.2 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$PATH_SEPARATOR/usr/libexec$PATH_SEPARATOR]dnl [/usr/sbin$PATH_SEPARATOR/usr/etc$PATH_SEPARATOR/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 = `$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 = `$PATH']) Check for each program in the blank-separated list PROGS-TO-CHECK-FOR existing in the PATH. If one 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_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a prefix of the target type as determined by `AC_CANONICAL_TARGET', followed by a dash (*note Canonicalizing::). If the tool cannot be found with a prefix, and if the build and target types are equal, then it is also searched for without a prefix. As noted in *Note Specifying the system type: Specifying Names, the target is rarely specified, because most of the time it is the same as the host: it is the type of system for which any compiler tool in the package produces code. What this macro looks for is, for example, _a tool (assembler, linker, etc.) that the compiler driver (`gcc' for the GNU C Compiler) uses to produce objects, archives or executables_. -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a prefix of the host type as specified by `--host', followed by a dash. For example, if the user runs `configure --build=x86_64-gnu --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. When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see *Note Specifying the system type: Specifying Names. -- Macro: AC_CHECK_TARGET_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_TARGET_TOOL', each of the tools in the list PROGS-TO-CHECK-FOR are checked with a prefix of the target type as determined by `AC_CANONICAL_TARGET', followed by a dash (*note Canonicalizing::). If none of the tools can be found with a prefix, and if the build and target types are equal, 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_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$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. When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see *Note Specifying the system type: Specifying Names. -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_PROG', but set VARIABLE to the absolute name of PROG-TO-CHECK-FOR if found. -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, set VARIABLE to the absolute name of the program found. -- Macro: AC_PATH_PROGS_FEATURE_CHECK (VARIABLE, PROGS-TO-CHECK-FOR, FEATURE-TEST, [ACTION-IF-NOT-FOUND], [PATH = `$PATH']) This macro was introduced in Autoconf 2.62. If VARIABLE is not empty, then set the cache variable `$ac_cv_path_VARIABLE' to its value. Otherwise, check for each program in the blank-separated list PROGS-TO-CHECK-FOR existing in PATH. For each program found, execute FEATURE-TEST with `$ac_path_VARIABLE' set to the absolute name of the candidate program. If no invocation of FEATURE-TEST sets the shell variable `$ac_cv_path_VARIABLE', then ACTION-IF-NOT-FOUND is executed. FEATURE-TEST will be run even when `ac_cv_path_VARIABLE' is set, to provide the ability to choose a better candidate found later in PATH; to accept the current setting and bypass all futher checks, FEATURE-TEST can execute `ac_path_VARIABLE_found=:'. Note that this macro has some subtle differences from `AC_CHECK_PROGS'. It is designed to be run inside `AC_CACHE_VAL', therefore, it should have no side effects. In particular, VARIABLE is not set to the final value of `ac_cv_path_VARIABLE', nor is `AC_SUBST' automatically run. Also, on failure, any action can be performed, whereas `AC_CHECK_PROGS' only performs `VARIABLE=VALUE-IF-NOT-FOUND'. Here is an example, similar to what Autoconf uses in its own configure script. It will search for an implementation of `m4' that supports the `indir' builtin, even if it goes by the name `gm4' or is not the first implementation on `PATH'. AC_CACHE_CHECK([for m4 that supports indir], [ac_cv_path_M4], [AC_PATH_PROGS_FEATURE_CHECK([M4], [m4 gm4], [[m4out=`echo 'changequote([,])indir([divnum])' | $ac_path_M4` test "x$m4out" = x0 \ && ac_cv_path_M4=$ac_path_M4 ac_path_M4_found=:]], [AC_MSG_ERROR([could not find m4 that supports indir])])]) AC_SUBST([M4], [$ac_cv_path_M4]) -- Macro: AC_PATH_TARGET_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_TARGET_TOOL', but set VARIABLE to the absolute name of the program if it is found. -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, [VALUE-IF-NOT-FOUND], [PATH = `$PATH']) Like `AC_CHECK_TOOL', but set VARIABLE to the absolute name of the program if it is found. When cross-compiling, this macro will issue a warning if no program prefixed with the host type could be found. For more information, see *Note Specifying the system type: Specifying Names. 5.3 Files ========= You might also need to check for the existence of files. Before using these macros, ask yourself whether a runtime 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. 5.4 Library Files ================= The following macros check for the presence of certain C, C++, or Fortran library archive files. -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) Test whether the library LIBRARY is available by trying to link a test program that calls function FUNCTION with the library. FUNCTION should be a function provided by the library. Use 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 prepends `-lLIBRARY' to `LIBS' and defines `HAVE_LIBLIBRARY' (in all capitals). This macro is intended to support building `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. Linkers are 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 fails to detect that LIBRARY is present, because linking the test program always fails 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'. `AC_CHECK_LIB' requires some care in usage, and should be avoided in some common cases. Many standard functions like `gethostbyname' appear in the standard C library on some hosts, and in special libraries like `nsl' on other hosts. On some hosts the special libraries contain variant implementations that you may not want to use. These days it is normally better to use `AC_SEARCH_LIBS([gethostbyname], [nsl])' instead of `AC_CHECK_LIB([nsl], [gethostbyname])'. -- 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_LINK_IFELSE([AC_LANG_CALL([], [FUNCTION])])' 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 fails to detect that FUNCTION is present, because linking the test program always fails with unresolved symbols. 5.5 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. 5.5.1 Portability of C Functions -------------------------------- Most usual functions can either be missing, or be b