This is Info file autoconf.info, produced by Makeinfo-1.55 from the input file ./autoconf.texi. START-INFO-DIR-ENTRY * Autoconf: (autoconf). Create source code configuration scripts. END-INFO-DIR-ENTRY This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and an `m4' macro package. Copyright (C) 1992, 1993, 1994 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation.  File: autoconf.info, Node: Top, Next: Introduction, Up: (dir) This file documents the GNU Autoconf package for creating scripts to configure source code packages using templates and an `m4' macro package. This is edition 2.1, for Autoconf version 2.1. * Menu: * Introduction:: Autoconf's purpose, strengths, and weaknesses. * Making configure Scripts:: How to organize and produce Autoconf scripts. * Setup:: Initialization and output. * Existing Tests:: Macros that check for particular features. * Writing Tests:: How to write new feature checks. * Results:: What to do with results from feature checks. * Writing Macros:: Adding new macros to Autoconf. * Manual Configuration:: Selecting features that can't be guessed. * Site Configuration:: Local defaults for `configure'. * Invoking configure:: How to use the Autoconf output. * Invoking config.status:: Recreating a configuration. * Questions:: Questions about Autoconf, with answers. * Upgrading:: Tips for upgrading from version 1. * History:: History of Autoconf. * Old Macro Names:: Backward compatibility macros. * Environment Variable Index:: Index of environment variables used. * Output Variable Index:: Index of variables set in output files. * Preprocessor Symbol Index:: Index of C preprocessor symbols defined. * Macro Index:: Index of Autoconf macros. -- The Detailed Node Listing -- Making `configure' Scripts * Writing configure.in:: What to put in an Autoconf input file. * Invoking autoscan:: Semi-automatic `configure.in' writing. * Invoking ifnames:: Listing the conditionals in source code. * Invoking autoconf:: How to create configuration scripts. * Invoking autoreconf:: Remaking multiple `configure' scripts. Initialization and Output Files * Input:: Where Autoconf should find files. * Output:: Creating output files. * Makefile Substitutions:: Using output variables in `Makefile's. * Configuration Headers:: Creating a configuration header file. * Subdirectories:: Configuring independent packages together. * Default Prefix:: Changing the default installation prefix. * Versions:: Version numbers in `configure'. Substitutions in Makefiles * Preset Output Variables:: Output variables that are always set. * Build Directories:: Compiling in a different directory. * Automatic Remaking:: Makefile rules for configuring. Configuration Header Files * Header Templates:: Input for the configuration headers. * Invoking autoheader:: How to create configuration templates. Existing Tests * Alternative Programs:: Selecting between alternative programs. * Libraries:: Library archives that might be missing. * Library Functions:: C library functions that might be missing. * Header Files:: Header files that might be missing. * Structures:: Structures or members that might be missing. * Typedefs:: `typedef's that might be missing. * Compiler Characteristics:: C compiler or machine architecture features. * System Services:: Operating system services. * UNIX Variants:: Special kludges for specific UNIX variants. Alternative Programs * Particular Programs:: Special handling to find certain programs. * Generic Programs:: How to find other programs. Library Functions * Particular Functions:: Special handling to find certain functions. * Generic Functions:: How to find other functions. Header Files * Particular Headers:: Special handling to find certain headers. * Generic Headers:: How to find other headers. Typedefs * Particular Typedefs:: Special handling to find certain types. * Generic Typedefs:: How to find other types. Writing Tests * Examining Declarations:: Detecting header files and declarations. * Examining Syntax:: Detecting language syntax features. * Examining Libraries:: Detecting functions and global variables. * Run Time:: Testing for run-time features. * Portable Shell:: Shell script portability pitfalls. * Testing Values and Files:: Checking strings and files. * Multiple Cases:: Tests for several possible values. * Language Choice:: Selecting which language to use for testing. Checking Run Time Behavior * Test Programs:: Running test programs. * Guidelines:: General rules for writing test programs. * Test Functions:: Avoiding pitfalls in test programs. Results of Tests * Defining Symbols:: Defining C preprocessor symbols. * Setting Output Variables:: Replacing variables in output files. * Caching Results:: Speeding up subsequent `configure' runs. * Printing Messages:: Notifying users of progress or problems. Caching Results * Cache Variable Names:: Shell variables used in caches. * Cache Files:: Files `configure' uses for caching. Writing Macros * Macro Definitions:: Basic format of an Autoconf macro. * Macro Names:: What to call your new macros. * Quoting:: Protecting macros from unwanted expansion. * Dependencies Between Macros:: What to do when macros depend on other macros. Dependencies Between Macros * Prerequisite Macros:: Ensuring required information. * Suggested Ordering:: Warning about possible ordering problems. * Obsolete Macros:: Warning about old ways of doing things. Manual Configuration * Specifying Names:: Specifying the system type. * Canonicalizing:: Getting the canonical system type. * System Type Variables:: Variables containing the system type. * Using System Type:: What to do with the system type. Site Configuration * External Software:: Working with other optional software. * Package Options:: Selecting optional features. * Site Details:: Configuring site details. * Transforming Names:: Changing program names when installing. * Site Defaults:: Giving `configure' local defaults. Transforming Program Names When Installing * Transformation Options:: `configure' options to transforme names. * Transformation Examples:: Sample uses of transforming names. * Transformation Rules:: `Makefile' uses of transforming names. Running `configure' Scripts * Basic Installation:: Instructions for typical cases. * Compilers and Options:: Selecting compilers and optimization. * Build Directory:: Configuring in a different directory. * Installation Names:: Installing in different directories. * Optional Features:: Selecting optional features. * System Type:: Specifying the system type. * Sharing Defaults:: Setting site-wide defaults for `configure'. * Operation Controls:: Changing how `configure' runs. Questions About Autoconf * Distributing:: Distributing `configure' scripts. * Why GNU m4:: Why not use the standard `m4'? * Bootstrapping:: Autoconf and GNU `m4' require each other? * Why Not Imake:: Why GNU uses `configure' instead of Imake. Upgrading From Version 1 * Changed File Names:: Files you might rename. * Changed Makefiles:: New things to put in `Makefile.in'. * Changed Macros:: Macro calls you might replace. * Invoking autoupdate:: Replacing old macro names in `configure.in'. * Changed Results:: Changes in how to check test results. * Changed Macro Writing:: Better ways to write your own macros. History of Autoconf * Genesis:: Prehistory and naming of `configure'. * Exodus:: The plagues of `m4' and Perl. * Leviticus:: The priestly code of portability arrives. * Numbers:: Growth and contributors. * Deuteronomy:: Approaching the promises of easy configuration.  File: autoconf.info, Node: Introduction, Next: Making configure Scripts, Prev: Top, Up: Top 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 electro-magnetic waves, the relativist consequences... An Engineer!, said the engineer, because before making Light, God split the Chaos into Land and Water; it takes a hell of an engineer to handle that big amount of mud, and orderly separation of solids from liquids... The computer scientist shouted: And the Chaos, where do you think it was coming from, hmm? ---Anonymous Autoconf is a tool for producing shell scripts that automatically configure software source code packages to adapt to many kinds of UNIX-like systems. The configuration scripts produced by Autoconf are independent of Autoconf when they are run, so their users do not need to have Autoconf. The configuration scripts produced by Autoconf require no manual user intervention when run; they do not normally even need an argument specifying the system type. Instead, they test for the presence of each feature that the software package they are for might need individually. (Before each check, they print a one-line message stating what they are checking for, so the user doesn't get too bored while waiting for the script to finish.) As a result, they deal well with systems that are hybrids or customized from the more common UNIX variants. There is no need to maintain files that list the features supported by each release of each variant of UNIX. For each software package that Autoconf is used with, it creates a configuration script from a template file that lists the system features that the package needs or can use. After the shell code to recognize and respond to a system feature has been written, Autoconf allows it to be shared by many software packages that can use (or need) that feature. If it later turns out that the shell code needs adjustment for some reason, it needs to be changed in only one place; all of the configuration scripts can be regenerated automatically to take advantage of the updated code. The Metaconfig package is similar in purpose to Autoconf, but the scripts it produces require manual user intervention, which is quite inconvenient when configuring large source trees. Unlike Metaconfig scripts, Autoconf scripts can support cross-compiling, if some care is taken in writing them. There are several jobs related to making portable software packages that Autoconf currently does not do. Among these are automatically creating `Makefile' files with all of the standard targets, and supplying replacements for standard library functions and header files on systems that lack them. Work is in progress to add those features in the future. Autoconf imposes some restrictions on the names of macros used with `#ifdef' in C programs (*note Preprocessor Symbol Index::.). Autoconf requires GNU `m4' in order to generate the scripts. It uses features that some UNIX versions of `m4' do not have. It also overflows internal limits of some versions of `m4', including GNU `m4' 1.0. You must use version 1.1 or later of GNU `m4'. Using version 1.3 or later will be much faster than 1.1 or 1.2. *Note Upgrading::, for information about upgrading from version 1. *Note History::, for the story of Autoconf's development. *Note Questions::, for answers to some common questions about Autoconf. Mail suggestions and bug reports for Autoconf to `bug-gnu-utils@prep.ai.mit.edu'. Please include the Autoconf version number, which you can get by running `autoconf --version'.  File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: Introduction, Up: Top Making `configure' Scripts ************************** The configuration scripts that Autoconf produces are by convention called `configure'. When run, `configure' creates several files, replacing configuration parameters in them with appropriate values. The files that `configure' creates are: * one or more `Makefile' files, one in each subdirectory of the package (*note Makefile Substitutions::.); * optionally, a C header file, the name of which is configurable, containing `#define' directives (*note Configuration Headers::.); * a shell script called `config.status' that, when run, will recreate the files listed above (*note Invoking config.status::.); * a shell script called `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.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 write `acconfig.h', and you will distribute the Autoconf-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.in configure.in --. .------> autoconf* -----> configure +---+ [aclocal.m4] --+ `---. [acsite.m4] ---' | +--> [autoheader*] -> [config.h.in] [acconfig.h] ----. | +-----' [config.h.top] --+ [config.h.bot] --' 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 ---' * Menu: * Writing configure.in:: What to put in an Autoconf input file. * Invoking autoscan:: Semi-automatic `configure.in' writing. * Invoking ifnames:: Listing the conditionals in source code. * Invoking autoconf:: How to create configuration scripts. * Invoking autoreconf:: Remaking multiple `configure' scripts.  File: autoconf.info, Node: Writing configure.in, Next: Invoking autoscan, Up: Making configure Scripts Writing `configure.in' ====================== To produce a `configure' script for a software package, create a file called `configure.in' 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.in' might need to contain some hand-crafted shell commands. The `autoscan' program can give you a good start in writing `configure.in' (*note Invoking autoscan::., for more information). The order in which `configure.in' calls the Autoconf macros is not important, with a few exceptions. Every `configure.in' 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 creating `configure' 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 could depend on things earlier in it. For example, library functions could be affected by typedefs and libraries. `AC_INIT(FILE)' checks for programs checks for libraries checks for header files checks for typedefs checks for structures checks for compiler characteristics checks for library functions checks for system services `AC_OUTPUT([FILE...])' It is best to put each macro call on its own line in `configure.in'. 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. When calling macros that take arguments, there must not be any blank space between the macro name and the open parenthesis. Arguments can be more than one line long if they are enclosed within the `m4' quote characters `[' and `]'. If you have a long line such as a list of file names, you can generally use a backslash at the end of a line to continue it logically on the next line (this is implemented by the shell, not by anything special that Autoconf does). Some macros handle two cases: what to do if the given condition is met, and what to do if the condition is not met. In some places you might want to do something if a condition is true but do nothing if it's false, or vice versa. To omit the true case, pass an empty value for the ACTION-IF-FOUND argument to the macro. To omit the false case, omit the ACTION-IF-NOT-FOUND argument to the macro, including the comma before it. You can include comments in `configure.in' files by starting them with the `m4' builtin macro `dnl', which discards text up through the next newline. These comments do not appear in the generated `configure' scripts. For example, it is helpful to begin `configure.in' files with a line like this: dnl Process this file with autoconf to produce a configure script.  File: autoconf.info, Node: Invoking autoscan, Next: Invoking ifnames, Prev: Writing configure.in, Up: Making configure Scripts Using `autoscan' to Create `configure.in' ========================================= The `autoscan' program can help you create a `configure.in' 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.in' for that package. You should manually examine `configure.scan' before renaming it to `configure.in'; it will probably need some adjustments. Occasionally `autoscan' outputs a macro in the wrong order relative to another macro, so that `autoconf' produces a warning; you need to move such macros manually. Also, if you want the package to use a configuration header file, you must add a call to `AC_CONFIG_HEADER' (*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 Invoking ifnames::., for information about a program that can help with that job). `autoscan' uses several data files, which are installed along with the distributed Autoconf macro files, to determine which macros to output when it finds particular symbols in a package's source files. These files all have the same format. Each line consists of a symbol, whitespace, and the Autoconf macro to output if that symbol is encountered. Lines starting with `#' are comments. `autoscan' is only installed if you already have Perl installed. `autoscan' accepts the following options: `--help' Print a summary of the command line options and exit. `--macrodir=DIR' Look for the data files in directory DIR instead of the default installation directory. You can also set the `AC_MACRODIR' environment variable to a directory; this option overrides the environment variable. `--verbose' Print the names of the files it examines and the potentially interesting symbols it finds in them. This output can be voluminous. `--version' Print the version number of Autoconf and exit.  File: autoconf.info, Node: Invoking ifnames, Next: Invoking autoconf, Prev: Invoking autoscan, Up: Making configure Scripts Using `ifnames' to List Conditionals ==================================== `ifnames' can help when writing a `configure.in' 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, this program can help you figure out what its `configure' needs to check for. It may help fill in some gaps in a `configure.in' generated by `autoscan' (*note Invoking autoscan::.). `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. `--macrodir=DIR' `-m DIR' Look for the Autoconf macro files in directory DIR instead of the default installation directory. Only used to get the version number. You can also set the `AC_MACRODIR' environment variable to a directory; this option overrides the environment variable. `--version' Print the version number of Autoconf and exit.  File: autoconf.info, Node: Invoking autoconf, Next: Invoking autoreconf, Prev: Invoking ifnames, Up: Making configure Scripts Using `autoconf' to Create `configure' ====================================== To create `configure' from `configure.in', run the `autoconf' program with no arguments. `autoconf' processes `configure.in' with the `m4' macro processor, using the Autoconf macros. If you give `autoconf' an argument, it reads that file instead of `configure.in' and writes the configuration script to the standard output instead of to `configure'. If you give `autoconf' the argument `-', it reads the standard input instead of `configure.in' and writes the configuration script on 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 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. `--localdir=DIR' `-l DIR' Look for the package file `aclocal.m4' in directory DIR instead of in the current directory. `--macrodir=DIR' `-m DIR' Look for the installed macro files in directory DIR. You can also set the `AC_MACRODIR' environment variable to a directory; this option overrides the environment variable. `--version' Print the version number of Autoconf and exit.  File: autoconf.info, Node: Invoking autoreconf, Prev: Invoking autoconf, Up: Making configure Scripts Using `autoreconf' to Update `configure' Scripts ================================================ If you have a lot of Autoconf-generated `configure' scripts, the `autoreconf' program can save you some work. It runs `autoconf' (and `autoheader', where appropriate) repeatedly to remake the Autoconf `configure' scripts and configuration header templates in the directory tree rooted at the current directory. By default, it only remakes those files that are older than their `configure.in' or (if present) `aclocal.m4'. Since `autoheader' does not change the timestamp of its output file if the file wouldn't be changing, this is not necessarily the minimum amount of work. If you install a new version of Autoconf, you can make `autoreconf' remake *all* of the files by giving it the `--force' option. If you give `autoreconf' the `--macrodir=DIR' or `--localdir=DIR' options, it passes them down to `autoconf' and `autoheader' (with relative paths adjusted properly). *Note Automatic Remaking::, for `Makefile' rules to automatically remake `configure' scripts when their source files change. That method handles the timestamps of configuration header templates properly, but does not pass `--macrodir=DIR' or `--localdir=DIR'. `autoreconf' accepts the following options: `--help' `-h' Print a summary of the command line options and exit. `--force' `-f' Remake even `configure' scripts and configuration headers that are newer than their input files (`configure.in' and, if present, `aclocal.m4'). `--localdir=DIR' `-l DIR' Look for the package files `aclocal.m4' and `acconfig.h' (but not `FILE.top' and `FILE.bot') in directory DIR instead of in the directory containing each `configure.in'. `--macrodir=DIR' `-m DIR' Look for the Autoconf macro files in directory DIR instead of the default installation directory. You can also set the `AC_MACRODIR' environment variable to a directory; this option overrides the environment variable. `--verbose' Print the name of each directory where `autoreconf' runs `autoconf' (and `autoheader', if appropriate). `--version' Print the version number of Autoconf and exit.  File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top Initialization and Output Files ******************************* Autoconf-generated `configure' scripts need some information about how to initialize, such as how to find the package's source files; and about the output files to produce. The following sections describe initialization and creating output files. * Menu: * Input:: Where Autoconf should find files. * Output:: Creating output files. * Makefile Substitutions:: Using output variables in `Makefile's. * Configuration Headers:: Creating a configuration header file. * Subdirectories:: Configuring independent packages together. * Default Prefix:: Changing the default installation prefix. * Versions:: Version numbers in `configure'.  File: autoconf.info, Node: Input, Next: Output, Up: Setup Finding `configure' Input ========================= Every `configure' script must call `AC_INIT' before doing anything else. The only other required macro is `AC_OUTPUT' (*note Output::.). - Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) Process any command-line arguments and find the source code directory. 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 (*note Invoking configure::., 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 `install-sh', `config.sub', `config.guess', and Cygnus `configure' scripts 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' programs have a rule that creates `install' from it if there is no `Makefile'.  File: autoconf.info, Node: Output, Next: Makefile Substitutions, Prev: Input, Up: Setup Creating Output Files ===================== Every Autoconf-generated `configure' script must finish by calling `AC_OUTPUT'. It is the macro that creates the `Makefile's and optional other files resulting from configuration. The only other required macro is `AC_INIT' (*note Input::.). - Macro: AC_OUTPUT ([FILE...] [,EXTRA-CMDS] [,INIT-CMDS]) Create output files. The FILE... argument is a whitespace-separated list of output files; it may be empty. This macro creates each file `FILE' by copying an input file (by default named `FILE.in'), substituting the output variable values. *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 (but not the parents of that directory). Usually, `Makefile's are created this way, but other files, such as `.gdbinit', can be specified as well. If `AC_CONFIG_HEADER', `AC_LINK_FILES', or `AC_CONFIG_SUBDIRS' has been called, this macro also creates the files named as their arguments. A typical call to `AC_OUTPUT' looks like this: AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile) You can override an input file name by appending it to FILE, separated by a colon. For example, AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk) If you pass EXTRA-CMDS, those commands will be inserted into `config.status' to be run after all its other processing. If INIT-CMDS are given, they are inserted just before EXTRA-CMDS, with shell variable, command, and backslash substitutions performed on them in `configure'. You can use INIT-CMDS to pass variables from `configure' to the EXTRA-CMDS. If you run `make' on subdirectories, you should run it using the `make' variable `MAKE'. Most versions of `make' set `MAKE' to the name of the `make' program plus any options it was given. (But many do not include in it the values of any variables set on the command line, so those are not passed on automatically.) Some old versions of `make' do not set this variable. The following macro allows you to use it even with those versions. - Macro: AC_PROG_MAKE_SET If `make' predefines the variable `MAKE', define output variable `SET_MAKE' to be empty. Otherwise, define `SET_MAKE' to contain `MAKE=make'. Calls `AC_SUBST' for `SET_MAKE'. To use this macro, place a line like this in each `Makefile.in' that runs `MAKE' on other directories: @SET_MAKE@  File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Output, Up: Setup Substitutions in Makefiles ========================== Each subdirectory in a distribution that contains something to be compiled or installed should come with a file `Makefile.in', from which `configure' will create a `Makefile' in that directory. To create a `Makefile', `configure' performs a simple variable substitution, replacing occurrences of `@VARIABLE@' in `Makefile.in' with the value that `configure' has determined for that variable. Variables that are substituted into output files in this way are called "output variables". They are ordinary shell variables that are set in `configure'. To make `configure' substitute a particular variable into the output files, the macro `AC_SUBST' must be called with that variable name as an argument. Any occurrences of `@VARIABLE@' for other variables are left unchanged. *Note Setting Output Variables::, for more information on creating output variables with `AC_SUBST'. A software package that uses a `configure' script should be distributed with a file `Makefile.in', but no `Makefile'; that way, the user has to properly configure the package for the local system before compiling it. *Note Makefile Conventions: (standards.info)Makefile Conventions, for more information on what to put in `Makefile's. * Menu: * Preset Output Variables:: Output variables that are always set. * Build Directories:: Compiling in a different directory. * Automatic Remaking:: Makefile rules for configuring.  File: autoconf.info, Node: Preset Output Variables, Next: Build Directories, Up: Makefile Substitutions 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. Here is what each of the preset ones contains. - 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: exec_prefix The installation prefix for architecture-dependent files. - Variable: prefix The installation prefix for architecture-independent files. - Variable: srcdir The directory that contains the source code for that `Makefile'. - Variable: top_srcdir The top-level source code directory for the package. In the top-level directory, this is the same as `srcdir'. - Variable: CFLAGS Debugging and optimization options for the C compiler. If it is not set in the environment when `configure' runs, the default value is set when you call `AC_PROG_CC' (or empty if you don't). `configure' uses this variable when compiling programs to test for C features. - Variable: CPPFLAGS Header file search directory (`-IDIR') and any other miscellaneous options for the C preprocessor and compiler. If it is not set in the environment when `configure' runs, the default value is empty. `configure' uses this variable when compiling or preprocessing programs to test for C features. - Variable: CXXFLAGS Debugging and optimization options for the C++ compiler. If it is not set in the environment when `configure' runs, the default value is set when you call `AC_PROG_CXX' (or empty if you don't). `configure' uses this variable when compiling programs to test for C++ features. - Variable: DEFS `-D' options to pass to the C compiler. If `AC_CONFIG_HEADER' 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: LDFLAGS Stripping (`-s') and any other miscellaneous 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 features. - Variable: LIBS `-l' and `-L' options to pass to the linker.  File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Preset Output Variables, Up: Makefile Substitutions Build Directories ----------------- You might want to compile a software package in a different directory from the one that contains the source code. Doing this allows you to compile the package for several architectures simultaneously from the same copy of the source code and keep multiple sets of object files on disk. To support doing this, `make' uses the `VPATH' variable to find the files that are in the source directory. GNU `make' and most other recent `make' programs can do this. Older `make' programs do not support `VPATH'; when using them, the source code must be in the same directory as the object files. To support `VPATH', each `Makefile.in' should contain two lines that look like: srcdir = @srcdir@ VPATH = @srcdir@ Do not set `VPATH' to the value of another variable, for example `VPATH = $(srcdir)', because some versions of `make' do not do variable substitutions on the value of `VPATH'. `configure' substitutes in the correct value for `srcdir' when it produces `Makefile.in'. Do not use the `make' variable `$<', which expands to the pathname of the file in the source directory (found with `VPATH'), except in implicit rules. (An implicit rule is one such as `.c.o', which tells how to create a `.o' file from a `.c' file.) Some versions of `make' do not set `$<' in explicit rules; they expand it to an empty value. Instead, `Makefile' command lines should always refer to source files by prefixing them with `$(srcdir)/'. For example: time.info: time.texinfo $(MAKEINFO) $(srcdir)/time.texinfo  File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions 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 any of these files that your package does not use. The `${srcdir}/' prefix is included because of limitations in the `VPATH' mechanism. The `stamp-' files are necessary because the timestamps of `config.h.in' and `config.h' will not be changed if remaking them does not change their contents. This feature avoids unnecessary recompilation. You should include the file `stamp-h.in' your package's distribution, so `make' will consider `config.h.in' up to date. On some old BSD systems, `touch' or any command that results in an empty file does not update the timestamps, so use a command like `date' as a workaround. ${srcdir}/configure: configure.in 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.in aclocal.m4 acconfig.h \ config.h.top config.h.bot cd ${srcdir} && autoheader date > ${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 In addition, you should pass `date > stamp-h' in the EXTRA-CMDS argument to `AC_OUTPUT', so `config.status' will ensure that `config.h' is considered up to date. *Note Output::, for more information about `AC_OUTPUT'. *Note Invoking config.status::, for more examples of handling configuration-related dependencies.  File: autoconf.info, Node: Configuration Headers, Next: Subdirectories, Prev: Makefile Substitutions, Up: Setup Configuration Header Files ========================== When a package tests more than a few C preprocessor symbols, the command lines to pass `-D' options to the compiler can get quite long. This causes two problems. One is that the `make' output is hard to visually scan for errors. More seriously, the command lines can exceed the length limits of some operating systems. As an alternative to passing `-D' options to the compiler, `configure' scripts can create a C header file containing `#define' directives. The `AC_CONFIG_HEADER' macro selects this kind of output. It should be called right after `AC_INIT'. The package should `#include' the configuration header file before any other header files, to prevent inconsistencies in declarations (for example, if it redefines `const'). Use `#include ' instead of `#include "config.h"', and pass the C compiler a `-I.' option (or `-I..'; whichever directory contains `config.h'). That way, even if the source directory is configured itself (perhaps to make a distribution), other build directories can also be configured without finding the `config.h' from the source directory. - Macro: AC_CONFIG_HEADER (HEADER-TO-CREATE ...) Make `AC_OUTPUT' create the file(s) in the whitespace-separated list HEADER-TO-CREATE 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-TO-CREATE is `config.h'. If HEADER-TO-CREATE already exists and its contents are identical to what `AC_OUTPUT' would put in it, it is left alone. Doing this allows some changes in configuration without needlessly causing object files that depend on the header file to be recompiled. Usually the input file is named `HEADER-TO-CREATE.in'; however, you can override the input file name by appending it to HEADER-TO-CREATE, separated by a colon. For example, AC_CONFIG_HEADER(defines.h:defines.hin) Doing this allows you to keep your filenames acceptable to MS-DOS. * Menu: * Header Templates:: Input for the configuration headers. * Invoking autoheader:: How to create configuration templates.  File: autoconf.info, Node: Header Templates, Next: Invoking autoheader, Up: Configuration Headers Configuration Header Templates ------------------------------ Your distribution should contain a template file that looks as you want the final header file to look, including comments, with default values in the `#define' statements. For example, suppose your `configure.in' makes these calls: AC_CONFIG_HEADER(conf.h) AC_CHECK_HEADERS(unistd.h) Then you could have code like the following in `conf.h.in'. On systems that have `unistd.h', `configure' will change the 0 to a 1. On other systems, it will leave the line unchanged. /* Define as 1 if you have unistd.h. */ #define HAVE_UNISTD_H 0 Alternately, if your code tests for configuration options using `#ifdef' instead of `#if', a default value can be to `#undef' the variable instead of to define it to a value. On systems that have `unistd.h', `configure' will change the second line to read `#define HAVE_UNISTD_H 1'. On other systems, it will comment that line out (in case the system predefines that symbol). /* Define if you have unistd.h. */ #undef HAVE_UNISTD_H  File: autoconf.info, Node: Invoking autoheader, Prev: Header Templates, Up: Configuration Headers Using `autoheader' to Create `config.h.in' ------------------------------------------ The `autoheader' program can create a template file of C `#define' statements for `configure' to use. If `configure.in' invokes `AC_CONFIG_HEADER(FILE)', `autoheader' creates `FILE.in'. Otherwise, `autoheader' creates `config.h.in'. If you give `autoheader' an argument, it uses that file instead of `configure.in' 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.in' and writes the header file to the standard output. `autoheader' scans `configure.in' and figures out which C preprocessor symbols it might define. It copies comments and `#define' and `#undef' statements from a file called `acconfig.h', which comes with and is installed with Autoconf. It also uses a file called `acconfig.h' in the current directory, if present. If you `AC_DEFINE' any additional symbols, you must create that file with entries for them. For symbols defined by `AC_CHECK_HEADERS', `AC_CHECK_FUNCS', `AC_CHECK_SIZEOF', or `AC_CHECK_LIB', `autoheader' generates comments and `#undef' statements itself rather than copying them from a file, since the possible symbols are effectively limitless. The file that `autoheader' creates contains mainly `#define' and `#undef' statements and their accompanying comments. If `./acconfig.h' contains the string `@TOP@', `autoheader' copies the lines before the line containing `@TOP@' into the top of the file that it generates. Similarly, if `./acconfig.h' contains the string `@BOTTOM@', `autoheader' copies the lines after that line to the end of the file it generates. Either or both of those strings may be omitted. An alternate way to produce the same effect is to create the files `FILE.top' (typically `config.h.top') and/or `FILE.bot' in the current directory. If they exist, `autoheader' copies them to the beginning and end, respectively, of its output. Their use is discouraged because they have file names that contain two periods, and so can not be stored on MS-DOS; also, they are two more files to clutter up the directory. But if you use the `--localdir=DIR' option to use an `acconfig.h' in another directory, they give you a way to put custom boilerplate in each individual `config.h.in'. `autoheader' accepts the following options: `--help' `-h' Print a summary of the command line options and exit. `--localdir=DIR' `-l DIR' Look for the package files `aclocal.m4' and `acconfig.h' (but not `FILE.top' and `FILE.bot') in directory DIR instead of in the current directory. `--macrodir=DIR' `-m DIR' Look for the installed macro files and `acconfig.h' in directory DIR. You can also set the `AC_MACRODIR' environment variable to a directory; this option overrides the environment variable. `--version' Print the version number of Autoconf and exit.  File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Headers, Up: Setup Configuring Other Packages in Subdirectories ============================================ In most situations, calling `AC_OUTPUT' is sufficient to produce `Makefile's in subdirectories. However, `configure' scripts that control more than one independent package can use `AC_CONFIG_SUBDIRS' to run `configure' scripts for other packages in subdirectories. - Macro: AC_CONFIG_SUBDIRS (DIR ...) Make `AC_OUTPUT' run `configure' in each subdirectory DIR in the given whitespace-separated list. If a given DIR is not found, no error is reported, so a `configure' script can configure whichever parts of a large source tree are present. If a given DIR contains `configure.in' but no `configure', the Cygnus `configure' script found by `AC_CONFIG_AUXDIR' 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 (e.g., to adjust a relative path for the cache file or source directory). This macro also sets the output variable `subdirs' to the list of directories `DIR ...'. `Makefile' rules can use this variable to determine which subdirectories to recurse into.  File: autoconf.info, Node: Default Prefix, Next: Versions, Prev: Subdirectories, Up: Setup Default Prefix ============== By default, `configure' sets the prefix for files it installs to `/usr/local'. The user of `configure' can select a different prefix using the `--prefix' and `--exec-prefix' options. There are two ways to change the default: when creating `configure', and when running it. Some software packages might want to install in a directory besides `/usr/local' by default. To accomplish that, use the `AC_PREFIX_DEFAULT' macro. - Macro: AC_PREFIX_DEFAULT (PREFIX) Set the default installation prefix to PREFIX instead of `/usr/local'. It may be convenient for users to have `configure' guess the installation prefix from the location of a related program that they have already installed. If you wish to do that, you can call `AC_PREFIX_PROGRAM'. - Macro: AC_PREFIX_PROGRAM (PROGRAM) If the user did not specify an installation prefix (using the `--prefix' option), guess a value for it by looking for PROGRAM in `PATH', the way the shell does. If PROGRAM is found, set the prefix to the parent of the directory containing PROGRAM; otherwise leave the prefix specified in `Makefile.in' unchanged. For example, if PROGRAM is `gcc' and the `PATH' contains `/usr/local/gnu/bin/gcc', set the prefix to `/usr/local/gnu'.