diff options
Diffstat (limited to 'util/autoconf/autoconf.info-1')
| -rw-r--r-- | util/autoconf/autoconf.info-1 | 1156 |
1 files changed, 0 insertions, 1156 deletions
diff --git a/util/autoconf/autoconf.info-1 b/util/autoconf/autoconf.info-1 deleted file mode 100644 index f49358c..0000000 --- a/util/autoconf/autoconf.info-1 +++ /dev/null @@ -1,1156 +0,0 @@ -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 <config.h>' 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'. - |