diff options
Diffstat (limited to 'util/autoconf/autoconf.texi')
| -rw-r--r-- | util/autoconf/autoconf.texi | 5125 |
1 files changed, 0 insertions, 5125 deletions
diff --git a/util/autoconf/autoconf.texi b/util/autoconf/autoconf.texi deleted file mode 100644 index 3ec9655..0000000 --- a/util/autoconf/autoconf.texi +++ /dev/null @@ -1,5125 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@setfilename autoconf.info -@settitle Autoconf -@c For double-sided printing, uncomment: -@c @setchapternewpage odd -@c %**end of header - -@set EDITION 2.1 -@set VERSION 2.1 -@set UPDATED November 1994 - -@iftex -@finalout -@end iftex - -@ifinfo -@format -START-INFO-DIR-ENTRY -* Autoconf: (autoconf). Create source code configuration scripts. -END-INFO-DIR-ENTRY -@end format - -This file documents the GNU Autoconf package for creating scripts to -configure source code packages using templates and an @code{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. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission -notice identical to this one except for the removal of this paragraph -(this paragraph not being relevant to the printed manual). - -@end ignore -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. -@end ifinfo - -@titlepage -@title Autoconf -@subtitle Creating Automatic Configuration Scripts -@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION} -@subtitle @value{UPDATED} -@author by David MacKenzie -@c I think I've rewritten all of Noah and Roland's contributions by now. - -@page -@vskip 0pt plus 1filll -Copyright @copyright{} 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. -@end titlepage - -@c Define an environment variable index. -@defcodeindex ev -@c Define an output variable index. -@defcodeindex ov -@c Define a CPP variable index. -@defcodeindex cv -@c Define a macro index that @@defmac doesn't write to. -@defcodeindex ma - -@node Top, Introduction, , (dir) -@comment node-name, next, previous, up - -@ifinfo -This file documents the GNU Autoconf package for creating scripts to -configure source code packages using templates and an @code{m4} macro -package. This is edition @value{EDITION}, for Autoconf version @value{VERSION}. - -@end ifinfo - -@c The master menu, created with texinfo-master-menu, goes here. - -@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 @code{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 @code{configure} Scripts - -* Writing configure.in:: What to put in an Autoconf input file. -* Invoking autoscan:: Semi-automatic @file{configure.in} writing. -* Invoking ifnames:: Listing the conditionals in source code. -* Invoking autoconf:: How to create configuration scripts. -* Invoking autoreconf:: Remaking multiple @code{configure} scripts. - -Initialization and Output Files - -* Input:: Where Autoconf should find files. -* Output:: Creating output files. -* Makefile Substitutions:: Using output variables in @file{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 @code{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:: @code{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 @code{configure} runs. -* Printing Messages:: Notifying users of progress or problems. - -Caching Results - -* Cache Variable Names:: Shell variables used in caches. -* Cache Files:: Files @code{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 @code{configure} local defaults. - -Transforming Program Names When Installing - -* Transformation Options:: @code{configure} options to transforme names. -* Transformation Examples:: Sample uses of transforming names. -* Transformation Rules:: @file{Makefile} uses of transforming names. - -Running @code{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 @code{configure}. -* Operation Controls:: Changing how @code{configure} runs. - -Questions About Autoconf - -* Distributing:: Distributing @code{configure} scripts. -* Why GNU m4:: Why not use the standard @code{m4}? -* Bootstrapping:: Autoconf and GNU @code{m4} require each other? -* Why Not Imake:: Why GNU uses @code{configure} instead of Imake. - -Upgrading From Version 1 - -* Changed File Names:: Files you might rename. -* Changed Makefiles:: New things to put in @file{Makefile.in}. -* Changed Macros:: Macro calls you might replace. -* Invoking autoupdate:: Replacing old macro names in @code{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 @code{configure}. -* Exodus:: The plagues of @code{m4} and Perl. -* Leviticus:: The priestly code of portability arrives. -* Numbers:: Growth and contributors. -* Deuteronomy:: Approaching the promises of easy configuration. -@end menu - -@node Introduction, Making configure Scripts, Top, Top -@chapter Introduction - -@display -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@dots{} 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@dots{} The computer scientist shouted: And the Chaos, -where do you think it was coming from, hmm? - ----Anonymous -@end display -@c (via Franc,ois Pinard) - -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 @file{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 -@code{#ifdef} in C programs (@pxref{Preprocessor Symbol Index}). - -Autoconf requires GNU @code{m4} in order to generate the scripts. It -uses features that some UNIX versions of @code{m4} do not have. It also -overflows internal limits of some versions of @code{m4}, including GNU -@code{m4} 1.0. You must use version 1.1 or later of GNU @code{m4}. -Using version 1.3 or later will be much faster than 1.1 or 1.2. - -@xref{Upgrading}, for information about upgrading from version 1. -@xref{History}, for the story of Autoconf's development. -@xref{Questions}, for answers to some common questions about Autoconf. - -Mail suggestions and bug reports for Autoconf to -@code{bug-gnu-utils@@prep.ai.mit.edu}. Please include the Autoconf version -number, which you can get by running @samp{autoconf --version}. - -@node Making configure Scripts, Setup, Introduction, Top -@chapter Making @code{configure} Scripts - -The configuration scripts that Autoconf produces are by convention -called @code{configure}. When run, @code{configure} creates several -files, replacing configuration parameters in them with appropriate -values. The files that @code{configure} creates are: - -@itemize @bullet -@item -one or more @file{Makefile} files, one in each subdirectory of the -package (@pxref{Makefile Substitutions}); - -@item -optionally, a C header file, the name of which is configurable, -containing @code{#define} directives (@pxref{Configuration Headers}); - -@item -a shell script called @file{config.status} that, when run, will recreate -the files listed above (@pxref{Invoking config.status}); - -@item -a shell script called @file{config.cache} that saves the results of -running many of the tests (@pxref{Cache Files}); - -@item -a file called @file{config.log} containing any messages produced by -compilers, to help debugging if @code{configure} makes a mistake. -@end itemize - -To create a @code{configure} script with Autoconf, you need to write an -Autoconf input file @file{configure.in} and run @code{autoconf} on it. -If you write your own feature tests to supplement those that come with -Autoconf, you might also write files called @file{aclocal.m4} and -@file{acsite.m4}. If you use a C header file to contain @code{#define} -directives, you might also write @file{acconfig.h}, and you will -distribute the Autoconf-generated file @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 -@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). -@code{autoconf} and @code{autoheader} also read the installed Autoconf -macro files (by reading @file{autoconf.m4}). - -@noindent -Files used in preparing a software package for distribution: -@example -@group -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 -@end group -@end example - -@noindent -Files used in configuring a software package: -@example -@group - .-------------> config.cache -configure* ------------+-------------> config.log - | -[config.h.in] -. v .-> [config.h] -. - +--> config.status* -+ +--> make* -Makefile.in ---' `-> Makefile ---' -@end group -@end example - -@menu -* Writing configure.in:: What to put in an Autoconf input file. -* Invoking autoscan:: Semi-automatic @file{configure.in} writing. -* Invoking ifnames:: Listing the conditionals in source code. -* Invoking autoconf:: How to create configuration scripts. -* Invoking autoreconf:: Remaking multiple @code{configure} scripts. -@end menu - -@node Writing configure.in, Invoking autoscan, , Making configure Scripts -@section Writing @file{configure.in} - -To produce a @code{configure} script for a software package, create a -file called @file{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 -@ref{Existing Tests}, for their descriptions. For most other -features, you can use Autoconf template macros to produce custom checks; -see @ref{Writing Tests}, for information about them. For especially -tricky or specialized features, @file{configure.in} might need to -contain some hand-crafted shell commands. The @code{autoscan} -program can give you a good start in writing @file{configure.in} -(@pxref{Invoking autoscan}, for more information). - -The order in which @file{configure.in} calls the Autoconf macros -is not important, with a few exceptions. Every -@file{configure.in} must contain a call to @code{AC_INIT} before -the checks, and a call to @code{AC_OUTPUT} at the end -(@pxref{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 (@pxref{Existing Tests}), -and they also warn you when creating @code{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. - -@display -@group -@code{AC_INIT(@var{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 -@code{AC_OUTPUT(@r{[}@var{file@dots{}}@r{]})} -@end group -@end display - -It is best to put each macro call on its own line in -@file{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 @code{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 @code{m4} quote -characters @samp{[} and @samp{]}. 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 @var{action-if-found} argument to the macro. To omit the false -case, omit the @var{action-if-not-found} argument to the macro, -including the comma before it. - -You can include comments in @file{configure.in} files by starting them -with the @code{m4} builtin macro @code{dnl}, which discards text up -through the next newline. These comments do not appear in the generated -@code{configure} scripts. For example, it is helpful to begin -@file{configure.in} files with a line like this: - -@example -dnl Process this file with autoconf to produce a configure script. -@end example - -@node Invoking autoscan, Invoking ifnames, Writing configure.in, Making configure Scripts -@section Using @code{autoscan} to Create @file{configure.in} - -The @code{autoscan} program can help you create a @file{configure.in} -file for a software package. @code{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 -@file{configure.scan} which is a preliminary @file{configure.in} for -that package. - -You should manually examine @file{configure.scan} before renaming it to -@file{configure.in}; it will probably need some adjustments. -Occasionally @code{autoscan} outputs a macro in the wrong order relative -to another macro, so that @code{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 -@code{AC_CONFIG_HEADER} (@pxref{Configuration Headers}). You might also -have to change or add some @code{#if} directives to your program in -order to make it work with Autoconf (@pxref{Invoking ifnames}, for -information about a program that can help with that job). - -@code{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 @samp{#} are comments. - -@code{autoscan} is only installed if you already have Perl installed. -@code{autoscan} accepts the following options: - -@table @code -@item --help -Print a summary of the command line options and exit. - -@item --macrodir=@var{dir} -@evindex AC_MACRODIR -Look for the data files in directory @var{dir} instead of the default -installation directory. You can also set the @code{AC_MACRODIR} -environment variable to a directory; this option overrides the -environment variable. - -@item --verbose -Print the names of the files it examines and the potentially interesting -symbols it finds in them. This output can be voluminous. - -@item --version -Print the version number of Autoconf and exit. -@end table - -@node Invoking ifnames, Invoking autoconf, Invoking autoscan, Making configure Scripts -@section Using @code{ifnames} to List Conditionals - -@code{ifnames} can help when writing a @file{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 @code{configure} needs to check for. It may help fill in some gaps -in a @file{configure.in} generated by @code{autoscan} (@pxref{Invoking -autoscan}). - -@code{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 @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} -directives. It prints each identifier on a line, followed by a -space-separated list of the files in which that identifier occurs. - -@noindent -@code{ifnames} accepts the following options: - -@table @code -@item --help -@itemx -h -Print a summary of the command line options and exit. - -@item --macrodir=@var{dir} -@itemx -m @var{dir} -@evindex AC_MACRODIR -Look for the Autoconf macro files in directory @var{dir} instead of the -default installation directory. Only used to get the version number. -You can also set the @code{AC_MACRODIR} -environment variable to a directory; this option overrides the -environment variable. - -@item --version -Print the version number of Autoconf and exit. -@end table - -@node Invoking autoconf, Invoking autoreconf, Invoking ifnames, Making configure Scripts -@section Using @code{autoconf} to Create @code{configure} - -To create @code{configure} from @file{configure.in}, run the -@code{autoconf} program with no arguments. @code{autoconf} processes -@file{configure.in} with the @code{m4} macro processor, using the -Autoconf macros. If you give @code{autoconf} an argument, it reads that -file instead of @file{configure.in} and writes the configuration script -to the standard output instead of to @code{configure}. If you give -@code{autoconf} the argument @samp{-}, it reads the standard input -instead of @file{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; @code{autoconf} reads them first. Then it -looks for the optional file @file{acsite.m4} in the directory that -contains the distributed Autoconf macro files, and for the optional file -@file{aclocal.m4} in the current directory. Those files can contain -your site's or the package's own Autoconf macro definitions -(@pxref{Writing Macros}, for more information). If a macro is defined -in more than one of the files that @code{autoconf} reads, the last -definition it reads overrides the earlier ones. - -@code{autoconf} accepts the following options: - -@table @code -@item --help -@itemx -h -Print a summary of the command line options and exit. - -@item --localdir=@var{dir} -@itemx -l @var{dir} -Look for the package file @file{aclocal.m4} in directory @var{dir} -instead of in the current directory. - -@item --macrodir=@var{dir} -@itemx -m @var{dir} -@evindex AC_MACRODIR -Look for the installed macro files in directory @var{dir}. You can also -set the @code{AC_MACRODIR} environment variable to a directory; this -option overrides the environment variable. - -@item --version -Print the version number of Autoconf and exit. -@end table - -@node Invoking autoreconf, , Invoking autoconf, Making configure Scripts -@section Using @code{autoreconf} to Update @code{configure} Scripts - -If you have a lot of Autoconf-generated @code{configure} scripts, the -@code{autoreconf} program can save you some work. It runs -@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to -remake the Autoconf @code{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 -@file{configure.in} or (if present) @file{aclocal.m4}. Since -@code{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 -@code{autoreconf} remake @emph{all} of the files by giving it the -@samp{--force} option. - -If you give @code{autoreconf} the @samp{--macrodir=@var{dir}} or -@samp{--localdir=@var{dir}} options, it passes them down to -@code{autoconf} and @code{autoheader} (with relative paths adjusted -properly). - -@xref{Automatic Remaking}, for @file{Makefile} rules to automatically -remake @code{configure} scripts when their source files change. That -method handles the timestamps of configuration header templates -properly, but does not pass @samp{--macrodir=@var{dir}} or -@samp{--localdir=@var{dir}}. - -@noindent -@code{autoreconf} accepts the following options: - -@table @code -@item --help -@itemx -h -Print a summary of the command line options and exit. - -@item --force -@itemx -f -Remake even @file{configure} scripts and configuration headers that are -newer than their input files (@file{configure.in} and, if present, -@file{aclocal.m4}). - -@item --localdir=@var{dir} -@itemx -l @var{dir} -Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but -not @file{@var{file}.top} and @file{@var{file}.bot}) in directory -@var{dir} instead of in the directory containing each @file{configure.in}. - -@item --macrodir=@var{dir} -@itemx -m @var{dir} -@evindex AC_MACRODIR -Look for the Autoconf macro files in directory @var{dir} instead of the -default installation directory. -You can also set the @code{AC_MACRODIR} -environment variable to a directory; this option overrides the -environment variable. - -@item --verbose -Print the name of each directory where @code{autoreconf} runs -@code{autoconf} (and @code{autoheader}, if appropriate). - -@item --version -Print the version number of Autoconf and exit. -@end table - -@node Setup, Existing Tests, Making configure Scripts, Top -@chapter Initialization and Output Files - -Autoconf-generated @code{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 @file{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 @code{configure}. -@end menu - -@node Input, Output, , Setup -@section Finding @code{configure} Input - -Every @code{configure} script must call @code{AC_INIT} before doing -anything else. The only other required macro is @code{AC_OUTPUT} -(@pxref{Output}). - -@defmac AC_INIT (@var{unique-file-in-source-dir}) -@maindex INIT -Process any command-line arguments and find the source code directory. -@var{unique-file-in-source-dir} is some file that is in the package's -source directory; @code{configure} checks for this file's existence to -make sure that the directory that it is told contains the source code in -fact does (@pxref{Invoking configure}, for more information). -@end defmac - -Packages that do manual configuration or use the @code{install} program -might need to tell @code{configure} where to find some other shell -scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places -it looks are correct for most cases. - -@defmac AC_CONFIG_AUX_DIR(@var{dir}) -@maindex CONFIG_AUX_DIR -Use the @file{install-sh}, @file{config.sub}, @file{config.guess}, and -Cygnus @code{configure} scripts that are in directory @var{dir}. These -are auxiliary files used in configuration. @var{dir} can be either -absolute or relative to @file{@var{srcdir}}. The default is -@file{@var{srcdir}} or @file{@var{srcdir}/..} or -@file{@var{srcdir}/../..}, whichever is the first that contains -@file{install-sh}. The other files are not checked for, so that using -@code{AC_PROG_INSTALL} does not automatically require distributing the -other auxiliary files. It checks for @file{install.sh} also, but that -name is obsolete because some @code{make} programs have a rule that -creates @file{install} from it if there is no @file{Makefile}. -@end defmac - -@node Output, Makefile Substitutions, Input, Setup -@section Creating Output Files - -Every Autoconf-generated @code{configure} script must finish by calling -@code{AC_OUTPUT}. It is the macro that creates the @file{Makefile}s and -optional other files resulting from configuration. The only other -required macro is @code{AC_INIT} (@pxref{Input}). - -@defmac AC_OUTPUT (@r{[}@var{file}@dots{}@r{] [,}@var{extra-cmds}@r{] [,}@var{init-cmds}@r{]}) -@maindex OUTPUT -Create output files. The @var{file}@dots{} argument is a -whitespace-separated list of output files; it may be empty. This macro -creates each file @file{@var{file}} by copying an input file (by default -named @file{@var{file}.in}), substituting the output variable values. -@xref{Makefile Substitutions}, for more information on using output variables. -@xref{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, @file{Makefile}s are -created this way, but other files, such as @file{.gdbinit}, can be -specified as well. - -If @code{AC_CONFIG_HEADER}, @code{AC_LINK_FILES}, or -@code{AC_CONFIG_SUBDIRS} has been called, this macro also creates the -files named as their arguments. - -A typical call to @code{AC_OUTPUT} looks like this: -@example -AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile) -@end example - -You can override an input file name by appending it to @var{file}, -separated by a colon. For example, -@example -AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk) -@end example - -If you pass @var{extra-cmds}, those commands will be inserted into -@file{config.status} to be run after all its other processing. If -@var{init-cmds} are given, they are inserted just before -@var{extra-cmds}, with shell variable, command, and backslash -substitutions performed on them in @code{configure}. You can use -@var{init-cmds} to pass variables from @code{configure} to the -@var{extra-cmds}. -@end defmac - -If you run @code{make} on subdirectories, you should run it using the -@code{make} variable @code{MAKE}. Most versions of @code{make} set -@code{MAKE} to the name of the @code{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 @code{make} do not set this variable. The -following macro allows you to use it even with those versions. - -@defmac AC_PROG_MAKE_SET -@maindex PROG_MAKE_SET -@ovindex SET_MAKE -If @code{make} predefines the variable @code{MAKE}, define output -variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE} -to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}. -@end defmac - -To use this macro, place a line like this in each @file{Makefile.in} -that runs @code{MAKE} on other directories: - -@example -@@SET_MAKE@@ -@end example - -@node Makefile Substitutions, Configuration Headers, Output, Setup -@section Substitutions in Makefiles - -Each subdirectory in a distribution that contains something to be -compiled or installed should come with a file @file{Makefile.in}, from -which @code{configure} will create a @file{Makefile} in that directory. -To create a @file{Makefile}, @code{configure} performs a simple variable -substitution, replacing occurrences of @samp{@@@var{variable}@@} in -@file{Makefile.in} with the value that @code{configure} has determined -for that variable. Variables that are substituted into output files in -this way are called @dfn{output variables}. They are ordinary shell -variables that are set in @code{configure}. To make @code{configure} -substitute a particular variable into the output files, the macro -@code{AC_SUBST} must be called with that variable name as an argument. -Any occurrences of @samp{@@@var{variable}@@} for other variables are -left unchanged. @xref{Setting Output Variables}, for more information on -creating output variables with @code{AC_SUBST}. - -A software package that uses a @code{configure} script should be -distributed with a file @file{Makefile.in}, but no @file{Makefile}; that -way, the user has to properly configure the package for the local system -before compiling it. - -@xref{Makefile Conventions, , Makefile Conventions, standards.info, The -GNU Coding Standards}, for more information on what to put in -@file{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. -@end menu - -@node Preset Output Variables, Build Directories, , Makefile Substitutions -@subsection 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. @xref{Output Variable Index}, for a -complete list of output variables. Here is what each of the preset ones -contains. - -@defvar configure_input -@ovindex configure_input -A comment saying that the file was generated automatically by -@code{configure} and giving the name of the input file. -@code{AC_OUTPUT} adds a comment line containing this variable to the top -of every @file{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: - -@example -#!/bin/sh -# @@configure_input@@ -@end example - -@noindent -The presence of that line also reminds people editing the file that it -needs to be processed by @code{configure} in order to be used. -@end defvar - -@defvar exec_prefix -@ovindex exec_prefix -The installation prefix for architecture-dependent files. -@end defvar - -@defvar prefix -@ovindex prefix -The installation prefix for architecture-independent files. -@end defvar - -@defvar srcdir -@ovindex srcdir -The directory that contains the source code for that @file{Makefile}. -@end defvar - -@defvar top_srcdir -@ovindex top_srcdir -The top-level source code directory for the package. In the top-level -directory, this is the same as @code{srcdir}. -@end defvar - -@defvar CFLAGS -@ovindex CFLAGS -Debugging and optimization options for the C compiler. If it is not set -in the environment when @code{configure} runs, the default value is set -when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure} -uses this variable when compiling programs to test for C features. -@end defvar - -@defvar CPPFLAGS -@ovindex CPPFLAGS -Header file search directory (@samp{-I@var{dir}}) and any other -miscellaneous options for the C preprocessor and compiler. If it is not -set in the environment when @code{configure} runs, the default value is -empty. @code{configure} uses this variable when compiling or -preprocessing programs to test for C features. -@end defvar - -@defvar CXXFLAGS -@ovindex CXXFLAGS -Debugging and optimization options for the C++ compiler. If it is not -set in the environment when @code{configure} runs, the default value is -set when you call @code{AC_PROG_CXX} (or empty if you don't). -@code{configure} uses this variable when compiling programs to test for -C++ features. -@end defvar - -@defvar DEFS -@ovindex DEFS -@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER} -is called, @code{configure} replaces @samp{@@DEFS@@} with -@samp{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This -variable is not defined while @code{configure} is performing its tests, -only when creating the output files. @xref{Setting Output Variables}, for -how to check the results of previous tests. -@end defvar - -@defvar LDFLAGS -@ovindex LDFLAGS -Stripping (@samp{-s}) and any other miscellaneous options for the -linker. If it is not set in the environment when @code{configure} runs, -the default value is empty. @code{configure} uses this variable when -linking programs to test for C features. -@end defvar - -@defvar LIBS -@ovindex LIBS -@samp{-l} and @samp{-L} options to pass to the linker. -@end defvar - -@node Build Directories, Automatic Remaking, Preset Output Variables, Makefile Substitutions -@subsection 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, @code{make} uses the @code{VPATH} variable to -find the files that are in the source directory. GNU @code{make} and -most other recent @code{make} programs can do this. Older @code{make} -programs do not support @code{VPATH}; when using them, the source code -must be in the same directory as the object files. - -To support @code{VPATH}, each @file{Makefile.in} should contain two -lines that look like: - -@example -srcdir = @@srcdir@@ -VPATH = @@srcdir@@ -@end example - -Do not set @code{VPATH} to the value of another variable, for example -@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do -variable substitutions on the value of @code{VPATH}. - -@code{configure} substitutes in the correct value for @code{srcdir} when -it produces @file{Makefile.in}. - -Do not use the @code{make} variable @code{$<}, which expands to the -pathname of the file in the source directory (found with @code{VPATH}), -except in implicit rules. (An implicit rule is one such as @samp{.c.o}, -which tells how to create a @file{.o} file from a @file{.c} file.) Some -versions of @code{make} do not set @code{$<} in explicit rules; they -expand it to an empty value. - -Instead, @file{Makefile} command lines should always refer to source -files by prefixing them with @samp{$(srcdir)/}. For example: - -@example -time.info: time.texinfo - $(MAKEINFO) $(srcdir)/time.texinfo -@end example - -@node Automatic Remaking, , Build Directories, Makefile Substitutions -@subsection Automatic Remaking - -You can put rules like the following in the top-level @file{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 @file{aclocal.m4} and those related to -configuration header files. Omit from the @file{Makefile.in} rules any -of these files that your package does not use. - -The @samp{$@{srcdir@}/} prefix is included because of limitations in the -@code{VPATH} mechanism. - -The @file{stamp-} files are necessary because the timestamps of -@file{config.h.in} and @file{config.h} will not be changed if remaking -them does not change their contents. This feature avoids unnecessary -recompilation. You should include the file @file{stamp-h.in} your -package's distribution, so @code{make} will consider @file{config.h.in} -up to date. On some old BSD systems, @code{touch} or any command that -results in an empty file does not update the timestamps, so use a -command like @code{date} as a workaround. - -@example -@group -$@{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 -@end group -@end example - -In addition, you should pass @samp{date > stamp-h} in the @var{extra-cmds} -argument to @code{AC_OUTPUT}, so @file{config.status} will ensure that -@file{config.h} is considered up to date. @xref{Output}, for more -information about @code{AC_OUTPUT}. - -@xref{Invoking config.status}, for more examples of handling -configuration-related dependencies. - -@node Configuration Headers, Subdirectories, Makefile Substitutions, Setup -@section Configuration Header Files - -When a package tests more than a few C preprocessor symbols, the command -lines to pass @samp{-D} options to the compiler can get quite long. -This causes two problems. One is that the @code{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 @samp{-D} options to the compiler, @code{configure} scripts can -create a C header file containing @samp{#define} directives. The -@code{AC_CONFIG_HEADER} macro selects this kind of output. It should be -called right after @code{AC_INIT}. - -The package should @samp{#include} the configuration header file before -any other header files, to prevent inconsistencies in declarations (for -example, if it redefines @code{const}). Use @samp{#include <config.h>} -instead of @samp{#include "config.h"}, and pass the C compiler a -@samp{-I.} option (or @samp{-I..}; whichever directory contains -@file{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 @file{config.h} from the source -directory. - -@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{}) -@maindex CONFIG_HEADER -@cvindex HAVE_CONFIG_H -Make @code{AC_OUTPUT} create the file(s) in the whitespace-separated -list @var{header-to-create} containing C preprocessor @code{#define} -statements, and replace @samp{@@DEFS@@} in generated files with -@samp{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. The usual -name for @var{header-to-create} is @file{config.h}. - -If @var{header-to-create} already exists and its contents are identical -to what @code{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 @file{@var{header-to-create}.in}; -however, you can override the input file name by appending it to -@var{header-to-create}, separated by a colon. For example, -@example -AC_CONFIG_HEADER(defines.h:defines.hin) -@end example -@noindent -Doing this allows you to keep your filenames acceptable to MS-DOS. -@end defmac - -@menu -* Header Templates:: Input for the configuration headers. -* Invoking autoheader:: How to create configuration templates. -@end menu - -@node Header Templates, Invoking autoheader, , Configuration Headers -@subsection 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 @code{#define} statements. For example, suppose your -@file{configure.in} makes these calls: - -@example -AC_CONFIG_HEADER(conf.h) -AC_CHECK_HEADERS(unistd.h) -@end example - -@noindent -Then you could have code like the following in @file{conf.h.in}. -On systems that have @file{unistd.h}, @code{configure} will change the 0 -to a 1. On other systems, it will leave the line unchanged. - -@example -@group -/* Define as 1 if you have unistd.h. */ -#define HAVE_UNISTD_H 0 -@end group -@end example - -Alternately, if your code tests for configuration options using -@code{#ifdef} instead of @code{#if}, a default value can be to -@code{#undef} the variable instead of to define it to a value. On -systems that have @file{unistd.h}, @code{configure} will change the -second line to read @samp{#define HAVE_UNISTD_H 1}. On other systems, -it will comment that line out (in case the system predefines that -symbol). - -@example -@group -/* Define if you have unistd.h. */ -#undef HAVE_UNISTD_H -@end group -@end example - -@node Invoking autoheader, , Header Templates, Configuration Headers -@subsection Using @code{autoheader} to Create @file{config.h.in} - -The @code{autoheader} program can create a template file of C -@samp{#define} statements for @code{configure} to use. If -@file{configure.in} invokes @code{AC_CONFIG_HEADER(@var{file})}, -@code{autoheader} creates @file{@var{file}.in}. Otherwise, -@code{autoheader} creates @file{config.h.in}. - -If you give @code{autoheader} an argument, it uses that file instead of -@file{configure.in} and writes the header file to the standard output -instead of to @file{config.h.in}. If you give @code{autoheader} an -argument of @samp{-}, it reads the standard input instead of -@file{configure.in} and writes the header file to the standard output. - -@code{autoheader} scans @file{configure.in} and figures out which C -preprocessor symbols it might define. It copies comments and -@code{#define} and @code{#undef} statements from a file called -@file{acconfig.h}, which comes with and is installed with Autoconf. It -also uses a file called @file{acconfig.h} in the current directory, if -present. If you @code{AC_DEFINE} any additional symbols, you must -create that file with entries for them. For symbols defined by -@code{AC_CHECK_HEADERS}, @code{AC_CHECK_FUNCS}, @code{AC_CHECK_SIZEOF}, -or @code{AC_CHECK_LIB}, @code{autoheader} generates comments and -@code{#undef} statements itself rather than copying them from a file, -since the possible symbols are effectively limitless. - -The file that @code{autoheader} creates contains mainly @code{#define} -and @code{#undef} statements and their accompanying comments. If -@file{./acconfig.h} contains the string @samp{@@TOP@@}, -@code{autoheader} copies the lines before the line containing -@samp{@@TOP@@} into the top of the file that it generates. Similarly, -if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, -@code{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{@var{file}.top} (typically @file{config.h.top}) and/or -@file{@var{file}.bot} in the current directory. If they exist, -@code{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 -@samp{--localdir=@var{dir}} option to use an @file{acconfig.h} in another -directory, they give you a way to put custom boilerplate in each -individual @file{config.h.in}. - -@code{autoheader} accepts the following options: - -@table @code -@item --help -@itemx -h -Print a summary of the command line options and exit. - -@item --localdir=@var{dir} -@itemx -l @var{dir} -Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but -not @file{@var{file}.top} and @file{@var{file}.bot}) in directory -@var{dir} instead of in the current directory. - -@item --macrodir=@var{dir} -@itemx -m @var{dir} -@evindex AC_MACRODIR -Look for the installed macro files and @file{acconfig.h} in directory -@var{dir}. You can also set the @code{AC_MACRODIR} environment variable -to a directory; this option overrides the environment variable. - -@item --version -Print the version number of Autoconf and exit. -@end table - -@node Subdirectories, Default Prefix, Configuration Headers, Setup -@section Configuring Other Packages in Subdirectories - -In most situations, calling @code{AC_OUTPUT} is sufficient to produce -@file{Makefile}s in subdirectories. However, @code{configure} scripts -that control more than one independent package can use -@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other -packages in subdirectories. - -@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) -@maindex CONFIG_SUBDIRS -@ovindex subdirs -Make @code{AC_OUTPUT} run @code{configure} in each subdirectory -@var{dir} in the given whitespace-separated list. If a given @var{dir} -is not found, no error is reported, so a @code{configure} script can -configure whichever parts of a large source tree are present. If a -given @var{dir} contains @file{configure.in} but no @code{configure}, -the Cygnus @code{configure} script found by @code{AC_CONFIG_AUXDIR} is -used. The subdirectory @code{configure} scripts are given the same -command line options that were given to this @code{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 @code{subdirs} to the list of directories @samp{@var{dir} -@dots{}}. @file{Makefile} rules can use this variable to determine -which subdirectories to recurse into. -@end defmac - -@node Default Prefix, Versions, Subdirectories, Setup -@section Default Prefix - -By default, @code{configure} sets the prefix for files it installs to -@file{/usr/local}. The user of @code{configure} can select a different -prefix using the @samp{--prefix} and @samp{--exec-prefix} options. -There are two ways to change the default: when creating -@code{configure}, and when running it. - -Some software packages might want to install in a directory besides -@file{/usr/local} by default. To accomplish that, use the -@code{AC_PREFIX_DEFAULT} macro. - -@defmac AC_PREFIX_DEFAULT (@var{prefix}) -Set the default installation prefix to @var{prefix} instead of @file{/usr/local}. -@end defmac - -It may be convenient for users to have @code{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 -@code{AC_PREFIX_PROGRAM}. - -@defmac AC_PREFIX_PROGRAM (@var{program}) -@maindex PREFIX_PROGRAM -If the user did not specify an installation prefix (using the -@samp{--prefix} option), guess a value for it by looking for -@var{program} in @code{PATH}, the way the shell does. If @var{program} -is found, set the prefix to the parent of the directory containing -@var{program}; otherwise leave the prefix specified in -@file{Makefile.in} unchanged. For example, if @var{program} is -@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc}, -set the prefix to @file{/usr/local/gnu}. -@end defmac - -@node Versions, , Default Prefix, Setup -@section Version Numbers in @code{configure} - -The following macros manage version numbers for @code{configure} -scripts. Using them is optional. - -@defmac AC_PREREQ (@var{version}) -@maindex PREREQ -Ensure that a recent enough version of Autoconf is being used. If the -version of Autoconf being used to create @code{configure} is earlier -than @var{version}, print an error message on the standard error output -and do not create @code{configure}. For example: - -@example -AC_PREREQ(1.8) -@end example - -This macro is useful if your @file{configure.in} relies on non-obvious -behavior that changed between Autoconf releases. If it merely needs -recently added macros, then @code{AC_PREREQ} is less useful, because the -@code{autoconf} program already tells the user which macros are not -found. The same thing happens if @file{configure.in} is processed by a -version of Autoconf older than when @code{AC_PREREQ} was added. -@end defmac - -@defmac AC_REVISION (@var{revision-info}) -@maindex REVISION -Copy revision stamp @var{revision-info} into the @code{configure} -script, with any dollar signs or double-quotes removed. This macro lets -you put a revision stamp from @file{configure.in} into @code{configure} -without RCS or CVS changing it when you check in @code{configure}. That -way, you can determine easily which revision of @file{configure.in} a -particular @code{configure} corresponds to. - -It is a good idea to call this macro before @code{AC_INIT} so that the -revision number is near the top of both @file{configure.in} and -@code{configure}. To support doing that, the @code{AC_REVISION} output -begins with @samp{#!/bin/sh}, like the normal start of a -@code{configure} script does. - -For example, this line in @file{configure.in}: - -@c The asis prevents RCS from changing the example in the manual. -@example -AC_REVISION($@asis{Revision: 1.30 }$)dnl -@end example - -@noindent -produces this in @code{configure}: - -@example -#!/bin/sh -# From configure.in Revision: 1.30 -@end example -@end defmac - -@node Existing Tests, Writing Tests, Setup, Top -@chapter Existing Tests - -These macros test for particular system features that packages -might need or want to use. If you need to test for a kind of feature -that none of these macros check for, you can probably do it by calling -primitive test macros with appropriate arguments (@pxref{Writing Tests}). - -These tests print messages telling the user which feature they're -checking for, and what they find. They cache their results for future -@code{configure} runs (@pxref{Caching Results}). - -Some of these macros set output variables. @xref{Makefile -Substitutions}, for how to get their values. The phrase ``define -@var{name}'' is used below as a shorthand to mean ``define C -preprocessor symbol @var{name} to the value 1''. @xref{Defining -Symbols}, for how to get those symbol definitions into your program. - -@menu -* 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:: @code{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. -@end menu - -@node Alternative Programs, Libraries, , Existing Tests -@section Alternative Programs - -These macros check for the presence or behavior of particular programs. -They are used to choose between several alternative programs and to -decide what to do once one has been chosen. -If there is no macro specifically defined to check for a program you need, -and you don't need to check for any special properties of -it, then you can use one of the general program check macros. - -@menu -* Particular Programs:: Special handling to find certain programs. -* Generic Programs:: How to find other programs. -@end menu - -@node Particular Programs, Generic Programs, , Alternative Programs -@subsection Particular Program Checks - -These macros check for particular programs---whether they exist, and -in some cases whether they support certain features. - -@defmac AC_DECL_YYTEXT -@maindex DECL_YYTEXT -@cvindex YYTEXT_POINTER -@ovindex LEX_OUTPUT_ROOT -Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead -of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to -the base of the file name that the lexer generates; usually -@file{lex.yy}, but sometimes something else. These results vary -according to whether @code{lex} or @code{flex} is being used. -@end defmac - -@defmac AC_PROG_AWK -@maindex PROG_AWK -@ovindex AWK -Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that -order, and set output variable @code{AWK} to the first one that it -finds. It tries @code{mawk} first because that is reported to be the -fastest implementation. -@end defmac - -@defmac AC_PROG_CC -@maindex PROG_CC -@ovindex CC -@ovindex CFLAGS -Determine a C compiler to use. If @code{CC} is not already set in the -environment, check for @code{gcc}, and use @code{cc} if it's not found. -Set output variable @code{CC} to the name of the compiler found. - -If using the GNU C compiler, set shell variable @code{GCC} to -@samp{yes}, empty otherwise. If output variable @code{CFLAGS} was -not already set, set it to @samp{-g -O} for the GNU C compiler -(@samp{-O} on systems where GCC does not accept @samp{-g}), or @samp{-g} -for other compilers. -@end defmac - -@defmac AC_PROG_CC_C_O -@maindex PROG_CC_C_O -@cvindex NO_MINUS_C_MINUS_O -If the C compiler does not accept the @samp{-c} and @samp{-o} options -simultaneously, define @code{NO_MINUS_C_MINUS_O}. -@end defmac - -@defmac AC_PROG_CPP -@maindex PROG_CPP -@ovindex CPP -Set output variable @code{CPP} to a command that runs the -C preprocessor. If @samp{$CC -E} doesn't work, it uses @file{/lib/cpp}. -It is only portable to run @code{CPP} on files with a @file{.c} -extension. - -If the current language is C (@pxref{Language Choice}), many of the -specific test macros use the value of @code{CPP} indirectly by calling -@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or -@code{AC_EGREP_CPP}. -@end defmac - -@defmac AC_PROG_CXX -@maindex PROG_CXX -@ovindex CXX -@ovindex CXXFLAGS -Determine a C++ compiler to use. Check if the environment variable -@code{CXX} or @code{CCC} (in that order) is set; if so, set output -variable @code{CXX} to its value. Otherwise search for a C++ compiler -under likely names (@code{c++}, @code{g++}, @code{gcc}, @code{CC}, and -@code{cxx}). If none of those checks succeed, as a last resort set -@code{CXX} to @code{gcc}. - -If using the GNU C++ compiler, set shell variable @code{GXX} to -@samp{yes}, empty otherwise. If output variable @code{CXXFLAGS} was -not already set, set it to @samp{-g -O} for the GNU C++ compiler -(@samp{-O} on systems where G++ does not accept @samp{-g}), or @samp{-g} -for other compilers. -@end defmac - -@defmac AC_PROG_CXXCPP -@maindex PROG_CXXCPP -@ovindex CXXCPP -Set output variable @code{CXXCPP} to a command that runs the -C++ preprocessor. If @samp{$CXX -E} doesn't work, it uses @file{/lib/cpp}. -It is only portable to run @code{CXXCPP} on files with a @file{.c}, -@file{.C}, or @file{.cc} extension. - -If the current language is C++ (@pxref{Language Choice}), many of the -specific test macros use the value of @code{CXXCPP} indirectly by -calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, -@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}. -@end defmac - -@defmac AC_PROG_GCC_TRADITIONAL -@maindex PROG_GCC_TRADITIONAL -@ovindex CC -Add @samp{-traditional} to output variable @code{CC} if using the -GNU C compiler and @code{ioctl} does not work properly without -@samp{-traditional}. That usually happens when the fixed header files -have not been installed on an old system. Since recent versions of the -GNU C compiler fix the header files automatically when installed, this -is becoming a less prevalent problem. -@end defmac - -@defmac AC_PROG_INSTALL -@maindex PROG_INSTALL -@ovindex INSTALL -@ovindex INSTALL_PROGRAM -@ovindex INSTALL_DATA -Set output variable @code{INSTALL} to the path of a BSD compatible -@code{install} program, if one is found in the current @code{PATH}. -Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, -checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its -default directories) to determine @var{dir} (@pxref{Output}). Also set -the variable @code{INSTALL_PROGRAM} to @samp{$@{INSTALL@}} and -@code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. - -This macro screens out various instances of @code{install} known to not -work. It prefers to find a C program rather than a shell script, for -speed. Instead of @file{install-sh}, it can also use @file{install.sh}, -but that name is obsolete because some @code{make} programs have a rule -that creates @file{install} from it if there is no @file{Makefile}. - -A copy of @file{install-sh} which you may use comes with Autoconf. If -you use @code{AC_PROG_INSTALL}, you must include either -@file{install-sh} or @file{install.sh} in your distribution, or -@code{configure} will produce an error message saying it can't find -them---even if the system you're on has a good @code{install} program. -This check is a safety measure to prevent you from accidentally leaving -that file out, which would prevent your package from installing on -systems that don't have a BSD-compatible @code{install} program. - -If you need to use your own installation program because it has -features not found in standard @code{install} programs, there is no -reason to use @code{AC_PROG_INSTALL}; just put the pathname of your -program into your @file{Makefile.in} files. -@end defmac - -@defmac AC_PROG_LEX -@maindex PROG_LEX -@ovindex LEX -@ovindex LEXLIB -If @code{flex} is found, set output variable @code{LEX} to -@samp{flex} and @code{LEXLIB} to @samp{-lfl}, if that library is in a -standard place. Otherwise set @code{LEX} to @samp{lex} and -@code{LEXLIB} to @samp{-ll}. -@end defmac - -@defmac AC_PROG_LN_S -@maindex PROG_LN_S -@ovindex LN_S -If @samp{ln -s} works on the current filesystem (the operating system -and filesystem support symbolic links), set output -variable @code{LN_S} to @samp{ln -s}, otherwise set it to @samp{ln}. -@end defmac - -@defmac AC_PROG_RANLIB -@maindex PROG_RANLIB -@ovindex RANLIB -Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} -is found, otherwise to @samp{:} (do nothing). -@end defmac - -@defmac AC_PROG_YACC -@maindex PROG_YACC -@ovindex YACC -If @code{bison} is found, set output variable @code{YACC} to -@samp{bison -y}. Otherwise, if @code{byacc} is found, set @code{YACC} -to @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. -@end defmac - -@node Generic Programs, , Particular Programs, Alternative Programs -@subsection Generic Program Checks - -These macros are used to find programs not covered by the particular -test macros. If you need to check the behavior of a program as well as -find out whether it is present, you have to write your own test for -it (@pxref{Writing Tests}). - -@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found}@r{]}) -@maindex CHECK_PROG -Check whether program @var{prog-to-check-for} exists in @code{PATH}. If -it is found, set @var{variable} to @var{value-if-found}, otherwise to -@var{value-if-not-found}, if given. If @var{variable} was already set, -do nothing. Calls @code{AC_SUBST} for @var{variable}. -@end defmac - -@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) -@maindex CHECK_PROGS -Check for each program in the whitespace-separated list -@var{progs-to-check-for} exists in @code{PATH}. If it is found, set -@var{variable} to the name of that program. Otherwise, continue -checking the next program in the list. If none of the programs in the -list are found, set @var{variable} to @var{value-if-not-found}; if -@var{value-if-not-found} is not specified, the value of @var{variable} -is not changed. Calls @code{AC_SUBST} for @var{variable}. -@end defmac - -@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) -@maindex PATH_PROG -Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire -path of @var{prog-to-check-for} if found. -@end defmac - -@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found}@r{]}) -@maindex PATH_PROGS -Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} -are found, set @var{variable} to the entire path of the program -found. -@end defmac - -@node Libraries, Library Functions, Alternative Programs, Existing Tests -@section Library Files - -The following macros check for the presence of certain C library archive -files. - -@defmac AC_CHECK_LIB (@var{library}, @var{function} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]}) -@maindex CHECK_LIB -Try to ensure that C function @var{function} is available by checking -whether a test C program can be linked with the library @var{library} to -get the function. @var{library} is the base name of the library; e.g., -to check for @samp{-lmp}, use @samp{mp} as the @var{library} argument. - -@var{action-if-found} is a list of shell commands to run if the link -with the library succeeds; @var{action-if-not-found} is a list of shell -commands to run if the link fails. If @var{action-if-found} and -@var{action-if-not-found} are not specified, the default action is to -add @samp{-l@var{library}} to @code{LIBS} and define -@samp{HAVE_LIB@var{library}} (in all capitals). - -If linking with @var{library} results in unresolved symbols, which would -be resolved by linking with additional libraries, give those libraries -as the @var{other-libraries} argument, separated by spaces: @samp{-lX11 --lXt}. Otherwise this macro will fail to detect that @var{library} is -present, because linking the test program will always fail with -unresolved symbols. -@end defmac - -@defmac AC_HAVE_LIBRARY (@var{library}, @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]}) -@maindex HAVE_LIBRARY -This macro is equivalent to calling @code{AC_CHECK_LIB} with a -@var{function} argument of @code{main}. In addition, @var{library} can -be written as any of @samp{foo}, @samp{-lfoo}, or @samp{libfoo.a}. In -all of those cases, the compiler is passed @samp{-lfoo}. However, -@var{library} can not be a shell variable; it must be a literal name. -This macro is considered obsolete. -@end defmac - -@node Library Functions, Header Files, Libraries, Existing Tests -@section Library Functions - -The following macros check for particular C library functions. -If there is no macro specifically defined to check for a function you need, -and you don't need to check for any special properties of -it, then you can use one of the general function check macros. - -@menu -* Particular Functions:: Special handling to find certain functions. -* Generic Functions:: How to find other functions. -@end menu - -@node Particular Functions, Generic Functions, , Library Functions -@subsection Particular Function Checks - -These macros check for particular C functions---whether they exist, and -in some cases how they respond when given certain arguments. - -@defmac AC_FUNC_ALLOCA -@maindex FUNC_ALLOCA -@cvindex C_ALLOCA -@cvindex HAVE_ALLOCA_H -@ovindex ALLOCA -Check how to get @code{alloca}. Tries to get a builtin version by -checking for @file{alloca.h} or the predefined C preprocessor macros -@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, -it defines @code{HAVE_ALLOCA_H}. - -If those attempts fail, it looks for the function in the standard C -library. If any of those methods succeed, it defines -@code{HAVE_ALLOCA}. Otherwise, it sets the output variable -@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so -programs can periodically call @samp{alloca(0)} to garbage collect). -This variable is separate from @code{LIBOBJS} so multiple programs can -share the value of @code{ALLOCA} without needing to create an actual -library, in case only some of them use the code in @code{LIBOBJS}. - -This macro does not try to get @code{alloca} from the System V R3 -@file{libPW} or the System V R4 @file{libucb} because those libraries -contain some incompatible functions that cause trouble. Some versions -do not even contain @code{alloca} or contain a buggy version. If you -still want to use their @code{alloca}, use @code{ar} to extract -@file{alloca.o} from them instead of compiling @file{alloca.c}. - -Source files that use @code{alloca} should start with a piece of code -like the following, to declare it properly. In some versions -of AIX, the declaration of @code{alloca} must precede everything else -except for comments and preprocessor directives. The @code{#pragma} -directive is indented so that pre-ANSI C compilers will ignore it, -rather than choke on it. - -@example -@group -/* AIX requires this to be the first thing in the file. */ -#ifdef __GNUC__ -# define alloca __builtin_alloca -#else -# if HAVE_ALLOCA_H -# include <alloca.h> -# else -# ifdef _AIX - #pragma alloca -# else -# ifndef alloca /* predefined by HP cc +Olibcalls */ -char *alloca (); -# endif -# endif -# endif -#endif -@end group -@end example -@end defmac - -@defmac AC_FUNC_CLOSEDIR_VOID -@maindex FUNC_CLOSEDIR_VOID -@cvindex CLOSEDIR_VOID -If the @code{closedir} function does not return a meaningful value, -define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its -return value for an error indicator. -@end defmac - -@defmac AC_FUNC_GETLOADAVG -@maindex FUNC_GETLOADAVG -@cvindex SVR4 -@cvindex DGUX -@cvindex UMAX -@cvindex UMAX4_3 -@cvindex NLIST_STRUCT -@cvindex NLIST_NAME_UNION -@cvindex GETLODAVG_PRIVILEGED -@cvindex NEED_SETGID -@ovindex LIBOBJS -@ovindex NEED_SETGID -@ovindex KMEM_GROUP -Check how to get the system load averages. If the system has the -@code{getloadavg} function, this macro defines @code{HAVE_GETLOADAVG}, -and adds to @code{LIBS} any libraries needed to get that function. - -Otherwise, it adds @samp{getloadavg.o} to the output variable -@code{LIBOBJS}, and possibly defines several other C preprocessor -macros and output variables: - -@enumerate -@item -It defines @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if -on those systems. - -@item -If it finds @file{nlist.h}, it defines @code{NLIST_STRUCT}. - -@item -If @samp{struct nlist} has an @samp{n_un} member, it defines -@code{NLIST_NAME_UNION}. - -@item -If compiling @file{getloadavg.c} defines @code{LDAV_PRIVILEGED}, -programs need to be installed specially on this system for -@code{getloadavg} to work, and this macro defines -@code{GETLOADAVG_PRIVILEGED}. - -@item -This macro sets the output variable @code{NEED_SETGID}. The value is -@samp{true} if special installation is required, @samp{false} if not. -If @code{NEED_SETGID} is @samp{true}, this macro sets @code{KMEM_GROUP} -to the name of the group that should own the installed program. -@end enumerate -@end defmac - -@defmac AC_FUNC_GETMNTENT -@maindex FUNC_GETMNTENT -@cvindex HAVE_GETMNTENT -Check for the @code{getmntent} in the @file{sun} and @file{seq} -libraries, for Irix 4 and PTX, respectively. Then, if @code{getmntent} is -available, define @code{HAVE_GETMNTENT}. -@end defmac - -@defmac AC_FUNC_MEMCMP -@maindex FUNC_MEMCMP -@ovindex LIBOBJS -If the @code{memcmp} function is not available, or does not work on -8-bit data (like the one on SunOS 4.1.3), add @samp{memcmp.o} to output -variable @code{LIBOBJS}. -@end defmac - -@defmac AC_FUNC_MMAP -@maindex FUNC_MMAP -@cvindex HAVE_MMAP -If the @code{mmap} function exists and works correctly on memory mapped -files, define @code{HAVE_MMAP}. -@end defmac - -@defmac AC_FUNC_SETVBUF_REVERSED -@maindex FUNC_SETVBUF_REVERSED -@cvindex SETVBUF_REVERSED -If @code{setvbuf} takes the buffering type as its second argument and -the buffer pointer as the third, instead of the other way around, define -@code{SETVBUF_REVERSED}. This is the case on System V before release 3. -@end defmac - -@defmac AC_FUNC_STRCOLL -@maindex FUNC_STRCOLL -@cvindex HAVE_STRCOLL -If the @code{strcoll} function exists and works correctly, define -@code{HAVE_STRCOLL}. This does a bit more than -@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect -definitions of @code{strcoll}, which should not be used. -@end defmac - -@defmac AC_FUNC_STRFTIME -@maindex FUNC_STRFTIME -@cvindex HAVE_STRFTIME -Check for @code{strftime} in the @file{intl} library, for SCO UNIX. -Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. -@end defmac - -@defmac AC_FUNC_UTIME_NULL -@maindex FUNC_UTIME_NULL -@cvindex HAVE_UTIME_NULL -If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to -the present, define @code{HAVE_UTIME_NULL}. -@end defmac - -@defmac AC_FUNC_VFORK -@maindex FUNC_VFORK -@cvindex HAVE_VFORK_H -@cvindex vfork -If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working -@code{vfork} is not found, define @code{vfork} to be @code{fork}. This -macro checks for several known errors in implementations of @code{vfork} -and considers the system to not have a working @code{vfork} if it -detects any of them. -@end defmac - -@defmac AC_FUNC_VPRINTF -@maindex FUNC_VPRINTF -@cvindex HAVE_VPRINTF -@cvindex HAVE_DOPRNT -If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if -@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} -is available, you may assume that @code{vfprintf} and @code{vsprintf} -are also available.) -@end defmac - -@defmac AC_FUNC_WAIT3 -@maindex FUNC_WAIT3 -@cvindex HAVE_WAIT3 -If @code{wait3} is found and fills in the contents of its third argument -(a @samp{struct rusage *}), which HP-UX does not do, define -@code{HAVE_WAIT3}. -@end defmac - -@node Generic Functions, , Particular Functions, Library Functions -@subsection Generic Function Checks - -These macros are used to find functions not covered by the particular -test macros. If the functions might be in libraries other than the -default C library, first call @code{AC_CHECK_LIB} for those libraries. -If you need to check the behavior of a function as well as find out -whether it is present, you have to write your own test for -it (@pxref{Writing Tests}). - -@defmac AC_CHECK_FUNC (@var{function}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex CHECK_FUNC -If C function @var{function} is available, run shell commands -@var{action-if-found}, otherwise @var{action-if-not-found}. If you just -want to define a symbol if the function is available, consider using -@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C -linkage even when @code{AC_LANG_CPLUSPLUS} has been called, since C++ is -more standardized than C is. (@pxref{Language Choice}, for more -information about selecting the language for checks.) -@end defmac - -@defmac AC_CHECK_FUNCS (@var{function}@dots{} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) -@maindex CHECK_FUNCS -@cvindex HAVE_@var{function} -For each given @var{function} in the whitespace-separated argument list -that is available, define @code{HAVE_@var{function}} (in all capitals). If -@var{action-if-found} is given, it is additional shell code to execute -when one of the functions is found. You can give it a value of -@samp{break} to break out of the loop on the first match. If -@var{action-if-not-found} is given, it is executed when one of the -functions is not found. -@end defmac - -@defmac AC_REPLACE_FUNCS (@var{function-name}@dots{}) -@maindex REPLACE_FUNCS -@ovindex LIBOBJS -For each given @var{function-name} in the whitespace-separated argument -list that is not in the C library, add @samp{@var{function-name}.o} to -the value of the output variable @code{LIBOBJS}. -@end defmac - -@node Header Files, Structures, Library Functions, Existing Tests -@section Header Files - -The following macros check for the presence of certain C header files. -If there is no macro specifically defined to check for a header file you need, -and you don't need to check for any special properties of -it, then you can use one of the general header file check macros. - -@menu -* Particular Headers:: Special handling to find certain headers. -* Generic Headers:: How to find other headers. -@end menu - -@node Particular Headers, Generic Headers, , Header Files -@subsection Particular Header Checks - -These macros check for particular system header files---whether they -exist, and in some cases whether they declare certain symbols. - -@defmac AC_DECL_SYS_SIGLIST -@maindex DECL_SYS_SIGLIST -@cvindex SYS_SIGLIST_DECLARED -Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist} is -declared in a system header file, either @file{signal.h} or -@file{unistd.h}. -@end defmac - -@defmac AC_DIR_HEADER -@maindex DIR_HEADER -@cvindex DIRENT -@cvindex SYSDIR -@cvindex SYSNDIR -@cvindex NDIR -@cvindex VOID_CLOSEDIR -Like calling @code{AC_HEADER_DIRENT} and @code{AC_FUNC_CLOSEDIR_VOID}, -but defines a different set of C preprocessor macros to indicate which -header file is found. This macro and the names it defines are -considered obsolete. The names it defines are: - -@c The printed table looks too spaced out with blank lines between the entries. -@table @file -@item dirent.h -@code{DIRENT} -@item sys/ndir.h -@code{SYSNDIR} -@item sys/dir.h -@code{SYSDIR} -@item ndir.h -@code{NDIR} -@end table - -In addition, if the @code{closedir} function does not return a -meaningful value, define @code{VOID_CLOSEDIR}. -@end defmac - -@defmac AC_HEADER_DIRENT -@maindex HEADER_DIRENT -@cvindex HAVE_DIRENT_H -@cvindex HAVE_NDIR_H -@cvindex HAVE_SYS_DIR_H -@cvindex HAVE_SYS_NDIR_H -Check for the following header files, and for the first one that is -found and defines @samp{DIR}, define the listed C preprocessor macro: - -@c The printed table looks too spaced out with blank lines between the entries. -@table @file -@item dirent.h -@code{HAVE_DIRENT_H} -@item sys/ndir.h -@code{HAVE_SYS_NDIR_H} -@item sys/dir.h -@code{HAVE_SYS_DIR_H} -@item ndir.h -@code{HAVE_NDIR_H} -@end table - -The directory library declarations in the source code should look -something like the following: - -@example -@group -#if HAVE_DIRENT_H -# include <dirent.h> -# define NAMLEN(dirent) strlen((dirent)->d_name) -#else -# define dirent direct -# define NAMLEN(dirent) (dirent)->d_namlen -# if HAVE_SYS_NDIR_H -# include <sys/ndir.h> -# endif -# if HAVE_SYS_DIR_H -# include <sys/dir.h> -# endif -# if HAVE_NDIR_H -# include <ndir.h> -# endif -#endif -@end group -@end example - -Using the above declarations, the program would declare variables to be -type @code{struct dirent}, not @code{struct direct}, and would access -the length of a directory entry name by passing a pointer to a -@code{struct dirent} to the @code{NAMLEN} macro. - -This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. -@end defmac - -@defmac AC_HEADER_MAJOR -@maindex HEADER_MAJOR -@cvindex MAJOR_IN_MKDEV -@cvindex MAJOR_IN_SYSMACROS -If @file{sys/types.h} does not define @code{major}, @code{minor}, and -@code{makedev}, but @file{sys/mkdev.h} does, define -@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define -@code{MAJOR_IN_SYSMACROS}. -@end defmac - -@defmac AC_HEADER_STDC -@maindex HEADER_STDC -@cvindex STDC_HEADERS -Define @code{STDC_HEADERS} if the system has ANSI C header files. -Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, -@file{string.h}, and @file{float.h}; if the system has those, it -probably has the rest of the ANSI C header files. This macro also -checks whether @file{string.h} declares @code{memchr} (and thus -presumably the other @code{mem} functions), whether @file{stdlib.h} -declare @code{free} (and thus presumably @code{malloc} and other related -functions), and whether the @file{ctype.h} macros work on characters -with the high bit set, as ANSI C requires. - -Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether -the system has ANSI-compliant header files (and probably C library -functions) because many systems that have GCC do not have ANSI C header -files. - -On systems without ANSI C headers, there is so much variation that it is -probably easier to declare the functions you use than to figure out -exactly what the system header files declare. Some systems contain a -mix of functions ANSI and BSD; some are mostly ANSI but lack -@samp{memmove}; some define the BSD functions as macros in -@file{string.h} or @file{strings.h}; some have only the BSD functions -but @file{string.h}; some declare the memory functions in -@file{memory.h}, some in @file{string.h}; etc. It is probably -sufficient to check for one string function and one memory function; if -the library has the ANSI versions of those then it probably has most of -the others. If you put the following in @file{configure.in}: - -@example -AC_HEADER_STDC -AC_CHECK_FUNCS(strchr memcpy) -@end example - -@noindent -then, in your code, you can put declarations like this: - -@example -@group -#if STDC_HEADERS -# include <string.h> -#else -# ifndef HAVE_STRCHR -# define strchr index -# define strrchr rindex -# endif -char *strchr (), *strrchr (); -# ifndef HAVE_MEMCPY -# define memcpy(d, s, n) bcopy ((s), (d), (n)) -# define memmove(d, s, n) bcopy ((s), (d), (n)) -# endif -#endif -@end group -@end example - -@noindent -If you use a function like @code{memchr}, @code{memset}, @code{strtok}, -or @code{strspn}, which have no BSD equivalent, then macros won't -suffice; you must provide an implementation of each function. An easy -way to incorporate your implementations only when needed (since the ones -in system C libraries may be hand optimized) is to, taking @code{memchr} -for example, put it in @file{memchr.c} and use -@samp{AC_REPLACE_FUNCS(memchr)}. -@end defmac - -@defmac AC_HEADER_SYS_WAIT -@maindex HEADER_SYS_WAIT -@cvindex HAVE_SYS_WAIT_H -If @file{sys/wait.h} exists and is compatible with POSIX.1, define -@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} -does not exist, or if it uses the old BSD @code{union wait} instead of -@code{int} to store a status value. If @file{sys/wait.h} is not POSIX.1 -compatible, then instead of including it, define the POSIX.1 macros with -their usual interpretations. Here is an example: - -@example -@group -#include <sys/types.h> -#if HAVE_SYS_WAIT_H -# include <sys/wait.h> -#endif -#ifndef WEXITSTATUS -# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) -#endif -#ifndef WIFEXITED -# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) -#endif -@end group -@end example -@end defmac - -@defmac AC_MEMORY_H -@maindex MEMORY_H -@cvindex NEED_MEMORY_H -Define @code{NEED_MEMORY_H} if @code{memcpy}, @code{memcmp}, etc. are -not declared in @file{string.h} and @file{memory.h} exists. This macro -is obsolete; instead, use @code{AC_CHECK_HEADERS(memory.h)}. See the -example for @code{AC_HEADER_STDC}. -@end defmac - -@defmac AC_UNISTD_H -@maindex UNISTD_H -@cvindex HAVE_UNISTD_H -Define @code{HAVE_UNISTD_H} if the system has @file{unistd.h}. This -macro is obsolete; instead, use @samp{AC_CHECK_HEADERS(unistd.h)}. - -The way to check if the system supports POSIX.1 is: - -@example -@group -#if HAVE_UNISTD_H -# include <sys/types.h> -# include <unistd.h> -#endif - -#ifdef _POSIX_VERSION -/* Code for POSIX.1 systems. */ -#endif -@end group -@end example - -@cvindex _POSIX_VERSION -@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on -POSIX.1 systems. If there is no @file{unistd.h}, it is definitely not a -POSIX.1 system. However, some non-POSIX.1 systems do have @file{unistd.h}. -@end defmac - -@defmac AC_USG -@maindex USG -@cvindex USG -Define @code{USG} if the system does not have @file{strings.h}, -@code{rindex}, @code{bzero}, etc. This implies that it has -@file{string.h}, @code{strrchr}, @code{memset}, etc. - -The symbol @code{USG} is obsolete. Instead of this macro, see the -example for @code{AC_HEADER_STDC}. -@end defmac - -@node Generic Headers, , Particular Headers, Header Files -@subsection Generic Header Checks - -These macros are used to find system header files not covered by the -particular test macros. If you need to check the contents of a header -as well as find out whether it is present, you have to write your own -test for it (@pxref{Writing Tests}). - -@defmac AC_CHECK_HEADER (@var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex CHECK_HEADER -If the system header file @var{header-file} exists, execute shell commands -@var{action-if-found}, otherwise execute @var{action-if-not-found}. If -you just want to define a symbol if the header file is available, -consider using @code{AC_CHECK_HEADERS} instead. -@end defmac - -@defmac AC_CHECK_HEADERS (@var{header-file}@dots{} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) -@maindex CHECK_HEADERS -@cvindex HAVE_@var{header} -For each given system header file @var{header-file} in the -whitespace-separated argument list that exists, define -@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} -is given, it is additional shell code to execute when one of the header -files is found. You can give it a value of @samp{break} to break out of -the loop on the first match. If @var{action-if-not-found} is given, it -is executed when one of the header files is not found. -@end defmac - -@node Structures, Typedefs, Header Files, Existing Tests -@section Structures - -The following macros check for certain structures or structure members. -To check structures not listed here, use @code{AC_EGREP_CPP} -(@pxref{Examining Declarations}) or @code{AC_TRY_COMPILE} -(@pxref{Examining Syntax}). - -@defmac AC_HEADER_STAT -@maindex HEADER_STAT -@maindex STAT_MACROS_BROKEN -If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in -@file{sys/stat.h} do not work properly (returning false positives), -define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, -Amdahl UTS and Motorola System V/88. -@end defmac - -@defmac AC_HEADER_TIME -@maindex HEADER_TIME -@cvindex TIME_WITH_SYS_TIME -If a program may include both @file{time.h} and @file{sys/time.h}, -define @code{TIME_WITH_SYS_TIME}. On some older systems, -@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not -protected against multiple inclusion, so programs should not explicitly -include both files. This macro is useful in programs that use, for -example, @code{struct timeval} or @code{struct timezone} as well as -@code{struct tm}. It is best used in conjunction with -@code{HAVE_SYS_TIME_H}, which can be checked for using -@code{AC_CHECK_HEADERS(sys/time.h)}. - -@example -@group -#if TIME_WITH_SYS_TIME -# include <sys/time.h> -# include <time.h> -#else -# if HAVE_SYS_TIME_H -# include <sys/time.h> -# else -# include <time.h> -# endif -#endif -@end group -@end example -@end defmac - -@defmac AC_STRUCT_ST_BLKSIZE -@maindex STRUCT_ST_BLKSIZE -@cvindex HAVE_ST_BLKSIZE -If @code{struct stat} contains an @code{st_blksize} member, define -@code{HAVE_ST_BLKSIZE}. -@end defmac - -@defmac AC_STRUCT_ST_BLOCKS -@maindex STRUCT_ST_BLOCKS -@cvindex HAVE_ST_BLOCKS -@ovindex LIBOBJS -If @code{struct stat} contains an @code{st_blocks} member, define -@code{HAVE_ST_BLOCKS}. Otherwise, add @samp{fileblocks.o} to the -output variable @code{LIBOBJS}. -@end defmac - -@defmac AC_STRUCT_ST_RDEV -@maindex STRUCT_ST_RDEV -@cvindex HAVE_ST_RDEV -If @code{struct stat} contains an @code{st_rdev} member, define -@code{HAVE_ST_RDEV}. -@end defmac - -@defmac AC_STRUCT_TM -@maindex STRUCT_TM -@cvindex TM_IN_SYS_TIME -If @file{time.h} does not define @code{struct tm}, define -@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} -had better define @code{struct tm}. -@end defmac - -@defmac AC_STRUCT_TIMEZONE -@maindex STRUCT_TIMEZONE -@cvindex HAVE_TM_ZONE -@cvindex HAVE_TZNAME -Figure out how to get the current timezone. If @code{struct tm} has a -@code{tm_zone} member, define @code{HAVE_TM_ZONE}. Otherwise, if the -external array @code{tzname} is found, define @code{HAVE_TZNAME}. -@end defmac - -@node Typedefs, Compiler Characteristics, Structures, Existing Tests -@section Typedefs - -The following macros check for C typedefs. If there is no macro -specifically defined to check for a typedef you need, and you don't need -to check for any special properties of it, then you can use a general -typedef check macro. - -@menu -* Particular Typedefs:: Special handling to find certain types. -* Generic Typedefs:: How to find other types. -@end menu - -@node Particular Typedefs, Generic Typedefs, , Typedefs -@subsection Particular Typedef Checks - -These macros check for particular C typedefs in @file{sys/types.h} and -@file{stdlib.h} (if it exists). - -@defmac AC_TYPE_GETGROUPS -@maindex TYPE_GETGROUPS -@cvindex GETGROUPS_T -Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} -is the base type of the array argument to @code{getgroups}. -@end defmac - -@defmac AC_TYPE_MODE_T -@maindex TYPE_MODE_T -@cvindex mode_t -If @code{mode_t} is not defined, define @code{mode_t} to be @code{int}. -@end defmac - -@defmac AC_TYPE_OFF_T -@maindex TYPE_OFF_T -@cvindex off_t -If @code{off_t} is not defined, define @code{off_t} to be @code{long}. -@end defmac - -@defmac AC_TYPE_PID_T -@maindex TYPE_PID_T -@cvindex pid_t -If @code{pid_t} is not defined, define @code{pid_t} to be @code{int}. -@end defmac - -@defmac AC_TYPE_SIGNAL -@maindex TYPE_SIGNAL -@cvindex RETSIGTYPE -If @file{signal.h} declares @code{signal} as returning a pointer to a -function returning @code{void}, define @code{RETSIGTYPE} to be -@code{void}; otherwise, define it to be @code{int}. - -Define signal handlers as returning type @code{RETSIGTYPE}: - -@example -@group -RETSIGTYPE -hup_handler () -@{ -@dots{} -@} -@end group -@end example -@end defmac - -@defmac AC_TYPE_SIZE_T -@maindex TYPE_SIZE_T -@cvindex size_t -If @code{size_t} is not defined, define @code{size_t} to be -@code{unsigned}. -@end defmac - -@defmac AC_TYPE_UID_T -@maindex TYPE_UID_T -@cvindex uid_t -@cvindex gid_t -If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and -@code{gid_t} to be @code{int}. -@end defmac - -@node Generic Typedefs, , Particular Typedefs, Typedefs -@subsection Generic Typedef Checks - -This macro is used to check for typedefs not covered by the particular -test macros. - -@defmac AC_CHECK_TYPE (@var{type}, @var{default}) -@maindex CHECK_TYPE -If the type @var{type} is not defined in @file{sys/types.h} or -@file{stdlib.h} (if it exists), define it to be the C (or C++) -builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}. -@end defmac - -@node Compiler Characteristics, System Services, Typedefs, Existing Tests -@section Compiler Characteristics - -The following macros check for C compiler or machine architecture -features. To check for characteristics not listed here, use -@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN} -(@pxref{Run Time}) - -@defmac AC_C_BIGENDIAN -@maindex C_BIGENDIAN -@cvindex WORDS_BIGENDIAN -If words are stored with the most significant byte first (like Motorola -and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}. -@end defmac - -@defmac AC_C_CONST -@maindex C_CONST -@cvindex const -If the C compiler does not fully support the keyword @code{const}, -define @code{const} to be empty. Some C compilers that do not define -@code{__STDC__} do support @code{const}; some compilers that define -@code{__STDC__} do not completely support @code{const}. Programs can -simply use @code{const} as if every C compiler supported it; for those -that don't, the @file{Makefile} or configuration header file will define -it as empty. -@end defmac - -@defmac AC_C_INLINE -@maindex C_INLINE -@cvindex inline -If the C compiler is a version of GCC that supports the keyword -@code{__inline} but not @code{inline} (such as some NeXT versions), -define @code{inline} to be @code{__inline}. -@end defmac - -@defmac AC_C_CHAR_UNSIGNED -@maindex C_CHAR_UNSIGNED -@cvindex __CHAR_UNSIGNED__ -If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, -unless the C compiler predefines it. -@end defmac - -@defmac AC_C_LONG_DOUBLE -@maindex C_LONG_DOUBLE -@cvindex HAVE_LONG_DOUBLE -If the C compiler supports the @code{long double} type, define -@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define -@code{__STDC__} do support the @code{long double} type; some compilers -that define @code{__STDC__} do not support @code{long double}. -@end defmac - -@defmac AC_CHECK_SIZEOF (@var{type}) -@maindex CHECK_SIZEOF -Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or -C++) builtin type @var{type}, e.g. @samp{int} or @samp{char *}. If -@samp{type} is unknown to the compiler, it gets a size of 0. @var{uctype} -is @var{type}, with lowercase converted to uppercase, spaces changed to -underscores, and asterisks changed to @samp{P}. For example, the call -@example -AC_CHECK_SIZEOF(int *) -@end example -@noindent -defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. -@end defmac - -@defmac AC_INT_16_BITS -@maindex INT_16_BITS -@cvindex INT_16_BITS -If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. -This macro is obsolete; it is more general to use -@samp{AC_CHECK_SIZEOF(int)} instead. -@end defmac - -@defmac AC_LONG_64_BITS -@maindex LONG_64_BITS -@cvindex LONG_64_BITS -If the C type @code{long int} is 64 bits wide, define -@code{LONG_64_BITS}. This macro is obsolete; it is more general to use -@samp{AC_CHECK_SIZEOF(long)} instead. -@end defmac - -@node System Services, UNIX Variants, Compiler Characteristics, Existing Tests -@section System Services - -The following macros check for operating system services or capabilities. - -@defmac AC_SYS_INTERPRETER -@maindex SYS_INTERPRETER -Check whether the system supports starting scripts with a line of the -form @samp{#!/bin/csh} to select the interpreter to use for the script. -After running this macro, shell code in @code{configure.in} can check -the variable @code{ac_cv_sys_interpreter}; it will be set to @samp{yes} -if the system supports @samp{#!}, @samp{no} if not. -@end defmac - -@defmac AC_PATH_X -@maindex PATH_X -Try to locate the X Window System include files and libraries. If the -user gave the command line options @samp{--x-includes=@var{dir}} and -@samp{--x-libraries=@var{dir}}, use those directories. If either or -both were not given, get the missing values by running @code{xmkmf} on a -trivial @file{Imakefile} and examining the @file{Makefile} that it -produces. If that fails (such as if @code{xmkmf} is not present), look -for them in several directories where they often reside. If either -method is successful, set the shell variables @code{x_includes} and -@code{x_libraries} to their locations, unless they are in directories -the compiler searches by default. - -If both methods fail, or the user gave the command line option -@samp{--without-x}, set the shell variable @code{no_x} to @samp{yes}; -otherwise set it to the empty string. -@end defmac - -@defmac AC_PATH_XTRA -@maindex PATH_XTRA -@ovindex X_CFLAGS -@ovindex X_LIBS -@ovindex X_EXTRA_LIBS -@ovindex X_PRE_LIBS -An enhanced version of @code{AC_PATH_X}. Add the C compiler flags that -X needs to output variable @code{X_CFLAGS}, and the X linker flags to -@code{X_LIBS}. If X is not available, add @samp{-DX_DISPLAY_MISSING} to -@code{X_CFLAGS}. - -Also check for special libraries that some systems need in order to -compile X programs. Add any that the system needs to output variable -@code{X_EXTRA_LIBS}. And check for special X11R6 libraries that need to -be linked with before @samp{-lX11}, and add any found to the output -variable @code{X_PRE_LIBS}. -@end defmac - -@defmac AC_SYS_LONG_FILE_NAMES -@maindex SYS_LONG_FILE_NAMES -@cvindex HAVE_LONG_FILE_NAMES -If the system supports file names longer than 14 characters, define -@code{HAVE_LONG_FILE_NAMES}. -@end defmac - -@defmac AC_SYS_RESTARTABLE_SYSCALLS -@maindex SYS_RESTARTABLE_SYSCALLS -@cvindex HAVE_RESTARTABLE_SYSCALLS -If the system automatically restarts a system call that is interrupted -by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. -@end defmac - -@node UNIX Variants, , System Services, Existing Tests -@section UNIX Variants - -The following macros check for certain operating systems that need -special treatment for some programs, due to exceptional oddities in -their header files or libraries. These macros are warts; they will be -replaced by a more systematic approach, based on the functions they make -available or the environments they provide. - -@defmac AC_AIX -@maindex AIX -@cvindex _ALL_SOURCE -If on AIX, define @code{_ALL_SOURCE}. Allows the use of some BSD -functions. Should be called before any macros that run the C compiler. -@end defmac - -@defmac AC_DYNIX_SEQ -@maindex DYNIX_SEQ -If on Dynix/PTX (Sequent UNIX), add @samp{-lseq} to output -variable @code{LIBS}. This macro is obsolete; instead, use -@code{AC_FUNC_GETMNTENT}. -@end defmac - -@defmac AC_IRIX_SUN -@maindex IRIX_SUN -If on IRIX (Silicon Graphics UNIX), add @samp{-lsun} to output variable -@code{LIBS}. This macro is obsolete. If you were using it to get -@code{getmntent}, use @code{AC_FUNC_GETMNTENT} instead. If you used it -for the NIS versions of the password and group functions, use -@samp{AC_CHECK_LIB(sun, getpwnam)}. -@end defmac - -@defmac AC_ISC_POSIX -@maindex ISC_POSIX -@cvindex _POSIX_SOURCE -@ovindex CC -If on a POSIXized ISC UNIX, define @code{_POSIX_SOURCE} and add -@samp{-posix} (for the GNU C compiler) or @samp{-Xp} (for other C -compilers) to output variable @code{CC}. This allows the use of -POSIX facilities. Must be called after @code{AC_PROG_CC} and before -any other macros that run the C compiler. -@end defmac - -@defmac AC_MINIX -@maindex MINIX -@cvindex _MINIX -@cvindex _POSIX_SOURCE -@cvindex _POSIX_1_SOURCE -If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define -@code{_POSIX_1_SOURCE} to be 2. This allows the use of POSIX -facilities. Should be called before any macros that run the C compiler. -@end defmac - -@defmac AC_SCO_INTL -@maindex SCO_INTL -@ovindex LIBS -If on SCO UNIX, add @samp{-lintl} to output variable @code{LIBS}. -This macro is obsolete; instead, use @code{AC_FUNC_STRFTIME}. -@end defmac - -@defmac AC_XENIX_DIR -@maindex XENIX_DIR -@ovindex LIBS -If on Xenix, add @samp{-lx} to output variable @code{LIBS}. Also, if -@file{dirent.h} is being used, add @samp{-ldir} to @code{LIBS}. This -macro is obsolete; use @code{AC_HEADER_DIRENT} instead. -@end defmac - -@node Writing Tests, Results, Existing Tests, Top -@chapter Writing Tests - -If the existing feature tests don't do something you need, you have to -write new ones. These macros are the building blocks. They provide -ways for other macros to check whether various kinds of features are -available and report the results. - -This chapter contains some suggestions and some of the reasons why the -existing tests are written the way they are. You can also learn a lot -about how to write Autoconf tests by looking at the existing ones. If -something goes wrong in one or more of the Autoconf tests, this -information can help you understand the assumptions behind them, which -might help you figure out how to best solve the problem. - -These macros check the output of the C compiler system. They do -not cache the results of their tests for future use (@pxref{Caching -Results}), because they don't know enough about the information they are -checking for to generate a cache variable name. They also do not print -any messages, for the same reason. The checks for particular kinds of C -features call these macros and do cache their results and print messages -about what they're checking for. - -@menu -* 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. -@end menu - -@node Examining Declarations, Examining Syntax, , Writing Tests -@section Examining Declarations - -The macro @code{AC_TRY_CPP} is used to check whether particular header -files exist. You can check for one at a time, or more than one if you -need several header files to all exist for some purpose. - -@defmac AC_TRY_CPP (@var{includes}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) -@maindex TRY_CPP -@var{includes} is C or C++ @code{#include} statements and declarations, -on which shell variable, backquote, and backslash substitutions are -performed. (Actually, it can be any C program, but other statements are -probably not useful.) If the preprocessor produces no error messages -while processing it, run shell commands @var{action-if-true}. Otherwise -run shell commands @var{action-if-false}. - -This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because -@samp{-g}, @samp{-O}, etc. are not valid options to many C -preprocessors. -@end defmac - -Here is now to find out whether a header file contains a particular -declaration, such as a typedef, a structure, a structure member, or a -function. Use @code{AC_EGREP_HEADER} instead of running @code{grep} -directly on the header file; on some systems the symbol might be defined -in another header file that the file you are checking @samp{#include}s. - -@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex EGREP_HEADER -If the output of running the preprocessor on the system header file -@var{header-file} matches the @code{egrep} regular expression -@var{pattern}, execute shell commands @var{action-if-found}, otherwise -execute @var{action-if-not-found}. -@end defmac - -To check for C preprocessor symbols, either defined by header files or -predefined by the C preprocessor, use @code{AC_EGREP_CPP}. Here is an -example of the latter: - -@example -AC_EGREP_CPP(yes, -[#ifdef _AIX - yes -#endif -], is_aix=yes, is_aix=no) -@end example - -@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex EGREP_CPP -@var{program} is the text of a C or C++ program, on which shell -variable, backquote, and backslash substitutions are performed. If the -output of running the preprocessor on @var{program} matches the -@code{egrep} regular expression @var{pattern}, execute shell commands -@var{action-if-found}, otherwise execute @var{action-if-not-found}. - -This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending -on which language is current, @pxref{Language Choice}), if it hasn't -been called already. -@end defmac - -@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests -@section Examining Syntax - -To check for a syntax feature of the C or C++ compiler, such as whether -it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to try to -compile a small program that uses that feature. You can also use it to -check for structures and structure members that are not present on all -systems. - -@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex TRY_COMPILE -Create a test C program to see whether a function whose body consists of -@var{function-body} can be compiled; @var{includes} is any -@code{#include} statements needed by the code in @var{function-body}. -If the file compiles successfully, run shell commands -@var{action-if-found}, otherwise run @var{action-if-not-found}. This -macro uses @code{CFLAGS} or @code{CXXFLAGS}, and @code{CPPFLAGS}, when -compiling. It does not try to link; use @code{AC_TRY_LINK} if you need -to do that (@pxref{Examining Libraries}). -@end defmac - -@node Examining Libraries, Run Time, Examining Syntax, Writing Tests -@section Examining Libraries - -To check for a library, a function, or a global variable, Autoconf -@code{configure} scripts try to compile and link a small program that -uses it. This is unlike Metaconfig, which by default uses @code{nm} -or @code{ar} on the C library to try to figure out which functions are -available. Trying to link with the function is usually a more reliable -approach because it avoids dealing with the variations in the options -and output formats of @code{nm} and @code{ar} and in the location of the -standard libraries. It also allows configuring for cross-compilation or -checking a function's runtime behavior if needed. On the other hand, it -can be slower than scanning the libraries once. - -A few systems have linkers that do not return a failure exit status when -there are unresolved functions in the link. This bug makes the -configuration scripts produced by Autoconf unusable on those systems. -However, some of them can be given options that make the exit status -correct. This is a problem that Autoconf does not currently handle -automatically. - -@code{AC_TRY_LINK} is used to compile test programs to test for -functions and global variables. It is also used (by -@code{AC_CHECK_LIB}) to check for libraries, by adding the library being -checked for to @code{LIBS} temporarily and trying to link a small -program. - -@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex TRY_LINK -Create a test C program to see whether a function whose body consists of -@var{function-body} can be compiled and linked; @var{includes} is any -@code{#include} statements needed by the code in @var{function-body}. -If the file compiles and links successfully, run shell commands -@var{action-if-found}, otherwise run @var{action-if-not-found}. This -macro uses @code{CFLAGS} or @code{CXXFLAGS}, @code{CPPFLAGS}, -@code{LDFLAGS}, and @code{LIBS} when compiling. -@end defmac - -@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) -@maindex COMPILE_CHECK -This is an obsolete version of @code{AC_TRY_LINK}, with the addition that it -prints @samp{checking for @var{echo-text}} to the standard output first, -if @var{echo-text} is non-empty. Use @code{AC_MSG_CHECKING} and -@code{AC_MSG_RESULT} instead to print messages (@pxref{Printing Messages}). -@end defmac - -@node Run Time, Portable Shell, Examining Libraries, Writing Tests -@section Checking Run Time Behavior - -Sometimes you need to find out how a system performs at run time, such -as whether a given function has a certain capability or bug. If you -can, make such checks when your program runs instead of when it is -configured. You can check for things like the machine's endianness when -your program initializes itself. - -If you really need to test for a run-time behavior while configuring, -you can write a test program to determine the result, and compile and -run it using @code{AC_TRY_RUN}. Avoid running test programs if -possible, because using them prevents people from configuring your -package for cross-compiling. - -@menu -* Test Programs:: Running test programs. -* Guidelines:: General rules for writing test programs. -* Test Functions:: Avoiding pitfalls in test programs. -@end menu - -@node Test Programs, Guidelines, , Run Time -@subsection Running Test Programs - -Use the following macro if you need to test run-time behavior of the -system while configuring. - -@defmac AC_TRY_RUN (@var{program}, @var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]}) -@maindex TRY_RUN -@var{program} is the text of a C program, on which shell variable and -backquote substitutions are performed. If it compiles and links -successfully and returns an exit status of 0 when executed, run shell -commands @var{action-if-true}. Otherwise run shell commands -@var{action-if-false}; the exit status of the program is available in -the shell variable @samp{$?}. This macro uses @code{CFLAGS} or -@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when -compiling. - -If the C compiler being used does not produce executables that run on -the system where @code{configure} is being run, then the test program is -not run. If the optional shell commands @var{action-if-cross-compiling} -are given, they are run instead and this macro calls @code{AC_C_CROSS} -if it has not already been called. Otherwise, @code{configure} prints -an error message and exits. -@end defmac - -Try to provide a pessimistic default value to use when cross-compiling -makes run-time tests impossible. You do this by passing the optional -last argument to @code{AC_TRY_RUN}. @code{autoconf} prints a warning -message when creating @code{configure} each time it encounters a call to -@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument -given. You may ignore the warning, though users will not be able to -configure your package for cross-compiling. A few of the macros -distributed with Autoconf produce this warning message. - -To configure for cross-compiling you can also choose a value for those -parameters based on the canonical system name (@pxref{Manual -Configuration}). Alternatively, set up a test results cache file with -the correct values for the target system (@pxref{Caching Results}). - -To provide a default for calls of @code{AC_TRY_RUN} that are embedded in -other macros, including a few of the ones that come with Autoconf, you -can call @code{AC_C_CROSS} before running them. Then, if the shell -variable @code{cross_compiling} is set to @samp{yes}, use an alternate -method to get the results instead of calling the macros. - -@defmac AC_C_CROSS -@maindex C_CROSS -If the C compiler being used does not produce executables that can run -on the system where @code{configure} is being run, set the shell -variable @code{cross_compiling} to @samp{yes}, otherwise @samp{no}. -@end defmac - -@node Guidelines, Test Functions, Test Programs, Run Time -@subsection Guidelines for Test Programs - -Test programs should not write anything to the standard output. They -should return 0 if the test succeeds, nonzero otherwise, so that success -can be distinguished easily from a core dump or other failure; -segmentation violations and other failures produce a nonzero exit -status. Test programs should @code{exit}, not @code{return}, from -@code{main}, because on some systems (old Suns, at least) the argument -to @code{return} in @code{main} is ignored. - -Test programs can use @code{#if} or @code{#ifdef} to check the values of -preprocessor macros defined by tests that have already run. For -example, if you call @code{AC_HEADER_STDC}, then later on in -@file{configure.in} you can have a test program that includes an ANSI C -header file conditionally: - -@example -@group -#if STDC_HEADERS -# include <stdlib.h> -#endif -@end group -@end example - -If a test program needs to use or create a data file, give it a name -that starts with @file{conftest}, such as @file{conftestdata}. The -@code{configure} script cleans up by running @samp{rm -rf conftest*} -after running test programs and if the script is interrupted. - -@node Test Functions, , Guidelines, Run Time -@subsection Test Functions - -Function declarations in test programs should have a prototype -conditionalized for C++. In practice, though, test programs rarely need -functions that take arguments. - -@example -#ifdef __cplusplus -foo(int i) -#else -foo(i) int i; -#endif -@end example - -Functions that test programs declare should also be conditionalized for -C++, which requires @samp{extern "C"} prototypes. Make sure to not -include any header files containing clashing prototypes. - -@example -#ifdef __cplusplus -extern "C" void *malloc(size_t); -#else -char *malloc(); -#endif -@end example - -If a test program calls a function with invalid parameters (just to see -whether it exists), organize the program to ensure that it never invokes -that function. You can do this by calling it in another function that is -never invoked. You can't do it by putting it after a call to -@code{exit}, because GCC version 2 knows that @code{exit} never returns -and optimizes out any code that follows it in the same block. - -If you include any header files, make sure to call the functions -relevant to them with the correct number of arguments, even if they are -just 0, to avoid compilation errors due to prototypes. GCC version 2 -has internal prototypes for several functions that it automatically -inlines; for example, @code{memcpy}. To avoid errors when checking for -them, either pass them the correct number of arguments or redeclare them -with a different return type (such as @code{char}). - -@node Portable Shell, Testing Values and Files, Run Time, Writing Tests -@section Portable Shell Programming - -When writing your own checks, there are some shell script programming -techniques you should avoid in order to make your code portable. The -Bourne shell and upward-compatible shells like Bash and the Korn shell -have evolved over the years, but to prevent trouble, do not take -advantage of features that were added after UNIX version 7, circa 1977. -You should not use shell functions, aliases, negated character classes, -or other features that are not found in all Bourne-compatible shells; -restrict yourself to the lowest common denominator. Even @code{unset} -is not supported by all shells! - -The set of external programs you should run in a @code{configure} script -is fairly small. @xref{Utilities in Makefiles, , Utilities in -Makefiles, standards.info, GNU Coding Standards}, for the list. This -restriction allows users to start out with a fairly small set of -programs and build the rest, avoiding too many interdependencies between -packages. - -Some of these external utilities have a portable subset of features, as -well; for example, don't rely on @code{ln} having a @samp{-f} option or -@code{cat} having any options. @code{sed} scripts should not contain -comments or use branch labels longer than 8 characters. Don't use -@samp{grep -s} to suppress output, because @samp{grep -s} on System V -does not suppress output, only error messages. Instead, redirect the -standard output and standard error (in case the file doesn't exist) of -@code{grep} to @file{/dev/null}. Check the exit status of @code{grep} -to determine whether it found a match. - -@node Testing Values and Files, Multiple Cases, Portable Shell, Writing Tests -@section Testing Values and Files - -@code{configure} scripts need to test properties of many files and -strings. Here are some portability problems to watch out for when doing -those tests. - -The @code{test} program is the way to perform many file and string -tests. It is often invoked by the alternate name @samp{[}, but using -that name in Autoconf code is asking for trouble since it is an -@code{m4} quote character. - -If you need to make multiple checks using @code{test}, combine -them with the shell operators @samp{&&} and @samp{||} instead of using -the @code{test} operators @samp{-a} and @samp{-o}. On System V, the -precedence of @samp{-a} and @samp{-o} is wrong relative to the unary -operators; consequently, POSIX does not specify them, so using them is -nonportable. If you combine @samp{&&} and @samp{||} in the same -statement, keep in mind that they have equal precedence. - -To enable @code{configure} scripts to support cross-compilation, they -shouldn't do anything that tests features of the host system instead of -the target system. But occasionally you may find it necessary to check -whether some arbitrary file exists. To do so, use @samp{test -f} or -@samp{test -r}. Do not use @samp{test -x}, because 4.3BSD does not have -it. - -Another nonportable shell programming construction is -@example -@var{var}=$@{@var{var}:-@var{value}@} -@end example -@noindent -The intent is to set @var{var} to @var{value} only if it is not already -set, but if @var{var} has any value, even the empty string, to leave it -alone. Old BSD shells, including the Ultrix @code{sh}, don't accept -the colon, and complain and die. A portable equivalent is -@example -: $@{@var{var}=@var{value}@} -@end example - -@node Multiple Cases, Language Choice, Testing Values and Files, Writing Tests -@section Multiple Cases - -Some operations are accomplished in several possible ways, depending on -the UNIX variant. Checking for them essentially requires a ``case -statement''. Autoconf does not directly provide one; however, it is -easy to simulate by using a shell variable to keep track of whether a -way to perform the operation has been found yet. - -Here is an example that uses the shell variable @code{fstype} to keep -track of whether the remaining cases need to be checked. - -@example -@group -AC_MSG_CHECKING(how to get filesystem type) -fstype=no -# The order of these tests is important. -AC_TRY_CPP([#include <sys/statvfs.h> -#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) -if test $fstype = no; then -AC_TRY_CPP([#include <sys/statfs.h> -#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) -fi -if test $fstype = no; then -AC_TRY_CPP([#include <sys/statfs.h> -#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX) -fi -# (more cases omitted here) -AC_MSG_RESULT($fstype) -@end group -@end example - -@node Language Choice, , Multiple Cases, Writing Tests -@section Language Choice - -Packages that use both C and C++ need to test features of both -compilers. Autoconf-generated @code{configure} scripts check for C -features by default. The following macros determine which language's -compiler is used in tests that follow in @file{configure.in}. - -@defmac AC_LANG_C -@maindex LANG_C -Do compilation tests using @code{CC} and @code{CPP} and use extension -@file{.c} for test programs. -@end defmac - -@defmac AC_LANG_CPLUSPLUS -@maindex LANG_CPLUSPLUS -Do compilation tests using @code{CXX} and @code{CXXCPP} and use -extension @file{.C} for test programs. -@end defmac - -@defmac AC_LANG_SAVE -@maindex LANG_SAVE -Remember the current language (as set by @code{AC_LANG_C} or -@code{AC_LANG_CPLUSPLUS}) on a stack. Does not change which language is -current. Use this macro and @code{AC_LANG_RESTORE} in macros that need -to temporarily switch to a particular language. -@end defmac - -@defmac AC_LANG_RESTORE -@maindex LANG_RESTORE -Select the language that is saved on the top of the stack, as set by -@code{AC_LANG_SAVE}, and remove it from the stack. This macro is -equivalent to either @code{AC_LANG_C} or @code{AC_LANG_CPLUSPLUS}, -whichever had been run most recently when @code{AC_LANG_SAVE} was last -called. - -Do not call this macro more times than @code{AC_LANG_SAVE}. -@end defmac - -@defmac AC_REQUIRE_CPP -@maindex REQUIRE_CPP -Ensure that whichever preprocessor would currently be used for tests has -been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an -argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, -depending on which language is current. -@end defmac - -@node Results, Writing Macros, Writing Tests, Top -@chapter Results of Tests - -Once @code{configure} has determined whether a feature exists, what can -it do to record that information? There are four sorts of things it can -do: define a C preprocessor symbol, set a variable in the output files, -save the result in a cache file for future @code{configure} runs, and -print a message letting the user know the result of the test. - -@menu -* Defining Symbols:: Defining C preprocessor symbols. -* Setting Output Variables:: Replacing variables in output files. -* Caching Results:: Speeding up subsequent @code{configure} runs. -* Printing Messages:: Notifying users of progress or problems. -@end menu - -@node Defining Symbols, Setting Output Variables, , Results -@section Defining C Preprocessor Symbols - -A common action to take in response to a feature test is to define a C -preprocessor symbol indicating the results of the test. That is done by -calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. - -By default, @code{AC_OUTPUT} places the symbols defined by these macros -into the output variable @code{DEFS}, which contains an option -@samp{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in -Autoconf version 1, there is no variable @code{DEFS} defined while -@code{configure} is running. To check whether Autoconf macros have -already defined a certain C preprocessor symbol, test the value of the -appropriate cache variable, as in this example: - -@example -AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF)) -if test "$ac_cv_func_vprintf" != yes; then -AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT)) -fi -@end example - -If @code{AC_CONFIG_HEADER} has been called, then instead of creating -@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the -correct values into @code{#define} statements in a template file. -@xref{Configuration Headers}, for more information about this kind of -output. - -@defmac AC_DEFINE (@var{variable} @r{[}, @var{value}@r{]}) -@maindex DEFINE -Define C preprocessor variable @var{variable}. If @var{value} is given, -set @var{variable} to that value (verbatim), otherwise set it to 1. -@var{value} should not contain literal newlines, and if you are not -using @code{AC_CONFIG_HEADER} it should not contain any @samp{#} -characters, as @code{make} tends to eat them. To use a shell variable -(which you need to do in order to define a value containing the -@code{m4} quote characters @samp{[} or @samp{]}), use -@code{AC_DEFINE_UNQUOTED} instead. The following example defines the C -preprocessor variable @code{EQUATION} to be the string constant -@samp{"$a > $b"}: - -@example -AC_DEFINE(EQUATION, "$a > $b") -@end example -@end defmac - -@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value}@r{]}) -@maindex DEFINE_UNQUOTED -Like @code{AC_DEFINE}, but three shell expansions are -performed---once---on @var{variable} and @var{value}: variable expansion -(@samp{$}), command substitution (@samp{`}), and backslash escaping -(@samp{\}). Single and double quote characters in the value have no -special meaning. Use this macro instead of @code{AC_DEFINE} when -@var{variable} or @var{value} is a shell variable. Examples: - -@example -AC_DEFINE_UNQUOTED(config_machfile, "$@{machfile@}") -AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) -AC_DEFINE_UNQUOTED($@{ac_tr_hdr@}) -@end example -@end defmac - -Due to the syntactical bizarreness of the Bourne shell, do not use -semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} -calls from other macro calls or shell code; that can cause syntax errors -in the resulting @code{configure} script. Use either spaces or -newlines. That is, do this: - -@example -AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") -@end example - -@noindent -or this: - -@example -AC_CHECK_HEADER(elf.h, - AC_DEFINE(SVR4) - LIBS="$LIBS -lelf") -@end example - -@noindent -instead of this: - -@example -AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") -@end example - -@node Setting Output Variables, Caching Results, Defining Symbols, Results -@section Setting Output Variables - -One way to record the results of tests is to set @dfn{output variables}, -which are shell variables whose values are substituted into files that -@code{configure} outputs. The two macros below create new output -variables. @xref{Preset Output Variables}, for a list of output -variables that are always available. - -@defmac AC_SUBST (@var{variable}) -@maindex SUBST -Create an output variable from a shell variable. Make @code{AC_OUTPUT} -substitute the variable @var{variable} into output files (typically one -or more @file{Makefile}s). This means that @code{AC_OUTPUT} will -replace instances of @samp{@@@var{variable}@@} in input files with the -value that the shell variable @var{variable} has when @code{AC_OUTPUT} -is called. The value of @var{variable} should not contain literal -newlines. -@end defmac - -@defmac AC_SUBST_FILE (@var{variable}) -@maindex SUBST_FILE -Another way to create an output variable from a shell variable. Make -@code{AC_OUTPUT} insert (without substitutions) the contents of the file -named by shell variable @var{variable} into output files. This means -that @code{AC_OUTPUT} will replace instances of -@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) -with the contents of the file that the shell variable @var{variable} -names when @code{AC_OUTPUT} is called. Set the variable to -@file{/dev/null} for cases that do not have a file to insert. - -This macro is useful for inserting @file{Makefile} fragments containing -special dependencies or other @code{make} directives for particular host -or target types into @file{Makefile}s. For example, @file{configure.in} -could contain: - -@example -AC_SUBST_FILE(host_frag)dnl -host_frag=$srcdir/conf/sun4.mh -@end example - -@noindent -and then a @file{Makefile.in} could contain: - -@example -@@host_frag@@ -@end example -@end defmac - -@node Caching Results, Printing Messages, Setting Output Variables, Results -@section Caching Results - -To avoid checking for the same features repeatedly in various -@code{configure} scripts (or repeated runs of one script), -@code{configure} saves the results of many of its checks in a @dfn{cache -file}. If, when a @code{configure} script runs, it finds a cache file, -it reads from it the results from previous runs and avoids rerunning -those checks. As a result, @code{configure} can run much faster than if -it had to perform all of the checks every time. - -@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) -@maindex CACHE_VAL -Ensure that the results of the check identified by @var{cache-id} are -available. If the results of the check were in the cache file that was -read, and @code{configure} was not given the @samp{--quiet} or -@samp{--silent} option, print a message saying that the result was -cached; otherwise, run the shell commands @var{commands-to-set-it}. -Those commands should have no side effects except for setting the -variable @var{cache-id}. In particular, they should not call -@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL} -should do that, based on the cached value. Also, they should not print -any messages, for example with @code{AC_MSG_CHECKING}; do that before -calling @code{AC_CACHE_VAL}, so the messages are printed regardless of -whether the results of the check are retrieved from the cache or -determined by running the shell commands. If the shell commands are run -to determine the value, the value will be saved in the cache file just -before @code{configure} creates its output files. @xref{Cache -Variable Names}, for how to choose the name of the @var{cache-id} variable. -@end defmac - -@menu -* Cache Variable Names:: Shell variables used in caches. -* Cache Files:: Files @code{configure} uses for caching. -@end menu - -@node Cache Variable Names, Cache Files, , Caching Results -@subsection Cache Variable Names - -The names of cache variables should have the following format: - -@example -@var{package-prefix}_cv_@var{value-type}_@var{specific-value}@r{[}_@var{additional-options}@r{]} -@end example - -@noindent -for example, @samp{ac_cv_header_stat_broken} or -@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: - -@table @asis -@item @var{package-prefix} -An abbreviation for your package or organization; the same prefix you -begin local Autoconf macros with, except lowercase by convention. -For cache values used by the distributed Autoconf macros, this value is -@samp{ac}. - -@item @code{_cv_} -Indicates that this shell variable is a cache value. - -@item @var{value-type} -A convention for classifying cache values, to produce a rational naming -system. The values used in Autoconf are listed in @ref{Macro Names}. - -@item @var{specific-value} -Which member of the class of cache values this test applies to. -For example, which function (@samp{alloca}), program (@samp{gcc}), or -output variable (@samp{INSTALL}). - -@item @var{additional-options} -Any particular behavior of the specific member that this test applies to. -For example, @samp{broken} or @samp{set}. This part of the name may -be omitted if it does not apply. -@end table - -Like their names, the values that may be assigned to cache variables -have a few restrictions. The values may not contain single quotes or -curly braces. Usually, their values will be boolean (@samp{yes} or -@samp{no}) or the names of files or functions; so this is not an -important restriction. - -@node Cache Files, , Cache Variable Names, Caching Results -@subsection Cache Files - -A cache file is a shell script that caches the results of configure -tests run on one system so they can be shared between configure scripts -and configure runs. It is not useful on other systems. If its contents -are invalid for some reason, the user may delete or edit it. - -By default, configure uses @file{./config.cache} as the cache file, -creating it if it does not exist already. @code{configure} accepts the -@samp{--cache-file=@var{file}} option to use a different cache file; -that is what @code{configure} does when it calls @code{configure} -scripts in subdirectories, so they share the cache. Giving -@samp{--cache-file=/dev/null} disables caching, for debugging -@code{configure}. @xref{Subdirectories}, for information on configuring -subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. -@file{config.status} only pays attention to the cache file if it is -given the @samp{--recheck} option, which makes it rerun -@code{configure}. - -It is wrong to try to distribute cache files for particular system types. -There is too much room for error in doing that, and too much -administrative overhead in maintaining them. For any features that -can't be guessed automatically, use the standard method of the canonical -system type and linking files (@pxref{Manual Configuration}). - -The cache file on a particular system will gradually accumulate whenever -someone runs a @code{configure} script; it will be initially -nonexistent. Running @code{configure} merges the new cache results with -the existing cache file. The site initialization script can specify a -site-wide cache file to use instead of the default, to make it work -transparently, as long as the same C compiler is used every time -(@pxref{Site Defaults}). - -@node Printing Messages, , Caching Results, Results -@section Printing Messages - -@code{configure} scripts need to give users running them several kinds -of information. The following macros print messages in ways appropriate -for each kind. The arguments to all of them get enclosed in shell -double quotes, so the shell performs variable and backquote substitution -on them. - -These macros are all wrappers around the @code{echo} shell command. -@code{configure} scripts should rarely need to run @code{echo} directly -to print messages for the user. Using these macros makes it easy to -change how and when each kind of message is printed; such changes need -only be made to the macro definitions, and all of the callers change -automatically. - -@defmac AC_MSG_CHECKING (@var{feature-description}) -@maindex MSG_CHECKING -Notify the user that @code{configure} is checking for a particular -feature. This macro prints a message that starts with @samp{checking } -and ends with @samp{...} and no newline. It must be followed by a call -to @code{AC_MSG_RESULT} to print the result of the check and the -newline. The @var{feature-description} should be something like -@samp{whether the Fortran compiler accepts C++ comments} or @samp{for -c89}. - -This macro prints nothing if @code{configure} is run with the -@samp{--quiet} or @samp{--silent} option. -@end defmac - -@defmac AC_MSG_RESULT (@var{result-description}) -@maindex MSG_RESULT -Notify the user of the results of a check. @var{result-description} is -almost always the value of the cache variable for the check, typically -@samp{yes}, @samp{no}, or a file name. This macro should follow a call -to @code{AC_MSG_CHECKING}, and the @var{result-description} should be -the completion of the message printed by the call to -@code{AC_MSG_CHECKING}. - -This macro prints nothing if @code{configure} is run with the -@samp{--quiet} or @samp{--silent} option. -@end defmac - -@defmac AC_MSG_ERROR (@var{error-description}) -@maindex MSG_ERROR -Notify the user of an error that prevents @code{configure} from -completing. This macro prints an error message on the standard error -stream and exits @code{configure} with a nonzero status. -@var{error-description} should be something like @samp{invalid value -$HOME for \$HOME}. -@end defmac - -@defmac AC_MSG_WARN (@var{problem-description}) -@maindex MSG_WARN -Notify the @code{configure} user of a possible problem. This macro -prints the message on the standard error stream; @code{configure} -continues running afterward, so macros that call @code{AC_MSG_WARN} should -provide a default (back-up) behavior for the situations they warn about. -@var{problem-description} should be something like @samp{ln -s seems to -make hard links}. -@end defmac - -The following two macros are an obsolete alternative to -@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT}. - -@defmac AC_CHECKING (@var{feature-description}) -@maindex CHECKING -This macro is similar to @code{AC_MSG_CHECKING}, except that it prints a -newline after the @var{feature-description}. It is useful mainly to -print a general description of the overall purpose of a group of feature -checks, e.g., - -@example -AC_CHECKING(if stack overflow is detectable) -@end example -@end defmac - -@defmac AC_VERBOSE (@var{result-description}) -@maindex VERBOSE -This macro is similar to @code{AC_MSG_RESULT}, except that it is meant -to follow a call to @code{AC_CHECKING} instead of -@code{AC_MSG_CHECKING}; it starts the message it prints with a tab. It -is considered obsolete. -@end defmac - -@node Writing Macros, Manual Configuration, Results, Top -@chapter Writing Macros - -When you write a feature test that could be applicable to more than one -software package, the best thing to do is encapsulate it in a new macro. -Here are some instructions and guidelines for writing Autoconf macros. - -@menu -* 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. -@end menu - -@node Macro Definitions, Macro Names, , Writing Macros -@section Macro Definitions - -@maindex DEFUN -Autoconf macros are defined using the @code{AC_DEFUN} macro, which is -similar to the @code{m4} builtin @code{define} macro. In addition to -defining a macro, @code{AC_DEFUN} adds to it some code which is used to -constrain the order in which macros are called (@pxref{Prerequisite -Macros}). - -An Autoconf macro definition looks like this: - -@example -AC_DEFUN(@var{macro-name}, [@var{macro-body}]) -@end example - -@noindent -The square brackets here do not indicate optional text: they should -literally be present in the macro definition to avoid macro expansion -problems (@pxref{Quoting}). You can refer to any arguments passed to -the macro as @samp{$1}, @samp{$2}, etc. - -To introduce comments in @code{m4}, use the @code{m4} builtin -@code{dnl}; it causes @code{m4} to discard the text through the next -newline. It is not needed between macro definitions in @file{acsite.m4} -and @file{aclocal.m4}, because all output is discarded until -@code{AC_INIT} is called. - -@xref{Definitions, , How to define new macros, m4.info, GNU m4}, for -more complete information on writing @code{m4} macros. - -@node Macro Names, Quoting, Macro Definitions, Writing Macros -@section Macro Names - -All of the Autoconf macros have all-uppercase names starting with -@samp{AC_} to prevent them from accidentally conflicting with other -text. All shell variables that they use for internal purposes have -mostly-lowercase names starting with @samp{ac_}. To ensure that your -macros don't conflict with present or future Autoconf macros, you should -prefix your own macro names and any shell variables they use with some -other sequence. Possibilities include your initials, or an abbreviation -for the name of your organization or software package. - -Most of the Autoconf macros' names follow a structured naming convention -that indicates the kind of feature check by the name. The macro names -consist of several words, separated by underscores, going from most -general to most specific. The names of their cache variables use the -same convention (@pxref{Cache Variable Names}, for more information on them). - -The first word of the name after @samp{AC_} usually tells the category -of feature being tested. Here are the categories used in Autoconf for -specific test macros, the kind of macro that you are more likely to -write. They are also used for cache variables, in all-lowercase. Use -them where applicable; where they're not, invent your own categories. - -@table @code -@item C -C language builtin features. -@item DECL -Declarations of C variables in header files. -@item FUNC -Functions in libraries. -@item GROUP -UNIX group owners of files. -@item HEADER -Header files. -@item LIB -C libraries. -@item PATH -The full path names to files, including programs. -@item PROG -The base names of programs. -@item STRUCT -Definitions of C structures in header files. -@item SYS -Operating system features. -@item TYPE -C builtin or declared types. -@item VAR -C variables in libraries. -@end table - -After the category comes the name of the particular feature being -tested. Any further words in the macro name indicate particular aspects -of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the -behavior of the @code{utime} function when called with a @code{NULL} -pointer. - -A macro that is an internal subroutine of another macro should have a -name that starts with the name of that other macro, followed by one or -more words saying what the internal macro does. For example, -@code{AC_PATH_X} has internal macros @code{AC_PATH_X_XMKMF} and -@code{AC_PATH_X_DIRECT}. - -@node Quoting, Dependencies Between Macros, Macro Names, Writing Macros -@section Quoting - -Macros that are called by other macros are evaluated by @code{m4} -several times; each evaluation might require another layer of quotes to -prevent unwanted expansions of macros or @code{m4} builtins, such as -@samp{define} and @samp{$1}. Quotes are also required around macro -arguments that contain commas, since commas separate the arguments from -each other. It's a good idea to quote any macro arguments that contain -newlines or calls to other macros, as well. - -Autoconf changes the @code{m4} quote characters -from the default @samp{`} and @samp{'} to @samp{[} and @samp{]}, because -many of the macros use @samp{`} and @samp{'}, mismatched. However, in a -few places the macros need to use brackets (usually in C program text or -regular expressions). In those places, they use the @code{m4} builtin -command @code{changequote} to temporarily change the quote characters to -@samp{<<} and @samp{>>}. (Sometimes, if they don't need to quote -anything, they disable quoting entirely instead by setting the quote -characters to empty strings.) Here is an example: - -@example -AC_TRY_LINK( -changequote(<<, >>)dnl -<<#include <time.h> -#ifndef tzname /* For SGI. */ -extern char *tzname[]; /* RS6000 and others reject char **tzname. */ -#endif>>, -changequote([, ])dnl -[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) -@end example - -When you create a @code{configure} script using newly written macros, -examine it carefully to check whether you need to add more quotes in -your macros. If one or more words have disappeared in the @code{m4} -output, you need more quotes. When in doubt, quote. - -However, it's also possible to put on too many layers of quotes. If -this happens, the resulting @code{configure} script will contain -unexpanded macros. The @code{autoconf} program checks for this problem -by doing @samp{grep AC_ configure}. - -@node Dependencies Between Macros, , Quoting, Writing Macros -@section Dependencies Between Macros - -Some Autoconf macros depend on other macros having been called first in -order to work correctly. Autoconf provides a way to ensure that certain -macros are called if needed and a way to warn the user if macros are -called in an order that might cause incorrect operation. - -@menu -* Prerequisite Macros:: Ensuring required information. -* Suggested Ordering:: Warning about possible ordering problems. -* Obsolete Macros:: Warning about old ways of doing things. -@end menu - -@node Prerequisite Macros, Suggested Ordering, , Dependencies Between Macros -@subsection Prerequisite Macros - -A macro that you write might need to use values that have previously -been computed by other macros. For example, @code{AC_DECL_YYTEXT} -examines the output of @code{flex} or @code{lex}, so it depends on -@code{AC_PROG_LEX} having been called first to set the shell variable -@code{LEX}. - -Rather than forcing the user of the macros to keep track of the -dependencies between them, you can use the @code{AC_REQUIRE} macro to do -it automatically. @code{AC_REQUIRE} can ensure that a macro is only -called if it is needed, and only called once. - -@defmac AC_REQUIRE (@var{macro-name}) -@maindex REQUIRE -If the @code{m4} macro @var{macro-name} has not already been called, -call it (without any arguments). Make sure to quote @var{macro-name} -with square brackets. @var{macro-name} must have been defined using -@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate -that it has been called. -@end defmac - -An alternative to using @code{AC_DEFUN} is to use @code{define} and call -@code{AC_PROVIDE}. Because this technique does not prevent nested -messages, it is considered obsolete. - -@defmac AC_PROVIDE (@var{this-macro-name}) -@maindex PROVIDE -Record the fact that @var{this-macro-name} has been called. -@var{this-macro-name} should be the name of the macro that is calling -@code{AC_PROVIDE}. An easy way to get it is from the @code{m4} builtin -variable @code{$0}, like this: - -@example -AC_PROVIDE([$0]) -@end example -@end defmac - -@node Suggested Ordering, Obsolete Macros, Prerequisite Macros, Dependencies Between Macros -@subsection Suggested Ordering - -Some macros should be run before another macro if both are called, but -neither @emph{requires} that the other be called. For example, a macro -that changes the behavior of the C compiler should be called before any -macros that run the C compiler. Many of these dependencies are noted in -the documentation. - -Autoconf provides the @code{AC_BEFORE} macro to warn users when macros -with this kind of dependency appear out of order in a -@file{configure.in} file. The warning occurs when creating -@code{configure} from @file{configure.in}, not when running -@code{configure}. -For example, @code{AC_PROG_CPP} checks whether the C compiler -can run the C preprocessor when given the @samp{-E} option. It should -therefore be called after any macros that change which C compiler is -being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: - -@example -AC_BEFORE([$0], [AC_PROG_CPP])dnl -@end example - -@noindent -This warns the user if a call to @code{AC_PROG_CPP} has already occurred -when @code{AC_PROG_CC} is called. - -@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) -@maindex BEFORE -Make @code{m4} print a warning message on the standard error output if -@var{called-macro-name} has already been called. @var{this-macro-name} -should be the name of the macro that is calling @code{AC_BEFORE}. The -macro @var{called-macro-name} must have been defined using -@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate -that it has been called. -@end defmac - -@node Obsolete Macros, , Suggested Ordering, Dependencies Between Macros -@subsection Obsolete Macros - -Configuration and portability technology has evolved over the years. -Often better ways of solving a particular problem are developed, or -ad-hoc approaches are systematized. This process has occurred in many -parts of Autoconf. One result is that some of the macros are now -considered @dfn{obsolete}; they still work, but are no longer considered -the best thing to do. Autoconf provides the @code{AC_OBSOLETE} macro to -warn users producing @code{configure} scripts when they use obsolete -macros, to encourage them to modernize. A sample call is: - -@example -AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl -@end example - -@defmac AC_OBSOLETE (@var{this-macro-name} @r{[}, @var{suggestion}@r{]}) -@maindex OBSOLETE -Make @code{m4} print a message on the standard error output warning that -@var{this-macro-name} is obsolete, and giving the file and line number -where it was called. @var{this-macro-name} should be the name of the -macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, -it is printed at the end of the warning message; for example, it can be -a suggestion for what to use instead of @var{this-macro-name}. -@end defmac - -@node Manual Configuration, Site Configuration, Writing Macros, Top -@chapter Manual Configuration - -A few kinds of features can't be guessed automatically by running test -programs. For example, the details of the object file format, or -special options that need to be passed to the compiler or linker. It is -possible to check for such features using ad-hoc means, such as having -@code{configure} check the output of the @code{uname} program, or -looking for libraries that are unique to particular systems. However, -Autoconf provides a uniform method for handling unguessable features. - -@menu -* 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. -@end menu - -@node Specifying Names, Canonicalizing, , Manual Configuration -@section Specifying the System Type - -Like other GNU @code{configure} scripts, Autoconf-generated -@code{configure} scripts can make decisions based on a canonical name -for the system type, which has the form: - -@example -@var{cpu}-@var{company}-@var{system} -@end example - -@code{configure} can usually guess the canonical name for the type of -system it's running on. To do so it runs a script called -@code{config.guess}, which derives the name using the @code{uname} -command or symbols predefined by the C preprocessor. - -Alternately, the user can specify the system type with command line -arguments to @code{configure}. Doing so is necessary when -cross-compiling. In the most complex case of cross-compiling, three -system types are involved. The options to specify them are: - -@table @code -@item --build=@var{build-type} -the type of system on which the package is being configured and -compiled (rarely needed); - -@item --host=@var{host-type} -the type of system on which the package will run; - -@item --target=@var{target-type} -the type of system for which any compiler tools in the package will -produce code. -@end table - -@noindent -If the user gives @code{configure} a non-option argument, it is used as -the default for the host, target, and build system types if the user -does not specify them explicitly with options. The target and build -types default to the host type if it is given and they are not. If you -are cross-compiling, you still have to specify the names of the -cross-tools you use, in particular the C compiler, on the -@code{configure} command line, e.g., - -@example -CC=m68k-coff-gcc configure --target=m68k-coff -@end example - -@code{configure} recognizes short aliases for many system types; for -example, @samp{decstation} can be given on the command line instead of -@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called -@code{config.sub} to canonicalize system type aliases. - -@node Canonicalizing, System Type Variables, Specifying Names, Manual Configuration -@section Getting the Canonical System Type - -The following macros make the system type available to @code{configure} -scripts. They run the shell script @code{config.guess} to determine any -values for the host, target, and build types that they need and the user -did not specify on the command line. They run @code{config.sub} to -canonicalize any aliases the user gave. If you use these macros, you -must distribute those two shell scripts along with your source code. -@xref{Output}, for information about the @code{AC_CONFIG_AUX_DIR} macro -which you can use to control which directory @code{configure} looks for -those scripts in. If you do not use either of these macros, -@code{configure} ignores any @samp{--host}, @samp{--target}, and -@samp{--build} options given to it. - -@defmac AC_CANONICAL_SYSTEM -@maindex CANONICAL_SYSTEM -Determine the system type and set output variables to the names of the -canonical system types. @xref{System Type Variables}, for details about -the variables this macro sets. -@end defmac - -@defmac AC_CANONICAL_HOST -@maindex CANONICAL_HOST -Perform only the subset of @code{AC_CANONICAL_SYSTEM} relevant to the -host type. This is all that is needed for programs that are not part of -a compiler toolchain. -@end defmac - -@node System Type Variables, Using System Type, Canonicalizing, Manual Configuration -@section System Type Variables - -After calling @code{AC_CANONICAL_SYSTEM}, the following output variables -contain the system type information. After @code{AC_CANONICAL_HOST}, -only the @code{host} variables below are set. - -@table @code -@ovindex build -@ovindex host -@ovindex target -@item @code{build}, @code{host}, @code{target} -the canonical system names; - -@item @code{build_alias}, @code{host_alias}, @code{target_alias} -@ovindex build_alias -@ovindex host_alias -@ovindex target_alias -the names the user specified, or the canonical names if -@code{config.guess} was used; - -@item @code{build_cpu}, @code{build_vendor}, @code{build_os} -@itemx @code{host_cpu}, @code{host_vendor}, @code{host_os} -@itemx @code{target_cpu}, @code{target_vendor}, @code{target_os} -@ovindex build_cpu -@ovindex host_cpu -@ovindex target_cpu -@ovindex build_vendor -@ovindex host_vendor -@ovindex target_vendor -@ovindex build_os -@ovindex host_os -@ovindex target_os -the individual parts of the canonical names (for convenience). -@end table - -@node Using System Type, , System Type Variables, Manual Configuration -@section Using the System Type - -How do you use a canonical system type? Usually, you use it in one or -more @code{case} statements in @file{configure.in} to select -system-specific C files. Then link those files, which have names based -on the system name, to generic names, such as @file{host.h} or -@file{target.c}. The @code{case} statement patterns can use shell -wildcards to group several cases together, like in this fragment: - -@example -case "$target" in -i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;; -i960-*-bout) obj_format=bout ;; -esac -@end example - -@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) -@maindex LINK_FILES -Make @code{AC_OUTPUT} link each of the existing files @var{source} to -the corresponding link name @var{dest}. Makes a symbolic link if -possible, otherwise a hard link. The @var{dest} and @var{source} names -should be relative to the top level source or build directory. - -For example, this call: - -@example -AC_LINK_FILES(config/$@{machine@}.h config/$@{obj_format@}.h, host.h object.h) -@end example - -@noindent -creates in the current directory @file{host.h}, which is a link to -@file{@var{srcdir}/config/$@{machine@}.h}, and @file{object.h}, which is a link -to @file{@var{srcdir}/config/$@{obj_format@}.h}. -@end defmac - -@node Site Configuration, Invoking configure, Manual Configuration, Top -@chapter Site Configuration - -@code{configure} scripts support several kinds of local configuration -decisions. There are ways for users to specify where external software -packages are, include or exclude optional features, install programs -under modified names, and set default values for @code{configure} -options. - -@menu -* 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 @code{configure} local defaults. -@end menu - -@node External Software, Package Options, , Site Configuration -@section Working With External Software - -Some packages require, or can optionally use, other software packages -which are already installed. The user can give @code{configure} -command line options to specify which such external software to use. -The options have one of these forms: - -@example ---with-@var{package}@r{[}=@var{arg}@r{]} ---without-@var{package} -@end example - -For example, @samp{--with-gnu-ld} means work with the GNU linker instead -of some other linker. @samp{--with-x11} means work with X11. - -The user can give an argument by following the package name with -@samp{=} and the argument. Giving an argument of @samp{no} is for -packages that are used by default; it says to @emph{not} use the -package. An argument that is neither @samp{yes} nor @samp{no} could -include a name or number of a version of the other package, to specify -more precisely which other package this program is supposed to work -with. If no argument is given, it defaults to @samp{yes}. -@samp{--without-@var{package}} is equivalent to -@samp{--with-@var{package}=no}. - -For each external software package that may be used, @file{configure.in} -should call @code{AC_ARG_WITH} to detect whether the @code{configure} -user asked to use it. Whether each package is used or not by -default, and which arguments are valid, is up to you. - -@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) -@maindex ARG_WITH -If the user gave @code{configure} the option @samp{--with-@var{package}} -or @samp{--without-@var{package}}, run shell commands -@var{action-if-true}. Otherwise run shell commands -@var{action-if-false}. The name @var{package} indicates another -software package that this program should work with. It should consist -only of alphanumeric characters and dashes. - -The option's argument is available to the shell commands -@var{action-if-true} in the shell variable @code{withval}. - -The argument @var{help-string} is a description of the option which -looks like this: -@example - --with-readline support fancy command line editing -@end example -@noindent -@var{help-string} may be more than one line long, if more detail is -needed. Just make sure the columns line up in @samp{configure --help}. -Avoid tabs in the help string. You'll need to enclose it in @samp{[} -and @samp{]} in order to produce the leading spaces. -@end defmac - -@defmac AC_WITH (@var{package}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) -@maindex WITH -This is an obsolete version of @code{AC_ARG_WITH} that does not -support providing a help string. -@end defmac - -@node Package Options, Site Details, External Software, Site Configuration -@section Choosing Package Options - -If a software package has optional compile-time features, the user can -give @code{configure} command line options to specify whether to -compile them. The options have one of these forms: - -@example ---enable-@var{feature}@r{[}=@var{arg}@r{]} ---disable-@var{feature} -@end example - -These options allow users to choose which optional features to build and -install. @samp{--enable-@var{feature}} options should never make a -feature behave differently or cause one feature to replace another. -They should only cause parts of the program to be built rather than left -out. - -The user can give an argument by following the feature name with -@samp{=} and the argument. Giving an argument of @samp{no} requests -that the feature @emph{not} be made available. A feature with an -argument looks like @samp{--enable-debug=stabs}. If no argument is -given, it defaults to @samp{yes}. @samp{--disable-@var{feature}} is -equivalent to @samp{--enable-@var{feature}=no}. - -For each optional feature, @file{configure.in} should call -@code{AC_ARG_ENABLE} to detect whether the @code{configure} user asked -to include it. Whether each feature is included or not by default, and -which arguments are valid, is up to you. - -@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) -@maindex ARG_ENABLE -If the user gave @code{configure} the option -@samp{--enable-@var{feature}} or @samp{--disable-@var{feature}}, run -shell commands @var{action-if-true}. Otherwise run shell commands -@var{action-if-false}. The name @var{feature} indicates an optional -user-level facility. It should consist only of alphanumeric characters -and dashes. - -The option's argument is available to the shell commands -@var{action-if-true} in the shell variable @code{enableval}. -The @var{help-string} argument is like that of @code{AC_ARG_WITH} -(@pxref{External Software}). -@end defmac - -@defmac AC_ENABLE (@var{feature}, @var{action-if-true} @r{[}, @var{action-if-false}@r{]}) -@maindex ENABLE -This is an obsolete version of @code{AC_ARG_ENABLE} that does not -support providing a help string. -@end defmac - -@node Site Details, Transforming Names, Package Options, Site Configuration -@section Configuring Site Details - -Some software packages require complex site-specific information. Some -examples are host names to use for certain services, company names, and -email addresses to contact. Since some configuration scripts generated -by Metaconfig ask for such information interactively, people sometimes -wonder how to get that information in Autoconf-generated configuration -scripts, which aren't interactive. - -Such site configuration information should be put in a file that is -edited @emph{only by users}, not by programs. The location of the file -can either be based on the @code{prefix} variable, or be a standard -location such as the user's home directory. It could even be specified -by an environment variable. The programs should examine that file at -run time, rather than at compile time. That approach is more convenient -for users and makes the configuration process simpler than getting the -information while configuring. @xref{Directory Variables, , Variables -for Installation Directories, standards, GNU Coding Standards}, for more -information on where to put data files. - -@node Transforming Names, Site Defaults, Site Details, Site Configuration -@section Transforming Program Names When Installing - -Autoconf supports changing the names of programs when installing them. -In order to use these transformations, @file{configure.in} must call the -macro @code{AC_ARG_PROGRAM}. - -@defmac AC_ARG_PROGRAM -@maindex ARG_PROGRAM -@ovindex program_transform_name -Place in output variable @code{program_transform_name} a sequence of -@code{sed} commands for changing the names of installed programs. - -If any of the options described below are given to @code{configure}, -program names are transformed accordingly. Otherwise, if -@code{AC_CANONICAL_SYSTEM} has been called and a @samp{--target} value -is given that differs from the host type (specified with @samp{--host} -or defaulted by @code{config.sub}), the target type followed by a dash -is used as a prefix. Otherwise, no program name transformation is done. -@end defmac - -@menu -* Transformation Options:: @code{configure} options to transforme names. -* Transformation Examples:: Sample uses of transforming names. -* Transformation Rules:: @file{Makefile} uses of transforming names. -@end menu - -@node Transformation Options, Transformation Examples, , Transforming Names -@subsection Transformation Options - -You can specify name transformations by giving @code{configure} these -command line options: - -@table @code -@item --program-prefix=@var{prefix} -prepend @var{prefix} to the names; - -@item --program-suffix=@var{suffix} -append @var{suffix} to the names; - -@item --program-transform-name=@var{expression} -perform @code{sed} substitution @var{expression} on the names. -@end table - -@node Transformation Examples, Transformation Rules, Transformation Options, Transforming Names -@subsection Transformation Examples - -These transformations are useful with programs that can be part of a -cross-compilation development environment. For example, a -cross-assembler running on a Sun 4 configured with -@samp{--target=i960-vxworks} is normally installed as -@file{i960-vxworks-as}, rather than @file{as}, which could be confused -with a native Sun 4 assembler. - -You can force a program name to begin with @file{g}, if you don't want -GNU programs installed on your system to shadow other programs with the -same name. For example, if you configure GNU @code{diff} with -@samp{--program-prefix=g}, then when you run @samp{make install} it is -installed as @file{/usr/local/bin/gdiff}. - -As a more sophistocated example, you could use -@example ---program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' -@end example -@noindent -to prepend @samp{g} to most of the program names in a source tree, -excepting those like @code{gdb} that already have one and those like -@code{less} and @code{lesskey} that aren't GNU programs. (That is -assuming that you have a source tree containing those programs that is -set up to use this feature.) - -One way to install multiple versions of some programs simultaneously is -to append a version number to the name of one or both. For example, if -you want to keep Autoconf version 1 around for awhile, you can configure -Autoconf version 2 using @samp{--program-suffix=2} to install the -programs as @file{/usr/local/bin/autoconf2}, -@file{/usr/local/bin/autoheader2}, etc. - -@node Transformation Rules, , Transformation Examples, Transforming Names -@subsection Transformation Rules - -Here is how to use the variable @code{program_transform_name} in a -@file{Makefile.in}: - -@example -transform=@@program_transform_name@@ -install: all - $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog|sed '$(transform)'` - -uninstall: - rm -f $(bindir)/`echo myprog|sed '$(transform)'` -@end example - -@noindent -If you have more than one program to install, you can do it in a loop: - -@example -PROGRAMS=cp ls rm -install: - for p in $(PROGRAMS); do \ - $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \ - done - -uninstall: - for p in $(PROGRAMS); do \ - rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \ - done -@end example - -Whether to do the transformations on documentation files (Texinfo or -@code{man}) is a tricky question; there seems to be no perfect answer, -due to the several reasons for name transforming. Documentation is not -usually particular to a specific architecture, and Texinfo files do not -conflict with system documentation. But they might conflict with -earlier versions of the same files, and @code{man} pages sometimes do -conflict with system documentation. As a compromise, it is probably -best to do name transformations on @code{man} pages but not on Texinfo -manuals. - -@node Site Defaults, , Transforming Names, Site Configuration -@section Setting Site Defaults - -Autoconf-generated @code{configure} scripts allow your site to provide -default values for some configuration values. You do this by creating -site- and system-wide initialization files. - -@evindex CONFIG_SITE -If the environment variable @code{CONFIG_SITE} is set, @code{configure} -uses its value as the name of a shell script to read. Otherwise, it -reads the shell script @file{@var{prefix}/share/config.site} if it exists, -then @file{@var{prefix}/etc/config.site} if it exists. Thus, -settings in machine-specific files override those in machine-independent -ones in case of conflict. - -Site files can be arbitrary shell scripts, but only certain kinds of -code are really appropriate to be in them. Because @code{configure} -reads any cache file after it has read any site files, a site file can -define a default cache file to be shared between all Autoconf-generated -@code{configure} scripts run on that system. If you set a default cache -file in a site file, it is a good idea to also set the output variable -@code{CC} in that site file, because the cache file is only valid for a -particular compiler, but many systems have several available. - -Site files are also good places to set default values for other output -variables, such as @code{CFLAGS}, if you need to give them non-default -values: anything you would normally do, repetitively, on the command -line. If you use non-default values for @var{prefix} or -@var{exec_prefix} (wherever you locate the site file), you can set them -in the site file if you specify it with the @code{CONFIG_SITE} -environment variable. - -You can set some cache values in the site file itself. Doing this is -useful if you are cross-compiling, so it is impossible to check features -that require running a test program. You could ``prime the cache'' by -setting those values correctly for that system in -@file{@var{prefix}/etc/config.site}. To find out the names of the cache -variables you need to set, look for shell variables with @samp{_cv_} in -their names in the affected @code{configure} scripts, or in the Autoconf -@code{m4} source code for those macros. - -The cache file is careful to not override any variables set in the site -files. Similarly, you should not override command-line options in the -site files. Your code should check that variables such as @code{prefix} -and @code{cache_file} have their default values (as set near the top of -@code{configure}) before changing them. - -Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The -command @samp{configure --prefix=/usr/share/local/gnu} would read this -file (if @code{CONFIG_SITE} is not set to a different file). - -@example -# config.site for configure -# -# Default --prefix and --exec-prefix. -test "$prefix" = NONE && prefix=/usr/share/local/gnu -test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu -# -# Give Autoconf 2.x generated configure scripts a shared default -# cache file for feature test results, architecture-specific. -if test "$cache_file" = ./config.cache; then - cache_file="$prefix/var/config.cache" - # A cache file is only valid for one C compiler. - CC=gcc -fi -@end example - -@node Invoking configure, Invoking config.status, Site Configuration, Top -@chapter Running @code{configure} Scripts - -Below are instructions on how to configure a package that uses a -@code{configure} script, suitable for inclusion as an @file{INSTALL} -file in the package. A plain-text version of @file{INSTALL} which you -may use comes with Autoconf. - -@menu -* 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 @code{configure}. -* Operation Controls:: Changing how @code{configure} runs. -@end menu - -@include install.texi - -@node Invoking config.status, Questions, Invoking configure, Top -@chapter Recreating a Configuration - -The @code{configure} script creates a file named @file{config.status} -which describes which configuration options were specified when the -package was last configured. This file is a shell script which, -if run, will recreate the same configuration. - -You can give @file{config.status} the @samp{--recheck} option to update -itself. This option is useful if you change @code{configure}, so that -the results of some tests might be different from the previous run. The -@samp{--recheck} option re-runs @code{configure} with the same arguments -you used before, plus the @samp{--no-create} option, which prevent -@code{configure} from running @file{config.status} and creating -@file{Makefile} and other files, and the @samp{--no-recursion} option, -which prevents @code{configure} from running other @code{configure} -scripts in subdirectories. (This is so other @file{Makefile} rules can -run @file{config.status} when it changes; @pxref{Automatic Remaking}, -for an example). - -@file{config.status} also accepts the options @samp{--help}, which -prints a summary of the options to @file{config.status}, and -@samp{--version}, which prints the version of Autoconf used to create -the @code{configure} script that generated @file{config.status}. - -@file{config.status} checks several optional environment variables that -can alter its behavior: - -@defvar CONFIG_SHELL -@evindex CONFIG_SHELL -The shell with which to run @code{configure} for the @samp{--recheck} -option. It must be Bourne-compatible. The default is @file{/bin/sh}. -@end defvar - -@defvar CONFIG_STATUS -@evindex CONFIG_STATUS -The file name to use for the shell script that records the -configuration. The default is @file{./config.status}. This variable is -useful when one package uses parts of another and the @code{configure} -scripts shouldn't be merged because they are maintained separately. -@end defvar - -The following variables provide one way for separately distributed -packages to share the values computed by @code{configure}. Doing so can -be useful if some of the packages need a superset of the features that -one of them, perhaps a common library, does. These variables allow a -@file{config.status} file to create files other than the ones that its -@file{configure.in} specifies, so it can be used for a different package. - -@defvar CONFIG_FILES -@evindex CONFIG_FILES -The files in which to perform @samp{@@@var{variable}@@} substitutions. -The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}. -@end defvar - -@defvar CONFIG_HEADERS -@evindex CONFIG_HEADERS -The files in which to substitute C @code{#define} statements. -The default is the arguments given to @code{AC_CONFIG_HEADER}; if that -macro was not called, @file{config.status} ignores this variable. -@end defvar - -These variables also allow you to write @file{Makefile} rules that -regenerate only some of the files. For example, in the dependencies -given above (@pxref{Automatic Remaking}), @file{config.status} is run -twice when @file{configure.in} has changed. If that bothers you, you -can make each run only regenerate the files for that rule: - -@example -@group -config.h: stamp-h -stamp-h: config.h.in config.status - CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status - echo > stamp-h - -Makefile: Makefile.in config.status - CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status -@end group -@end example - -@noindent -(If @file{configure.in} does not call @code{AC_CONFIG_HEADER}, there is -no need to set @code{CONFIG_HEADERS} in the @code{make} rules.) - -@node Questions, Upgrading, Invoking config.status, Top -@chapter Questions About Autoconf - -Several questions about Autoconf come up occasionally. Here some of them -are addressed. - -@menu -* Distributing:: Distributing @code{configure} scripts. -* Why GNU m4:: Why not use the standard @code{m4}? -* Bootstrapping:: Autoconf and GNU @code{m4} require each other? -* Why Not Imake:: Why GNU uses @code{configure} instead of Imake. -@end menu - -@node Distributing, Why GNU m4, , Questions -@section Distributing @code{configure} Scripts - -@display -What are the restrictions on distributing @code{configure} -scripts that Autoconf generates? How does that affect my -programs that use them? -@end display - -There are no restrictions on how the configuration scripts that Autoconf -produces may be distributed or used. In Autoconf version 1, they were -covered by the GNU General Public License. We still encourage software -authors to distribute their work under terms like those of the GPL, but -doing so is not required to use Autoconf. - -Of the other files that might be used with @code{configure}, -@file{config.h.in} is under whatever copyright you use for your -@file{configure.in}, since it is derived from that file and from the -public domain file @file{acconfig.h}. @file{config.sub} and -@file{config.guess} have an exception to the GPL when they are used with -an Autoconf-generated @code{configure} script, which permits you to -distribute them under the same terms as the rest of your package. -@file{install-sh} is from the X Consortium and is not copyrighted. - -@node Why GNU m4, Bootstrapping, Distributing, Questions -@section Why Require GNU @code{m4}? - -@display -Why does Autoconf require GNU @code{m4}? -@end display - -Many @code{m4} implementations have hard-coded limitations on the size -and number of macros, which Autoconf exceeds. They also lack several -builtin macros that it would be difficult to get along without in a -sophisticated application like Autoconf, including: - -@example -builtin -indir -patsubst -__file__ -__line__ -@end example - -Since only software maintainers need to use Autoconf, and since GNU -@code{m4} is simple to configure and install, it seems reasonable to -require GNU @code{m4} to be installed also. Many maintainers of GNU and -other free software already have most of the GNU utilities installed, -since they prefer them. - -@node Bootstrapping, Why Not Imake, Why GNU m4, Questions -@section How Can I Bootstrap? - -@display -If Autoconf requires GNU @code{m4} and GNU @code{m4} has an -Autoconf @code{configure} script, how do I bootstrap? It seems -like a chicken and egg problem! -@end display - -This is a misunderstanding. Although GNU @code{m4} does come with a -@code{configure} script produced by Autoconf, Autoconf is not required -in order to run the script and install GNU @code{m4}. Autoconf is only -required if you want to change the @code{m4} @code{configure} script, -which few people have to do (mainly its maintainer). - -@node Why Not Imake, , Bootstrapping, Questions -@section Why Not Imake? - -@display -Why not use Imake instead of @code{configure} scripts? -@end display - -Several people have written addressing this question, so I include -adaptations of their explanations here. - -The following answer is based on one written by Richard Pixley: - -Autoconf generated scripts frequently work on machines which it has -never been set up to handle before. That is, it does a good job of -inferring a configuration for a new system. Imake cannot do this. - -Imake uses a common database of host specific data. For X11, this makes -sense because the distribution is made as a collection of tools, by one -central authority who has control over the database. - -GNU tools are not released this way. Each GNU tool has a maintainer; -these maintainers are scattered across the world. Using a common -database would be a maintenance nightmare. Autoconf may appear to be -this kind of database, but in fact it is not. Instead of listing host -dependencies, it lists program requirements. - -Imake is special-purpose. It is directed at building the X11 -distribution. By comparison to the GNU tools, this is a simple problem. -If you view the GNU suite as a collection of native tools, then the -problems are similar. But the GNU tools are more powerful than that. -The development tools can be configured as cross tools in almost any -host+target permutation. All of these configurations can be installed -concurrently. They can even be configured to share host independent -files across hosts. Imake doesn't address these issues. - -Imake templates are a form of standardization. The GNU coding standards -address the same issues without necessarily imposing the same -restrictions. - -Here is some further explanation, written by Per Bothner: - -One of the advantages of Imake is that it easy to generate large -Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms. -However, @code{cpp} is not programmable: it has limited conditional -facilities, and no looping. And @code{cpp} cannot inspect its -environment. - -All of these problems are solved by using @code{sh} instead of -@code{cpp}. The shell is fully programmable, has macro substitution, -can execute (or source) other shell scripts, and can inspect its -environment. - -Paul Eggert elaborates more: - -With Autoconf, installers need not assume that Imake itself is already -installed and working well. This may not seem like much of an advantage -to people who are accustomed to Imake. But on many hosts Imake is not -installed or the default installation is not working well, and requiring -Imake to install a package hinders the acceptance of that package on -those hosts. For example, the Imake template and configuration files -might not be installed properly on a host, or the Imake build procedure -might wrongly assume that all source files are in one big directory -tree, or the Imake configuration might assume one compiler whereas the -package or the installer needs to use another, or there might be a -version mismatch between the Imake expected by the package and the Imake -suported by the host. These problems are much rarer with Autoconf, -where each package comes with its own independent configuration -processor. - -Also, Imake often suffers from unexpected interactions between -@code{make} and the installer's C preprocessor. The fundamental problem -here is that the C preprocessor was designed to preprocess C programs, -not @file{Makefile}s. This is much less of a problem with Autoconf, -which uses the general-purpose preprocessor @code{m4}, and where the -package's author (rather than the installer) does the preprocessing in a -standard way. - -Finally, Mark Eichin notes: - -Imake isn't all that extensible, either. In order to add new features to -Imake, you need to provide you own project template, and duplicate most -of the features of the existing one. This means that for a sophisticated -project, using the vendor-provided Imake templates fails to provide any -leverage---since they don't cover anything that your own project needs -(unless it is an X11 program). - -On the other side, though: - -The one advantage that Imake has over @code{configure}: -@file{Imakefile}s tend to be much shorter (likewise, less redundant) -than @file{Makefile.in}s. There is a fix to this, however---at least -for the Kerberos V5 tree, we've modified things to call in common -@file{post.in} and @file{pre.in} @file{Makefile} fragments for the -entire tree. This means that a lot of common things don't have to be -duplicated, even though they normally are in @code{configure} setups. - -@node Upgrading, History, Questions, Top -@chapter Upgrading From Version 1 - -Autoconf version 2 is mostly backward compatible with version 1. -However, it introduces better ways to do some things, and doesn't -support some of the ugly things in version 1. So, depending on how -sophisticated your @file{configure.in} files are, you might have to do -some manual work in order to upgrade to version 2. This chapter points -out some problems to watch for when upgrading. Also, perhaps your -@code{configure} scripts could benefit from some of the new features in -version 2; the changes are summarized in the file @file{NEWS} in the -Autoconf distribution. - -First, make sure you have GNU @code{m4} version 1.1 or higher installed, -preferably 1.3 or higher. Versions before 1.1 have bugs that prevent -them from working with Autoconf version 2. Versions 1.3 and later are -much faster than earlier versions, because as of version 1.3, GNU -@code{m4} has a more efficient implementation of diversions and can -freeze its internal state in a file that it can read back quickly. - -@menu -* Changed File Names:: Files you might rename. -* Changed Makefiles:: New things to put in @file{Makefile.in}. -* Changed Macros:: Macro calls you might replace. -* Invoking autoupdate:: Replacing old macro names in @code{configure.in}. -* Changed Results:: Changes in how to check test results. -* Changed Macro Writing:: Better ways to write your own macros. -@end menu - -@node Changed File Names, Changed Makefiles, , Upgrading -@section Changed File Names - -If you have an @file{aclocal.m4} installed with Autoconf (as opposed to -in a particular package's source directory), you must rename it to -@file{acsite.m4}. @xref{Invoking autoconf}. - -If you distribute @file{install.sh} with your package, rename it to -@file{install-sh} so @code{make} builtin rules won't inadvertantly -create a file called @file{install} from it. @code{AC_PROG_INSTALL} -looks for the script under both names, but it is best to use the new name. - -If you were using @file{config.h.top} or @file{config.h.bot}, you still -can, but you will have less clutter if you merge them into -@file{acconfig.h}. @xref{Invoking autoheader}. - -@node Changed Makefiles, Changed Macros, Changed File Names, Upgrading -@section Changed Makefiles - -Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in -your @file{Makefile.in} files, so they can take advantage of the values -of those variables in the environment when @code{configure} is run. -Doing this isn't necessary, but it's a convenience for users. - -Also add @samp{@@configure_input@@} in a comment to each input file for -@code{AC_OUTPUT}, so that the output files will contain a comment saying -they were produced by @code{configure}. Automatically selecting the -right comment syntax for all the kinds of files that people call -@code{AC_OUTPUT} on became too much work. - -Add @file{config.log} and @file{config.cache} to the list of files you -remove in @code{distclean} targets. - -If you have the following in @file{Makefile.in}: - -@example -prefix = /usr/local -exec_prefix = $@{prefix@} -@end example - -@noindent -you must change it to: - -@example -prefix = @@prefix@@ -exec_prefix = @@exec_prefix@@ -@end example - -@noindent -The old feature of replacing those variables without @samp{@@} -characters around them has been removed. - -@node Changed Macros, Invoking autoupdate, Changed Makefiles, Upgrading -@section Changed Macros - -Many of the macros were renamed in Autoconf version 2. You can still -use the old names, but the new ones are clearer, and it's easier to find -the documentation for them. @xref{Old Macro Names}, for a table showing -the new names for the old macros. Use the @code{autoupdate} program to -convert your @file{configure.in} to using the new macro names. -@xref{Invoking autoupdate}. - -Some macros have been superseded by similar ones that do the job better, -but are not call-compatible. If you get warnings about calling obsolete -macros while running @code{autoconf}, you may safely ignore them, but -your @code{configure} script will generally work better if you follow -the advice it prints about what to replace the obsolete macros with. In -particular, the mechanism for reporting the results of tests has -changed. If you were using @code{echo} or @code{AC_VERBOSE} (perhaps -via @code{AC_COMPILE_CHECK}), your @code{configure} script's output will -look better if you switch to @code{AC_MSG_CHECKING} and -@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best -in conjunction with cache variables. @xref{Caching Results}. - -@node Invoking autoupdate, Changed Results, Changed Macros, Upgrading -@section Using @code{autoupdate} to Modernize @code{configure} - -The @code{autoupdate} program updates a @file{configure.in} file that -calls Autoconf macros by their old names to use the current macro names. -In version 2 of Autoconf, most of the macros were renamed to use a more -uniform and descriptive naming scheme. @xref{Macro Names}, for a -description of the new scheme. Although the old names still work -(@pxref{Old Macro Names}, for a list of the old macro names and the -corresponding new names), you can make your @file{configure.in} files -more readable and make it easier to use the current Autoconf -documentation if you update them to use the new macro names. - -@evindex SIMPLE_BACKUP_SUFFIX -If given no arguments, @code{autoupdate} updates @file{configure.in}, -backing up the original version with the suffix @file{~} (or the value -of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is -set). If you give @code{autoupdate} an argument, it reads that file -instead of @file{configure.in} and writes the updated file to the -standard output. - -@noindent -@code{autoupdate} accepts the following options: - -@table @code -@item --help -@itemx -h -Print a summary of the command line options and exit. - -@item --macrodir=@var{dir} -@itemx -m @var{dir} -@evindex AC_MACRODIR -Look for the Autoconf macro files in directory @var{dir} instead of the -default installation directory. -You can also set the @code{AC_MACRODIR} -environment variable to a directory; this option overrides the -environment variable. - -@item --version -Print the version number of @code{autoupdate} and exit. -@end table - -@node Changed Results, Changed Macro Writing, Invoking autoupdate, Upgrading -@section Changed Results - -If you were checking the results of previous tests by examining the -shell variable @code{DEFS}, you need to switch to checking the values of -the cache variables for those tests. @code{DEFS} no longer exists while -@code{configure} is running; it is only created when generating output -files. This difference from version 1 is because properly quoting the -contents of that variable turned out to be too cumbersome and -inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache -Variable Names}. - -For example, here is a @file{configure.in} fragment written for Autoconf -version 1: - -@example -AC_HAVE_FUNCS(syslog) -case "$DEFS" in -*-DHAVE_SYSLOG*) ;; -*) # syslog is not in the default libraries. See if it's in some other. - saved_LIBS="$LIBS" - for lib in bsd socket inet; do - AC_CHECKING(for syslog in -l$lib) - LIBS="$saved_LIBS -l$lib" - AC_HAVE_FUNCS(syslog) - case "$DEFS" in - *-DHAVE_SYSLOG*) break ;; - *) ;; - esac - LIBS="$saved_LIBS" - done ;; -esac -@end example - -Here is a way to write it for version 2: - -@example -AC_CHECK_FUNCS(syslog) -if test $ac_cv_func_syslog = no; then - # syslog is not in the default libraries. See if it's in some other. - for lib in bsd socket inet; do - AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG) - LIBS="$LIBS $lib"; break]) - done -fi -@end example - -If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding -backslashes before quotes, you need to remove them. It now works -predictably, and does not treat quotes (except backquotes) specially. -@xref{Setting Output Variables}. - -All of the boolean shell variables set by Autoconf macros now use -@samp{yes} for the true value. Most of them use @samp{no} for false, -though for backward compatibility some use the empty string instead. If -you were relying on a shell variable being set to something like 1 or -@samp{t} for true, you need to change your tests. - -@node Changed Macro Writing, , Changed Results, Upgrading -@section Changed Macro Writing - -When defining your own macros, you should now use @code{AC_DEFUN} -instead of @code{define}. @code{AC_DEFUN} automatically calls -@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} -do not interrupt other macros, to prevent nested @samp{checking@dots{}} -messages on the screen. There's no actual harm in continuing to use the -older way, but it's less convenient and attractive. @xref{Macro -Definitions}. - -You probably looked at the macros that came with Autoconf as a guide for -how to do things. It would be a good idea to take a look at the new -versions of them, as the style is somewhat improved and they take -advantage of some new features. - -If you were doing tricky things with undocumented Autoconf internals -(macros, variables, diversions), check whether you need to change -anything to account for changes that have been made. Perhaps you can -even use an officially supported technique in version 2 instead of -kludging. Or perhaps not. - -To speed up your locally written feature tests, add caching to them. -See whether any of your tests are of general enough usefulness to -encapsulate into macros that you can share. - -@node History, Old Macro Names, Upgrading, Top -@chapter History of Autoconf - -You may be wondering, Why was Autoconf originally written? How did it -get into its present form? (Why does it look like gorilla spit?) If -you're not wondering, then this chapter contains no information useful -to you, and you might as well skip it. If you @emph{are} wondering, -then let there be light@dots{} - -@menu -* Genesis:: Prehistory and naming of @code{configure}. -* Exodus:: The plagues of @code{m4} and Perl. -* Leviticus:: The priestly code of portability arrives. -* Numbers:: Growth and contributors. -* Deuteronomy:: Approaching the promises of easy configuration. -@end menu - -@node Genesis, Exodus, , History -@section Genesis - -In June 1991 I was maintaining many of the GNU utilities for the Free -Software Foundation. As they were ported to more platforms and more -programs were added, the number of @samp{-D} options that users had to -select in the @file{Makefile} (around 20) became burdensome. Especially -for me---I had to test each new release on a bunch of different systems. -So I wrote a little shell script to guess some of the correct settings -for the fileutils package, and released it as part of fileutils 2.0. -That @code{configure} script worked well enough that the next month I -adapted it (by hand) to create similar @code{configure} scripts for -several other GNU utilities packages. Brian Berliner also adapted one -of my scripts for his CVS revision control system. - -Later that summer, I learned that Richard Stallman and Richard Pixley -were developing similar scripts to use in the GNU compiler tools; so I -adapted my @code{configure} scripts to support their evolving interface: -using the file name @file{Makefile.in} as the templates; adding -@samp{+srcdir}, the first option (of many); and creating -@file{config.status} files. - -@node Exodus, Leviticus, Genesis, History -@section Exodus - -As I got feedback from users, I incorporated many improvements, using -Emacs to search and replace, cut and paste, similar changes in each of -the scripts. As I adapted more GNU utilities packages to use -@code{configure} scripts, updating them all by hand became impractical. -Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail -saying that the @code{configure} scripts were great, and asking if I had -a tool for generating them that I could send him. No, I thought, but -I should! So I started to work out how to generate them. And the -journey from the slavery of hand-written @code{configure} scripts to the -abundance and ease of Autoconf began. - -Cygnus @code{configure}, which was being developed at around that time, -is table driven; it is meant to deal mainly with a discrete number of -system types with a small number of mainly unguessable features (such as -details of the object file format). The automatic configuration system -that Brian Fox had developed for Bash takes a similar approach. For -general use, it seems to me a hopeless cause to try to maintain an -up-to-date database of which features each variant of each operating -system has. It's easier and more reliable to check for most features on -the fly---especially on hybrid systems that people have hacked on -locally or that have patches from vendors installed. - -I considered using an architecture similar to that of Cygnus -@code{configure}, where there is a single @code{configure} script that -reads pieces of @file{configure.in} when run. But I didn't want to have -to distribute all of the feature tests with every package, so I settled -on having a different @code{configure} made from each -@file{configure.in} by a preprocessor. That approach also offered more -control and flexibility. - -I looked briefly into using the Metaconfig package, by Larry Wall, -Harlan Stenn, and Raphael Manfredi, but I decided not to for several -reasons. The @code{Configure} scripts it produces are interactive, -which I find quite inconvenient; I didn't like the ways it checked for -some features (such as library functions); I didn't know that it was -still being maintained, and the @code{Configure} scripts I had -seen didn't work on many modern systems (such as System V R4 and NeXT); -it wasn't very flexible in what it could do in response to a feature's -presence or absence; I found it confusing to learn; and it was too big -and complex for my needs (I didn't realize then how much Autoconf would -eventually have to grow). - -I considered using Perl to generate my style of @code{configure} scripts, -but decided that @code{m4} was better suited to the job of simple -textual substitutions: it gets in the way less, because output is -implicit. Plus, everyone already has it. (Initially I didn't rely on -the GNU extensions to @code{m4}.) Also, some of my friends at the -University of Maryland had recently been putting @code{m4} front ends on -several programs, including @code{tvtwm}, and I was interested in trying -out a new language. - -@node Leviticus, Numbers, Exodus, History -@section Leviticus - -Since my @code{configure} scripts determine the system's capabilities -automatically, with no interactive user intervention, I decided to call -the program that generates them Autoconfig. But with a version number -tacked on, that name would be too long for old UNIX file systems, so -I shortened it to Autoconf. - -In the fall of 1991 I called together a group of fellow questers after -the Holy Grail of portability (er, that is, alpha testers) to give me -feedback as I encapsulated pieces of my handwritten scripts in @code{m4} -macros and continued to add features and improve the techniques used in -the checks. Prominent among the testers were -@ifinfo -Franc,ois -@end ifinfo -@tex -Fran\c cois -@end tex -Pinard, who came up with the idea of making an @file{autoconf} shell -script to run @code{m4} and check for unresolved macro calls; Richard -Pixley, who suggested running the compiler instead of searching the file -system to find include files and symbols, for more accurate results; -Karl Berry, who got Autoconf to configure @TeX{} and added the -macro index to the documentation; and Ian Taylor, who added support for -creating a C header file as an alternative to putting @samp{-D} options -in a @file{Makefile}, so he could use Autoconf for his UUCP package. The -alpha testers cheerfully adjusted their files again and again as the -names and calling conventions of the Autoconf macros changed from -release to release. They all contributed many specific checks, great -ideas, and bug fixes. - -@node Numbers, Deuteronomy, Leviticus, History -@section Numbers - -In July 1992, after months of alpha testing, I released Autoconf 1.0, -and converted many GNU packages to use it. I was surprised by how -positive the reaction to it was. More people started using it than I -could keep track of, including people working on software that wasn't -part of the GNU Project (such as TCL, FSP, and Kerberos V5). -Autoconf continued to improve rapidly, as many people using the -@code{configure} scripts reported problems they encountered. - -Autoconf turned out to be a good torture test for @code{m4} -implementations. UNIX @code{m4} started to dump core because of the -length of the macros that Autoconf defined, and several bugs showed up -in GNU @code{m4} as well. Eventually, we realized that we needed to use -some features that only GNU @code{m4} has. 4.3BSD @code{m4}, in -particular, has an impoverished set of builtin macros; the System V -version is better, but still doesn't provide everything we need. - -More development occurred as people put Autoconf under more stresses -(and to uses I hadn't anticipated). Karl Berry added checks for X11. -david zuhn contributed C++ support. -@ifinfo -Franc,ois -@end ifinfo -@tex -Fran\c cois -@end tex -Pinard made it diagnose invalid arguments. Jim Blandy bravely coerced -it into configuring GNU Emacs, laying the groundwork for several later -improvements. Roland McGrath got it to configure the GNU C Library, -wrote the @code{autoheader} script to automate the creation of C header -file templates, and added a @samp{--verbose} option to @code{configure}. -Noah Friedman added the @samp{--macrodir} option and @code{AC_MACRODIR} -environment variable. (He also coined the term @dfn{autoconfiscate} to -mean ``adapt a software package to use Autoconf''.) Roland and Noah -improved the quoting protection in @code{AC_DEFINE} and fixed many bugs, -especially when I got sick of dealing with portability problems from -February through June, 1993. - -@node Deuteronomy, , Numbers, History -@section Deuteronomy - -A long wish list for major features had accumulated, and the effect of -several years of patching by various people had left some residual -cruft. In April 1994, while working for Cygnus Support, I began a major -revision of Autoconf. I added most of the features of the Cygnus -@code{configure} that Autoconf had lacked, largely by adapting the -relevant parts of Cygnus @code{configure} with the help of david zuhn -and Ken Raeburn. These features include support for using -@file{config.sub}, @file{config.guess}, @samp{--host}, and -@samp{--target}; making links to files; and running @code{configure} -scripts in subdirectories. Adding these features enabled Ken to convert -GNU @code{as}, and Rob Savoye to convert DejaGNU, to using Autoconf. - -I added more features in response to other peoples' requests. Many -people had asked for @code{configure} scripts to share the results of -the checks between runs, because (particularly when configuring a large -source tree, like Cygnus does) they were frustratingly slow. Mike -Haertel suggested adding site-specific initialization scripts. People -distributing software that had to unpack on MS-DOS asked for a way to -override the @file{.in} extension on the file names, which produced file -names like @file{config.h.in} containing two dots. Jim Avera did an -extensive examination of the problems with quoting in @code{AC_DEFINE} -and @code{AC_SUBST}; his insights led to significant improvements. -Richard Stallman asked that compiler output be sent to @file{config.log} -instead of @file{/dev/null}, to help people debug the Emacs -@code{configure} script. - -I made some other changes because of my dissatisfaction with the quality -of the program. I made the messages showing results of the checks less -ambiguous, always printing a result. I regularized the names of the -macros and cleaned up coding style inconsistencies. I added some -auxiliary utilities that I had developed to help convert source code -packages to use Autoconf. With the help of -@ifinfo -Franc,ois -@end ifinfo -@tex -Fran\c cois -@end tex -Pinard, I made the macros not interrupt each others' messages. -(That feature revealed some performance bottlenecks in GNU @code{m4}, -which he hastily corrected!) -I reorganized the documentation around problems people want to solve. -And I began a testsuite, because experience -had shown that Autoconf has a pronounced tendency to regress when we -change it. - -Again, several alpha testers gave invaluable feedback, especially -@ifinfo -Franc,ois -@end ifinfo -@tex -Fran\c cois -@end tex -Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, and Mark Eichin. - -Finally, version 2.0 was ready. And there was much rejoicing. -(And I have free time again. I think. Yeah, right.) - -@node Old Macro Names, Environment Variable Index, History, Top -@chapter Old Macro Names - -In version 2 of Autoconf, most of the macros were renamed to use a more -uniform and descriptive naming scheme. Here are the old names of the -macros that were renamed, followed by the current names of those macros. -Although the old names are still accepted by the @code{autoconf} program -for backward compatibility, the old names are considered obsolete. -@xref{Macro Names}, for a description of the new naming scheme. - -@table @code -@item AC_ALLOCA -@maindex ALLOCA -@code{AC_FUNC_ALLOCA} -@item AC_ARG_ARRAY -@maindex ARG_ARRAY -removed because of limited usefulness -@item AC_CHAR_UNSIGNED -@maindex CHAR_UNSIGNED -@code{AC_C_CHAR_UNSIGNED} -@item AC_CONST -@maindex CONST -@code{AC_C_CONST} -@item AC_CROSS_CHECK -@maindex CROSS_CHECK -@code{AC_C_CROSS} -@item AC_ERROR -@maindex ERROR -@code{AC_MSG_ERROR} -@item AC_FIND_X -@maindex FIND_X -@code{AC_PATH_X} -@item AC_FIND_XTRA -@maindex FIND_XTRA -@code{AC_PATH_XTRA} -@item AC_FUNC_CHECK -@maindex FUNC_CHECK -@code{AC_CHECK_FUNC} -@item AC_GCC_TRADITIONAL -@maindex GCC_TRADITIONAL -@code{AC_PROG_GCC_TRADITIONAL} -@item AC_GETGROUPS_T -@maindex GETGROUPS_T -@code{AC_TYPE_GETGROUPS} -@item AC_GETLOADAVG -@maindex GETLOADAVG -@code{AC_FUNC_GETLOADAVG} -@item AC_HAVE_FUNCS -@maindex HAVE_FUNCS -@code{AC_CHECK_FUNCS} -@item AC_HAVE_HEADERS -@maindex HAVE_HEADERS -@code{AC_CHECK_HEADERS} -@item AC_HAVE_POUNDBANG -@maindex HAVE_POUNDBANG -@code{AC_SYS_INTERPRETER} (different calling convention) -@item AC_HEADER_CHECK -@maindex HEADER_CHECK -@code{AC_CHECK_HEADER} -@item AC_HEADER_EGREP -@maindex HEADER_EGREP -@code{AC_EGREP_HEADER} -@item AC_INLINE -@maindex INLINE -@code{AC_C_INLINE} -@item AC_LN_S -@maindex LN_S -@code{AC_PROG_LN_S} -@item AC_LONG_DOUBLE -@maindex LONG_DOUBLE -@code{AC_C_LONG_DOUBLE} -@item AC_LONG_FILE_NAMES -@maindex LONG_FILE_NAMES -@code{AC_SYS_LONG_FILE_NAMES} -@item AC_MAJOR_HEADER -@maindex MAJOR_HEADER -@code{AC_HEADER_MAJOR} -@item AC_MINUS_C_MINUS_O -@maindex MINUS_C_MINUS_O -@code{AC_PROG_CC_C_O} -@item AC_MMAP -@maindex MMAP -@code{AC_FUNC_MMAP} -@item AC_MODE_T -@maindex MODE_T -@code{AC_TYPE_MODE_T} -@item AC_OFF_T -@maindex OFF_T -@code{AC_TYPE_OFF_T} -@item AC_PID_T -@maindex PID_T -@code{AC_TYPE_PID_T} -@item AC_PREFIX -@maindex PREFIX -@code{AC_PREFIX_PROGRAM} -@item AC_PROGRAMS_CHECK -@maindex PROGRAMS_CHECK -@code{AC_CHECK_PROGS} -@item AC_PROGRAMS_PATH -@maindex PROGRAMS_PATH -@code{AC_PATH_PROGS} -@item AC_PROGRAM_CHECK -@maindex PROGRAM_CHECK -@code{AC_CHECK_PROG} -@item AC_PROGRAM_EGREP -@maindex PROGRAM_EGREP -@code{AC_EGREP_CPP} -@item AC_PROGRAM_PATH -@maindex PROGRAM_PATH -@code{AC_PATH_PROG} -@item AC_REMOTE_TAPE -@maindex REMOTE_TAPE -removed because of limited usefulness -@item AC_RESTARTABLE_SYSCALLS -@maindex RESTARTABLE_SYSCALLS -@code{AC_SYS_RESTARTABLE_SYSCALLS} -@item AC_RETSIGTYPE -@maindex RETSIGTYPE -@code{AC_TYPE_SIGNAL} -@item AC_RSH -@maindex RSH -removed because of limited usefulness -@item AC_SETVBUF_REVERSED -@maindex SETVBUF_REVERSED -@code{AC_FUNC_SETVBUF_REVERSED} -@item AC_SET_MAKE -@maindex SET_MAKE -@code{AC_PROG_MAKE_SET} -@item AC_SIZEOF_TYPE -@maindex SIZEOF_TYPE -@code{AC_CHECK_SIZEOF} -@item AC_SIZE_T -@maindex SIZE_T -@code{AC_TYPE_SIZE_T} -@item AC_STAT_MACROS_BROKEN -@maindex STAT_MACROS_BROKEN -@code{AC_HEADER_STAT} -@item AC_STDC_HEADERS -@maindex STDC_HEADERS -@code{AC_HEADER_STDC} -@item AC_STRCOLL -@maindex STRCOLL -@code{AC_FUNC_STRCOLL} -@item AC_ST_BLKSIZE -@maindex ST_BLKSIZE -@code{AC_STRUCT_ST_BLKSIZE} -@item AC_ST_BLOCKS -@maindex ST_BLOCKS -@code{AC_STRUCT_ST_BLOCKS} -@item AC_ST_RDEV -@maindex ST_RDEV -@code{AC_STRUCT_ST_RDEV} -@item AC_SYS_SIGLIST_DECLARED -@maindex SYS_SIGLIST_DECLARED -@code{AC_DECL_SYS_SIGLIST} -@item AC_TEST_CPP -@maindex TEST_CPP -@code{AC_TRY_CPP} -@item AC_TEST_PROGRAM -@maindex TEST_PROGRAM -@code{AC_TRY_RUN} -@item AC_TIMEZONE -@maindex TIMEZONE -@code{AC_STRUCT_TIMEZONE} -@item AC_TIME_WITH_SYS_TIME -@maindex TIME_WITH_SYS_TIME -@code{AC_HEADER_TIME} -@item AC_UID_T -@maindex UID_T -@code{AC_TYPE_UID_T} -@item AC_UTIME_NULL -@maindex UTIME_NULL -@code{AC_FUNC_UTIME_NULL} -@item AC_VFORK -@maindex VFORK -@code{AC_FUNC_VFORK} -@item AC_VPRINTF -@maindex VPRINTF -@code{AC_FUNC_VPRINTF} -@item AC_WAIT3 -@maindex WAIT3 -@code{AC_FUNC_WAIT3} -@item AC_WARN -@maindex WARN -@code{AC_MSG_WARN} -@item AC_WORDS_BIGENDIAN -@maindex WORDS_BIGENDIAN -@code{AC_C_BIGENDIAN} -@item AC_YYTEXT_POINTER -@maindex YYTEXT_POINTER -@code{AC_DECL_YYTEXT} -@end table - -@node Environment Variable Index, Output Variable Index, Old Macro Names, Top -@unnumbered Environment Variable Index - -This is an alphabetical list of the environment variables that Autoconf -checks. - -@printindex ev - -@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top -@unnumbered Output Variable Index - -This is an alphabetical list of the variables that Autoconf can -substitute into files that it creates, typically one or more -@file{Makefile}s. @xref{Setting Output Variables}, for more information on how -this is done. - -@printindex ov - -@node Preprocessor Symbol Index, Macro Index, Output Variable Index, Top -@unnumbered Preprocessor Symbol Index - -This is an alphabetical list of the C preprocessor symbols that the -Autoconf macros define. To work with Autoconf, C source code needs to -use these names in @code{#if} directives. - -@printindex cv - -@node Macro Index, , Preprocessor Symbol Index, Top -@unnumbered Macro Index - -This is an alphabetical list of the Autoconf macros. To make the list -easier to use, the macros are listed without their preceding @samp{AC_}. - -@printindex ma - -@contents -@bye |