diff options
Diffstat (limited to 'doc/autoconf.texi')
| -rw-r--r-- | doc/autoconf.texi | 11346 |
1 files changed, 11346 insertions, 0 deletions
diff --git a/doc/autoconf.texi b/doc/autoconf.texi new file mode 100644 index 0000000..2728b2f --- /dev/null +++ b/doc/autoconf.texi @@ -0,0 +1,11346 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename autoconf.info +@settitle Autoconf + +@finalout +@setchapternewpage odd +@setcontentsaftertitlepage + +@include version.texi + +@c A simple macro for optional variables. +@macro ovar{varname} +@r{[}@var{\varname\}@r{]} +@end macro + +@c I don't like the way URL are displayed in TeX with @uref. +@ifhtml +@macro href{url, title} +@uref{\url\, \title\} +@end macro +@end ifhtml +@ifnothtml +@macro href{url, title} +\title\@footnote{\title\, @url{\url\}.} +@end macro +@end ifnothtml + + +@dircategory GNU admin +@direntry +* Autoconf: (autoconf). Create source code configuration scripts +@end direntry + +@dircategory Individual utilities +@direntry +* autoscan: (autoconf)autoscan Invocation. + Semi-automatic @file{configure.ac} writing +* ifnames: (autoconf)ifnames Invocation. + Listing the conditionals in source code +* autoconf: (autoconf)autoconf Invocation. + How to create configuration scripts +* autoreconf: (autoconf)autoreconf Invocation. + Remaking multiple @code{configure} scripts +* configure: (autoconf)configure Invocation. + Configuring a package +* config.status: (autoconf)config.status Invocation. + Recreating a configuration +@end direntry + +@ifinfo +Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie. + +This file documents the GNU Autoconf package for creating scripts to +configure source code packages using templates and an @code{m4} macro +package. + +Copyright 2003-2022,2023 Thomas E. Dickey@* +Copyright 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001 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 David MacKenzie and Ben Elliston +@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, 1995, 1996, 1998, 1999, 2000, +2001 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 an Autoconf macro index that @defmac doesn't write to. +@defcodeindex ma +@c Define an M4sugar macro index that @defmac doesn't write to. +@defcodeindex ms + +@node Top, Introduction, (dir), (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 the GNU 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 +* The GNU build system:: A set of tools for portable software packages +* 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 +* Programming in M4:: Layers on top of which Autoconf is written +* Writing Autoconf Macros:: Adding new macros to Autoconf +* Portable Shell:: Shell script portability pitfalls +* Manual Configuration:: Selecting features that can't be guessed +* Site Configuration:: Local defaults for @code{configure} +* Running configure scripts:: How to use the Autoconf output +* config.status Invocation:: Recreating a configuration +* Obsolete Constructs:: Kept for backward compatibility +* Questions:: Questions about Autoconf, with answers +* History:: History of Autoconf +* 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 +* Autoconf Macro Index:: Index of Autoconf macros +* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros +* Concept Index:: General index + +@detailmenu --- The Detailed Node Listing --- + +The GNU build system + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + +Making @code{configure} Scripts + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic @file{configure.ac} writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple @code{configure} scripts + +Writing @file{configure.ac} + +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac + +Initialization and Output Files + +* Notices:: Copyright, version numbers in @code{configure} +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in @file{Makefile}s +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix + +Substitutions in Makefiles + +* Preset Output Variables:: Output variables that are always set +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring + +Configuration Header Files + +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates + +Existing Tests + +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants + +Common Behavior + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + +Alternative Programs + +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs + +Library Functions + +* Function Portability:: Pitfalls with usual 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 + +Declarations + +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations + +Structures + +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members + +Types + +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types + +Compilers and Preprocessors + +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise + +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 +* Systemology:: A zoology of operating systems +* 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 @code{configure} users + +Caching Results + +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files @code{configure} uses for caching +* Cache Checkpointing:: Loading and saving the cache file + +Programming in M4 + +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros + +M4 Quotation + +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote + +Programming in M4sugar + +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros + +Writing Autoconf Macros + +* Macro Definitions:: Basic format of an Autoconf macro +* Macro Names:: What to call your new macros +* Reporting Messages:: Notifying @code{autoconf} users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros @`a la Autoconf + +Dependencies Between Macros + +* Prerequisite Macros:: Ensuring required information +* Suggested Ordering:: Warning about possible ordering problems + +Portable Shell Programming + +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles + +Manual Configuration + +* Specifying Names:: Specifying the system type +* Canonicalizing:: Getting the canonical 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 +* Pretty Help Strings:: Formatting help string +* 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 transform 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 +* Multiple Architectures:: Compiling for multiple architectures at once +* 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} +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how @code{configure} runs + +Obsolete Constructs + +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in @file{config.h.in} +* autoupdate Invocation:: Automatic update of @file{configure.ac} +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips + +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 +* Changed Results:: Changes in how to check test results +* Changed Macro Writing:: Better ways to write your own macros + +Upgrading From Version 2.13 + +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros + +Questions About Autoconf + +* Distributing:: Distributing @code{configure} scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses @code{configure} instead of Imake + +History of Autoconf + +* Genesis:: Prehistory and naming of @code{configure} +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + +@end detailmenu +@end menu + +@c ============================================================= Introduction. + +@node Introduction, The GNU build system, Top, Top +@chapter Introduction + +@flushright +A physicist, an engineer, and a computer scientist were discussing the +nature of God. ``Surely a Physicist,'' said the physicist, ``because +early in the Creation, God made Light; and you know, Maxwell's +equations, the dual nature of electromagnetic waves, the relativistic +consequences@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 flushright +@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 +@sc{unix}-like systems. The configuration scripts produced by Autoconf +are independent of Autoconf when they are run, so their users do not +need to have Autoconf. + +The configuration scripts produced by Autoconf require no manual user +intervention when run; they do not normally even need an argument +specifying the system type. Instead, they individually test for the +presence of each feature that the software package they are for might need. +(Before each check, they print a one-line message stating what they are +checking for, so the user doesn't get too bored while waiting for the +script to finish.) As a result, they deal well with systems that are +hybrids or customized from the more common @sc{unix} variants. There is +no need to maintain files that list the features supported by each +release of each variant of @sc{unix}. + +For each software package that Autoconf is used with, it creates a +configuration script from a template file that lists the system features +that the package needs or can use. After the shell code to recognize +and respond to a system feature has been written, Autoconf allows it to +be shared by many software packages that can use (or need) that feature. +If it later turns out that the shell code needs adjustment for some +reason, it needs to be changed in only one place; all of the +configuration scripts can be regenerated automatically to take advantage +of the updated code. + +The Metaconfig package is similar in purpose to Autoconf, but the +scripts it produces require manual user intervention, which is quite +inconvenient when configuring large source trees. Unlike Metaconfig +scripts, Autoconf scripts can support cross-compiling, if some care is +taken in writing them. + +Autoconf does not solve all problems related to making portable software +packages---for a more complete solution, it should be used in concert +with other GNU build tools like Automake and Libtool. These other tools +take on jobs like the creation of a portable, recursive @file{Makefile} +with all of the standard targets, linking of shared libraries, and so +on. @xref{The GNU build system}, for more information. + +Autoconf imposes some restrictions on the names of macros used with +@code{#if} in C programs (@pxref{Preprocessor Symbol Index}). + +Autoconf requires @sc{gnu} M4 in order to generate the scripts. It uses +features that some @sc{unix} versions of M4, including @sc{gnu} M4 1.3, +do not have. You must use version 1.4 or later of @sc{gnu} M4. + +@xref{Autoconf 1}, 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. + + +See the @href{http://www.gnu.org/software/autoconf/autoconf.html, +Autoconf web page} for up-to-date information, details on the mailing +lists, pointers to a list of known bugs, etc. + +Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing +list}. + +Bug reports should be preferably submitted to the +@href{http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf, +Autoconf Gnats database}, or sent to @email{bug-autoconf@@gnu.org, the +Autoconf Bugs mailing list}. If possible, first check that your bug is +not already solved in current development versions, and that it has not +been reported yet. Be sure to include all the needed information and a +short @file{configure.ac} that demonstrates the problem. + +Autoconf's development tree is accessible via @sc{cvs}; see the Autoconf +web page for details. There is also a +@href{http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/, @sc{cvs}web +interface to the Autoconf development tree}. Patches relative to the +current @sc{cvs} version can be sent for review to the +@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}. + +Because of its mission, Autoconf includes only a set of often-used +macros that have already demonstrated their usefulness. Nevertheless, +if you wish to share your macros, or find existing ones, see the +@href{http://www.gnu.org/software/ac-archive/, Autoconf Macro +Archive}, which is kindly run by @email{simons@@computer.org, +Peter Simons}. + + +@c ================================================= The GNU build system + +@node The GNU build system, Making configure Scripts, Introduction, Top +@chapter The GNU build system + +Autoconf solves an important problem---reliable discovery of +system-specific build and runtime information---but this is only one +piece of the puzzle for the development of portable software. To this +end, the GNU project has developed a suite of integrated utilities to +finish the job Autoconf started: the GNU build system, whose most +important components are Autoconf, Automake, and Libtool. In this +chapter, we introduce you to those tools, point you to sources of more +information, and try to convince you to use the entire GNU build system +for your software. + +@menu +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system +@end menu + +@node Automake, Libtool, The GNU build system, The GNU build system +@section Automake + +The ubiquity of @code{make} means that a @code{Makefile} is almost the +only viable way to distribute automatic build rules for software, but +one quickly runs into @code{make}'s numerous limitations. Its lack of +support for automatic dependency tracking, recursive builds in +subdirectories, reliable timestamps (e.g. for network filesystems), and +so on, mean that developers must painfully (and often incorrectly) +reinvent the wheel for each project. Portability is non-trivial, thanks +to the quirks of @code{make} on many systems. On top of all this is the +manual labor required to implement the many standard targets that users +have come to expect (@code{make install}, @code{make distclean}, +@code{make uninstall}, etc.). Since you are, of course, using Autoconf, +you also have to insert repetitive code in your @code{Makefile.in} to +recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions +provided by @code{configure}. Into this mess steps @dfn{Automake}. +@cindex Automake + +Automake allows you to specify your build needs in a @code{Makefile.am} +file with a vastly simpler and more powerful syntax than that of a plain +@code{Makefile}, and then generates a portable @code{Makefile.in} for +use with Autoconf. For example, the @code{Makefile.am} to build and +install a simple ``Hello world'' program might look like: + +@example +bin_PROGRAMS = hello +hello_SOURCES = hello.c +@end example + +@noindent +The resulting @code{Makefile.in} (~400 lines) automatically supports all +the standard targets, the substitutions provided by Autoconf, automatic +dependency tracking, @code{VPATH} building, and so on. @code{make} will +build the @code{hello} program, and @code{make install} will install it +in @file{/usr/local/bin} (or whatever prefix was given to +@code{configure}, if not @file{/usr/local}). + +Automake may require that additional tools be present on the +@emph{developer's} machine. For example, the @code{Makefile.in} that +the developer works with may not be portable (e.g. it might use special +features of your compiler to automatically generate dependency +information). Running @code{make dist}, however, produces a +@file{hello-1.0.tar.gz} package (or whatever the program/version is) +with a @code{Makefile.in} that will work on any system. + +The benefits of Automake increase for larger packages (especially ones +with subdirectories), but even for small programs the added convenience +and portability can be substantial. And that's not all@dots{} + +@node Libtool, Pointers, Automake, The GNU build system +@section Libtool + +Very often, one wants to build not only programs, but libraries, so that +other programs can benefit from the fruits of your labor. Ideally, one +would like to produce @emph{shared} (dynamically-linked) libraries, +which can be used by multiple programs without duplication on disk or in +memory and can be updated independently of the linked programs. +Producing shared libraries portably, however, is the stuff of +nightmares---each system has its own incompatible tools, compiler flags, +and magic incantations. Fortunately, GNU provides a solution: +@dfn{Libtool}. +@cindex Libtool + +Libtool handles all the requirements of building shared libraries for +you, and at this time seems to be the @emph{only} way to do so with any +portability. It also handles many other headaches, such as: the +interaction of @code{Makefile} rules with the variable suffixes of +shared libraries, linking reliably to shared libraries before they are +installed by the superuser, and supplying a consistent versioning system +(so that different versions of a library can be installed or upgraded +without breaking binary compatibility). Although Libtool, like +Autoconf, can be used on its own, it is most simply utilized in +conjunction with Automake---there, Libtool is used automatically +whenever shared libraries are needed, and you need not know its syntax. + +@node Pointers, , Libtool, The GNU build system +@section Pointers + +Developers who are used to the simplicity of @code{make} for small +projects on a single system might be daunted at the prospect of learning +to use Automake and Autoconf. As your software is distributed to more +and more users, however, you will otherwise quickly find yourself +putting lots of effort into reinventing the services that the GNU build +tools provide, and making the same mistakes that they once made and +overcame. (Besides, since you're already learning Autoconf, Automake +will be a piece of cake.) + +There are a number of places that you can go to for more information on +the GNU build tools. + +@itemize @minus + +@item Web + +The home pages for +@href{http://www.gnu.org/software/autoconf/,Autoconf}, and +@href{http://www.gnu.org/software/libtool/,Libtool}. + +@item Books + +The book @cite{GNU Autoconf, Automake and Libtool}@footnote{@cite{GNU +Autoconf, Automake and Libtool}, by G. V. Vaughan, B. Elliston, +T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN 1578701902.} +describes the complete GNU build environment. You can also find the +entire book on-line at @href{http://sources.redhat.com/autobook/,``The +Goat Book'' home page}. + +@item Tutorials and Examples + +The @href{http://sources.redhat.com/autoconf/,Autoconf Developer Page} +maintains links to a number of Autoconf/Automake tutorials online, and +also links to the @href{http://www.gnu.org/software/ac-archive/, +Autoconf Macro Archive}. + +@end itemize + +@c ================================================= Making configure Scripts. + +@node Making configure Scripts, Setup, The GNU build system, Top +@chapter Making @code{configure} Scripts +@cindex @file{aclocal.m4} +@cindex @code{configure} + +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 @minus +@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{config.status Invocation}); + +@item +an optional shell script normally called @file{config.cache} +(created when using @samp{configure --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 + +@cindex @file{configure.in} +@cindex @file{configure.ac} +To create a @code{configure} script with Autoconf, you need to write an +Autoconf input file @file{configure.ac} (or @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 run +@code{autoheader}, and you will distribute the 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 +your source files --> [autoscan*] --> [configure.scan] --> configure.ac + +@group +configure.ac --. + | .------> autoconf* -----> configure +[aclocal.m4] --+---+ + | `-----> [autoheader*] --> [config.h.in] +[acsite.m4] ---' +@end group + +Makefile.in -------------------------------> Makefile.in +@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.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic @file{configure.ac} writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple @code{configure} scripts +@end menu + +@node Writing configure.ac, autoscan Invocation, Making configure Scripts, Making configure Scripts +@section Writing @file{configure.ac} + +To produce a @code{configure} script for a software package, create a +file called @file{configure.ac} that contains invocations of the +Autoconf macros that test the system features your package needs or can +use. Autoconf macros already exist to check for many features; see +@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.ac} might need to contain some +hand-crafted shell commands; see @ref{Portable Shell}. The +@code{autoscan} program can give you a good start in writing +@file{configure.ac} (@pxref{autoscan Invocation}, for more information). + +Previous versions of Autoconf promoted the name @file{configure.in}, +which is somewhat ambiguous (the tool needed to produce this file is not +described by its extension), and introduces a slight confusion with +@file{config.h.in} and so on (for which @samp{.in} means ``to be +processed by @code{configure}''). Using @file{configure.ac} is now +preferred. + +@menu +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac +@end menu + +@node Shell Script Compiler, Autoconf Language, Writing configure.ac, Writing configure.ac +@subsection A Shell Script Compiler + +Just as for any other computer language, in order to properly program +@file{configure.ac} in Autoconf you must understand @emph{what} problem +the language tries to address and @emph{how} it does so. + +The problem Autoconf addresses is that the world is a mess. After all, +you are using Autoconf in order to have your package compile easily on +all sorts of different systems, some of them being extremely hostile. +Autoconf itself bears the price for these differences: @code{configure} +must run on all those systems, and thus @code{configure} must limit itself +to their lowest common denominator of features. + +Naturally, you might then think of shell scripts; who needs +@code{autoconf}? A set of properly written shell functions is enough to +make it easy to write @code{configure} scripts by hand. Sigh! +Unfortunately, shell functions do not belong to the least common +denominator; therefore, where you would like to define a function and +use it ten times, you would instead need to copy its body ten times. + +So, what is really needed is some kind of compiler, @code{autoconf}, +that takes an Autoconf program, @file{configure.ac}, and transforms it +into a portable shell script, @code{configure}. + +How does @code{autoconf} perform this task? + +There are two obvious possibilities: creating a brand new language or +extending an existing one. The former option is very attractive: all +sorts of optimizations could easily be implemented in the compiler and +many rigorous checks could be performed on the Autoconf program +(e.g. rejecting any non-portable construct). Alternatively, you can +extend an existing language, such as the @code{sh} (Bourne shell) +language. + +Autoconf does the latter: it is a layer on top of @code{sh}. It was +therefore most convenient to implement @code{autoconf} as a macro +expander: a program that repeatedly performs @dfn{macro expansions} on +text input, replacing macro calls with macro bodies and producing a pure +@code{sh} script in the end. Instead of implementing a dedicated +Autoconf macro expander, it is natural to use an existing +general-purpose macro language, such as M4, and implement the extensions +as a set of M4 macros. + + +@node Autoconf Language, configure.ac Layout, Shell Script Compiler, Writing configure.ac +@subsection The Autoconf Language +@cindex quotation + +The Autoconf language is very different from many other computer +languages because it treats actual code the same as plain text. Whereas +in C, for instance, data and instructions have very different syntactic +status, in Autoconf their status is rigorously the same. Therefore, we +need a means to distinguish literal strings from text to be expanded: +quotation. + +When calling macros that take arguments, there must not be any blank +space between the macro name and the open parenthesis. Arguments should +be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be +separated by commas. Any leading spaces in arguments are ignored, +unless they are quoted. You may safely leave out the quotes when the +argument is simple text, but @emph{always} quote complex arguments such +as other macro calls. This rule applies recursively for every macro +call, including macros called from other macros. + +For instance: + +@example +AC_CHECK_HEADER([stdio.h], + [AC_DEFINE([HAVE_STDIO_H])], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) +@end example + +@noindent +is quoted properly. You may safely simplify its quotation to: + +@example +AC_CHECK_HEADER(stdio.h, + [AC_DEFINE(HAVE_STDIO_H)], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) +@end example + +@noindent +Notice that the argument of @code{AC_MSG_ERROR} is still quoted; +otherwise, its comma would have been interpreted as an argument separator. + +The following example is wrong and dangerous, as it is underquoted: + +@example +AC_CHECK_HEADER(stdio.h, + AC_DEFINE(HAVE_STDIO_H), + AC_MSG_ERROR([Sorry, can't do anything for you])) +@end example + +In other cases, you may have to use text that also resembles a macro +call. You must quote that text even when it is not passed as a macro +argument: + +@example +echo "Hard rock was here! --[AC_DC]" +@end example + +@noindent +which will result in + +@example +echo "Hard rock was here! --AC_DC" +@end example + +@noindent +When you use the same text in a macro argument, you must therefore have +an extra quotation level (since one is stripped away by the macro +substitution). In general, then, it is a good idea to @emph{use double +quoting for all literal string arguments}: + +@example +AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) +@end example + +You are now able to understand one of the constructs of Autoconf that +has been continually misunderstood@dots{} The rule of thumb is that +@emph{whenever you expect macro expansion, expect quote expansion}; +i.e., expect one level of quotes to be lost. For instance: + +@example +AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])]) +@end example + +@noindent +is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is +@samp{char b[10];} and will be expanded once, which results in +@samp{char b10;}. (There was an idiom common in Autoconf's past to +address this issue via the M4 @code{changequote} primitive, but do not +use it!) Let's take a closer look: the author meant the first argument +to be understood as a literal, and therefore it must be quoted twice: + +@example +AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) +@end example + +@noindent +Voil@`a, you actually produce @samp{char b[10];} this time! + +The careful reader will notice that, according to these guidelines, the +``properly'' quoted @code{AC_CHECK_HEADER} example above is actually +lacking three pairs of quotes! Nevertheless, for the sake of readability, +double quotation of literals is used only where needed in this manual. + +Some macros take optional arguments, which this documentation represents +as @ovar{arg} (not to be confused with the quote characters). You may +just leave them empty, or use @samp{[]} to make the emptiness of the +argument explicit, or you may simply omit the trailing commas. The +three lines below are equivalent: + +@example +AC_CHECK_HEADERS(stdio.h, [], [], []) +AC_CHECK_HEADERS(stdio.h,,,) +AC_CHECK_HEADERS(stdio.h) +@end example + +It is best to put each macro call on its own line in +@file{configure.ac}. Most of the macros don't add extra newlines; they +rely on the newline after the macro call to terminate the commands. +This approach makes the generated @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. + +You can include comments in @file{configure.ac} files by starting them +with the @samp{#}. For example, it is helpful to begin +@file{configure.ac} files with a line like this: + +@example +# Process this file with autoconf to produce a configure script. +@end example + +@node configure.ac Layout, , Autoconf Language, Writing configure.ac +@subsection Standard @file{configure.ac} Layout + +The order in which @file{configure.ac} calls the Autoconf macros is not +important, with a few exceptions. Every @file{configure.ac} 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 @code{configure} is created if they +are called out of order. + +To encourage consistency, here is a suggested order for calling the +Autoconf macros. Generally speaking, the things near the end of this +list are those that could depend on things earlier in it. For example, +library functions could be affected by types and libraries. + +@display +@group +Autoconf requirements +@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} +information on the package +checks for programs +checks for libraries +checks for header files +checks for types +checks for structures +checks for compiler characteristics +checks for library functions +checks for system services +@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})} +@code{AC_OUTPUT} +@end group +@end display + + +@node autoscan Invocation, ifnames Invocation, Writing configure.ac, Making configure Scripts +@section Using @code{autoscan} to Create @file{configure.ac} +@cindex @code{autoscan} + +The @code{autoscan} program can help you create and/or maintain a +@file{configure.ac} 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.ac} +for that package, and checks a possibly existing @file{configure.ac} for +completeness. + +When using @command{autoscan} to create a @file{configure.ac}, you +should manually examine @file{configure.scan} before renaming it to +@file{configure.ac}; 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_HEADERS} (@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{ifnames Invocation}, for +information about a program that can help with that job). + +When using @command{autoscan} to maintain a @file{configure.ac}, simply +consider adding its suggestions. The file @file{autoscan.log} will +contain detailed information on why a macro is requested. + +@code{autoscan} uses several data files (installed along with Autoconf) +to determine which macros to output when it finds particular symbols in +a package's source files. These data files all have the same format: +each line consists of a symbol, whitespace, and the Autoconf macro to +output if that symbol is encountered. Lines starting with @samp{#} are +comments. + +@code{autoscan} is only installed if you already have Perl installed. +@code{autoscan} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Print the names of the files it examines and the potentially interesting +symbols it finds in them. This output can be voluminous. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. +@end table + +@node ifnames Invocation, autoconf Invocation, autoscan Invocation, Making configure Scripts +@section Using @code{ifnames} to List Conditionals +@cindex @code{ifnames} + +@code{ifnames} can help you write @file{configure.ac} for a software +package. It prints the identifiers that the package already uses in C +preprocessor conditionals. If a package has already been set up to have +some portability, @code{ifnames} can thus help you figure out what its +@code{configure} needs to check for. It may help fill in some gaps in a +@file{configure.ac} generated by @code{autoscan} (@pxref{autoscan +Invocation}). + +@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 @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. +@end table + +@node autoconf Invocation, autoreconf Invocation, ifnames Invocation, Making configure Scripts +@section Using @code{autoconf} to Create @code{configure} +@cindex @code{autoconf} + +To create @code{configure} from @file{configure.ac}, run the +@code{autoconf} program with no arguments. @code{autoconf} processes +@file{configure.ac} 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.ac} and writes the configuration script +to the standard output instead of to @code{configure}. If you give +@code{autoconf} the argument @option{-}, it reads from the standard +input instead of @file{configure.ac} and writes the configuration script +to the standard output. + +The Autoconf macros are defined in several files. Some of the files are +distributed with Autoconf; @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 Autoconf 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 @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Report processing steps. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@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 --output=@var{file} +@itemx -o @var{file} +Save output (script or trace) to @var{file}. The file @option{-} stands +for the standard output. + +@item --warnings=@var{category} +@itemx -W @var{category} +@evindex WARNINGS +Report the warnings related to @var{category} (which can actually be a +comma separated list). @xref{Reporting Messages}, macro +@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special +values include: + +@table @samp +@item all +report all the warnings + +@item none +report none + +@item error +treats warnings as errors + +@item no-@var{category} +disable warnings falling into @var{category} +@end table + +Warnings about @samp{syntax} are enabled by default, and the environment +variable @code{WARNINGS}, a comma separated list of categories, is +honored. @command{autoconf -W @var{category}} will actually +behave as if you had run: + +@example +autoconf --warnings=syntax,$WARNINGS,@var{category} +@end example + +@noindent +If you want to disable @command{autoconf}'s defaults and @code{WARNINGS}, +but (for example) enable the warnings about obsolete constructs, you +would use @option{-W none,obsolete}. + +@cindex Back trace +@cindex Macro invocation stack +@command{autoconf} displays a back trace for errors, but not for +warnings; if you want them, just pass @option{-W error}. For instance, +on this @file{configure.ac}: + +@example +AC_DEFUN([INNER], +[AC_TRY_RUN([true])]) + +AC_DEFUN([OUTER], +[INNER]) + +AC_INIT +OUTER +@end example + +@noindent +you get: + +@example +$ autoconf -Wcross +configure.ac:8: warning: AC_TRY_RUN called without default \ +to allow cross compiling +$ autoconf -Wcross,error +configure.ac:8: error: AC_TRY_RUN called without default \ +to allow cross compiling +acgeneral.m4:3044: AC_TRY_RUN is expanded from... +configure.ac:2: INNER is expanded from... +configure.ac:5: OUTER is expanded from... +configure.ac:8: the top level +@end example + +@item --trace=@var{macro}[:@var{format}] +@itemx -t @var{macro}[:@var{format}] +Do not create the @code{configure} script, but list the calls to +@var{macro} according to the @var{format}. Multiple @option{--trace} +arguments can be used to list several macros. Multiple @option{--trace} +arguments for a single macro are not cumulative; instead, you should +just make @var{format} as long as needed. + +The @var{format} is a regular string, with newlines if desired, and +several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see +below for details on the @var{format}. + +@item --initialization +@itemx -i +By default, @option{--trace} does not trace the initialization of the +Autoconf macros (typically the @code{AC_DEFUN} definitions). This +results in a noticeable speedup, but can be disabled by this option. +@end table + + +It is often necessary to check the content of a @file{configure.ac} +file, but parsing it yourself is extremely fragile and error-prone. It +is suggested that you rely upon @option{--trace} to scan +@file{configure.ac}. + +The @var{format} of @option{--trace} can use the following special +escapes: + +@table @samp +@item $$ +The character @samp{$}. + +@item $f +The filename from which @var{macro} is called. + +@item $l +The line number from which @var{macro} is called. + +@item $d +The depth of the @var{macro} call. This is an M4 technical detail that +you probably don't want to know about. + +@item $n +The name of the @var{macro}. + +@item $@var{num} +The @var{num}th argument of the call to @var{macro}. + +@item $@@ +@itemx $@var{sep}@@ +@itemx $@{@var{separator}@}@@ +All the arguments passed to @var{macro}, separated by the character +@var{sep} or the string @var{separator} (@samp{,} by default). Each +argument is quoted, i.e. enclosed in a pair of square brackets. + +@item $* +@itemx $@var{sep}* +@itemx $@{@var{separator}@}* +As above, but the arguments are not quoted. + +@item $% +@itemx $@var{sep}% +@itemx $@{@var{separator}@}% +As above, but the arguments are not quoted, all new line characters in +the arguments are smashed, and the default separator is @samp{:}. + +The escape @samp{$%} produces single-line trace outputs (unless you put +newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do +not. +@end table + +For instance, to find the list of variables that are substituted, use: + +@example +@group +$ autoconf -t AC_SUBST +configure.ac:2:AC_SUBST:ECHO_C +configure.ac:2:AC_SUBST:ECHO_N +configure.ac:2:AC_SUBST:ECHO_T +@i{More traces deleted} +@end group +@end example + +@noindent +The example below highlights the difference between @samp{$@@}, +@samp{$*}, and @strong{$%}. + +@example +@group +$ cat configure.ac +AC_DEFINE(This, is, [an +[example]]) +$ autoconf -t 'AC_DEFINE:@@: $@@ +*: $* +$: $%' +@@: [This],[is],[an +[example]] +*: This,is,an +[example] +$: This:is:an [example] +@end group +@end example + +@noindent +The @var{format} gives you a lot of freedom: + +@example +@group +$ autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";' +$ac_subst@{"ECHO_C"@} = "configure.ac:2"; +$ac_subst@{"ECHO_N"@} = "configure.ac:2"; +$ac_subst@{"ECHO_T"@} = "configure.ac:2"; +@i{More traces deleted} +@end group +@end example + +@noindent +A long @var{separator} can be used to improve the readability of complex +structures, and to ease its parsing (for instance when no single +character is suitable as a separator)): + +@example +@group +$ autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*' +AUTOCONF|:::::|autoconf|:::::|$missing_dir +@i{More traces deleted} +@end group +@end example + +@node autoreconf Invocation, , autoconf Invocation, Making configure Scripts +@section Using @code{autoreconf} to Update @code{configure} Scripts +@cindex @code{autoreconf} + +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.ac} 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 +@option{--force} option. + +If you give @code{autoreconf} the @option{--autoconf-dir=@var{dir}} or +@option{--localdir=@var{dir}} options, it passes them down to +@code{autoconf} and @code{autoheader} (with relative paths adjusted +properly). + +@code{autoreconf} does not support having, in the same directory tree, +both directories that are parts of a larger package (sharing +@file{aclocal.m4} and @file{acconfig.h}) and directories that are +independent packages (each with their own @file{aclocal.m4} and +@file{acconfig.h}). It assumes that they are all part of the same +package if you use @option{--localdir}, or that each directory is a +separate package if you don't use it. This restriction may be removed +in the future. + +@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 @option{--autoconf-dir=@var{dir}} or +@option{--localdir=@var{dir}}. + +@noindent +@code{autoreconf} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +Print the name of each directory where @code{autoreconf} runs +@code{autoconf} (and @code{autoheader}, if appropriate). + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --force +@itemx -f +Remake even @file{configure} scripts and configuration headers that are +newer than their input files (@file{configure.ac} and, if present, +@file{aclocal.m4}). + +@item --install +@itemx -i +Copy missing auxiliary files. This option is similar to the option +@code{--add-missing} in other tools. + +@item --symlink +@itemx -s +Instead of copying missing auxiliary files, install symbolic links. + +@item --localdir=@var{dir} +@itemx -l @var{dir} +Have @code{autoconf} and @code{autoheader} look for the package files +@file{aclocal.m4} and (@code{autoheader} only) @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.ac}. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@item --m4dir=@var{dir} +@itemx -M @var{dir} +Specify location of additional macro files (@file{m4} by default). +@end table + + +@c ========================================= Initialization and Output Files. + +@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 the creation of output files. + +@menu +* Notices:: Copyright, version numbers in @code{configure} +* Input:: Where Autoconf should find files +* Output:: Outputting results from the configuration +* Configuration Actions:: Preparing the output based on results +* Configuration Files:: Creating output files +* Makefile Substitutions:: Using output variables in @file{Makefile}s +* Configuration Headers:: Creating a configuration header file +* Configuration Commands:: Running arbitrary instantiation commands +* Configuration Links:: Links depending from the configuration +* Subdirectories:: Configuring independent packages together +* Default Prefix:: Changing the default installation prefix +@end menu + +@node Notices, Input, Setup, Setup +@section Notices in @code{configure} + +The following macros manage version numbers for @code{configure} +scripts. Using them is optional. + +@c FIXME: AC_PREREQ should not be here, but where should it go? +@defmac AC_PREREQ (@var{version}) +@maindex PREREQ +@cindex Version +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 to the standard error output +and do not create @code{configure}. For example: + +@example +AC_PREREQ(@value{VERSION}) +@end example + +This macro is the only macro that may be used before @code{AC_INIT}, but +for consistency, you are invited not to do so. +@end defmac + +@defmac AC_COPYRIGHT (@var{copyright-notice}) +@maindex COPYRIGHT +@cindex Copyright Notice +State that, in addition to the Free Software Foundation's copyright on +the Autoconf macros, parts of your @code{configure} are covered by the +@var{copyright-notice}. + +The @var{copyright-notice} will show up in both the head of +@code{configure} and in @samp{configure --version}. +@end defmac + + +@defmac AC_REVISION (@var{revision-info}) +@maindex REVISION +@cindex 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.ac} into @code{configure} +without @sc{rcs} or @code{cvs} changing it when you check in +@code{configure}. That way, you can determine easily which revision of +@file{configure.ac} a particular @code{configure} corresponds to. + +For example, this line in @file{configure.ac}: + +@c The asis prevents RCS from changing the example in the manual. +@example +AC_REVISION($@asis{Revision: 1.30 }$) +@end example + +@noindent +produces this in @code{configure}: + +@example +#! /bin/sh +# From configure.ac Revision: 1.30 +@end example +@end defmac + + +@node Input, Output, Notices, 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{package}, @var{version}, @ovar{bug-report-address}) +@maindex INIT +Process any command-line arguments and perform various initializations +and verifications. Set the name of the @var{package} and its +@var{version}. The optional argument @var{bug-report-address} should be +the email to which users should send bug reports. +@end defmac + +@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir}) +@maindex CONFIG_SRCDIR +@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. Occasionally people accidentally specify the wrong directory +with @option{--srcdir}; this is a safety check. @xref{configure +Invocation}, for more information. +@end defmac + + +@c FIXME: Remove definitively once --install explained. +@c +@c Small packages may store all their macros in @code{aclocal.m4}. As the +@c set of macros grows, or for maintenance reasons, a maintainer may prefer +@c to split the macros in several files. In this case, Autoconf must be +@c told which files to load, and in which order. +@c +@c @defmac AC_INCLUDE (@var{file}@dots{}) +@c @maindex INCLUDE +@c @c FIXME: There is no longer shell globbing. +@c Read the macro definitions that appear in the listed files. A list of +@c space-separated filenames or shell globbing patterns is expected. The +@c files will be read in the order they're listed. +@c +@c Because the order of definition of macros is important (only the last +@c definition of a macro is used), beware that it is @code{AC_INIT} that +@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that +@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within +@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in +@c the latter case, non-macro lines from included files may end up in the +@c @file{configure} script, whereas in the former case, they'd be discarded +@c just like any text that appear before @code{AC_INIT}. +@c @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 auxiliary build tools (e.g., @file{install-sh}, +@file{config.sub}, @file{config.guess}, Cygnus @code{configure}, +Automake and Libtool scripts etc.) 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 @command{make} have a rule that creates +@file{install} from it if there is no @file{Makefile}. +@end defmac + + +@node Output, Configuration Actions, Input, Setup +@section Outputting Files + +Every Autoconf-generated @code{configure} script must finish by calling +@code{AC_OUTPUT}. It is the macro that generates @file{config.status}, +which will create the @file{Makefile}s and any other files resulting +from configuration. The only other required macro is @code{AC_INIT} +(@pxref{Input}). + +@defmac AC_OUTPUT +@maindex OUTPUT +@cindex Instantiation +Generate @file{config.status} and launch it. Call this macro once, at +the end of @file{configure.ac}. + +@file{config.status} will take all the configuration actions: all the +output files (see @ref{Configuration Files}, macro +@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, +macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration +Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see +@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories +to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) +are honored. +@end defmac + +Historically, the usage of @code{AC_OUTPUT} was somewhat different. +@xref{Obsolete Macros}, for a description of the arguments that +@code{AC_OUTPUT} used to support. + + +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 Configuration Actions, Configuration Files, Output, Setup +@section Taking Configuration Actions + +@file{configure} is designed so that it appears to do everything itself, +but there is actually a hidden slave: @file{config.status}. +@file{configure} is in charge of examining your system, but it is +@file{config.status} that actually takes the proper actions based on the +results of @file{configure}. The most typical task of +@file{config.status} is to @emph{instantiate} files. + +This section describes the common behavior of the four standard +instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, +@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all +have this prototype: + +@c Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something +@c awful. +@example +AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}]) +@end example + +@noindent +where the arguments are: + +@table @var +@item @var{tag}@dots{} +A whitespace-separated list of tags, which are typically the names of +the files to instantiate. + +@item commands +Shell commands output literally into @file{config.status}, and +associated with a tag that the user can use to tell @file{config.status} +which the commands to run. The commands are run each time a @var{tag} +request is given to @file{config.status}; typically, each time the file +@file{@var{tag}} is created. + +@item init-cmds +Shell commands output @emph{unquoted} near the beginning of +@file{config.status}, and executed each time @file{config.status} runs +(regardless of the tag). Because they are unquoted, for example, +@samp{$var} will be output as the value of @code{var}. @var{init-cmds} +is typically used by @file{configure} to give @file{config.status} some +variables it needs to run the @var{commands}. +@end table + +All these macros can be called multiple times, with different +@var{tag}s, of course! + +You are encouraged to use literals as @var{tags}. In particular, you +should avoid + +@example +@dots{} && my_foos="$my_foos fooo" +@dots{} && my_foos="$my_foos foooo" +AC_CONFIG_FOOS($my_foos) +@end example + +@noindent +and use this instead: + +@example +@dots{} && AC_CONFIG_FOOS(fooo) +@dots{} && AC_CONFIG_FOOS(foooo) +@end example + +The macro @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use +specials @var{tag}s: they may have the form @samp{@var{output}} or +@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated +from its templates, @var{inputs} if specified, defaulting to +@samp{@var{output}.in}. + +For instance +@samp{AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)} asks for +the creation of @file{Makefile} that will be the expansion of the +output variables in the concatenation of @file{boiler/top.mk} and +@file{boiler/bot.mk}. + +The special value @samp{-} might be used to denote the standard output +when used in @var{output}, or the standard input when used in the +@var{inputs}. You most probably don't need to use this in +@file{configure.ac}, but it is convenient when using the command line +interface of @file{./config.status}, see @ref{config.status Invocation}, +for more details. + +The @var{inputs} may be absolute or relative filenames. In the latter +case they are first looked for in the build tree, and then in the source +tree. + + +@node Configuration Files, Makefile Substitutions, Configuration Actions, Setup +@section Creating Configuration Files + +Be sure to read the previous section, @ref{Configuration Actions}. + +@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_FILES +Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input +file (by default @file{@var{file}.in}), substituting the output variable +values. +@c Before we used to have this feature, which was later rejected +@c because it complicates the write of Makefiles: +@c If the file would be unchanged, it is left untouched, to preserve +@c timestamp. +This macro is one of the instantiating macros, see @ref{Configuration +Actions}. @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. Usually, @file{Makefile}s are created this way, +but other files, such as @file{.gdbinit}, can be specified as well. + +Typical calls to @code{AC_CONFIG_FILES} look like this: + +@example +AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile) +AC_CONFIG_FILES(autoconf, chmod +x autoconf) +@end example + +You can override an input file name by appending to @var{file} a +colon-separated list of input files. Examples: + +@example +AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk + lib/Makefile:boiler/lib.mk) +@end example + +@noindent +Doing this allows you to keep your file names acceptable to MS-DOS, or +to prepend and/or append boilerplate to the file. +@end defmac + + + +@node Makefile Substitutions, Configuration Headers, Configuration Files, 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, 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 +* Installation Directory Variables:: Other preset output variables +* Build Directories:: Supporting multiple concurrent compiles +* Automatic Remaking:: Makefile rules for configuring +@end menu + +@node Preset Output Variables, Installation Directory Variables, Makefile Substitutions, 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. @xref{Installation Directory +Variables}, for the list of the preset ones related to installation +directories. Below are listed the other preset ones. They all are +precious variables (@pxref{Setting Output Variables}, +@code{AC_ARG_VAR}). + +@c Just say no to ASCII sorting! We're humans, not computers. +@c These variables are listed as they would be in a dictionary: +@c actor +@c Actress +@c actress + +@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 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 CPPFLAGS +@ovindex CPPFLAGS +Header file search directory (@option{-I@var{dir}}) and any other +miscellaneous options for the C and C++ preprocessors and compilers. 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 and 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 +@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS} +is called, @code{configure} replaces @samp{@@DEFS@@} with +@option{-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 ECHO_C +@defvarx ECHO_N +@defvarx ECHO_T +@ovindex ECHO_C +@ovindex ECHO_N +@ovindex ECHO_T +How does one suppress the trailing newline from @code{echo} for +question-answer message pairs? These variables provide a way: + +@example +echo $ECHO_N "And the winner is... $ECHO_C" +sleep 100000000000 +echo "$@{ECHO_T@}dead." +@end example + +@noindent +Some old and uncommon @code{echo} implementations offer no means to +achieve this, in which case @code{ECHO_T} is set to tab. You might not +want to use it. +@end defvar + +@defvar FFLAGS +@ovindex FFLAGS +Debugging and optimization options for the Fortran 77 compiler. If it +is not set in the environment when @code{configure} runs, the default +value is set when you call @code{AC_PROG_F77} (or empty if you don't). +@code{configure} uses this variable when compiling programs to test for +Fortran 77 features. +@end defvar + +@defvar LDFLAGS +@ovindex LDFLAGS +Stripping (@option{-s}), path (@option{-L}), and any other miscellaneous +options for the linker. Don't use this variable to pass library names +(@option{-l}) to the linker, use @code{LIBS} instead. 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, C++ and Fortran 77 features. +@end defvar + +@defvar LIBS +@ovindex LIBS +@option{-l} options to pass to the linker. The default value is empty, +but some Autoconf macros may prepend extra libraries to this variable if +those libraries are found and provide necessary functions, see +@ref{Libraries}. @code{configure} uses this variable when linking +programs to test for C, C++ and Fortran 77 features. +@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 + +@node Installation Directory Variables, Build Directories, Preset Output Variables, Makefile Substitutions +@subsection Installation Directory Variables + +The following variables specify the directories where the package will +be installed, see @ref{Directory Variables,, Variables for Installation +Directories, standards, The GNU Coding Standards}, for more information. +See the end of this section for details on when and how to use these +variables. + +@defvar bindir +@ovindex bindir +The directory for installing executables that users run. +@end defvar + +@defvar datadir +@ovindex datadir +The directory for installing read-only architecture-independent data. +@end defvar + +@defvar exec_prefix +@ovindex exec_prefix +The installation prefix for architecture-dependent files. By default +it's the same as @var{prefix}. You should avoid installing anything +directly to @var{exec_prefix}. However, the default value for +directories containing architecture-dependent files should be relative +to @var{exec_prefix}. +@end defvar + +@defvar includedir +@ovindex includedir +The directory for installing C header files. +@end defvar + +@defvar infodir +@ovindex infodir +The directory for installing documentation in Info format. +@end defvar + +@defvar libdir +@ovindex libdir +The directory for installing object code libraries. +@end defvar + +@defvar libexecdir +@ovindex libexecdir +The directory for installing executables that other programs run. +@end defvar + +@defvar localstatedir +@ovindex localstatedir +The directory for installing modifiable single-machine data. +@end defvar + +@defvar mandir +@ovindex mandir +The top-level directory for installing documentation in man format. +@end defvar + +@defvar oldincludedir +@ovindex oldincludedir +The directory for installing C header files for non-gcc compilers. +@end defvar + +@defvar prefix +@ovindex prefix +The common installation prefix for all files. If @var{exec_prefix} +is defined to a different value, @var{prefix} is used only for +architecture-independent files. +@end defvar + +@defvar sbindir +@ovindex sbindir +The directory for installing executables that system +administrators run. +@end defvar + +@defvar sharedstatedir +@ovindex sharedstatedir +The directory for installing modifiable architecture-independent data. +@end defvar + +@defvar sysconfdir +@ovindex sysconfdir +The directory for installing read-only single-machine data. +@end defvar + + +Most of these variables have values that rely on @code{prefix} or +@code{exec_prefix}. It is on purpose that the directory output +variables keep them unexpanded: typically @samp{@@datadir@@} will be +replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}. + +This behavior is mandated by the @sc{gnu} coding standards, so that when +the user runs: + +@table @samp +@item make +she can still specify a different prefix from the one specified to +@command{configure}, in which case, if needed, the package shall hard +code dependencies to her late desires. + +@item make install +she can specify a different installation location, in which case the +package @emph{must} still depend on the location which was compiled in +(i.e., never recompile when @samp{make install} is run). This is an +extremely important feature, as many people may decide to install all +the files of a package grouped together, and then install links from +the final locations to there. +@end table + +In order to support these features, it is essential that @code{datadir} +remains being defined as @samp{$@{prefix@}/share} to depend upon the +current value of @code{prefix}. + +A corollary is that you should not use these variables but in Makefiles. +For instance, instead of trying to evaluate @code{datadir} in +@file{configure} and hardcoding it in Makefiles using +e.g. @samp{AC_DEFINE_UNQUOTED(DATADIR, "$datadir")}, you should add +@samp{-DDATADIR="$(datadir)"} to your @code{CPPFLAGS}. + +Similarly you should not rely on @code{AC_OUTPUT_FILES} to replace +@code{datadir} and friends in your shell scripts and other files, rather +let @command{make} manage their replacement. For instance Autoconf +ships templates of its shell scripts ending with @samp{.sh}, and uses +this Makefile snippet: + +@example +.sh: + rm -f $@@ $@@.tmp + sed 's,@@datadir\@@,$(pkgdatadir),g' $< >$@@.tmp + chmod +x $@@.tmp + mv $@@.tmp $@@ +@end example + +Three things are noteworthy: + +@table @samp +@item @@datadir\@@ +The backslash prevents @command{configure} from replacing +@samp{@@datadir@@} in the sed expression itself. + +@item $(pkgdatadir) +Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable +instead. + +@item , +Don't use @samp{/} in the sed expression(s) since most probably the +variables you use, such as @samp{$(pkgdatadir)}, will contain +some. +@end table + + +@node Build Directories, Automatic Remaking, Installation Directory Variables, Makefile Substitutions +@subsection Build Directories + +You can support compiling a software package for several architectures +simultaneously from the same copy of the source code. The object files +for each architecture are kept in their own directory. + +To support doing this, @code{make} uses the @code{VPATH} variable to +find the files that are in the source directory. @sc{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}. + +Do not use the @code{make} variable @code{$<}, which expands to the +file name 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 for +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 @command{make} will consider +@file{config.h.in} up to date. Don't use @command{touch} +(@pxref{Limitations of Usual Tools}), rather use @command{echo} (using +@command{date} would cause needless differences, hence @sc{cvs} +conflicts etc.). + +@example +@group +$(srcdir)/configure: configure.ac aclocal.m4 + cd $(srcdir) && autoconf + +# autoheader might not change config.h.in, so touch a stamp file. +$(srcdir)/config.h.in: stamp-h.in +$(srcdir)/stamp-h.in: configure.ac aclocal.m4 + cd $(srcdir) && autoheader + echo timestamp > $(srcdir)/stamp-h.in + +config.h: stamp-h +stamp-h: config.h.in config.status + ./config.status + +Makefile: Makefile.in config.status + ./config.status + +config.status: configure + ./config.status --recheck +@end group +@end example + +@noindent +(Be careful if you copy these lines directly into your Makefile, as you +will need to convert the indented lines to start with the tab character.) + +In addition, you should use @samp{AC_CONFIG_FILES(stamp-h, echo +timestamp > stamp-h)} 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{config.status Invocation}, for more examples of handling +configuration-related dependencies. + +@node Configuration Headers, Configuration Commands, Makefile Substitutions, Setup +@section Configuration Header Files +@cindex Configuration Header +@cindex @file{config.h} + +When a package tests more than a few C preprocessor symbols, the command +lines to pass @option{-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 @option{-D} options to the compiler, @code{configure} scripts can +create a C header file containing @samp{#define} directives. The +@code{AC_CONFIG_HEADERS} 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 +@option{-I.} option (or @option{-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_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_HEADERS +@cvindex HAVE_CONFIG_H +This macro is one of the instantiating macros, see @ref{Configuration +Actions}. Make @code{AC_OUTPUT} create the file(s) in the +whitespace-separated list @var{header} containing C preprocessor +@code{#define} statements, and replace @samp{@@DEFS@@} in generated +files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. +The usual name for @var{header} is @file{config.h}. + +If @var{header} 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}.in}; however, you can +override the input file name by appending to @var{header}, a +colon-separated list of input files. Examples: + +@example +AC_CONFIG_HEADERS(config.h:config.hin) +AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post) +@end example + +@noindent +Doing this allows you to keep your file names acceptable to MS-DOS, or +to prepend and/or append boilerplate to the file. +@end defmac + +@xref{Configuration Actions}, for more details on @var{header}. + +@menu +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates +@end menu + +@node Header Templates, autoheader Invocation, Configuration Headers, Configuration Headers +@subsection Configuration Header Templates +@cindex Configuration Header Template +@cindex @file{config.h.in} + +Your distribution should contain a template file that looks as you want +the final header file to look, including comments, with @code{#undef} +statements which are used as hooks. For example, suppose your +@file{configure.ac} makes these calls: + +@example +AC_CONFIG_HEADERS(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 @samp{#define} +@samp{HAVE_UNISTD_H} to 1. On other systems, the whole line will be +commented out (in case the system predefines that symbol). + +@example +@group +/* Define as 1 if you have unistd.h. */ +#undef HAVE_UNISTD_H +@end group +@end example + +You can then decode the configuration header using the preprocessor +directives: + +@example +@group +#include <conf.h> + +#if HAVE_UNISTD_H +# include <unistd.h> +#else +/* We are in trouble. */ +#endif +@end group +@end example + +The use of old form templates, with @samp{#define} instead of +@samp{#undef} is strongly discouraged. + +Since it is a tedious task to keep a template header up to date, you may +use @code{autoheader} to generate it, see @ref{autoheader Invocation}. + + +@node autoheader Invocation, Autoheader Macros, Header Templates, Configuration Headers +@subsection Using @code{autoheader} to Create @file{config.h.in} +@cindex @code{autoheader} + +The @command{autoheader} program can create a template file of C +@samp{#define} statements for @code{configure} to use. If +@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})}, +@command{autoheader} creates @file{@var{file}.in}; if multiple file +arguments are given, the first one is used. Otherwise, +@command{autoheader} creates @file{config.h.in}. + +In order to do its job, @command{autoheader} needs you to document all +of the symbols that you might use; i.e., there must be at least one +@code{AC_DEFINE} or one @code{AC_DEFINE_UNQUOTED} using its third +argument for each symbol (@pxref{Defining Symbols}). An additional +constraint is that the first argument of @code{AC_DEFINE} must be a +literal. Note that all symbols defined by Autoconf's built-in tests are +already documented properly; you only need to document those that you +define yourself. + +You might wonder why @command{autoheader} is needed: after all, why +would @command{configure} need to ``patch'' a @file{config.h.in} to +produce a @file{config.h} instead of just creating @file{config.h} from +scratch? Well, when everything rocks, the answer is just that we are +wasting our time maintaining @command{autoheader}: generating +@file{config.h} directly is all that is needed. When things go wrong, +however, you'll be thankful for the existence of @command{autoheader}. + +The fact that the symbols are documented is important in order to +@emph{check} that @file{config.h} makes sense. The fact that there is a +well defined list of symbols that should be @code{#define}'d (or not) is +also important for people who are porting packages to environments where +@command{configure} cannot be run: they just have to @emph{fill in the +blanks}. + +But let's come back to the point: @command{autoheader}'s invocation@dots{} + +If you give @command{autoheader} an argument, it uses that file instead +of @file{configure.ac} and writes the header file to the standard output +instead of to @file{config.h.in}. If you give @command{autoheader} an +argument of @option{-}, it reads the standard input instead of +@file{configure.ac} and writes the header file to the standard output. + +@code{autoheader} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --verbose +@itemx -v +Report processing steps. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@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 --warnings=@var{category} +@itemx -W @var{category} +@evindex WARNINGS +Report the warnings related to @var{category} (which can actually be a +comma separated list). Current categories include: + +@table @samp +@item obsolete +report the uses of obsolete constructs + +@item all +report all the warnings + +@item none +report none + +@item error +treats warnings as errors + +@item no-@var{category} +disable warnings falling into @var{category} +@end table + +@end table + + + +@node Autoheader Macros, , autoheader Invocation, Configuration Headers +@subsection Autoheader Macros + +@code{autoheader} scans @file{configure.ac} and figures out which C +preprocessor symbols it might define. It knows how to generate +templates for symbols defined by @code{AC_CHECK_HEADERS}, +@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional +symbol, you must define a template for it. If there are missing +templates, @code{autoheader} fails with an error message. + +The simplest way to create a template for a @var{symbol} is to supply +the @var{description} argument to an @samp{AC_DEFINE(@var{symbol})}; see +@ref{Defining Symbols}. You may also use one of the following macros. + +@defmac AH_VERBATIM (@var{key}, @var{template}) +@maindex AH_VERBATIM +@maindex VERBATIM +Tell @code{autoheader} to include the @var{template} as-is in the header +template file. This @var{template} is associated with the @var{key}, +which is used to sort all the different templates and guarantee their +uniqueness. It should be the symbol that can be @code{AC_DEFINE}'d. + +For example: + +@example +AH_VERBATIM([_GNU_SOURCE], +[/* Enable GNU extensions on systems that have them. */ +#ifndef _GNU_SOURCE +# define _GNU_SOURCE +#endif]) +@end example +@end defmac + + +@defmac AH_TEMPLATE (@var{key}, @var{description}) +@maindex AH_TEMPLATE +@maindex TEMPLATE +Tell @code{autoheader} to generate a template for @var{key}. This macro +generates standard templates just like @code{AC_DEFINE} when a +@var{description} is given. + +For example: + +@example +AH_TEMPLATE([CRAY_STACKSEG_END], + [Define to one of _getb67, GETB67, getb67 + for Cray-2 and Cray-YMP systems. This + function is required for alloca.c support + on those systems.]) +@end example + +@noindent +will generate the following template, with the description properly +justified. + +@example +/* Define to one of _getb67, GETB67, getb67 for Cray-2 and + Cray-YMP systems. This function is required for alloca.c + support on those systems. */ +#undef CRAY_STACKSEG_END +@end example +@end defmac + + +@defmac AH_TOP (@var{text}) +@maindex AH_TOP +@maindex TOP +Include @var{text} at the top of the header template file. +@end defmac + + +@defmac AH_BOTTOM (@var{text}) +@maindex AH_BOTTOM +@maindex BOTTOM +Include @var{text} at the bottom of the header template file. +@end defmac + + +@node Configuration Commands, Configuration Links, Configuration Headers, Setup +@section Running Arbitrary Configuration Commands + +You execute arbitrary commands either before, during and after +@file{config.status} is run. The three following macros accumulate the +commands to run when they are called multiple times. +@code{AC_CONFIG_COMMANDS} replaces the obsolete macro +@code{AC_OUTPUT_COMMANDS}, see @ref{Obsolete Macros}, for details. + +@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_COMMANDS +Specify additional shell commands to run at the end of +@file{config.status}, and shell commands to initialize any variables +from @code{configure}. Associate the commands to the @var{tag}. Since +typically the @var{cmds} create a file, @var{tag} should naturally be +the name of that file. This macro is one of the instantiating macros, +see @ref{Configuration Actions}. + +Here is an unrealistic example: +@example +fubar=42 +AC_CONFIG_COMMANDS(fubar, + [echo this is extra $fubar, and so on.], + [fubar=$fubar]) +@end example + +Here is a better one: +@example +AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp]) +@end example +@end defmac + +@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds}) +@maindex OUTPUT_COMMANDS_PRE +Execute the @var{cmds} right before creating @file{config.status}. A +typical use is computing values derived from variables built during the +execution of @code{configure}: + +@example +AC_CONFIG_COMMANDS_PRE( +[LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` +AC_SUBST(LTLIBOBJS)]) +@end example +@end defmac + +@defmac AC_CONFIG_COMMANDS_POST (@var{cmds}) +@maindex OUTPUT_COMMANDS_POST +Execute the @var{cmds} right after creating @file{config.status}. +@end defmac + + + + +@node Configuration Links, Subdirectories, Configuration Commands, Setup +@section Creating Configuration Links + +You may find it convenient to create links whose destinations depend upon +results of tests. One can use @code{AC_CONFIG_COMMANDS} but the +creation of relative symbolic links can be delicate when the package is +built in another directory than its sources. + +@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds}) +@maindex CONFIG_LINKS +@cindex Links +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. This +macro is one of the instantiating macros, see @ref{Configuration +Actions}. + +For example, this call: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example + +@noindent +creates in the current directory @file{host.h} as a link to +@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a +link to @file{@var{srcdir}/config/$obj_format.h}. + +The tempting value @samp{.} for @var{dest} is invalid: it makes it +impossible for @samp{config.status} to guess the links to establish. + +One can then run: +@example +./config.status host.h object.h +@end example +@noindent +to create the links. +@end defmac + + + +@node Subdirectories, Default Prefix, Configuration Links, 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. Each @var{dir} should +be a literal, i.e., please do not use: + +@example +if test "$package_foo_enabled" = yes; then + $my_subdirs="$my_subdirs foo" +fi +AC_CONFIG_SUBDIRS($my_subdirs) +@end example + +@noindent +because this prevents @samp{./configure --help=recursive} from +displaying the options of the package @code{foo}. Rather, you should +write: + +@example +if test "$package_foo_enabled" = yes then; + AC_CONFIG_SUBDIRS(foo) +fi +@end example + +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 @code{configure.gnu}, +it is run instead of @code{configure}. This is for packages that might +use a non-autoconf script @code{Configure}, which can't be called +through a wrapper @code{configure} since it would be the same file on +case-insensitive filesystems. Likewise, if a @var{dir} contains +@file{configure.ac} but no @code{configure}, the Cygnus @code{configure} +script found by @code{AC_CONFIG_AUX_DIR} 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. This macro may be called multiple +times. +@end defmac + +@node Default Prefix, , 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 @option{--prefix} and @option{--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}) +@maindex PREFIX_DEFAULT +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 +@option{--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 + + + +@c ======================================================== Existing tests + +@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 +* Common Behavior:: Macros' standard schemes +* Alternative Programs:: Selecting between alternative programs +* Files:: Checking for the existence of files +* Libraries:: Library archives that might be missing +* Library Functions:: C library functions that might be missing +* Header Files:: Header files that might be missing +* Declarations:: Declarations that may be missing +* Structures:: Structures or members that might be missing +* Types:: Types that might be missing +* Compilers and Preprocessors:: Checking for compiling programs +* System Services:: Operating system services +* UNIX Variants:: Special kludges for specific UNIX variants +@end menu + +@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests +@section Common Behavior + +Much effort has been expended to make Autoconf easy to learn. The most +obvious way to reach this goal is simply to enforce standard interfaces +and behaviors, avoiding exceptions as much as possible. Because of +history and inertia, unfortunately, there are still too many exceptions +in Autoconf; nevertheless, this section describes some of the common +rules. + +@menu +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros +@end menu + +@node Standard Symbols, Default Includes, Common Behavior, Common Behavior +@subsection Standard Symbols + +All the generic macros that @code{AC_DEFINE} a symbol as a result of +their test transform their @var{argument}s to a standard alphabet. +First, @var{argument} is converted to upper case and any asterisks +(@samp{*}) are each converted to @samp{P}. Any remaining characters +that are not alphanumeric are converted to underscores. + +For instance, + +@example +AC_CHECK_TYPES(struct $Expensive*) +@end example + +@noindent +will define the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check succeeds. + + +@node Default Includes, , Standard Symbols, Common Behavior +@subsection Default Includes +@cindex Includes, default + +Several tests depend upon a set of header files. Since these headers +are not universally available, tests actually have to provide a set of +protected includes, such as: + +@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 + +@noindent +Unless you know exactly what you are doing, you should avoid using +unconditional includes, and check the existence of the headers you +include beforehand (@pxref{Header Files}). + +Most generic macros provide the following default set of includes: + +@example +@group +#include <stdio.h> +#if HAVE_SYS_TYPES_H +# include <sys/types.h> +#endif +#if HAVE_SYS_STAT_H +# include <sys/stat.h> +#endif +#if STDC_HEADERS +# include <stdlib.h> +# include <stddef.h> +#else +# if HAVE_STDLIB_H +# include <stdlib.h> +# endif +#endif +#if HAVE_STRING_H +# if !STDC_HEADERS && HAVE_MEMORY_H +# include <memory.h> +# endif +# include <string.h> +#endif +#if HAVE_STRINGS_H +# include <strings.h> +#endif +#if HAVE_INTTYPES_H +# include <inttypes.h> +#else +# if HAVE_STDINT_H +# include <stdint.h> +# endif +#endif +#if HAVE_UNISTD_H +# include <unistd.h> +#endif +@end group +@end example + +If the default includes are used, then Autoconf will automatically check +for the presence of these headers and their compatibility, i.e., you +don't need to run @code{AC_HEADERS_STDC}, nor check for @file{stdlib.h} +etc. + +These headers are checked for in the same order as they are included. +For instance, on some systems @file{string.h} and @file{strings.h} both +exist, but conflict. Then @code{HAVE_STRING_H} will be defined, but +@code{HAVE_STRINGS_H} won't. + +@node Alternative Programs, Files, Common Behavior, Existing Tests +@section Alternative Programs +@cindex Programs, checking + +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, 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_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 is found. +It tries @code{mawk} first because that is reported to be the +fastest implementation. +@end defmac + + +@defmac AC_PROG_EGREP +@ovindex EGREP +Check for @code{grep -E}, @code{egrep} in that +order, and set output variable @code{EGREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_FGREP +@ovindex FGREP +Check for @code{grep -F}, @code{fgrep} in that +order, and set output variable @code{FGREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_GREP +@ovindex GREP +Check for @code{grep}, @code{ggrep} in that +order, and set output variable @code{GREP} to the first one that is found. +@end defmac + + +@defmac AC_PROG_INSTALL +@maindex PROG_INSTALL +@ovindex INSTALL +@ovindex INSTALL_PROGRAM +@ovindex INSTALL_DATA +@ovindex INSTALL_SCRIPT +Set output variable @code{INSTALL} to the path of a @sc{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 variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to +@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. + +This macro screens out various instances of @code{install} known not to +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}. + +Autoconf comes with a copy of @file{install-sh} that you can use. 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 @sc{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 file name of your program into your +@file{Makefile.in} files. +@end defmac + +@defmac AC_PROG_LEX +@maindex PROG_LEX +@ovindex LEX +@ovindex LEXLIB +@cvindex YYTEXT_POINTER +@ovindex LEX_OUTPUT_ROOT +If @code{flex} is found, set output variable @code{LEX} to @samp{flex} +and @code{LEXLIB} to @option{-lfl}, if that library is in a standard +place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to +@option{-ll}. + +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. + +You are encouraged to use Flex in your sources, since it is both more +pleasant to use than plain Lex and the C source it produces is portable. +In order to ensure portability, however, you must either provide a +function @code{yywrap} or, if you don't use it (e.g., your scanner has +no @samp{#include}-like feature), simply include a @samp{%noyywrap} +statement in the scanner's source. Once this done, the scanner is +portable (unless @emph{you} felt free to use nonportable constructs) and +does not depend on any library. In this case, and in this case only, it +is suggested that you use this Autoconf snippet: + +@example +AC_PROG_LEX +if test "$LEX" != flex; then + LEX="$SHELL $missing_dir/missing flex" + AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) + AC_SUBST(LEXLIB, '') +fi +@end example + +The shell script @command{missing} can be found in the Automake +distribution. + +To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes +(indirectly) this macro twice, which will cause an annoying but benign +``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions +of Automake will fix this issue, meanwhile, just ignore this message. +@end defmac + +@defmac AC_PROG_LN_S +@maindex PROG_LN_S +@ovindex LN_S +If @samp{ln -s} works on the current file system (the operating system +and file system support symbolic links), set the output variable +@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set +@code{LN_S} to @samp{ln} and otherwise set it to @samp{cp -p}. + +If you make a link a directory other than the current directory, its +meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely +create links using @samp{$(LN_S)}, either find out which form is used +and adjust the arguments, or always invoke @code{ln} in the directory +where the link is to be created. + +In other words, it does not work to do: +@example +$(LN_S) foo /x/bar +@end example + +Instead, do: + +@example +(cd /x && $(LN_S) foo bar) +@end example +@end defmac + +@defmac AC_PROG_RANLIB +@maindex PROG_RANLIB +@ovindex RANLIB +Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} +is found, and otherwise to @samp{:} (do nothing). +@end defmac + +@defmac AC_PROG_YACC +@maindex PROG_YACC +@ovindex YACC +If @code{byacc} is found, set @code{YACC} to @samp{byacc}. +Otherwise, if @code{bison} is found, +set output variable @code{YACC} to @samp{bison -y}. +Finally, if neither @code{byacc} or @code{bison} is found, +set @code{YACC} to @samp{yacc}. +@end defmac + +@node Generic Programs, , Particular Programs, Alternative Programs +@subsection Generic Program and File Checks + +These macros are used to find programs not covered by the ``particular'' +test macros. If you need to check the behavior of a program as well as +find out whether it is present, you have to write your own test for it +(@pxref{Writing Tests}). By default, these macros use the environment +variable @code{PATH}. If you need to check for a program that might not +be in the user's @code{PATH}, you can pass a modified path to use +instead, like this: + +@example +AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) +@end example + +You are strongly encouraged to declare the @var{variable} passed to +@code{AC_CHECK_PROG} etc. as precious, @xref{Setting Output Variables}, +@code{AC_ARG_VAR}, for more details. + +@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject}) +@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. Always pass over @var{reject} (an +absolute file name) even if it is the first found in the search path; in +that case, set @var{variable} using the absolute file name of the +@var{prog-to-check-for} found that is not @var{reject}. 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}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_PROGS +Check for each program in the whitespace-separated list +@var{progs-to-check-for} exists on the @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_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_TOOL +Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} +with a prefix of the host type as determined by +@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}). +For example, if the user runs @samp{configure --host=i386-gnu}, then +this call: +@example +AC_CHECK_TOOL(RANLIB, ranlib, :) +@end example +@noindent +sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in +@code{PATH}, or otherwise to @samp{ranlib} if that program exists in +@code{PATH}, or to @samp{:} if neither program exists. +@end defmac + +@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex CHECK_TOOLS +Like @code{AC_CHECK_TOOL}, each of the tools in the list @var{progs-to-check-for} are +checked with a prefix of the host type as determined by @code{AC_CANONICAL_HOST}, +followed by a dash (@pxref{Canonicalizing}). If none of the tools can be found with a +prefix, then the first one without a prefix is used. If a tool is found, set +@var{variable} to the name of that program. If none of the tools 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}, @ovar{value-if-not-found}, @ovar{path}) +@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}, @ovar{value-if-not-found}, @ovar{path}) +@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 + +@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) +@maindex PATH_TOOL +Like @code{AC_CHECK_TOOL}, but set @var{variable} to the entire +path of the program if it is found. +@end defmac + + +@node Files, Libraries, Alternative Programs, Existing Tests +@section Files +@cindex File, checking + +You might also need to check for the existence of files. Before using +these macros, ask yourself whether a run time test might not be a better +solution. Be aware that, like most Autoconf macros, they test a feature +of the host machine, and therefore, they die when cross-compiling. + +@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FILE +Check whether file @var{file} exists on the native system. If it is +found, execute @var{action-if-found}, otherwise do +@var{action-if-not-found}, if given. +@end defmac + +@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FILES +Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. +Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) +for each file found. +@end defmac + + +@node Libraries, Library Functions, Files, Existing Tests +@section Library Files +@cindex Library, checking + +The following macros check for the presence of certain C, C++ or Fortran +77 library archive files. + +@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@maindex CHECK_LIB +Depending on the current language(@pxref{Language Choice}), try to +ensure that the C, C++, or Fortran 77 function @var{function} is +available by checking whether a test 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 @option{-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} is not +specified, the default action will prepend @option{-l@var{library}} to +@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all +capitals). This macro is intended to support building of @code{LIBS} in +a right-to-left (least-dependent to most-dependent) fashion such that +library dependencies are satisfied as a natural side-effect of +consecutive tests. Some linkers are very sensitive to library ordering +so the order in which @code{LIBS} is generated is important to reliable +detection of libraries. + +If linking with @var{library} results in unresolved symbols that would +be resolved by linking with additional libraries, give those libraries +as the @var{other-libraries} argument, separated by spaces: +e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect +that @var{library} is present, because linking the test program will +always fail with unresolved symbols. The @var{other-libraries} argument +should be limited to cases where it is desirable to test for one library +in the presence of another that is not already in @code{LIBS}. +@end defmac + + +@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@maindex SEARCH_LIBS +Search for a library defining @var{function} if it's not already +available. This equates to calling @code{AC_TRY_LINK_FUNC} first +with no libraries, then for each library listed in @var{search-libs}. + +Add @option{-l@var{library}} to @code{LIBS} for the first library found +to contain @var{function}, and run @var{action-if-found}. If the +function is not found, run @var{action-if-not-found}. + +If linking with @var{library} results in unresolved symbols that would +be resolved by linking with additional libraries, give those libraries +as the @var{other-libraries} argument, separated by spaces: +e.g. @option{-lXt -lX11}. Otherwise, this macro will fail to detect +that @var{function} is present, because linking the test program will +always fail with unresolved symbols. +@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 +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions +@end menu + +@node Function Portability, Particular Functions, Library Functions, Library Functions +@subsection Portability of Classical Functions + +Most usual functions can either be missing, or be buggy, or be limited +on some architectures. This section tries to make an inventory of these +portability issues. By definition, this list will always require +additions, please help us keeping it as complete as possible + +@table @code + +@item unlink +The @sc{posix} spec says that @code{unlink} causes the given files to be +removed only after there are no more open file handles for it. Not all +OS's support this behaviour though. So even on systems that provide +@code{unlink}, you cannot portably assume it is OK to call it on files +that are open. For example, on Windows 9x and ME, such a call would fail; +on DOS it could even lead to file system corruption, as the file might end +up being written to after the OS has removed it. + +@end table + + +@node Particular Functions, Generic Functions, Function Portability, Library Functions +@subsection Particular Function Checks +@cindex Function, checking + +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-@sc{ansi} C compilers will ignore it, rather than +choke on it. + +@example +@group +/* AIX requires this to be the first thing in the file. */ +#ifndef __GNUC__ +# 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_CHOWN +@maindex FUNC_CHOWN +If the @code{chown} function is available and works (in particular, it +should accept @option{-1} for @code{uid} and @code{gid}), define +@code{HAVE_CHOWN}. +@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_ERROR_AT_LINE +@maindex FUNC_ERROR_AT_LINE +If the @code{error_at_line} function is not found, require an +@code{AC_LIBOBJ} replacement of @samp{error}. +@end defmac + +@defmac AC_FUNC_FNMATCH +@maindex FUNC_FNMATCH +If the @code{fnmatch} function is available and works (unlike the one on +Solaris 2.4), define @code{HAVE_FNMATCH}. +@end defmac + +@defmac AC_FUNC_FORK +@maindex FUNC_FORK +@cvindex HAVE_VFORK_H +@cvindex HAVE_WORKING_FORK +@cvindex HAVE_WORKING_VFORK +@cvindex vfork +This macro checks for the @code{fork} and @code{vfork} functions. If a +working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro +checks whether @code{fork} is just a stub by trying to run it. + +If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working +@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, +define @code{vfork} to be @code{fork} for backward compatibility with +previous versions of @command{autoconf}. 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. It is not considered +to be an implementation error if a child's invocation of @code{signal} +modifies the parent's signal handler, since child processes rarely change +their signal handlers. + +Since this macro defines @code{vfork} only for backward compatibility with +previous versions of @command{autoconf} you're encouraged to define it +yourself in new code: +@example +@group +#if !HAVE_WORKING_VFORK +# define vfork fork +#endif +@end group +@end example +@end defmac + +@defmac AC_FUNC_FSEEKO +@maindex FUNC_FSEEKO +@cvindex _LARGEFILE_SOURCE +If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. +Define @code{_LARGEFILE_SOURCE} if necessary. +@end defmac + +@defmac AC_FUNC_GETGROUPS +@maindex FUNC_GETGROUPS +@ovindex GETGROUPS_LIBS +If the @code{getgroups} function is available and works (unlike on +Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define +@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries +needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. +@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 +@cvindex C_GETLOADAVG +@ovindex LIBOBJS +@ovindex NEED_SETGID +@ovindex KMEM_GROUP +@ovindex GETLOADAVG_LIBS +Check how to get the system load averages. If the system has the +@code{getloadavg} function, define @code{HAVE_GETLOADAVG}, and set +@code{GETLOADAVG_LIBS} to any libraries needed to get that function. +Also add @code{GETLOADAVG_LIBS} to @code{LIBS}. + +Otherwise, require an @code{AC_LIBOBJ} replacement (@file{getloadavg.c}) +of @samp{getloadavg}, and possibly define several other C preprocessor +macros and output variables: + +@enumerate +@item +Define @code{C_GETLOADAVG}. + +@item +Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on +those systems. + +@item +If @file{nlist.h} is found, define @code{NLIST_STRUCT}. + +@item +If @samp{struct nlist} has an @samp{n_un.n_name} member, define +@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol +@code{NLIST_NAME_UNION} is still defined, but do not depend upon it. + +@item +Programs may need to be installed setgid (or setuid) for +@code{getloadavg} to work. In this case, define +@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID} +to @samp{true} (and otherwise to @samp{false}), and set +@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 @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen} +libraries, for Irix 4, PTX, and Unixware, respectively. Then, if +@code{getmntent} is available, define @code{HAVE_GETMNTENT}. +@end defmac + +@defmac AC_FUNC_GETPGRP +@maindex FUNC_GETPGRP +@cvindex GETPGRP_VOID +If @code{getpgrp} takes no argument (the @sc{posix.1} version), define +@code{GETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes +a process ID as an argument. This macro does not check whether +@code{getpgrp} exists at all; if you need to work in that situation, +first call @code{AC_CHECK_FUNC} for @code{getpgrp}. +@end defmac + +@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK +@maindex FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK +@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK +If @file{link} is a symbolic link, then @code{lstat} should treat +@file{link/} the same as @file{link/.}. However, many older +@code{lstat} implementations incorrectly ignore trailing slashes. + +It is safe to assume that if @code{lstat} incorrectly ignores +trailing slashes, then other symbolic-link-aware functions like +@code{unlink} and @code{unlink} also incorrectly ignore trailing slashes. + +If @code{lstat} behaves properly, define +@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an +@code{AC_LIBOBJ} replacement of @code{lstat}. +@end defmac + +@defmac AC_FUNC_MALLOC +@maindex FUNC_MALLOC +If the @code{malloc} works correctly (@samp{malloc (0)} returns a valid +pointer), define @code{HAVE_MALLOC}. +@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), or fails when comparing 16 +bytes or more and with at least one buffer not starting on a 4-byte +boundary (such as the one on NeXT x86 OpenStep), require an +@code{AC_LIBOBJ} replacement for @samp{memcmp}. +@end defmac + +@defmac AC_FUNC_MKTIME +@maindex FUNC_MKTIME +@ovindex LIBOBJS +If the @code{mktime} function is not available, or does not work +correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. +@end defmac + +@defmac AC_FUNC_MMAP +@maindex FUNC_MMAP +@cvindex HAVE_MMAP +If the @code{mmap} function exists and works correctly, define +@code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped +memory. +@end defmac + +@defmac AC_FUNC_OBSTACK +@maindex FUNC_OBSTACK +@cvindex HAVE_OBSTACK +@cindex obstack +If the obstacks are found, define @code{HAVE_OBSTACK}, else require an +@code{AC_LIBOBJ} replacement for @samp{obstack}. +@end defmac + +@defmac AC_FUNC_SELECT_ARGTYPES +@maindex FUNC_SELECT_ARGTYPES +@cvindex SELECT_TYPE_ARG1 +@cvindex SELECT_TYPE_ARG234 +@cvindex SELECT_TYPE_ARG5 +Determines the correct type to be passed for each of the +@code{select} function's arguments, and defines those types +in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and +@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults +to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, +and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. +@end defmac + +@defmac AC_FUNC_SETPGRP +@maindex FUNC_SETPGRP +@cvindex SETPGRP_VOID +If @code{setpgrp} takes no argument (the @sc{posix.1} version), define +@code{SETPGRP_VOID}. Otherwise, it is the @sc{bsd} version, which takes +two process IDs as arguments. This macro does not check whether +@code{setpgrp} exists at all; if you need to work in that situation, +first call @code{AC_CHECK_FUNC} for @code{setpgrp}. +@end defmac + +@defmac AC_FUNC_STAT +@defmacx AC_FUNC_LSTAT +@maindex FUNC_STAT +@maindex FUNC_LSTAT +@cvindex HAVE_STAT_EMPTY_STRING_BUG +@cvindex HAVE_LSTAT_EMPTY_STRING_BUG +Determine whether @code{stat} or @code{lstat} have the bug that it +succeeds when given the zero-length file name argument. The @code{stat} +and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do +this. + +If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or +@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ} +replacement of it. +@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}. +@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} that should not be used. +@end defmac + +@defmac AC_FUNC_STRTOD +@maindex FUNC_STRTOD +@ovindex POW_LIB +If the @code{strtod} function does not exist or doesn't work correctly, +ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, +because @file{strtod.c} is likely to need @samp{pow}, set the output +variable @code{POW_LIB} to the extra library needed. +@end defmac + +@defmac AC_FUNC_STRERROR_R +@maindex FUNC_STRERROR_R +@cvindex HAVE_STRERROR_R +@cvindex HAVE_WORKING_STRERROR_R +If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}. If +its implementation correctly returns a @code{char *}, define +@code{HAVE_WORKING_STRERROR_R}. On at least DEC UNIX 4.0[A-D] and HP-UX +B.10.20, @code{strerror_r} returns @code{int}. Actually, this tests +only whether it returns a scalar or an array, but that should be enough. +This is used by the common @file{error.c}. +@end defmac + +@defmac AC_FUNC_STRFTIME +@maindex FUNC_STRFTIME +@cvindex HAVE_STRFTIME +Check for @code{strftime} in the @file{intl} library, for SCO @sc{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_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 + +@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}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@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(C++)} has been called, since C is more +standardized than C++. (@pxref{Language Choice}, for more information +about selecting the language for checks.) +@end defmac + +@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex CHECK_FUNCS +@cvindex HAVE_@var{function} +For each @var{function} in the whitespace-separated argument list, +define @code{HAVE_@var{function}} (in all capitals) if it is available. +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 + +Autoconf follows a philosophy that was formed over the years by those +who have struggled for portability: isolate the portability issues in +specific files, and then program as if you were in a @sc{posix} +environment. Some functions may be missing or unfixable, and your +package must be ready to replace them. + +Use the first three of the following macros to specify a function to be +replaced, and the last one (@code{AC_REPLACE_FUNCS}) to check for and +replace the function if needed. + +@defmac AC_LIBOBJ (@var{function}) +@maindex LIBOBJ +@ovindex LIBOBJS +Specify that @samp{@var{function}.c} must be included in the executables +to replace a missing or broken implementation of @var{function}. + +Technically, it adds @samp{@var{function}.$ac_objext} to the output +variable @code{LIBOBJS} and calls @code{AC_LIBSOURCE} for +@samp{@var{function}.c}. You should not directly change @code{LIBOBJS}, +since this is not traceable. +@end defmac + +@defmac AC_LIBSOURCE (@var{file}) +@maindex LIBSOURCE +Specify that @var{file} might be needed to compile the project. If you +need to know what files might be needed by a @file{configure.ac}, you +should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. + +This macro is called automatically from @code{AC_LIBOBJ}, but you must +call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In +that case, since shell variables cannot be traced statically, you must +pass to @code{AC_LIBSOURCE} any possible files that the shell variable +might cause @code{AC_LIBOBJ} to need. For example, if you want to pass +a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either +@code{"foo"} or @code{"bar"}, you should do: + +@example +AC_LIBSOURCE(foo.c) +AC_LIBSOURCE(bar.c) +AC_LIBOBJ($foo_or_bar) +@end example + +@noindent +There is usually a way to avoid this, however, and you are encouraged to +simply call @code{AC_LIBOBJ} with literal arguments. + +Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with +slightly different semantics: the old macro took the function name, +e.g. @code{foo}, as its argument rather than the file name. +@end defmac + +@defmac AC_LIBSOURCES (@var{files}) +@maindex LIBSOURCES +Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a +comma-separated M4 list. Thus, the above example might be rewritten: + +@example +AC_LIBSOURCES([foo.c, bar.c]) +AC_LIBOBJ($foo_or_bar) +@end example +@end defmac + +@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) +@maindex REPLACE_FUNCS +@ovindex LIBOBJS +Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as +@var{action-if-not-found}. You can declare your replacement function by +enclosing the prototype in @samp{#if !HAVE_@var{function}}. If the +system has the function, it probably declares it in a header file you +should be including, so you shouldn't redeclare it lest your declaration +conflict. +@end defmac + +@node Header Files, Declarations, Library Functions, Existing Tests +@section Header Files +@cindex Header, checking + +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, 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_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. For the first one that is +found and defines @samp{DIR}, define the listed C preprocessor macro: + +@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}} +@item @file{dirent.h} @tab @code{HAVE_DIRENT_H} +@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H} +@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H} +@item @file{ndir.h} @tab @code{HAVE_NDIR_H} +@end multitable + +The directory-library declarations in your 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 +of 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_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_STDC +@maindex HEADER_STDC +@cvindex STDC_HEADERS +Define @code{STDC_HEADERS} if the system has @sc{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 @sc{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 @sc{ansi} C requires. + +Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether +the system has @sc{ansi}-compliant header files (and probably C library +functions) because many systems that have GCC do not have @sc{ansi} C +header files. + +On systems without @sc{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 @sc{ansi} and @sc{bsd}; some are mostly @sc{ansi} but +lack @samp{memmove}; some define the @sc{bsd} functions as macros in +@file{string.h} or @file{strings.h}; some have only the @sc{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 @sc{ansi} versions of those then it probably has +most of the others. If you put the following in @file{configure.ac}: + +@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 +# if !HAVE_STRCHR +# define strchr index +# define strrchr rindex +# endif +char *strchr (), *strrchr (); +# if !HAVE_MEMCPY +# define memcpy(d, s, n) bcopy ((s), (d), (n)) +# define memmove(d, s, n) bcopy ((s), (d), (n)) +# endif +#endif +@end group +@end example + +@noindent +If you use a function like @code{memchr}, @code{memset}, @code{strtok}, +or @code{strspn}, which have no @sc{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 @sc{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 @sc{bsd} @code{union wait} instead +of @code{int} to store a status value. If @file{sys/wait.h} is not +@sc{posix.1} compatible, then instead of including it, define the +@sc{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 + +@cvindex _POSIX_VERSION +@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on +@sc{posix.1} systems. If there is no @file{unistd.h}, it is definitely +not a @sc{posix.1} system. However, some non-@sc{posix.1} systems do +have @file{unistd.h}. + +The way to check if the system supports @sc{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 + +@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_HEADER_TIOCGWINSZ +@maindex HEADER_TIOCGWINSZ +@cvindex GWINSZ_IN_SYS_IOCTL +@c FIXME: I need clarifications from Jim. +If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then +define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be +found in @file{<termios.h>}. + +Use: + +@example +@group +#if HAVE_TERMIOS_H +# include <termios.h> +#endif + +#if GWINSZ_IN_SYS_IOCTL +# include <sys/ioctl.h> +#endif +@end group +@end example +@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}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_HEADER +If the system header file @var{header-file} is usable, 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. + +The meaning of ``usable'' depends upon the content of @var{includes}: + +@table @asis +@item if @var{includes} is empty +check whether + +@example +@var{header-file} +@end example + +@noindent +can be @emph{preprocessed} without error. + +@item if @var{include} is set +Check whether + +@example +@var{includes} +#include <@var{header-file}> +@end example + +@noindent +can be @emph{compiled} without error. You may use +@code{AC_CHECK_HEADER} (and @code{AC_CHECK_HEADERS}) to check whether +two headers are compatible. +@end table + +You may pass any kind of dummy content for @var{includes}, such as a +single space, a comment, to check whether @var{header-file} compiles +with success. +@end defmac + +@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@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. + +Be sure to read the documentation of @code{AC_CHECK_HEADER} to +understand the influence of @var{includes}. +@end defmac + +@node Declarations, Structures, Header Files, Existing Tests +@section Declarations +@cindex Declaration, checking + +The following macros check for the declaration of variables and +functions. If there is no macro specifically defined to check for a +symbol you need, then you can use the general macros (@pxref{Generic +Declarations}) or, for more complex tests, you may use +@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}). + +@menu +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations +@end menu + +@node Particular Declarations, Generic Declarations, Declarations, Declarations +@subsection Particular Declaration Checks + +The following macros check for certain declarations. + +@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 + +@node Generic Declarations, , Particular Declarations, Declarations +@subsection Generic Declaration Checks + +These macros are used to find declarations not covered by the ``particular'' +test macros. + +@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_DECL +If @var{symbol} (a function or a variable) is not declared in +@var{includes} and a declaration is needed, run the shell commands +@var{action-if-not-found}, otherwise @var{action-if-found}. If no +@var{includes} are specified, the default includes are used +(@pxref{Default Includes}). + +This macro actually tests whether it is valid to use @var{symbol} as an +r-value, not if it is really declared, because it is much safer to avoid +introducing extra declarations when they are not needed. +@end defmac + +@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_DECLS +@cvindex HAVE_DECL_@var{symbol} +For each of the @var{symbols} (@emph{comma}-separated list), define +@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if +@var{symbol} is declared, otherwise to @samp{0}. If +@var{action-if-not-found} is given, it is additional shell code to +execute when one of the function declarations is needed, otherwise +@var{action-if-found} is executed. + +This macro uses an m4 list as first argument: +@example +AC_CHECK_DECLS(strdup) +AC_CHECK_DECLS([strlen]) +AC_CHECK_DECLS([malloc, realloc, calloc, free]) +@end example + +Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not +declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead +of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are +@emph{sure} that the check was performed, use +@code{HAVE_DECL_@var{symbol}} just like any other result of Autoconf: + +@example +#if !HAVE_DECL_SYMBOL +extern char *symbol; +#endif +@end example + +@noindent +If the test may have not been performed, however, because it is safer +@emph{not} to declare a symbol than to use a declaration that conflicts +with the system's one, you should use: + +@example +#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC +char *malloc (size_t *s); +#endif +@end example + +@noindent +You fall into the second category only in extreme situations: either +your files may be used without being configured, or they are used during +the configuration. In most cases the traditional approach is enough. +@end defmac + + +@node Structures, Types, Declarations, Existing Tests +@section Structures +@cindex Structure, checking + +The following macros check for the presence of certain members in C +structures. If there is no macro specifically defined to check for a +member you need, then you can use the general structure-member macro +(@pxref{Generic Structures}) or, for more complex tests, you may use +@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}). + +@menu +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members +@end menu + +@node Particular Structures, Generic Structures, Structures, Structures +@subsection Particular Structure Checks + +The following macros check for certain structures or structure members. + +@defmac AC_STRUCT_ST_BLKSIZE +@maindex STRUCT_ST_BLKSIZE +@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE +@cvindex HAVE_ST_BLKSIZE +If @code{struct stat} contains an @code{st_blksize} member, define +@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name, +@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in +the future. This macro is obsoleted, and should be replaced by + +@example +AC_CHECK_MEMBERS([struct stat.st_blksize]) +@end example +@end defmac + +@defmac AC_STRUCT_ST_BLOCKS +@maindex STRUCT_ST_BLOCKS +@cvindex HAVE_STRUCT_STAT_ST_BLOCKS +@cvindex HAVE_ST_BLOCKS +@ovindex LIBOBJS +If @code{struct stat} contains an @code{st_blocks} member, define +@code{HAVE_STRUCT STAT_ST_BLOCKS}. Otherwise, require an +@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name, +@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the +future. +@end defmac + +@defmac AC_STRUCT_ST_RDEV +@maindex STRUCT_ST_RDEV +@cvindex HAVE_ST_RDEV +@cvindex HAVE_STRUCT_STAT_ST_RDEV +If @code{struct stat} contains an @code{st_rdev} member, define +@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro, +@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported +in the future. Actually, even the new macro is obsolete, and should be +replaced by: +@example +AC_CHECK_MEMBERS([struct stat.st_rdev]) +@end example +@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_STRUCT_TM_TM_ZONE} (and the +obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array +@code{tzname} is found, define @code{HAVE_TZNAME}. +@end defmac + +@node Generic Structures, , Particular Structures, Structures +@subsection Generic Structure Checks + +These macros are used to find structure members not covered by the +``particular'' test macros. + +@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_MEMBER +Check whether @var{member} is a member of the aggregate @var{aggregate}. +If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). + +@example +AC_CHECK_MEMBER(struct passwd.pw_gecos,, + [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], + [#include <pwd.h>]) +@end example + +You can use this macro for sub-members: + +@example +AC_CHECK_MEMBER(struct top.middle.bot) +@end example +@end defmac + +@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_MEMBERS +Check for the existence of each @samp{@var{aggregate}.@var{member}} of +@var{members} using the previous macro. When @var{member} belongs to +@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all +capitals, with spaces and dots replaced by underscores). + +This macro uses m4 lists: +@example +AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) +@end example +@end defmac + + +@node Types, Compilers and Preprocessors, Structures, Existing Tests +@section Types + +The following macros check for C types, either builtin or typedefs. If +there is no macro specifically defined to check for a type you need, and +you don't need to check for any special properties of it, then you can +use a general type-check macro. + +@menu +* Particular Types:: Special handling to find certain types +* Generic Types:: How to find other types +@end menu + +@node Particular Types, Generic Types, Types, Types +@subsection Particular Type Checks + +These macros check for particular C types in @file{sys/types.h}, +@file{stdlib.h} and others, if they exist. + +@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 +Equivalent to @samp{AC_CHECK_TYPE(mode_t, int)}. +@end defmac + +@defmac AC_TYPE_OFF_T +@maindex TYPE_OFF_T +@cvindex off_t +Equivalent to @samp{AC_CHECK_TYPE(off_t, long)}. +@end defmac + +@defmac AC_TYPE_PID_T +@maindex TYPE_PID_T +@cvindex pid_t +Equivalent to @samp{AC_CHECK_TYPE(pid_t, 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 +Equivalent to @samp{AC_CHECK_TYPE(size_t, 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 Types, , Particular Types, Types +@subsection Generic Type Checks + +These macros are used to check for types not covered by the ``particular'' +test macros. + +@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_TYPE +Check whether @var{type} is defined. It may be a compiler builtin type +or defined by the @ovar{includes} (@pxref{Default Includes}). +@end defmac + + +@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) +@maindex CHECK_TYPES +For each @var{type} of the @var{types} that is defined, define +@code{HAVE_@var{type}} (in all capitals). If no @var{includes} are +specified, the default includes are used (@pxref{Default Includes}). If +@var{action-if-found} is given, it is additional shell code to execute +when one of the types is found. If @var{action-if-not-found} is given, +it is executed when one of the types is not found. + +This macro uses m4 lists: +@example +AC_CHECK_TYPES(ptrdiff_t) +AC_CHECK_TYPES([unsigned long long, uintmax_t]) +@end example + +@end defmac + +Autoconf, up to 2.13, used to provide to another version of +@code{AC_CHECK_TYPE}, broken by design. In order to keep backward +compatibility, a simple heuristics, quite safe but not totally, is +implemented. In case of doubt, read the documentation of the former +@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}. + + +@node Compilers and Preprocessors, System Services, Types, Existing Tests +@section Compilers and Preprocessors + +@ovindex EXEEXT +All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX}, +@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on +the output of the compiler, typically to the empty string if Unix and +@samp{.exe} if Win32 or OS/2. + +@ovindex OBJEXT +They also define the output variable @code{OBJEXT} based on the +output of the compiler, after .c files have been excluded, typically +to @samp{o} if Unix, @samp{obj} if Win32. + +If the compiler being used does not produce executables, they fail. If +the executables can't be run, and cross-compilation is not enabled, they +fail too. @xref{Manual Configuration}, for more on support for cross +compiling. + +@menu +* Generic Compiler Characteristics:: Language independent tests +* C Compiler:: Checking its characteristics +* C++ Compiler:: Likewise +* Fortran 77 Compiler:: Likewise +@end menu + +@node Generic Compiler Characteristics, C Compiler, Compilers and Preprocessors, Compilers and Preprocessors +@subsection Generic Compiler Characteristics + +@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @ovar{includes}) +@maindex CHECK_SIZEOF +Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the +size in bytes of @var{type}. If @samp{type} is unknown, it gets a size +of 0. If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). If you provide @var{include}, make sure to +include @file{stdio.h} which is required for this macro to run. + +This macro now works even when cross-compiling. The @var{unused} +argument was used when cross-compiling. + +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 + + +@node C Compiler, C++ Compiler, Generic Compiler Characteristics, Compilers and Preprocessors +@subsection C Compiler Characteristics + +@defmac AC_PROG_CC (@ovar{compiler-search-list}) +@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 @code{cc}, then for other C +compilers. Set output variable @code{CC} to the name of the compiler +found. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of C compilers to +search for. This just gives the user an opportunity to specify an +alternative search list for the C compiler. For example, if you didn't +like the default order, then you could invoke @code{AC_PROG_CC} like +this: + +@example +AC_PROG_CC(cl egcs gcc cc) +@end example + +If using the @sc{gnu} C compiler, set shell variable @code{GCC} to +@samp{yes}. If output variable @code{CFLAGS} was not already set, set +it to @option{-g -O2} for the @sc{gnu} C compiler (@option{-O2} on systems +where GCC does not accept @option{-g}), or @option{-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 @option{-c} and @option{-o} options +simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually +tests both the compiler found by @code{AC_PROG_CC}, and, if different, +the first @code{cc} in the path. The test fails if one fails. This +macro was created for @sc{gnu} Make to choose the default C compilation +rule. +@end defmac + +@defmac AC_PROG_CC_STDC +@maindex PROG_CC_STDC +@ovindex CC +If the C compiler is not in @sc{ansi} C mode by default, try to add an +option to output variable @code{CC} to make it so. This macro tries +various options that select @sc{ansi} C on some system or another. It +considers the compiler to be in @sc{ansi} C mode if it handles function +prototypes correctly. + +If you use this macro, you should check after calling it whether the C +compiler has been set to accept @sc{ansi} C; if not, the shell variable +@code{ac_cv_prog_cc_stdc} is set to @samp{no}. If you wrote your source +code in @sc{ansi} C, you can make an un-@sc{ansi}fied copy of it by +using the program @code{ansi2knr}, which comes with Automake. +@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, @file{/lib/cpp} is used. +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}. + +Some preprocessors don't indicate missing include files by the error +status. For such preprocessors an internal variable is set that causes +other macros to check the standard error from the preprocessor and +consider the test failed if any warnings have been reported. +@end defmac + + +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 +@cindex Endianness +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 @sc{ansi} C qualifier +@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. + +Occasionally installers use a C++ compiler to compile C code, typically +because they lack a C compiler. This causes problems with @code{const}, +because C and C++ treat @code{const} differently. For example: + +@example +const int foo; +@end example + +@noindent +is valid in C but not in C++. These differences unfortunately cannot be +papered over by defining @code{const} to be empty. + +If @code{autoconf} detects this situation, it leaves @code{const} alone, +as this generally yields better results in practice. However, using a +C++ compiler to compile C code is not recommended or supported, and +installers who run into trouble in this area should get a C compiler +like GCC to compile their C code. +@end defmac + +@defmac AC_C_VOLATILE +@maindex C_VOLATILE +@cvindex volatile +If the C compiler does not understand the keyword @code{volatile}, +define @code{volatile} to be empty. Programs can simply use +@code{volatile} as if every C compiler supported it; for those that do +not, the @file{Makefile} or configuration header will define it as +empty. + +If the correctness of your program depends on the semantics of +@code{volatile}, simply defining it to be empty does, in a sense, break +your code. However, given that the compiler does not support +@code{volatile}, you are at its mercy anyway. At least your +program will compile, when it wouldn't before. + +In general, the @code{volatile} keyword is a feature of @sc{ansi} C, so +you might expect that @code{volatile} is available only when +@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does +support volatile, but does not defined @code{__STDC__}. +@end defmac + +@defmac AC_C_INLINE +@maindex C_INLINE +@cvindex inline +If the C compiler supports the keyword @code{inline}, do nothing. +Otherwise define @code{inline} to @code{__inline__} or @code{__inline} +if it accepts one of those, otherwise define @code{inline} to be empty. +@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_C_STRINGIZE +@maindex C_STRINGIZE +@cvindex HAVE_STRINGIZE +If the C preprocessor supports the stringizing operator, define +@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is +found in macros such as this: + +@example +#define x(y) #y +@end example +@end defmac + +@defmac AC_C_PROTOTYPES +@maindex C_PROTOTYPES +@cvindex PROTOTYPES +@cvindex PARAMS +Check to see if function prototypes are understood by the compiler. If +so, define @samp{PROTOTYPES}. In the case the compiler does not handle +prototypes, you should use @code{ansi2knr}, which comes with the +Automake distribution, to unprotoize function definitions. For +function prototypes, you should first define @code{PARAMS}: + +@example +#ifndef PARAMS +# if PROTOTYPES +# define PARAMS(protos) protos +# else /* no PROTOTYPES */ +# define PARAMS(protos) () +# endif /* no PROTOTYPES */ +#endif +@end example + +@noindent +then use it this way: + +@example +size_t my_strlen PARAMS ((const char *)); +@end example +@end defmac + +@defmac AC_PROG_GCC_TRADITIONAL +@maindex PROG_GCC_TRADITIONAL +@ovindex CC +Add @option{-traditional} to output variable @code{CC} if using the +@sc{gnu} C compiler and @code{ioctl} does not work properly without +@option{-traditional}. That usually happens when the fixed header files +have not been installed on an old system. Since recent versions of the +@sc{gnu} C compiler fix the header files automatically when installed, +this is becoming a less prevalent problem. +@end defmac + + +@node C++ Compiler, Fortran 77 Compiler, C Compiler, Compilers and Preprocessors +@subsection C++ Compiler Characteristics + + +@defmac AC_PROG_CXX (@ovar{compiler-search-list}) +@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, then set output +variable @code{CXX} to its value. + +Otherwise, if the macro is invoked without an argument, then search for +a C++ compiler under the likely names (first @code{g++} and @code{c++} +then other names). If none of those checks succeed, then as a last +resort set @code{CXX} to @code{g++}. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of C++ compilers to +search for. This just gives the user an opportunity to specify an +alternative search list for the C++ compiler. For example, if you +didn't like the default order, then you could invoke @code{AC_PROG_CXX} +like this: + +@example +AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc) +@end example + +If using the @sc{gnu} C++ compiler, set shell variable @code{GXX} to +@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set +it to @option{-g -O2} for the @sc{gnu} C++ compiler (@option{-O2} on +systems where G++ does not accept @option{-g}), or @option{-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, @file{/lib/cpp} is used. +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}. + +Some preprocessors don't indicate missing include files by the error +status. For such preprocessors an internal variable is set that causes +other macros to check the standard error from the preprocessor and +consider the test failed if any warnings have been reported. However, +it is not known whether such broken preprocessors exist for C++. +@end defmac + + + +@node Fortran 77 Compiler, , C++ Compiler, Compilers and Preprocessors +@subsection Fortran 77 Compiler Characteristics + +@defmac AC_PROG_F77 (@ovar{compiler-search-list}) +@maindex PROG_FORTRAN +@ovindex F77 +@ovindex FFLAGS +Determine a Fortran 77 compiler to use. If @code{F77} is not already +set in the environment, then check for @code{g77} and @code{f77}, and +then some other names. Set the output variable @code{F77} to the name +of the compiler found. + +This macro may, however, be invoked with an optional first argument +which, if specified, must be a space separated list of Fortran 77 +compilers to search for. This just gives the user an opportunity to +specify an alternative search list for the Fortran 77 compiler. For +example, if you didn't like the default order, then you could invoke +@code{AC_PROG_F77} like this: + +@example +AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90) +@end example + +If using @code{g77} (the @sc{gnu} Fortran 77 compiler), then +@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}. +If the output variable @code{FFLAGS} was not already set in the +environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} +where @code{g77} does not accept @option{-g}). Otherwise, set +@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. +@end defmac + +@defmac AC_PROG_F77_C_O +@maindex PROG_F77_C_O +@cvindex F77_NO_MINUS_C_MINUS_O +Test if the Fortran 77 compiler accepts the options @option{-c} and +@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it +does not. +@end defmac + + +The following macros check for Fortran 77 compiler characteristics. To +check for characteristics not listed here, use @code{AC_TRY_COMPILE} +(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}), +making sure to first set the current language to Fortran 77 +@code{AC_LANG(Fortran 77)} (@pxref{Language Choice}). + + +@defmac AC_F77_LIBRARY_LDFLAGS +@maindex F77_LIBRARY_LDFLAGS +@ovindex FLIBS +Determine the linker flags (e.g. @option{-L} and @option{-l}) for the +@dfn{Fortran 77 intrinsic and run-time libraries} that are required to +successfully link a Fortran 77 program or shared library. The output +variable @code{FLIBS} is set to these flags. + +This macro is intended to be used in those situations when it is +necessary to mix, e.g. C++ and Fortran 77 source code into a single +program or shared library (@pxref{Mixing Fortran 77 With C and C++,,, +automake, GNU Automake}). + +For example, if object files from a C++ and Fortran 77 compiler must be +linked together, then the C++ compiler/linker must be used for linking +(since special C++-ish things need to happen at link time like calling +global constructors, instantiating templates, enabling exception +support, etc.). + +However, the Fortran 77 intrinsic and run-time libraries must be linked +in as well, but the C++ compiler/linker doesn't know by default how to +add these Fortran 77 libraries. Hence, the macro +@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77 +libraries. + +The macro @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} will probably +also be necessary to link C/C++ with Fortran; see below. +@end defmac + + +@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex F77_DUMMY_MAIN +@cvindex F77_DUMMY_MAIN +With many compilers, the Fortran libraries detected by +@code{AC_F77_LIBRARY_LDFLAGS} provide their own @code{main} entry +function that initializes things like Fortran I/O, and which then calls +a user-provided entry function named e.g. @code{MAIN__} to run the +user's program. The @code{AC_F77_DUMMY_MAIN} or @code{AC_F77_MAIN} +macro figures out how to deal with this interaction. + +When using Fortran for purely numerical functions (no I/O, etcetera), +users often prefer to provide their own @code{main} and skip the Fortran +library initializations. In this case, however, one may still need to +provide a dummy @code{MAIN__} routine in order to prevent linking errors +on some systems. @code{AC_F77_DUMMY_MAIN} detects whether any such +routine is @emph{required} for linking, and what its name is; the shell +variable @code{F77_DUMMY_MAIN} holds this name, @code{unknown} when no +solution was found, and @code{none} when no such dummy main is needed. + +By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} to the +name of this routine (e.g. @code{MAIN__}) @emph{if} it is required. +@ovar{action-if-not-found} defaults to exiting with an error. + +In order to link with Fortran routines, the user's C/C++ program should +then include the following code to define the dummy main if it is +needed: + +@example +#ifdef F77_DUMMY_MAIN +# ifdef __cplusplus + extern "C" +# endif + int F77_DUMMY_MAIN() @{ return 1; @} +#endif +@end example + +Note that @code{AC_F77_DUMMY_MAIN} is called automatically from +@code{AC_F77_WRAPPERS}; there is generally no need to call it explicitly +unless one wants to change the default actions. +@end defmac + +@defmac AC_F77_MAIN +@maindex F77_MAIN +@cvindex F77_MAIN +As discussed above for @code{AC_F77_DUMMY_MAIN}, many Fortran libraries +allow you to provide an entry point called e.g. @code{MAIN__} instead of +the usual @code{main}, which is then called by a @code{main} function in +the Fortran libraries that initializes things like Fortran I/O. The +@code{AC_F77_MAIN} macro detects whether it is @emph{possible} to +utilize such an alternate main function, and defines @code{F77_MAIN} to +the name of the function. (If no alternate main function name is found, +@code{F77_MAIN} is simply defined to @code{main}.) + +Thus, when calling Fortran routines from C that perform things like I/O, +one should use this macro and name the "main" function @code{F77_MAIN} +instead of @code{main}. +@end defmac + +@defmac AC_F77_WRAPPERS +@maindex F77_WRAPPERS +@cvindex F77_FUNC +@cvindex F77_FUNC_ +Defines C macros @code{F77_FUNC(name,NAME)} and +@code{F77_FUNC_(name,NAME)} to properly mangle the names of C/C++ +identifiers, and identifiers with underscores, respectively, so that +they match the name-mangling scheme used by the Fortran 77 compiler. + +Fortran 77 is case-insensitive, and in order to achieve this the Fortran +77 compiler converts all identifiers into a canonical case and format. +To call a Fortran 77 subroutine from C or to write a C function that is +callable from Fortran 77, the C program must explicitly use identifiers +in the format expected by the Fortran 77 compiler. In order to do this, +one simply wraps all C identifiers in one of the macros provided by +@code{AC_F77_WRAPPERS}. For example, suppose you have the following +Fortran 77 subroutine: + +@example + subroutine foobar(x,y) + double precision x, y + y = 3.14159 * x + return + end +@end example + +You would then declare its prototype in C or C++ as: + +@example +#define FOOBAR_F77 F77_FUNC(foobar,FOOBAR) +#ifdef __cplusplus +extern "C" /* prevent C++ name mangling */ +#endif +void FOOBAR_F77(double *x, double *y); +@end example + +Note that we pass both the lowercase and uppercase versions of the +function name to @code{F77_FUNC} so that it can select the right one. +Note also that all parameters to Fortran 77 routines are passed as +pointers (@pxref{Mixing Fortran 77 With C and C++,,, automake, GNU +Automake}). + +Although Autoconf tries to be intelligent about detecting the +name-mangling scheme of the Fortran 77 compiler, there may be Fortran 77 +compilers that it doesn't support yet. In this case, the above code +will generate a compile-time error, but some other behavior +(e.g. disabling Fortran-related features) can be induced by checking +whether the @code{F77_FUNC} macro is defined. + +Now, to call that routine from a C program, we would do something like: + +@example +@{ + double x = 2.7183, y; + FOOBAR_F77(&x, &y); +@} +@end example + +If the Fortran 77 identifier contains an underscore +(e.g. @code{foo_bar}), you should use @code{F77_FUNC_} instead of +@code{F77_FUNC} (with the same arguments). This is because some Fortran +77 compilers mangle names differently if they contain an underscore. +@end defmac + +@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar}) +@maindex F77_FUNC +Given an identifier @var{name}, set the shell variable @var{shellvar} to +hold the mangled version @var{name} according to the rules of the +Fortran 77 linker (see also @code{AC_F77_WRAPPERS}). @var{shellvar} is +optional; if it is not supplied, the shell variable will be simply +@var{name}. The purpose of this macro is to give the caller a way to +access the name-mangling information other than through the C +preprocessor as above; for example, to call Fortran routines from some +language other than C/C++. +@end defmac + +@node System Services, UNIX Variants, Compilers and Preprocessors, Existing Tests +@section System Services + +The following macros check for operating system services or capabilities. + +@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 @option{--x-includes=@var{dir}} and +@option{--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 +@option{--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 +@cvindex X_DISPLAY_MISSING +An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags +that X needs to output variable @code{X_CFLAGS}, and the X linker flags +to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not +available. + +This macro also checks for special libraries that some systems need in +order to compile X programs. It adds any that the system needs to +output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 +libraries that need to be linked with before @option{-lX11}, and adds +any found to the output variable @code{X_PRE_LIBS}. + +@c This is an incomplete kludge. Make a real way to do it. +@c If you need to check for other X functions or libraries yourself, then +@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to +@c @code{LIBS} temporarily, like this: (FIXME - add example) +@end defmac + +@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.ac} can check +the shell variable @code{interpval}; it will be set to @samp{yes} +if the system supports @samp{#!}, @samp{no} if not. +@end defmac + +@defmac AC_SYS_LARGEFILE +@maindex SYS_LARGEFILE +@cvindex _FILE_OFFSET_BITS +@cvindex _LARGE_FILES +@ovindex CC +Arrange for +@href{http://www.sas.com/standards/large.file/x_open.20Mar96.html, +large-file support}. On some hosts, one must use special compiler +options to build programs that can access large files. Append any such +options to the output variable @code{CC}. Define +@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. + +Large-file support can be disabled by configuring with the +@option{--disable-largefile} option. + +If you use this macro, check that your program works even when +@code{off_t} is longer than @code{long}, since this is common when +large-file support is enabled. For example, it is not correct to print +an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", +(long) X)}. +@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_POSIX_TERMIOS +@maindex SYS_POSIX_TERMIOS +@cindex POSIX termios headers +@cindex termios POSIX headers +Check to see if POSIX termios headers and functions are available on the +system. If so, set the shell variable @code{am_cv_sys_posix_termios} to +@samp{yes}. If not, set the variable to @samp{no}. +@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 @sc{bsd} +functions. Should be called before any macros that run the C compiler. +@end defmac + +@defmac AC_ISC_POSIX +@maindex ISC_POSIX +@cvindex _POSIX_SOURCE +@ovindex CC +If on a POSIXized ISC @sc{unix}, define @code{_POSIX_SOURCE} and add +@option{-posix} (for the @sc{gnu} C compiler) or @option{-Xp} (for other C +compilers) to output variable @code{CC}. This allows the use of +@sc{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 @sc{posix} +facilities. Should be called before any macros that run the C compiler. +@end defmac + + + + +@c ========================================================= Writing Tests + +@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. + +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. +@xref{Writing Autoconf Macros}, for how to do that. + +@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 +* Systemology:: A zoology of operating systems +* 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, 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}, @ovar{action-if-true}, @ovar{action-if-false}) +@maindex TRY_CPP +@var{includes} is C or C++ @code{#include} statements and declarations, +on which shell variable, back quote, 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 +@option{-g}, @option{-O}, etc. are not valid options to many C +preprocessors. +@end defmac + +Here is how 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}, @ovar{action-if-not-found}) +@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}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex EGREP_CPP +@var{program} is the text of a C or C++ program, on which shell +variable, back quote, 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, C++ or Fortran 77 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}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_COMPILE +Create a C, C++ or Fortran 77 test program (depending on which language +is current, @pxref{Language Choice}), to see whether a function whose +body consists of @var{function-body} can be compiled. + +For C and C++, @var{includes} is any @code{#include} statements needed +by the code in @var{function-body} (@var{includes} will be ignored if +the currently selected language is Fortran 77). This macro also uses +@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently +selected language, as well as @code{CPPFLAGS}, when compiling. If +Fortran 77 is the currently selected language then @code{FFLAGS} will be +used when compiling. + +If the file compiles successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. + +This macro 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. If users encounter this problem, they might be able to +solve it by setting @code{LDFLAGS} in the environment to pass whatever +options the linker needs (for example, @option{-Wl,-dn} on @sc{mips +risc/os}). + +@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 (@pxref{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}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_LINK +Depending on the current language (@pxref{Language Choice}), create a +test program to see whether a function whose body consists of +@var{function-body} can be compiled and linked. + +For C and C++, @var{includes} is any @code{#include} statements needed +by the code in @var{function-body} (@var{includes} will be ignored if +the currently selected language is Fortran 77). This macro also uses +@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently +selected language, as well as @code{CPPFLAGS}, when compiling. If +Fortran 77 is the currently selected language then @code{FFLAGS} will be +used when compiling. However, both @code{LDFLAGS} and @code{LIBS} will +be used during linking in all cases. + +If the file compiles and links successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. +@end defmac + +@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}) +@maindex TRY_LINK_FUNC +Depending on the current language (@pxref{Language Choice}), create a +test program to see whether a program whose body consists of +a prototype of and a call to @var{function} can be compiled and linked. + +If the file compiles and links successfully, run shell commands +@var{action-if-found}, otherwise run @var{action-if-not-found}. +@end defmac + + + +@node Run Time, Systemology, 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 this 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, 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}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling}) +@maindex TRY_RUN +@var{program} is the text of a C program, on which shell variable and +back quote 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. 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 host 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_PROG_CC} 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. + + +@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.ac} you can have a test program that includes an +@sc{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{conftest.data}. 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 Systemology, Multiple Cases, Run Time, Writing Tests +@section Systemology + +This section aims at presenting some systems and pointers to +documentation. It may help you addressing particular problems reported +by users. + +@table @asis +@item @sc{qnx 4.25} +@cindex @sc{qnx 4.25} +@c FIXME: Please, if you feel like writing something more precise, +@c it'd be great. In particular, I can't understand the difference with +@c QNX Neutrino. +@sc{qnx} is a realtime operating system running on Intel architecture +meant to be scalable from the small embedded systems to hundred +processor super-computer. It claims to be @sc{posix} certified. More +information is available on the @href{www.qnx.com, @sc{qnx} home page}, +including the @href{http://support.qnx.com/support/docs/qnx4/, @sc{qnx} +man pages}. +@end table + + +@node Multiple Cases, Language Choice, Systemology, Writing Tests +@section Multiple Cases + +Some operations are accomplished in several possible ways, depending on +the @sc{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 file system 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 +@cindex Language + +Autoconf-generated @code{configure} scripts check for the C compiler and +its features by default. Packages that use other programming languages +(maybe more than one, e.g. C and C++) need to test features of the +compilers for the respective languages. The following macros determine +which programming language is used in the subsequent tests in +@file{configure.ac}. + +@defmac AC_LANG (@var{language}) +Do compilation tests using the compiler, preprocessor and file +extensions for the specified @var{language}. + +Supported languages are: + +@table @samp +@item C +Do compilation tests using @code{CC} and @code{CPP} and use extension +@file{.c} for test programs. + +@item C++ +Do compilation tests using @code{CXX} and @code{CXXCPP} and use +extension @file{.C} for test programs. + +@item Fortran 77 +Do compilation tests using @code{F77} and use extension @file{.f} for +test programs. +@end table +@end defmac + +@defmac AC_LANG_PUSH (@var{language}) +@maindex LANG_PUSH +Remember the current language (as set by @code{AC_LANG}) on a stack, and +then select the @var{language}. Use this macro and @code{AC_LANG_POP} +in macros that need to temporarily switch to a particular language. +@end defmac + +@defmac AC_LANG_POP (@ovar{language}) +@maindex LANG_POP +Select the language that is saved on the top of the stack, as set by +@code{AC_LANG_PUSH}, and remove it from the stack. + +If given, @var{language} specifies the language we just @emph{quit}. It +is a good idea to specify it when it's known (which should be the +case@dots{}), since Autoconf will detect inconsistencies. + +@example +AC_LANG_PUSH(Fortran 77) +# Perform some tests on Fortran 77. +# ... +AC_LANG_POP(Fortran 77) +@end example +@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 + + + +@c ====================================================== Results of Tests. + +@node Results, Programming in M4, 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 @code{configure} users +@end menu + +@node Defining Symbols, Setting Output Variables, Results, 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 +@option{-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_HEADERS} 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}, @ovar{value}, @ovar{description}) +@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_HEADERS} 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 M4 quote +characters @samp{[} or @samp{]}), use @code{AC_DEFINE_UNQUOTED} instead. +@var{description} is only useful if you are using +@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into +the generated @file{config.h.in} as the comment before the macro define. +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}, @ovar{value}, @ovar{description}) +@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 + +Another 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}, @ovar{value}) +@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. This value of @var{variable} should not contain literal +newlines. + +If @var{value} is given, in addition assign it to @samp{variable}. +@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.ac} +could contain: + +@example +AC_SUBST_FILE(host_frag) +host_frag=$srcdir/conf/sun4.mh +@end example + +@noindent +and then a @file{Makefile.in} could contain: + +@example +@@host_frag@@ +@end example +@end defmac + +@cindex Previous Variable +@cindex Variable, Precious +Running @command{configure} in different environments can be extremely +dangerous. If for instance the user runs @samp{CC=bizarre-cc +./configure}, then the cache, @file{config.h} and many other output +files will depend upon @command{bizarre-cc} being the C compiler. If +for some reason the user runs @command{/configure} again, or if it is +run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, +and @pxref{config.status Invocation}), then the configuration can be +inconsistent, composed of results depending upon two different +compilers. + +Such variables are named @dfn{precious variables}, and can be declared +as such by @code{AC_ARG_VAR}. + +@defmac AC_ARG_VAR (@var{variable}, @var{description}) +@maindex ARG_VAR +Declare @var{variable} is a precious variable, and include its +@var{description} in the variable section of @samp{./configure --help}. + +Being precious means that +@itemize @minus +@item +@var{variable} is @code{AC_SUBST}'d. + +@item +@var{variable} is kept in the cache including if it was not specified on +the @samp{./configure} command line. Indeed, while @command{configure} +can notice the definition of @code{CC} in @samp{./configure +CC=bizarre-cc}, it is impossible to notice it in @samp{CC=bizarre-cc +./configure}, which, unfortunately, is what most users do. + +@item +@var{variable} is checked for consistency between two +@command{configure} runs. For instance: + +@example +$ ./configure --silent --config-cache +$ CC=cc ./configure --silent --config-cache +configure: error: `CC' was not set in the previous run +configure: error: changes in the environment can compromise \ +the build +configure: error: run `make distclean' and/or \ +`rm config.cache' and start over +@end example + +@noindent +and similarly if the variable is unset, or if its content is changed. + + +@item +@var{variable} is kept during automatic reconfiguration +(@pxref{config.status Invocation}) as if it had been passed as a command +line argument, including when no cache is used: + +@example +$ CC=/usr/bin/cc ./configure undeclared_var=raboof --silent +$ ./config.status --recheck +running /bin/sh ./configure undeclared_var=raboof --silent \ + CC=/usr/bin/cc --no-create --no-recursion +@end example +@end itemize +@end defmac + + +@node Caching Results, Printing Messages, Setting Output Variables, Results +@section Caching Results +@cindex Cache + +To avoid checking for the same features repeatedly in various +@code{configure} scripts (or in repeated runs of one script), +@code{configure} can optionally save the results of many checks in a +@dfn{cache file} (@pxref{Cache Files}). If a @code{configure} script +runs with caching enabled and finds a cache file, it reads the results +of previous runs from the cache and avoids rerunning those checks. As a +result, @code{configure} can then 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 @option{--quiet} or +@option{--silent} option, print a message saying that the result was +cached; otherwise, run the shell commands @var{commands-to-set-it}. 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. + +The @var{commands-to-set-it} @emph{must have no side effects} except for +setting the variable @var{cache-id}, see below. +@end defmac + +@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it}) +@maindex CACHE_CHECK +A wrapper for @code{AC_CACHE_VAL} that takes care of printing the +messages. This macro provides a convenient shorthand for the most +common way to use these macros. It calls @code{AC_MSG_CHECKING} for +@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and +@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. + +The @var{commands-to-set-it} @emph{must have no side effects} except for +setting the variable @var{cache-id}, see below. +@end defmac + +It is very common to find buggy macros using @code{AC_CACHE_VAL} or +@code{AC_CACHE_CHECK}, because people are tempted to call +@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that +@emph{follows} the call to @code{AC_CACHE_VAL} should call +@code{AC_DEFINE}, by examining the value of the cache variable. For +instance, the following macro is broken: + +@example +@group +AC_DEFUN([AC_SHELL_TRUE], +[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi]) +]) +@end group +@end example + +@noindent +This fails if the cache is enabled: the second time this macro is run, +@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation +is: + +@example +@group +AC_DEFUN([AC_SHELL_TRUE], +[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], + [ac_cv_shell_true_works=no + true && ac_cv_shell_true_works=yes]) + if test $ac_cv_shell_true_works = yes; then + AC_DEFINE([TRUE_WORKS], 1 + [Define if `true(1)' works properly.]) + fi +]) +@end group +@end example + +Also, @var{commands-to-set-it} 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. + +@menu +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files @code{configure} uses for caching +* Cache Checkpointing:: Loading and saving the cache file +@end menu + +@node Cache Variable Names, Cache Files, Caching Results, Caching Results +@subsection Cache Variable Names +@cindex Cache variable + +The names of cache variables should have the following format: + +@example +@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options} +@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. This string +@emph{must} be present in the variable name, including the leading +underscore. + +@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 + +The values assigned to cache variables may not contain newlines. +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 Checkpointing, 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, @code{configure} uses no cache file (technically, it uses +@option{--cache-file=/dev/null}), to avoid problems caused by accidental +use of stale cache files. + +To enable caching, @code{configure} accepts @option{--config-cache} (or +@option{-C}) to cache results in the file @file{config.cache}. +Alternatively, @option{--cache-file=@var{file}} specifies that +@var{file} be the cache file. The cache file is created if it does not +exist already. When @code{configure} calls @code{configure} scripts in +subdirectories, it uses the @option{--cache-file} argument so that they +share the same cache. @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 @option{--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 site initialization script can specify a site-wide cache file to +use, instead of the usual per-program cache. In this case, the cache +file will gradually accumulate information whenever someone runs a new +@code{configure} script. (Running @code{configure} merges the new cache +results with the existing cache file.) This may cause problems, +however, if the system configuration (e.g. the installed libraries or +compilers) changes and the stale cache file is not deleted. + +@node Cache Checkpointing, , Cache Files, Caching Results +@subsection Cache Checkpointing + +If your configure script, or a macro called from configure.ac, happens +to abort the configure process, it may be useful to checkpoint the cache +a few times at key points using @code{AC_CACHE_SAVE}. Doing so will +reduce the amount of time it takes to re-run the configure script with +(hopefully) the error that caused the previous abort corrected. + +@c FIXME: Do we really want to document this guy? +@defmac AC_CACHE_LOAD +@maindex CACHE_LOAD +Loads values from existing cache file, or creates a new cache file if a +cache file is not found. Called automatically from @code{AC_INIT}. +@end defmac + +@defmac AC_CACHE_SAVE +@maindex CACHE_SAVE +Flushes all cached values to the cache file. Called automatically from +@code{AC_OUTPUT}, but it can be quite useful to call +@code{AC_CACHE_SAVE} at key points in configure.ac. +@end defmac + +For instance: + +@example +@r{ @dots{} AC_INIT, etc. @dots{}} +@group +# Checks for programs. +AC_PROG_CC +AC_PROG_GCC_TRADITIONAL +@r{ @dots{} more program checks @dots{}} +AC_CACHE_SAVE +@end group + +@group +# Checks for libraries. +AC_CHECK_LIB(nsl, gethostbyname) +AC_CHECK_LIB(socket, connect) +@r{ @dots{} more lib checks @dots{}} +AC_CACHE_SAVE +@end group + +@group +# Might abort... +AM_PATH_GTK(1.0.2,, (exit 1); exit) +AM_PATH_GTKMM(0.9.5,, (exit 1); exit) +@end group +@r{ @dots{} AC_OUTPUT, etc. @dots{}} +@end example + +@node Printing Messages, , Caching Results, Results +@section Printing Messages +@cindex Messages, from @code{configure} + +@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 back-quote +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 will change +automatically. + +To diagnose static issues, i.e., when @code{autoconf} is run, see +@ref{Reporting Messages}. + +@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 +@option{--quiet} or @option{--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 +@option{--quiet} or @option{--silent} option. +@end defmac + +@defmac AC_MSG_NOTICE (@var{message}) +@maindex MSG_NOTICE +Deliver the @var{message} to the user. It is useful mainly to print a +general description of the overall purpose of a group of feature checks, +e.g., + +@example +AC_MSG_NOTICE([checking if stack overflow is detectable]) +@end example + +This macro prints nothing if @code{configure} is run with the +@option{--quiet} or @option{--silent} option. +@end defmac + +@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status}) +@maindex MSG_ERROR +Notify the user of an error that prevents @code{configure} from +completing. This macro prints an error message to the standard error +output and exits @code{configure} with @var{exit-status} (1 by default). +@var{error-description} should be something like @samp{invalid value +$HOME for \$HOME}. + +The @var{error-description} should start with a lower-case letter, and +``cannot'' is preferred to ``can't''. +@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 to the standard error output; @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 + + + +@c ====================================================== Programming in M4. + +@node Programming in M4, Writing Autoconf Macros, Results, Top +@chapter Programming in M4 + +Autoconf is written on top of two layers: @dfn{M4sugar}, which provides +convenient macros for pure M4 programming, and @dfn{M4sh}, which +provides macros dedicated to shell script generation. + +As of this version of Autoconf, these two layers are still experimental, +and their interface might change in the future. As a matter of fact, +@emph{anything that is not documented must not be used}. + +@menu +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros +@end menu + +@node M4 Quotation, Programming in M4sugar, Programming in M4, Programming in M4 +@section M4 Quotation +@cindex quotation + +@c FIXME: Grmph, yet another quoting myth: quotation has *never* +@c prevented `expansion' of $1. Unless it refers to the expansion +@c of the value of $1? Anyway, we need a rewrite here@dots{} + +The most common brokenness of existing macros is an improper quotation. +This section, which users of Autoconf can skip, but which macro writers +@emph{must} read, first justifies the quotation scheme that was chosen +for Autoconf and then ends with a rule of thumb. Understanding the +former helps one to follow the latter. + +@menu +* Active Characters:: Characters that change the behavior of m4 +* One Macro Call:: Quotation and one macro call +* Quotation and Nested Macros:: Macros calling macros +* Quadrigraphs:: Another way to escape special characters +* Quotation Rule Of Thumb:: One parenthesis, one quote +@end menu + +@node Active Characters, One Macro Call, M4 Quotation, M4 Quotation +@subsection Active Characters + +To fully understand where proper quotation is important, you first need +to know what are the special characters in Autoconf: @samp{#} introduces +a comment inside which no macro expansion is performed, @samp{,} +separates arguments, @samp{[} and @samp{]} are the quotes themselves, +and finally @samp{(} and @samp{)} (which @code{m4} tries to match by +pairs). + +In order to understand the delicate case of macro calls, we first have +to present some obvious failures. Below they are ``obvious-ified'', +although you find them in real life, they are usually in disguise. + +Comments, introduced by a hash and running up to the newline, are opaque +tokens to the top level: active characters are turned off, and there is +no macro expansion: + +@example +# define([def], ine) +@result{}# define([def], ine) +@end example + +Each time there can be a macro expansion, there is a quotation +expansion; i.e., one level of quotes is stripped: + +@example +int tab[10]; +@result{}int tab10; +[int tab[10];] +@result{}int tab[10]; +@end example + +Without this in mind, the reader will try hopelessly to use her macro +@code{array}: + +@example +define([array], [int tab[10];]) +array +@result{}int tab10; +[array] +@result{}array +@end example + +@noindent +How can you correctly output the intended results@footnote{Using +@code{defn}.}? + + +@node One Macro Call, Quotation and Nested Macros, Active Characters, M4 Quotation +@subsection One Macro Call + +Let's proceed on the interaction between active characters and macros +with this small macro, which just returns its first argument: + +@example +define([car], [$1]) +@end example + +@noindent +The two pairs of quotes above are not part of the arguments of +@code{define}; rather, they are understood by the top level when it +tries to find the arguments of @code{define}. Therefore, it is +equivalent to write: + +@example +define(car, $1) +@end example + +@noindent +But, while it is acceptable for a @file{configure.ac} to avoid unneeded +quotes, it is bad practice for Autoconf macros which must both be more +robust and also advocate perfect style. + +At the top level, there are only two possible quotings: either you +quote or you don't: + +@example +car(foo, bar, baz) +@result{}foo +[car(foo, bar, baz)] +@result{}car(foo, bar, baz) +@end example + +Let's pay attention to the special characters: + +@example +car(#) +@error{}EOF in argument list +@end example + +The closing parenthesis is hidden in the comment; with a hypothetical +quoting, the top level understood it this way: + +@example +car([#)] +@end example + +@noindent +Proper quotation, of course, fixes the problem: + +@example +car([#]) +@result{}# +@end example + +The reader will easily understand the following examples: + +@example +car(foo, bar) +@result{}foo +car([foo, bar]) +@result{}foo, bar +car((foo, bar)) +@result{}(foo, bar) +car([(foo], [bar)]) +@result{}(foo +car([], []) +@result{} +car([[]], [[]]) +@result{}[] +@end example + +With this in mind, we can explore the cases where macros invoke +macros@dots{} + + +@node Quotation and Nested Macros, Quadrigraphs, One Macro Call, M4 Quotation +@subsection Quotation and Nested Macros + +The examples below use the following macros: + +@example +define([car], [$1]) +define([active], [ACT, IVE]) +define([array], [int tab[10]]) +@end example + +Each additional embedded macro call introduces other possible +interesting quotations: + +@example +car(active) +@result{}ACT +car([active]) +@result{}ACT, IVE +car([[active]]) +@result{}active +@end example + +In the first case, the top level looks for the arguments of @code{car}, +and finds @samp{active}. Because @code{m4} evaluates its arguments +before applying the macro, @samp{active} is expanded, which results in: + +@example +car(ACT, IVE) +@result{}ACT +@end example + +@noindent +In the second case, the top level gives @samp{active} as first and only +argument of @code{car}, which results in: + +@example +active +@result{}ACT, IVE +@end example + +@noindent +i.e., the argument is evaluated @emph{after} the macro that invokes it. +In the third case, @code{car} receives @samp{[active]}, which results in: + +@example +[active] +@result{}active +@end example + +@noindent +exactly as we already saw above. + +The example above, applied to a more realistic example, gives: + +@example +car(int tab[10];) +@result{}int tab10; +car([int tab[10];]) +@result{}int tab10; +car([[int tab[10];]]) +@result{}int tab[10]; +@end example + +@noindent +Huh? The first case is easily understood, but why is the second wrong, +and the third right? To understand that, you must know that after +@code{m4} expands a macro, the resulting text is immediately subjected +to macro expansion and quote removal. This means that the quote removal +occurs twice---first before the argument is passed to the @code{car} +macro, and second after the @code{car} macro expands to the first +argument. + +As the author of the Autoconf macro @code{car}, you then consider it to +be incorrect that your users have to double-quote the arguments of +@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for +quoted car: + +@example +define([qar], [[$1]]) +@end example + +@noindent +and check that @code{qar} is properly fixed: + +@example +qar([int tab[10];]) +@result{}int tab[10]; +@end example + +@noindent +Ahhh! That's much better. + +But note what you've done: now that the arguments are literal strings, +if the user wants to use the results of expansions as arguments, she has +to use an @emph{unquoted} macro call: + +@example +qar(active) +@result{}ACT +@end example + +@noindent +where she wanted to reproduce what she used to do with @code{car}: + +@example +car([active]) +@result{}ACT, IVE +@end example + +@noindent +Worse yet: she wants to use a macro that produces a set of @code{cpp} +macros: + +@example +define([my_includes], [#include <stdio.h>]) +car([my_includes]) +@result{}#include <stdio.h> +qar(my_includes) +@error{}EOF in argument list +@end example + +This macro, @code{qar}, because it double quotes its arguments, forces +its users to leave their macro calls unquoted, which is dangerous. +Commas and other active symbols are interpreted by @code{m4} before +they are given to the macro, often not in the way the users expect. +Also, because @code{qar} behaves differently from the other macros, +it's an exception that should be avoided in Autoconf. + + +@node Quadrigraphs, Quotation Rule Of Thumb, Quotation and Nested Macros, M4 Quotation +@subsection Quadrigraphs +@cindex quadrigraphs +@cindex @samp{@@<:@@} +@cindex @samp{@@:>@@} +@cindex @samp{@@S|@@} +@cindex @samp{@@%:@@} + +When writing an autoconf macro you may occasionally need to generate +special characters that are difficult to express with the standard +autoconf quoting rules. For example, you may need to output the regular +expression @samp{[^[]}, which matches any character other than @samp{[}. +This expression contains unbalanced brackets so it cannot be put easily +into an M4 macro. + +You can work around this problem by using one of the following +@dfn{quadrigraphs}: + +@table @samp +@item @@<:@@ +@samp{[} +@item @@:>@@ +@samp{]} +@item @@S|@@ +@samp{$} +@item @@%:@@ +@samp{#} +@end table + +Quadrigraphs are replaced at a late stage of the translation process, +after @command{m4} is run, so they do not get in the way of M4 quoting. +For example, the string @samp{[^@@<:@@]}, if properly quoted, will +appear as @samp{[^[]} in the @code{configure} script. + + +@node Quotation Rule Of Thumb, , Quadrigraphs, M4 Quotation +@subsection Quotation Rule Of Thumb + +To conclude, the quotation rule of thumb is: + +@center @emph{One pair of quotes per pair of parentheses.} + +Never over-quote, never under-quote, in particular in the definition of +macros. In the few places where the macros need to use brackets +(usually in C program text or regular expressions), properly quote +@emph{the arguments}! + +It is common to read Autoconf programs with snippets like: + +@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 + +@noindent +which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} +double quoting, so you just need: + +@example +AC_TRY_LINK( +[#include <time.h> +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others reject char **tzname. */ +#endif], + [atoi (*tzname);], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) +@end example + +@noindent +The M4-fluent reader will note that these two examples are rigorously +equivalent, since @code{m4} swallows both the @samp{changequote(<<, >>)} +and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these +quotes are not part of the arguments! + +Simplified, the example above is just doing this: + +@example +changequote(<<, >>)dnl +<<[]>> +changequote([, ])dnl +@end example + +@noindent +instead of simply: + +@example +[[]] +@end example + + +With macros that do not double quote their arguments (which is the +rule), double-quote the (risky) literals: + +@example +AC_LINK_IFELSE([AC_LANG_PROGRAM( +[[#include <time.h> +#ifndef tzname /* For SGI. */ +extern char *tzname[]; /* RS6000 and others reject char **tzname. */ +#endif]], + [atoi (*tzname);])], + [ac_cv_var_tzname=yes], + [ac_cv_var_tzname=no]) +@end example + +See @xref{Quadrigraphs}, for what to do if you run into a hopeless case +where quoting does not suffice. + +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 Programming in M4sugar, , M4 Quotation, Programming in M4 +@section Programming in M4sugar + +@cindex M4sugar +M4 by itself provides only a small, but sufficient, set of all-purpose +macros. M4sugar introduces additional generic macros. Its name was +coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 +M4sugar''. + +@menu +* Redefined M4 Macros:: M4 builtins changed in M4sugar +* Forbidden Patterns:: Catching unexpanded macros +@end menu + +@node Redefined M4 Macros, Forbidden Patterns, Programming in M4sugar, Programming in M4sugar +@subsection Redefined M4 Macros + +All the M4 native macros are moved in the @samp{m4_} pseudo-namespace, +e.g., M4sugar renames @code{define} as @code{m4_define} etc. There is +one exception: @code{dnl} kept its original name, and no @code{m4_dnl} +is defined. + +M4sugar redefines some M4 macros, and made them slightly incompatible +with their native equivalent. + +@defmac m4_defn (@var{macro}) +@msindex defn +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. See @code{m4_undefine}. +@end defmac + +@defmac m4_undefine (@var{macro}) +@msindex undefine +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. Use + +@example +m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) +@end example + +@noindent +to recover the behavior of the builtin. +@end defmac + +@defmac m4_popdef (@var{macro}) +@msindex defn +Contrary to the M4 builtin, this macro fails if @var{macro} is not +defined. See @code{m4_undefine}. +@end defmac + +@node Forbidden Patterns, , Redefined M4 Macros, Programming in M4sugar +@subsection Forbidden Patterns + +M4sugar provides a means to define suspicious patterns, patterns +describing tokens which should not be found in the output. For +instance, if an Autoconf @file{configure} script includes tokens such as +@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went +wrong (typically a macro was not evaluated because of over quotation). + +M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}. + +@defmac m4_pattern_forbid (@var{pattern}) +@msindex pattern_forbid +Declare no token matching @var{pattern} must be found in the output. +Comments are not checked; this can be a problem if, for instance, you +have some macro left unexpanded after an @samp{#include}. No consensus +is currently found in the Autoconf community, as some people consider it +should be valid to name macros in comments (which doesn't makes sense to +the author of this documentation, as @samp{#}-comments should document +the output, not the input, documented vy @samp{dnl}-comments). +@end defmac + +Of course, you might encounter exceptions to these generic rules, for +instance you might have to refer to @samp{$m4_flags}. + +@defmac m4_pattern_allow (@var{pattern}) +@msindex pattern_allow +Any token matching @var{pattern} is allowed, including if it matches an +@code{m4_pattern_forbid} pattern. +@end defmac + +@c=================================================== Writing Autoconf Macros. + +@node Writing Autoconf Macros, Portable Shell, Programming in M4, Top +@chapter Writing Autoconf 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 +* Reporting Messages:: Notifying @code{autoconf} users +* Dependencies Between Macros:: What to do when macros depend on other macros +* Obsoleting Macros:: Warning about old ways of doing things +* Coding Style:: Writing Autoconf macros @`a la Autoconf +@end menu + +@node Macro Definitions, Macro Names, Writing Autoconf Macros, Writing Autoconf Macros +@section Macro Definitions + +@maindex DEFUN +Autoconf macros are defined using the @code{AC_DEFUN} macro, which is +similar to the M4 builtin @code{define} macro. In addition to defining +a macro, @code{AC_DEFUN} adds to it some code that 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 + +You can refer to any arguments passed to the macro as @samp{$1}, +@samp{$2}, etc. @xref{Definitions,, How to define new macros, m4.info, +GNU m4}, for more complete information on writing M4 macros. + +Be sure to properly quote both the @var{macro-body} @emph{and} the +@var{macro-name} to avoid any problems if the macro happens to have +been previously defined. + +Each macro should have a header comment that gives its prototype, and a +brief description. When arguments have default values, display them in +the prototype. For example: + +@example +# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) +# -------------------------------------- +define([AC_MSG_ERROR], +[@{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); @}]) +@end example + +Comments about the macro should be left in the header comment. Most +other comments will make their way into @file{configure}, so just keep +using @samp{#} to introduce comments. + +@cindex @code{dnl} +If you have some very special comments about pure M4 code, comments +that make no sense in @file{configure} and in the header comment, then +use the builtin @code{dnl}: it causes @code{m4} to discard the text +through the next newline. + +Keep in mind that @code{dnl} is rarely needed to introduce comments; +@code{dnl} is more useful to get rid of the newlines following macros +that produce no output, such as @code{AC_REQUIRE}. + + +@node Macro Names, Reporting Messages, Macro Definitions, Writing Autoconf 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 +@sc{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 MEMBER +Members of aggregates. +@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. + +An internal macro should have a name that starts with an underscore; +Autoconf internals should therefore start with @samp{_AC_}. +Additionally, a macro that is an internal subroutine of another macro +should have a name that starts with an underscore and 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 Reporting Messages, Dependencies Between Macros, Macro Names, Writing Autoconf Macros +@section Reporting Messages +@cindex Messages, from @code{autoconf} + +When macros statically diagnose abnormal situations, benign or fatal, +they should report them using these macros. For dynamic issues, i.e., +when @code{configure} is run, see @ref{Printing Messages}. + +@defmac AC_DIAGNOSE (@var{category}, @var{message}) +@maindex DIAGNOSE +Report @var{message} as a warning (or as an error if requested by the +user) if it falls into the @var{category}. You are encouraged to use +standard categories, which currently include: + +@table @samp +@item all +messages that don't fall into one of the following category. Use of an +empty @var{category} is equivalent. + +@item cross +related to cross compilation issues. + +@item obsolete +use of an obsolete construct. + +@item syntax +dubious syntactic constructs, incorrectly ordered macro calls. +@end table +@end defmac + +@defmac AC_WARNING (@var{message}) +@maindex WARNING +Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are +strongly encouraged to use a finer grained category. +@end defmac + +@defmac AC_FATAL (@var{message}) +@maindex FATAL +Report a severe error @var{message}, and have @code{autoconf} die. +@end defmac + +When the user runs @samp{autoconf -W error}, warnings from +@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see +@ref{autoconf Invocation}. + +@node Dependencies Between Macros, Obsoleting Macros, Reporting Messages, Writing Autoconf 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 +@end menu + +@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, 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 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. + +@code{AC_REQUIRE} must be used inside an @code{AC_DEFUN}'d macro; it +must not be called from the top level. +@end defmac + +@code{AC_REQUIRE} is often misunderstood. It really implements +dependencies between macros in the sense that if one macro depends upon +another, the latter will be expanded @emph{before} the body of the +former. In particular, @samp{AC_REQUIRE(FOO)} is not replaced with the +body of @code{FOO}. For instance, this definition of macros: + +@example +@group +AC_DEFUN([TRAVOLTA], +[test "$body_temparature_in_celsius" -gt "38" && + dance_floor=occupied]) +AC_DEFUN([NEWTON_JOHN], +[test "$hair_style" = "curly" && + dance_floor=occupied]) +@end group + +@group +AC_DEFUN([RESERVE_DANCE_FLOOR], +[if date | grep '^Sat.*pm' >/dev/null 2>&1; then + AC_REQUIRE([TRAVOLTA]) + AC_REQUIRE([NEWTON_JOHN]) +fi]) +@end group +@end example + +@noindent +with this @file{configure.ac} + +@example +AC_INIT +RESERVE_DANCE_FLOOR +if test "$dance_floor" = occupied; then + AC_MSG_ERROR([cannot pick up here, let's move]) +fi +@end example + +@noindent +will not leave you with a better chance to meet a kindred soul at +other times than Saturday night since it expands into: + +@example +@group +test "$body_temperature_in_Celsius" -gt "38" && + dance_floor=occupied +test "$hair_style" = "curly" && + dance_floor=occupied +fi +if date | grep '^Sat.*pm' >/dev/null 2>&1; then + + +fi +@end group +@end example + +This behavior was chosen on purpose: (i) it prevents messages in +required macros from interrupting the messages in the requiring macros; +(ii) it avoids bad surprises when shell conditionals are used, as in: + +@example +@group +if @dots{}; then + AC_REQUIRE([SOME_CHECK]) +fi +@dots{} +SOME_CHECK +@end group +@end example + + +You are encouraged to put all @code{AC_REQUIRE}s at the beginning of a +macro. You can use @code{dnl} to avoid the empty lines they leave. + +@node Suggested Ordering, , 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.ac} file. The warning occurs when creating +@code{configure} from @file{configure.ac}, not when running +@code{configure}. + +For example, @code{AC_PROG_CPP} checks whether the C compiler +can run the C preprocessor when given the @option{-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 to 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 Obsoleting Macros, Coding Style, Dependencies Between Macros, Writing Autoconf Macros +@section Obsoleting 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, hence they should be replaced with more modern +macros. Ideally, @code{autoupdate} should substitute the old macro calls +with their modern implementation. + +Autoconf provides a simple means to obsolete a macro. + +@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) +@maindex DEFUN +@maindex AU_DEFUN +Define @var{old-macro} as @var{implementation}. The only difference +with @code{AC_DEFUN} is that the user will be warned that +@var{old-macro} is now obsolete. + +If she then uses @code{autoupdate}, the call to @var{old-macro} will be +replaced by the modern @var{implementation}. The additional +@var{message} is then printed. +@end defmac + +@node Coding Style, , Obsoleting Macros, Writing Autoconf Macros +@section Coding Style + +The Autoconf macros follow a strict coding style. You are encouraged to +follow this style, especially if you intend to distribute your macro, +either by contributing it to Autoconf itself, or via other means. + +The first requirement is to pay great attention to the quotation, for +more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. + +Do not try to invent new interfaces. It is likely that there is a macro +in Autoconf that resembles the macro you are defining: try to stick to +this existing interface (order of arguments, default values, etc.). We +@emph{are} conscious that some of these interfaces are not perfect; +nevertheless, when harmless, homogeneity should be preferred over +creativity. + +Be careful about clashes both between M4 symbols and between shell +variables. + +If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), +you are unlikely to generate conflicts. Nevertheless, when you need to +set a special value, @emph{avoid using a regular macro name}; rather, +use an ``impossible'' name. For instance, up to version 2.13, the macro +@code{AC_SUBST} used to remember what @var{symbol}s were already defined +by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. +But since there is a macro named @code{AC_SUBST_FILE}, it was just +impossible to @samp{AC_SUBST(FILE)}! In this case, +@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should +have been used (yes, with the parentheses)@dots{}or better yet, high-level +macros such as @code{AC_EXPAND_ONCE}. + +No Autoconf macro should ever enter the user-variable name space; i.e., +except for the variables that are the actual result of running the +macro, all shell variables should start with @code{ac_}. In +addition, small macros or any macro that is likely to be embedded in +other macros should be careful not to use obvious names. + +@cindex @code{dnl} +Do not use @code{dnl} to introduce comments: most of the comments you +are likely to write are either header comments which are not output +anyway, or comments that should make their way into @file{configure}. +There are exceptional cases where you do want to comment special M4 +constructs, in which case @code{dnl} is right, but keep in mind that it +is unlikely. + +M4 ignores the leading spaces before each argument, use this feature to +indent in such a way that arguments are (more or less) aligned with the +opening parenthesis of the macro being called. For instance, instead of + +@example +AC_CACHE_CHECK(for EMX OS/2 environment, +ac_cv_emxos2, +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], +[ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) +@end example + +@noindent +write + +@example +AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +@end example + +@noindent +or even + +@example +AC_CACHE_CHECK([for EMX OS/2 environment], + [ac_cv_emxos2], + [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], + [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +@end example + +When using @code{AC_TRY_RUN} or any macro that cannot work when +cross-compiling, provide a pessimistic value (typically @samp{no}). + +Feel free to use various tricks to prevent auxiliary tools, such as +syntax-highlighting editors, from behaving improperly. For instance, +instead of: + +@example +patsubst([$1], [$"]) +@end example + +@noindent +use + +@example +patsubst([$1], [$""]) +@end example + +@noindent +so that Emacsen do not open a endless ``string'' at the first quote. +For the same reasons, avoid: + +@example +test $[#] != 0 +@end example + +@noindent +and use: + +@example +test $[@@%:@@] != 0 +@end example + +@noindent +Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, +breaking the bracket-matching highlighting from Emacsen. Note the +preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do +not escape when it is unneeded. Common examples of useless quotation +are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), +etc. If you add portability issues to the picture, you'll prefer +@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something +better than hacking Autoconf @code{:-)}. + +When using @command{sed}, don't use @option{-e} except for indenting +purpose. With the @code{s} command, the preferred separator is @samp{/} +unless @samp{/} itself is used in the command, in which case you should +use @samp{,}. + +@xref{Macro Definitions}, for details on how to define a macro. If a +macro doesn't use @code{AC_REQUIRE} and it is expected to never be the +object of an @code{AC_REQUIRE} directive, then use @code{define}. In +case of doubt, use @code{AC_DEFUN}. All the @code{AC_REQUIRE} +statements should be at the beginning of the macro, @code{dnl}'ed. + +You should not rely on the number of arguments: instead of checking +whether an argument is missing, test that it is not empty. It provides +both a simpler and a more predictable interface to the user, and saves +room for further arguments. + +Unless the macro is short, try to leave the closing @samp{])} at the +beginning of a line, followed by a comment that repeats the name of the +macro being defined. This introduces an additional newline in +@code{configure}; normally, that is not a problem, but if you want to +remove it you can use @samp{[]dnl} on the last line. You can similarly +use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} +is recommended instead of @samp{dnl} to ensure that M4 does not +interpret the @samp{dnl} as being attached to the preceding text or +macro output. For example, instead of: + +@example +AC_DEFUN([AC_PATH_X], +[AC_MSG_CHECKING([for X]) +AC_REQUIRE_CPP() +@r{# @dots{}omitted@dots{}} + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) +fi]) +@end example + +@noindent +you would write: + +@example +AC_DEFUN([AC_PATH_X], +[AC_REQUIRE_CPP()[]dnl +AC_MSG_CHECKING([for X]) +@r{# @dots{}omitted@dots{}} + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) +fi[]dnl +])# AC_PATH_X +@end example + +If the macro is long, try to split it into logical chunks. Typically, +macros that check for a bug in a function and prepare its +@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform +this setup. Do not hesitate to introduce auxiliary macros to factor +your code. + +In order to highlight the recommended coding style, here is a macro +written the old way: + +@example +dnl Check for EMX on OS/2. +dnl _AC_EMXOS2 +AC_DEFUN(_AC_EMXOS2, +[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], +ac_cv_emxos2=yes, ac_cv_emxos2=no)]) +test "$ac_cv_emxos2" = yes && EMXOS2=yes]) +@end example + +@noindent +and the new way: + +@example +# _AC_EMXOS2 +# ---------- +# Check for EMX on OS/2. +define([_AC_EMXOS2], +[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], +[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], + [ac_cv_emxos2=yes], + [ac_cv_emxos2=no])]) +test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl +])# _AC_EMXOS2 +@end example + + + + +@c ============================================= Portable Shell Programming + +@node Portable Shell, Manual Configuration, Writing Autoconf Macros, Top +@chapter 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 the Korn shell and Bash +have evolved over the years, but to prevent trouble, do not take +advantage of features that were added after @sc{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! Also, include a space +after the exclamation point in interpreter specifications, like this: + +@example +#! /usr/bin/perl +@end example + +@noindent +If you omit the space before the path, then 4.2@sc{bsd} based systems +(such as Sequent DYNIX) will ignore the line, because they interpret +@samp{#! /} as a 4-byte magic number. + +The set of external programs you should run in a @code{configure} script +is fairly small. @xref{Utilities in Makefiles,, Utilities in +Makefiles, standards, 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; see +@ref{Limitations of Usual Tools}. + +@menu +* Shellology:: A zoology of shells +* Here-Documents:: Quirks and tricks +* File Descriptors:: FDs and redirections +* File System Conventions:: File- and pathnames +* Shell Substitutions:: Variable and command expansions +* Assignments:: Varying side effects of assignments +* Special Shell Variables:: Variables you should not change +* Limitations of Builtins:: Portable use of not so portable /bin/sh +* Limitations of Usual Tools:: Portable use of portable tools +* Limitations of Make:: Portable Makefiles +@end menu + +@node Shellology, Here-Documents, Portable Shell, Portable Shell +@section Shellology + +There are several families of shells, most prominently the Bourne +family and the C shell family which are deeply incompatible. If you +want to write portable shell scripts, avoid members of the C shell +family. + +Below we describe some of the members of the Bourne shell family. + +@table @asis +@item Ash +@cindex Ash +@command{ash} is often used on @sc{gnu}/Linux and @sc{bsd} systems as a +light-weight Bourne-compatible shell. Ash 0.2 has some bugs that are +fixed in the 0.3.x series, but portable shell scripts should workaround +them, since version 0.2 is still shipped with many @sc{gnu}/Linux +distributions. + +To be compatible with Ash 0.2: + +@itemize @minus +@item +don't use @samp{$?} after expanding empty or unset variables: + +@example +foo= +false +$foo +echo "Don't use it: $?" +@end example + +@item +don't use command substitution within variable expansion: + +@example +cat $@{FOO=`bar`@} +@end example + +@item +beware that single builtin substitutions are not performed by a sub +shell, hence their effect applies to the current shell! @xref{Shell +Substitutions}, item ``Command Substitution''. +@end itemize + +@item Bash +@cindex Bash +To detect whether you are running @command{bash}, test if +@code{BASH_VERSION} is set. To disable its extensions and require +@sc{posix} compatibility, run @samp{set -o posix}. @xref{Bash POSIX +Mode,, Bash @sc{posix} Mode, bash, The GNU Bash Reference Manual}, for +details. + +@item @command{/usr/xpg4/bin/sh} on Solaris +@cindex @command{/usr/xpg4/bin/sh} on Solaris +The @sc{posix}-compliant Bourne shell on a Solaris system is +@command{/usr/xpg4/bin/sh} and is part of an extra optional package. +There is no extra charge for this package, but it is also not part of a +minimal OS install and therefore some folks may not have it. + +@item Zsh +@cindex Zsh +To detect whether you are running @command{zsh}, test if +@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} +compatible with the Bourne shell: you have to run @samp{emulate sh} and +set @code{NULLCMD} to @samp{:}. @xref{Compatibility,, Compatibility, +zsh, The Z Shell Manual}, for details. + +Zsh 3.0.8 is the native @command{/bin/sh} on Mac OS X 10.0.3. +@end table + +The following discussion between Russ Allbery and Robert Lipe is worth +reading: + +@noindent +Russ Allbery: + +@quotation +The @sc{gnu} assumption that @command{/bin/sh} is the one and only shell +leads to a permanent deadlock. Vendors don't want to break user's +existent shell scripts, and there are some corner cases in the Bourne +shell that are not completely compatible with a @sc{posix} shell. Thus, +vendors who have taken this route will @emph{never} (OK@dots{}``never say +never'') replace the Bourne shell (as @command{/bin/sh}) with a +@sc{posix} shell. +@end quotation + +@noindent +Robert Lipe: + +@quotation +This is exactly the problem. While most (at least most System V's) do +have a bourne shell that accepts shell functions most vendor +@command{/bin/sh} programs are not the @sc{posix} shell. + +So while most modern systems do have a shell _somewhere_ that meets the +@sc{posix} standard, the challenge is to find it. +@end quotation + +@node Here-Documents, File Descriptors, Shellology, Portable Shell +@section Here-Documents + +Don't rely on @samp{\} being preserved just because it has no special +meaning together with the next symbol. in the native @command{/bin/sh} +on OpenBSD 2.7 @samp{\"} expands to @samp{"} in here-documents with +unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} +use @samp{\\} to get @samp{\}. + +With OpenBSD 2.7's @command{/bin/sh} + +@example +@group +$ cat <<EOF +> \" \\ +> EOF +" \ +@end group +@end example + +@noindent +and with Bash: + +@example +@group +bash-2.04$ cat <<EOF +> \" \\ +> EOF +\" \ +@end group +@end example + + +Many older shells (including the Bourne shell) implement here-documents +inefficiently. Users can generally speed things up by using a faster +shell, e.g., by using the command @samp{bash ./configure} rather than +plain @samp{./configure}. + +Some shells can be extremely inefficient when there are a lot of +here-documents inside a single statement. For instance if your +@file{configure.ac} includes something like: + +@example +@group +if <cross_compiling>; then + assume this and that +else + check this + check that + check something else + @dots{} + on and on forever + @dots{} +fi +@end group +@end example + +A shell parses the whole @code{if}/@code{fi} construct, creating +temporary files for each here document in it. Some shells create links +for such here-documents on every @code{fork}, so that the clean-up code +they had installed correctly removes them. It is creating the links +that the shell can take forever. + +Moving the tests out of the @code{if}/@code{fi}, or creating multiple +@code{if}/@code{fi} constructs, would improve the performance +significantly. Anyway, this kind of construct is not exactly the +typical use of Autoconf. In fact, it's even not recommended, because M4 +macros can't look into shell conditionals, so we may fail to expand a +macro when it was expanded before in a conditional path, and the +condition turned out to be false at run-time, and we end up not +executing the macro at all. + +@node File Descriptors, File System Conventions, Here-Documents, Portable Shell +@section File Descriptors + +Some file descriptors shall not be used, since some systems, admittedly +arcane, use them for special purpose: + +@table @asis +@item 3 +some systems may open it to @samp{/dev/tty}. + +@item 4 +used on the Kubota Titan. +@end table + +Don't redirect several times the same file descriptor, as you are doomed +to failure under Ultrix. + +@example +ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 +UWS V4.4 (Rev. 11) +$ eval 'echo matter >fullness' >void +illegal io +$ eval '(echo matter >fullness)' >void +illegal io +$ (eval '(echo matter >fullness)') >void +Ambiguous output redirect. +@end example + +@noindent +In each case the expected result is of course @file{fullness} containing +@samp{matter} and @file{void} being empty. + +Don't try to redirect the standard error of a command substitution: it +must be done @emph{inside} the command substitution: when running +@samp{: `cd /zorglub` 2>/dev/null} expect the error message to +escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. + +It is worth noting that Zsh (but not Ash nor Bash) makes it possible +in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. + +Most shells, if not all (including Bash, Zsh, Ash), output traces on +stderr, even for sub-shells. This might result in undesired content +if you meant to capture the standard-error output of the inner command: + +@example +$ ash -x -c '(eval "echo foo >&2") 2>stderr' +$ cat stderr ++ eval echo foo >&2 ++ echo foo +foo +$ bash -x -c '(eval "echo foo >&2") 2>stderr' +$ cat stderr ++ eval 'echo foo >&2' +++ echo foo +foo +$ zsh -x -c '(eval "echo foo >&2") 2>stderr' +@i{# Traces on startup files deleted here.} +$ cat stderr ++zsh:1> eval echo foo >&2 ++zsh:1> echo foo +foo +@end example + +@noindent +You'll appreciate the various levels of detail@dots{} + +One workaround is to grep out uninteresting lines, hoping not to remove +good ones@dots{} + +@node File System Conventions, Shell Substitutions, File Descriptors, Portable Shell +@section File System Conventions + +While @command{autoconf} and friends will usually be run on some Unix +variety, it can and will be used on other systems, most notably @sc{dos} +variants. This impacts several assumptions regarding file and +path names. + +@noindent +For example, the following code: + +@example +case $foo_dir in + /*) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; +esac +@end example + +@noindent +will fail to properly detect absolute paths on those systems, because +they can use a drivespec, and will usually use a backslash as directory +separator. The canonical way to check for absolute paths is: + +@example +case $foo_dir in + [\\/]* | ?:[\\/]* ) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; +esac +@end example + +@noindent +Make sure you quote the brackets if appropriate and keep the backslash as +first character (@pxref{Limitations of Builtins}). + +Also, because the colon is used as part of a drivespec, these systems don't +use it as path separator. When creating or accessing paths, use +@code{$ac_path_separator} instead (or the @code{PATH_SEPARATOR} output +variable). @command{autoconf} sets this to the appropriate value (@samp{:} +or @samp{;}) when it starts up. + +File names need extra care as well. While @sc{dos}-based environments +that are Unixy enough to run @command{autoconf} (such as DJGPP) will +usually be able to handle long file names properly, there are still +limitations that can seriously break packages. Several of these issues +can be easily detected by the +@href{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk} +package. + +A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to +indicate where they apply: @sc{sfn} means the issues are only relevant to +plain @sc{dos}, not to @sc{dos} boxes under Windows, while @sc{lfn} +identifies problems that exist even under Windows. + +@table @asis +@item No multiple dots (@sc{sfn}) +@sc{dos} cannot handle multiple dots in filenames. This is an especially +important thing to remember when building a portable configure script, +as @command{autoconf} uses a .in suffix for template files. + +This is perfectly OK on Unices: + +@example +AC_CONFIG_HEADER(config.h) +AC_CONFIG_FILES([source.c foo.bar]) +AC_OUTPUT +@end example + +@noindent +but it causes problems on @sc{dos}, as it requires @samp{config.h.in}, +@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable +to @sc{dos}-based environments, you should use this instead: + +@example +AC_CONFIG_HEADER(config.h:config.hin) +AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) +AC_OUTPUT +@end example + +@item No leading dot (@sc{sfn}) +@sc{dos} cannot handle filenames that start with a dot. This is usually +not a very important issue for @command{autoconf}. + +@item Case insensitivity (@sc{lfn}) +@sc{dos} is case insensitive, so you cannot, for example, have both a +file called @samp{INSTALL} and a directory called @samp{install}. This +also affects @command{make}; if there's a file called @samp{INSTALL} in +the directory, @command{make install} will do nothing (unless the +@samp{install} target is marked as PHONY). + +@item The 8+3 limit (@sc{sfn}) +Because the @sc{dos} file system only stores the first 8 characters of +the filename and the first 3 of the extension, those must be unique. +That means that @file{foobar-part1.c}, @file{foobar-part2.c} and +@file{foobar-prettybird.c} all resolve to the same filename +(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and +@file{foo.bartender}. + +Note: This is not usually a problem under Windows, as it uses numeric +tails in the short version of filenames to make them unique. However, a +registry setting can turn this behaviour off. While this makes it +possible to share file trees containing long file names between @sc{sfn} +and @sc{lfn} environments, it also means the above problem applies there +as well. + +@item Invalid characters +Some characters are invalid in @sc{dos} filenames, and should therefore +be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\}, +@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. +In a @sc{sfn} environment, other characters are also invalid. These +include @samp{+}, @samp{,}, @samp{[} and @samp{]}. +@end table + +@node Shell Substitutions, Assignments, File System Conventions, Portable Shell +@section Shell Substitutions + +Contrary to a persistent urban legend, the Bourne shell does not +systematically split variables and backquoted expressions, in particular +on the right-hand side of assignments and in the argument of @code{case}. +For instance, the following code: + +@example +case "$given_srcdir" in +.) top_srcdir="`echo "$dots" | sed 's,/$,,'`" +*) top_srcdir="$dots$given_srcdir" ;; +esac +@end example + +@noindent +is more readable when written as: + +@example +case $given_srcdir in +.) top_srcdir=`echo "$dots" | sed 's,/$,,'` +*) top_srcdir=$dots$given_srcdir ;; +esac +@end example + +@noindent +and in fact it is even @emph{more} portable: in the first case of the +first attempt, the computation of @code{top_srcdir} is not portable, +since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}. +Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"} +the same way. There is just no portable way to use double-quoted +strings inside double-quoted backquoted expressions (pfew!). + +@table @code +@item $@@ +@cindex @samp{"$@@"} +One of the most famous shell-portability issues is related to +@samp{"$@@"}: when there are no positional arguments, it is supposed to +be equivalent to nothing. But some shells, for instance under Digital +Unix 4.0 and 5.0, will then replace it with an empty argument. To be +portable, use @samp{$@{1+"$@@"@}}. + +@item $@{@var{var}:-@var{value}@} +@cindex $@{@var{var}:-@var{value}@} +Old @sc{bsd} shells, including the Ultrix @code{sh}, don't accept the +colon for any shell substitution, and complain and die. + +@item $@{@var{var}=@var{literal}@} +@cindex $@{@var{var}=@var{literal}@} +Be sure to quote: + +@example +: $@{var='Some words'@} +@end example + +@noindent +otherwise some shells, such as on Digital Unix V 5.0, will die because +of a ``bad substitution''. + +Solaris' @command{/bin/sh} has a frightening bug in its interpretation +of this. Imagine you need set a variable to a string containing +@samp{@}}. This @samp{@}} character confuses Solaris' @command{/bin/sh} +when the affected variable was already set. This bug can be exercised +by running: + +@example +$ unset foo +$ foo=$@{foo='@}'@} +$ echo $foo +@} +$ foo=$@{foo='@}' # no error; this hints to what the bug is +$ echo $foo +@} +$ foo=$@{foo='@}'@} +$ echo $foo +@}@} + ^ ugh! +@end example + +It seems that @samp{@}} is interpreted as matching @samp{$@{}, even +though it is enclosed in single quotes. The problem doesn't happen +using double quotes. + +@item $@{@var{var}=@var{expanded-value}@} +@cindex $@{@var{var}=@var{expanded-value}@} +On Ultrix, +running + +@example +default="yu,yaa" +: $@{var="$default"@} +@end example + +@noindent +will set @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of +each char will be set. You won't observe the phenomenon using a simple +@samp{echo $var} since apparently the shell resets the 8th bit when it +expands $var. Here are two means to make this shell confess its sins: + +@example +$ cat -v <<EOF +$var +EOF +@end example + +@noindent +and + +@example +$ set | grep '^var=' | cat -v +@end example + +One classic incarnation of this bug is: + +@example +default="a b c" +: $@{list="$default"@} +for c in $list; do + echo $c +done +@end example + +@noindent +You'll get @samp{a b c} on a single line. Why? Because there are no +spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th +bit set, hence no IFS splitting is performed!!! + +One piece of good news is that Ultrix works fine with @samp{: +$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is +then that @sc{qnx} 4.25 then sets @var{list} to the @emph{last} item of +@var{default}! + +The portable way out consists in using a double assignment, to switch +the 8th bit twice on Ultrix: + +@example +list=$@{list="$default"@} +@end example + +@noindent +@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, +use: + +@example +test "$@{var+set@}" = set || var=@var{@{value@}} +@end example + + +@item `@var{commands}` +@cindex `@var{commands}` +@cindex Command Substitution +While in general it makes no sense, do not substitute a single builtin +with side effects as Ash 0.2, trying to optimize, does not fork a +sub-shell to perform the command. + +For instance, if you wanted to check that @command{cd} is silent, do not +use @samp{test -z "`cd /`"} because the following can happen: + +@example +$ pwd +/tmp +$ test -n "`cd /`" && pwd +/ +@end example + +@noindent +The result of @samp{foo=`exit 1`} is left as an exercise to the reader. + + +@item $(@var{commands}) +@cindex $(@var{commands}) +This construct is meant to replace @samp{`@var{commands}`}; they can be +nested while this is impossible to do portably with back quotes. +Unfortunately it is not yet widely supported. Most notably, even recent +releases of Solaris don't support it: + +@example +$ showrev -c /bin/sh | grep version +Command version: SunOS 5.8 Generic 109324-02 February 2001 +$ echo $(echo blah) +syntax error: `(' unexpected +@end example + +@noindent +nor does @sc{irix} 6.5's Bourne shell: +@example +$ uname -a +IRIX firebird-image 6.5 07151432 IP22 +$ echo $(echo blah) +$(echo blah) +@end example +@end table + + +@node Assignments, Special Shell Variables, Shell Substitutions, Portable Shell +@section Assignments + +When setting several variables in a row, be aware that the order of the +evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} +gives @samp{1} with sh on Solaris, but @samp{2} with Bash. You must use +@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. + +Don't rely on the exit status of an assignment: Ash 0.2 does not change +the status and propagates that of the last statement: + +@example +$ false || foo=bar; echo $? +1 +$ false || foo=`:`; echo $? +0 +@end example + +@noindent +and to make things even worse, @sc{qnx 4.25} just sets the exit status +to 0 in any case: + +@example +$ foo=`exit 1`; echo $? +0 +@end example + +To assign default values, follow this algorithm: + +@enumerate +@item +If the default value is a literal and does not contain any closing +brace, use: + +@example +: $@{var='my literal'@} +@end example + +@item +If the default value contains no closing brace, has to be expanded, and +the variable being initialized will never be IFS-split (i.e., it's not a +list), then use: + +@example +: $@{var="$default"@} +@end example + +@item +If the default value contains no closing brace, has to be expanded, and +the variable being initialized will be IFS-split (i.e., it's a list), +then use: + +@example +var=$@{var="$default"@} +@end example + +@item +If the default value contains a closing brace, then use: + +@example +test "$@{var+set@}" = set || var='$@{indirection@}' +@end example +@end enumerate + +In most cases @samp{var=$@{var="$default"@}} is fine, but in case of +doubt, just use the latter. @xref{Shell Substitutions}, items +@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} +for the rationale. + + +@node Special Shell Variables, Limitations of Builtins, Assignments, Portable Shell +@section Special Shell Variables + +Some shell variables should not be used, since they can have a deep +influence on the behavior of the shell. In order to recover a sane +behavior from the shell, some variables should be unset, but +@command{unset} is not portable (@pxref{Limitations of Builtins}) and a +fallback value is needed. We list these values below. + +@c Alphabetical order, case insensitive, `A' before `a'. +@table @code +@item CDPATH +@evindex CDPATH +When this variable is set @code{cd} is verbose, so idioms such as +@samp{abs=`cd $rel && pwd`} break because @code{abs} receives the path +twice. + +@c FIXME: Which shells? How do they behave? +Setting @code{CDPATH} to the empty value is not enough for most shells. +A simple colon is enough except for @code{zsh}, which prefers a leading +dot: + +@example +zsh-3.1.6 % mkdir foo && (CDPATH=: cd foo) +/tmp/foo +zsh-3.1.6 % (CDPATH=:. cd foo) +/tmp/foo +zsh-3.1.6 % (CDPATH=.: cd foo) +zsh-3.1.6 % +@end example + +@noindent +(of course we could just @code{unset} @code{CDPATH}, since it also +behaves properly if set to the empty string). + +Life wouldn't be so much fun if @command{bash} and @command{zsh} had the +same behavior: + +@example +bash-2.02 % (CDPATH=:. cd foo) +bash-2.02 % (CDPATH=.: cd foo) +/tmp/foo +@end example + +Therefore, a portable solution to neutralize @samp{CDPATH} is + +@example +CDPATH=$@{ZSH_VERSION+.@}: +@end example + +@noindent +Note that since @command{zsh} supports @command{unset}, you may unset +@samp{CDPATH} using @samp{:} as a fallback, see +@ref{Limitations of Builtins}. + +@item IFS +@evindex IFS +Don't set the first character of @code{IFS} to backslash. Indeed, +Bourne shells use the first character (backslash) when joining the +components in @samp{"$@@"} and some shells then re-interpret (!) the +backslash escapes, so you can end up with backspace and other strange +characters. + +@item LANG +@itemx LC_ALL +@itemx LC_TIME +@itemx LC_CTYPE +@itemx LANGUAGE +@itemx LC_COLLATE +@itemx LC_NUMERIC +@itemx LC_MESSAGES +@evindex LANG +@evindex LC_ALL +@evindex LC_TIME +@evindex LC_CTYPE +@evindex LANGUAGE +@evindex LC_COLLATE +@evindex LC_NUMERIC +@evindex LC_MESSAGES + +These must not be set unconditionally because not all systems understand +e.g. @samp{LANG=C} (notably SCO). Fixing @env{LC_MESSAGES} prevents +Solaris @command{sh} from translating var values in @code{set}! Non-C +@env{LC_CTYPE} values break the ctype check. Fixing @env{LC_COLLATE} +makes scripts more portable in some cases. For example, it causes the +regular expression @samp{[a-z]} to match only lower-case letters on +@sc{ascii} platforms. However, @samp{[a-z]} does not work in general +even when @env{LC_COLLATE} is fixed; for example, it does not work for +@sc{ebcdic} platforms. For maximum portability, you should use regular +expressions like @samp{[abcdefghijklmnopqrstuvwxyz]} that list +characters explicitly instead of relying on ranges. + +@emph{If} one of these variables is set, you should try to unset it, +using @samp{C} as a fall back value. see @ref{Limitations of Builtins}, +builtin @command{unset}, for more details. + +@item NULLCMD +@evindex NULLCMD +When executing the command @samp{>foo}, @command{zsh} executes +@samp{$NULLCMD >foo}. The Bourne shell considers @code{NULLCMD} is +@samp{:}, while @command{zsh}, even in Bourne shell compatibility mode, +sets @code{NULLCMD} to @samp{cat}. If you forgot to set @code{NULLCMD}, +your script might be suspended waiting for data on its standard input. + +@item status +@evindex status +This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), +hence read-only. Do not use it. + +@item PATH_SEPARATOR +@evindex PATH_SEPARATOR +On DJGPP systems, the @code{PATH_SEPARATOR} variable can be set to +either @samp{:} or @samp{;} to control the path separator @command{bash} +uses to set up certain environment variables (such as +@code{PATH}). Since this only works inside bash, you want autoconf to +detect the regular @sc{dos} path separator @samp{;}, so it can be safely +substituted in files that may not support @samp{;} as path separator. So +either unset this variable or set it to @samp{;}. + +@item RANDOM +@evindex RANDOM +Many shells provide @code{RANDOM}, a variable that returns a different +integer when used. Most of the time, its value does not change when it +is not used, but on @sc{irix 6.5} the value changes all the time. This +can be observed by using @command{set}. +@end table + + +@node Limitations of Builtins, Limitations of Usual Tools, Special Shell Variables, Portable Shell +@section Limitations of Shell Builtins + +No, no, we are serious: some shells do have limitations! :) + +You should always keep in mind that any built-in or command may support +options, and therefore have a very different behavior with arguments +starting with a dash. For instance, the innocent @samp{echo "$word"} +can give unexpected results when @code{word} starts with a dash. It is +often possible to avoid this problem using @samp{echo "x$word"}, taking +the @samp{x} into account later in the pipe. + +@table @asis +@item @command{!} +@cindex @command{!} +You can't use @command{!}, you'll have to rewrite your code. + + +@item @command{break} +@c ------------------ +@cindex @command{break} +The use of @samp{break 2}, etcetera, is safe. + + +@item @command{case} +@c ----------------- +@cindex @command{case} +You don't need to quote the argument; no splitting is performed. + +You don't need the final @samp{;;}, but you should use it. + +Because of a bug in its @code{fnmatch}, @command{bash} fails to properly +handle backslashes in character classes: + +@example +bash-2.02$ case /tmp in [/\\]*) echo OK;; esac +bash-2.02$ +@end example + +@noindent +This is extremely unfortunate, since you are likely to use this code to +handle @sc{unix} or @sc{ms-dos} absolute paths. To work around this +bug, always put the backslash first: + +@example +bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac +OK +bash-2.02$ case /tmp in [\\/]*) echo OK;; esac +OK +@end example + + +@item @command{echo} +@c ----------------- +@cindex @command{echo} +The simple @code{echo} is probably the most surprising source of +portability troubles. It is not possible to use @samp{echo} portably +unless both options and escape sequences are omitted. New applications +which are not aiming at portability should use @samp{printf} instead of +@samp{echo}. + +Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N} +etc. for a means to simulate @option{-c}. + +Do not use backslashes in the arguments, as there is no consensus on +their handling. On @samp{echo '\n' | wc -l}, the @command{sh} of +Digital Unix 4.0, @sc{mips risc/os} 4.52, answer 2, but the Solaris' +@command{sh}, Bash and Zsh (in @command{sh} emulation mode) report 1. +Please note that the problem is truly @command{echo}: all the shells +understand @samp{'\n'} as the string composed of a backslash and an +@samp{n}. + +Because of these problems, do not pass a string containing arbitrary +characters to @command{echo}. For example, @samp{echo "$foo"} is safe +if you know that @var{foo}'s value cannot contain backslashes and cannot +start with @samp{-}, but otherwise you should use a here-document like +this: + +@example +cat <<EOF +$foo +EOF +@end example + + +@item @command{exit} +@c ----------------- +@cindex @command{exit} +The default value of @command{exit} is supposed to be @code{$?}; +unfortunately, some shells, such as the DJGPP port of Bash 2.04, just +perform @samp{exit 0}. + +@example +bash-2.04$ foo=`exit 1` || echo fail +fail +bash-2.04$ foo=`(exit 1)` || echo fail +fail +bash-2.04$ foo=`(exit 1); exit` || echo fail +bash-2.04$ +@end example + +Using @samp{exit $?} restores the expected behavior. + +Some shell scripts, such as those generated by @command{autoconf}, use a +trap to clean up before exiting. If the last shell command exited with +nonzero status, the trap also exits with nonzero status so that the +invoker can tell that an error occurred. + +Unfortunately, in some shells, such as Solaris 8 @command{sh}, an exit +trap ignores the @code{exit} command's status. In these shells, a trap +cannot determine whether it was invoked by plain @code{exit} or by +@code{exit 1}. Instead of calling @code{exit} directly, use the +@code{AC_MSG_ERROR} macro that has a workaround for this problem. + + +@item @command{export} +@c ------------------- +@cindex @command{export} +The builtin @command{export} dubs @dfn{environment variable} a shell +variable. Each update of exported variables corresponds to an update of +the environment variables. Conversely, each environment variable +received by the shell when it is launched should be imported as a shell +variable marked as exported. + +Alas, many shells, such as Solaris 2.5, IRIX 6.3, IRIX 5.2, AIX 4.1.5 +and DU 4.0, forget to @command{export} the environment variables they +receive. As a result, two variables are coexisting: the environment +variable and the shell variable. The following code demonstrates this +failure: + +@example +#! /bin/sh +echo $FOO +FOO=bar +echo $FOO +exec /bin/sh $0 +@end example + +@noindent +when run with @samp{FOO=foo} in the environment, these shells will print +alternately @samp{foo} and @samp{bar}, although it should only print +@samp{foo} and then a sequence of @samp{bar}s. + +Therefore you should @command{export} again each environment variable +that you update. + + +@item @command{false} +@c ------------------ +@cindex @command{false} +Don't expect @command{false} to exit with status 1: in the native Bourne +shell of Solaris 8, it exits with status 255. + + +@item @command{for} +@c ---------------- +@cindex @command{for} +To loop over positional arguments, use: + +@example +for arg +do + echo "$arg" +done +@end example + +@noindent +You may @emph{not} leave the @code{do} on the same line as @code{for}, +since some shells improperly grok: + +@example +for arg; do + echo "$arg" +done +@end example + +If you want to explicitly refer to the positional arguments, given the +@samp{$@@} bug (@pxref{Shell Substitutions}), use: + +@example +for arg in $@{1+"$@@"@}; do + echo "$arg" +done +@end example + +@item @command{if} +@c --------------- +@cindex @command{if} +Using @samp{!} is not portable. Instead of: + +@example +if ! cmp -s file file.new; then + mv file.new file +fi +@end example + +@noindent +use: + +@example +if cmp -s file file.new; then :; else + mv file.new file +fi +@end example + +There are shells that do not reset the exit status from an @command{if}: + +@example +$ if (exit 42); then true; fi; echo $? +42 +@end example + +@noindent +whereas a proper shell should have printed @samp{0}. This is especially +bad in Makefiles since it produces false failures. This is why properly +written Makefiles, such as Automake's, have such hairy constructs: + +@example +if test -f "$file"; then + install "$file" "$dest" +else + : +fi +@end example + + +@item @command{set} +@c ---------------- +@cindex @command{set} +This builtin faces the usual problem with arguments starting with a +dash. Modern shells such as Bash or Zsh understand @option{--} to specify +the end of the options (any argument after @option{--} is a parameters, +even @samp{-x} for instance), but most shells simply stop the option +processing as soon as a non-option argument is found. Therefore, use +@samp{dummy} or simply @samp{x} to end the option processing, and use +@command{shift} to pop it out: + +@example +set x $my_list; shift +@end example + +@item @command{shift} +@c ------------------ +@cindex @command{shift} +Not only is @command{shift}ing a bad idea when there is nothing left to +shift, but in addition it is not portable: the shell of @sc{mips +risc/os} 4.52 refuses to do it. + +@item @command{test} +@c ----------------- +@cindex @command{test} +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 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 @option{-a} and @option{-o}. On System V, the +precedence of @option{-a} and @option{-o} is wrong relative to the unary +operators; consequently, @sc{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. + +You may use @samp{!} with @command{test}, but not with @command{if}: +@samp{test ! -r foo || exit 1}. + +@item @command{test} (files) +@c ------------------------- +To enable @code{configure} scripts to support cross-compilation, they +shouldn't do anything that tests features of the build system instead of +the host 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 @sc{4.3bsd} does not +have it. Do not use @samp{test -e} either, because Solaris 2.5 does not +have it. + +@item @command{test} (strings) +@c --------------------------- +Avoid @samp{test "@var{string}"}, in particular if @var{string} might +start with a dash, since @code{test} might interpret its argument as an +option (e.g., @samp{@var{string} = "-n"}). + +Contrary to a common belief, @samp{test -n @var{string}} and @samp{test +-z @var{string}} @strong{are} portable, nevertheless many shells (such +as Solaris 2.5, AIX 3.2, UNICOS 10.0.0.6, Digital Unix 4 etc.) have +bizarre precedence and may be confused if @var{string} looks like an +operator: + +@example +$ test -n = +test: argument expected +@end example + +If there are risks, use @samp{test "x@var{string}" = x} or @samp{test +"x@var{string}" != x} instead. + +It is frequent to find variations of the following idiom: + +@example +test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && + @var{action} +@end example + +@noindent +to take an action when a token matches a given pattern. Such constructs +should always be avoided by using: + +@example +echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && + @var{action} +@end example + +@noindent +Use @code{case} where possible since it is faster, being a shell builtin: + + +@example +case $ac_feature in + *[!-a-zA-Z0-9_]*) @var{action};; +esac +@end example + +Alas, negated character classes are probably not portable, although no +shell is known to not support the @sc{posix.2} syntax @samp{[!@dots{}]} +(when in interactive mode, @command{zsh} is confused by the +@samp{[!@dots{}]} syntax and looks for an event in its history because of +@samp{!}). Many shells do not support the alternative syntax +@samp{[^@dots{}]} (Solaris, Digital Unix, etc.). + +One solution can be: + +@example +expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + @var{action} +@end example + +@noindent +or better yet + +@example +expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + @var{action} +@end example + +@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo +"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when +@samp{@var{foo}} contains backslashes. + + +@item @command{trap} +@c ----------------- +@cindex @command{trap} +It is safe to trap at least the signals 1, 2, 13 and 15. You can also +trap 0, i.e., have the @command{trap} run when the script ends (either via an +explicit @command{exit}, or the end of the script). + +Although @sc{posix} is not absolutely clear on this point, it is widely +admitted that when entering the trap @samp{$?} should be set to the exit +status of the last command run before the trap. The ambiguity can be +summarized as: ``when the trap is launched by an @command{exit}, what is +the @emph{last} command run: that before @command{exit}, or +@command{exit} itself?'' + +Bash considers @command{exit} to be the last command, while Zsh and +Solaris 8 @command{sh} consider that when the trap is run it is +@emph{still} in the @command{exit}, hence it is the previous exit status +that the trap receives: + +@example +$ cat trap.sh +trap 'echo $?' 0 +(exit 42); exit 0 +$ zsh trap.sh +42 +$ bash trap.sh +0 +@end example + +The portable solution is then simple: when you want to @samp{exit 42}, +run @samp{(exit 42); exit 42}, the first @command{exit} being used to +set the exit status to 42 for Zsh, and the second to trigger the trap +and pass 42 as exit status for Bash. + +The shell in FreeBSD 4.0 has the following bug: @samp{$?} is reset to 0 +by empty lines if the code is inside @command{trap}. + +@example +$ trap 'false + +echo $?' 0 +$ exit +0 +@end example + +@noindent +Fortunately, this bug only affects @command{trap}. + +@item @command{true} +@c ----------------- +@cindex @command{true} +@cindex @command{:} +Don't worry: as far as we know @command{true} is portable. +Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the +portable shell community tends to prefer using @command{:}. This has a +funny side effect: when asked whether @command{false} is more portable +than @command{true} Alexandre Oliva answered: + +@quotation +In a sense, yes, because if it doesn't exist, the shell will produce an +exit status of failure, which is correct for @command{false}, but not +for @command{true}. +@end quotation + + +@item @command{unset} +@c ------------------ +@cindex @command{unset} +You cannot assume the support of @command{unset}, nevertheless, because +it is extremely useful to disable embarrassing variables such as +@code{CDPATH} or @code{LANG}, you can test for its existence and use +it @emph{provided} you give a neutralizing value when @command{unset} is +not supported: + +@example +if (unset FOO) >/dev/null 2>&1; then + unset=unset +else + unset=false +fi +$unset CDPATH || CDPATH=: +@end example + +@xref{Special Shell Variables}, for some neutralizing values. Also, see +@ref{Limitations of Builtins}, documentation of @command{export}, for +the case of environment variables. +@end table + +@node Limitations of Usual Tools, Limitations of Make, Limitations of Builtins, Portable Shell +@section Limitations of Usual Tools + +The small set of tools you can expect to find on any machine can still +include some limitations you should be aware of. + +@table @asis +@item @command{awk} +@c ---------------- +@cindex @command{awk} +Don't leave white spaces before the parentheses in user functions calls, +@sc{gnu} awk will reject it: + +@example +$ gawk 'function die () @{ print "Aaaaarg!" @} + BEGIN @{ die () @}' +gawk: cmd. line:2: BEGIN @{ die () @} +gawk: cmd. line:2: ^ parse error +$ gawk 'function die () @{ print "Aaaaarg!" @} + BEGIN @{ die() @}' +Aaaaarg! +@end example + +If you want your program to be deterministic, don't depend on @code{for} +on arrays: + +@example +$ cat for.awk +END @{ + arr["foo"] = 1 + arr["bar"] = 1 + for (i in arr) + print i +@} +$ gawk -f for.awk </dev/null +foo +bar +$ nawk -f for.awk </dev/null +bar +foo +@end example + +Some AWK, such as HPUX 11.0's native one, have regex engines fragile to +inner anchors: + +@example +$ echo xfoo | $AWK '/foo|^bar/ @{ print @}' +$ echo bar | $AWK '/foo|^bar/ @{ print @}' +bar +$ echo xfoo | $AWK '/^bar|foo/ @{ print @}' +xfoo +$ echo bar | $AWK '/^bar|foo/ @{ print @}' +bar +@end example + +@noindent +Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, +or use a simple test to reject such AWK. + + +@item @command{cat} +@c ---------------- +@cindex @command{cat} +Don't rely on any option. The option @option{-v}, which displays +non-printing characters, @emph{seems} portable, though. + + +@item @command{cc} +@c --------------- +When a compilation such as @samp{cc foo.c -o foo} fails, some compilers +(such as @sc{cds} on Reliant @sc{unix}) leave a @file{foo.o}. + + +@item @command{cmp} +@c ---------------- +@cindex @command{cmp} +@command{cmp} performs a raw data comparison of two files, while +@command{diff} compares two text files. Therefore, if you might compare +DOS files, even if only checking whether two files are different, use +@command{diff} to avoid spurious differences due to differences of +newline encoding. + + +@item @command{cp} +@c --------------- +@cindex @command{cp} +@c This is thanks to Ian. +SunOS @command{cp} does not support @option{-f}, although its +@command{mv} does. It's possible to deduce why @command{mv} and +@command{cp} are different with respect to @option{-f}. @command{mv} +prompts by default before overwriting a read-only file. @command{cp} +does not. Therefore, @command{mv} requires a @option{-f} option, but +@command{cp} does not. @command{mv} and @command{cp} behave differently +with respect to read-only files because the simplest form of +@command{cp} cannot overwrite a read-only file, but the simplest form of +@command{mv} can. This is because @command{cp} opens the target for +write access, whereas @command{mv} simply calls @code{link} (or, in +newer systems, @code{rename}). +@c Ian said: ``I don't think -p or -r are portable''!!! How can you live +@c without -r??? + + +@item @command{diff} +@c ----------------- +@cindex @command{diff} +Option @option{-u} is nonportable. + +Some implementations, such as Tru64's, fail when comparing to +@file{/dev/null}. Use an empty file instead. + +@item @command{dirname} +@c -------------------- +@cindex @command{dirname} +Not all hosts have @command{dirname}, but it is reasonably easy to +emulate, e.g.: + +@example +dir=`expr "x$file" : 'x\(.*\)/[^/]*' \| + '.' : '.' +@end example + +@noindent +But there are a few subtilities, e.g., under UN*X, should @samp{//1} +give @samp{/}? Paul Eggert answers: + +@quotation +No, under some older flavors of Unix, leading @samp{//} is a special +path name: it refers to a ``super-root'' and is used to access other +machines' files. Leading @samp{///}, @samp{////}, etc. are equivalent +to @samp{/}; but leading @samp{//} is special. I think this tradition +started with Apollo Domain/OS, an OS that is still in use on some older +hosts. + +POSIX.2 allows but does not require the special treatment for @samp{//}. +It says that the behavior of dirname on path names of the form +@samp{//([^/]+/*)?} is implementation defined. In these cases, GNU +@command{dirname} returns @samp{/}, but it's more portable to return +@samp{//} as this works even on those older flavors of Unix. + +I have heard rumors that this special treatment of @samp{//} may be +dropped in future versions of POSIX, but for now it's still the +standard. +@end quotation + + +@item @command{egrep} +@c ------------------ +@cindex @command{egrep} +The empty alternative is not portable, use @samp{?} instead. For +instance with Digital Unix v5.0: + +@example +> printf "foo\n|foo\n" | egrep '^(|foo|bar)$' +|foo +> printf "bar\nbar|\n" | egrep '^(foo|bar|)$' +bar| +> printf "foo\nfoo|\n|bar\nbar\n" | egrep '^(foo||bar)$' +foo +|bar +@end example + +@command{egrep} also suffers the limitations of @command{grep}. + + +@item @command{expr} +@c ----------------- +@cindex @command{expr} +No @command{expr} keyword starts with @samp{x}, so use @samp{expr +x"@var{word}" : 'x@var{regex}'} to keep @command{expr} from +misinterpreting @var{word}. + +Don't use @code{length}, @code{substr}, @code{match} and @code{index}. + +@item @command{expr} (@samp{|}) +@cindex @command{expr} (@samp{|}) +You can use @samp{|}. Although @sc{posix} does require that @samp{expr +''} return the empty string, it does not specify the result when you +@samp{|} together the empty string (or zero) with the empty string. For +example: + +@example +expr '' \| '' +@end example + +@sc{gnu}/Linux and @sc{posix.2-1992} return the empty string for this +case, but traditional Unix returns @samp{0} (Solaris is one such +example). In the latest @sc{posix} draft, the specification has been +changed to match traditional Unix's behavior (which is bizarre, but it's +too late to fix this). Please note that the same problem does arise +when the empty string results from a computation, as in: + +@example +expr bar : foo \| foo : bar +@end example + +@noindent +Avoid this portability problem by avoiding the empty string. + + +@item @command{expr} (@samp{:}) +@c ---------------------------- +@cindex @command{expr} +Don't use @samp{\?}, @samp{\+} and @samp{\|} in patterns, they are +not supported on Solaris. + +The @sc{posix.2-1992} standard is ambiguous as to whether @samp{expr a : +b} (and @samp{expr 'a' : '\(b\)'}) output @samp{0} or the empty string. +In practice, it outputs the empty string on most platforms, but portable +scripts should not assume this. For instance, the @sc{qnx} 4.25 native +@command{expr} returns @samp{0}. + +You may believe that one means to get a uniform behavior would be to use +the empty string as a default value: + +@example +expr a : b \| '' +@end example + +@noindent +unfortunately this behaves exactly as the original expression, see the +@samp{@command{expr} (@samp{:})} entry for more information. + +Older @command{expr} implementations (e.g. SunOS 4 @command{expr} and +Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes +@command{expr} to fail if the matched substring is longer than 120 +bytes. In this case, you might want to fall back on @samp{echo|sed} if +@command{expr} fails. + +Don't leave, there is some more! + +The @sc{qnx} 4.25 @command{expr}, in addition of preferring @samp{0} to +the empty string, has a funny behavior in its exit status: it's always 1 +when parentheses are used! + +@example +$ val=`expr 'a' : 'a'`; echo "$?: $val" +0: 1 +$ val=`expr 'a' : 'b'`; echo "$?: $val" +1: 0 + +$ val=`expr 'a' : '\(a\)'`; echo "?: $val" +1: a +$ val=`expr 'a' : '\(b\)'`; echo "?: $val" +1: 0 +@end example + +@noindent +In practice this can be a big problem if you are ready to catch failures +of @command{expr} programs with some other method (such as using +@command{sed}), since you may get twice the result. For instance + +@example +$ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' +@end example + +@noindent +will output @samp{a} on most hosts, but @samp{aa} on @sc{qnx} 4.25. A +simple work around consists in testing @command{expr} and use a variable +set to @command{expr} or to @command{false} according to the result. + + +@item @command{find} +@c ----------------- +The option @option{-maxdepth} seems to be GNU specific. Tru64 v5.1, +NetBSD 1.5 and Solaris 2.5 @command{find} commands do not understand it. + + +@item @command{grep} +@c ----------------- +@cindex @command{grep} +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. + +Don't use multiple regexps with @option{-e}, as some @code{grep} will only +honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway, +Stardent Vistra SVR4 @code{grep} lacks @option{-e}@dots{} Instead, use +alternation and @code{egrep}. + + +@item @command{ln} +@c --------------- +@cindex @command{ln} +@cindex Symbolic links +Don't rely on @command{ln} having a @option{-f} option. Symbolic links +are not available on old systems, use @samp{ln} as a fall back. + +For versions of the DJGPP before 2.04, @command{ln} emulates soft links +for executables by generating a stub that in turn calls the real +program. This feature also works with nonexistent files like in the +Unix spec. So @samp{ln -s file link} will generate @file{link.exe}, +which will attempt to call @file{file.exe} if run. But this feature only +works for executables, so @samp{cp -p} is used instead for these +systems. DJGPP versions 2.04 and later have full symlink support. + + +@item @command{mv} +@c --------------- +@cindex @command{mv} +The only portable options are @option{-f} and @option{-i}. + +Moving individual files between file systems is portable (it was in V6), +but it is not always atomic: when doing @samp{mv new existing}, there's +a critical section where neither the old nor the new version of +@file{existing} actually exists. + +Moving directories across mount points is not portable, use @command{cp} +and @command{rm}. + + +@item @command{sed} +@c ---------------- +@cindex @command{sed} +Patterns should not include the separator (unless escaped), even as part +of a character class. In conformance with @sc{posix}, the Cray +@command{sed} will reject @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}. + +Sed scripts should not use branch labels longer than 8 characters and +should not contain comments. + +Don't include extra @samp{;}, as some @command{sed}, such as NetBSD +1.4.2's, try to interpret the second as a command: + +@example +$ echo a | sed 's/x/x/;;s/x/x/' +sed: 1: "s/x/x/;;s/x/x/": invalid command code ; +@end example + +Input should have reasonably long lines, since some @command{sed} have +an input buffer limited to 4000 bytes. + +Alternation, @samp{\|}, is common but not portable. +@c FIXME: I know Solaris is guilty, but I don't remember how. +Anchors (@samp{^} and @samp{$}) inside groups are not portable. + +Nested groups are extremely portable, but there is at least one +@command{sed} (System V/68 Base Operating System R3V7.1) that does not +support it. + +Of course the option @option{-e} is portable, but it is not needed. No +valid Sed program can start with a dash, so it does not help +disambiguating. Its sole usefulness is helping enforcing indenting as +in: + +@example +sed -e @var{instruction-1} \ + -e @var{instruction-2} +@end example + +@noindent +as opposed to + +@example +sed @var{instruction-1};@var{instruction-2} +@end example + +Contrary to yet another urban legend, you may portably use @samp{&} in +the replacement part of the @code{s} command to mean ``what was +matched''. + + +@item @command{sed} (@samp{t}) +@c --------------------------- +@cindex @command{sed} (@samp{t}) +Some old systems have @command{sed} that ``forget'' to reset their +@samp{t} flag when starting a new cycle. For instance on @sc{mips +risc/os}, and on @sc{irix} 5.3, if you run the following @command{sed} +script (the line numbers are not actual part of the texts): + +@example +s/keep me/kept/g # a +t end # b +s/.*/deleted/g # c +: end # d +@end example + +@noindent +on + +@example +delete me # 1 +delete me # 2 +keep me # 3 +delete me # 4 +@end example + +@noindent +you get + +@example +deleted +delete me +kept +deleted +@end example + +@noindent +instead of + +@example +deleted +deleted +kept +deleted +@end example + +Why? When processing 1, a matches, therefore sets the t flag, b jumps to +d, and the output is produced. When processing line 2, the t flag is +still set (this is the bug). Line a fails to match, but @command{sed} +is not supposed to clear the t flag when a substitution fails. Line b +sees that the flag is set, therefore it clears it, and jumps to d, hence +you get @samp{delete me} instead of @samp{deleted}. When processing 3 t +is clear, a matches, so the flag is set, hence b clears the flags and +jumps. Finally, since the flag is clear, 4 is processed properly. + +There are two things one should remind about @samp{t} in @command{sed}. +Firstly, always remember that @samp{t} jumps if @emph{some} substitution +succeeded, not only the immediately preceding substitution, therefore, +always use a fake @samp{t clear; : clear} to reset the t flag where +indeed. + +Secondly, you cannot rely on @command{sed} to clear the flag at each new +cycle. + +One portable implementation of the script above is: + +@example +t clear +: clear +s/keep me/kept/g +t end +s/.*/deleted/g +: end +@end example + +@item @command{touch} +@c ------------------ +@cindex @command{touch} +On some old @sc{bsd} systems, @command{touch} or any command that +results in an empty file does not update the timestamps, so use a +command like @code{echo} as a workaround. + +GNU @command{touch} 3.16r (and presumably all before that) fails to work +on SunOS 4.1.3 when the empty file is on an @sc{nfs}-mounted 4.2 volume. + +@end table + + +@node Limitations of Make, , Limitations of Usual Tools, Portable Shell +@section Limitations of Make + +Make itself suffers a great number of limitations, only a few of which +being listed here. First of all, remember that since commands are +executed by the shell, all its weaknesses are inherited@dots{} + +@table @asis +@item Leading underscore in macro names +Some Make don't support leading underscores in macro names, such as on +NEWS-OS 4.2R. + +@example +$ cat Makefile +_am_include = # +_am_quote = +all:; @@echo this is test + +% make +Make: Must be a separator on rules line 2. Stop. + +$ cat Makefile2 +am_include = # +am_quote = +all:; @@echo this is test + +$ make -f Makefile2 +this is test +@end example + +@item @code{VPATH} +@cindex @code{VPATH} +Don't use it! For instance any assignment to @code{VPATH} causes Sun +@command{make} to only execute the first set of double-colon rules. +@end table + + + + +@c ================================================== Manual Configuration + +@node Manual Configuration, Site Configuration, Portable Shell, 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. You +can 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 +* Using System Type:: What to do with the system type +@end menu + +@node Specifying Names, Canonicalizing, Manual Configuration, Manual Configuration +@section Specifying the System Type + +Like other @sc{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: +@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be +@samp{@var{system}} or @samp{@var{kernel}-@var{system}} + +@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 infers 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@footnote{For +backward compatibility, @code{configure} will accept a system type as an +option by itself. Such an option will override the defaults for build, +host and target system types. The following configure statement will +configure a cross toolchain that will run on NetBSD/alpha but generate +code for GNU Hurd/sparc, which is also the build platform. + +@example +./configure --host=alpha-netbsd sparc-gnu +@end example +}: + +@table @option +@item --build=@var{build-type} +the type of system on which the package is being configured and +compiled. + +@item --host=@var{host-type} +@ovindex cross_compiling +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 (rarely needed). By default, it is the same as host. +@end table + +They all default to the result of running @code{config.guess}, unless +you specify either @option{--build} or @option{--host}. In this case, the +default becomes the system type you specified. If you specify both, and +they're different, @code{configure} will enter cross compilation mode, +so it won't run any tests that require execution. + +Hint: if you mean to override the result of @code{config.guess}, prefer +@option{--build} over @option{--host}. In the future, @option{--host} will +not override the name of the build system type. Also, if you specify +@option{--host}, but not @option{--build}, when @code{configure} performs +the first compiler test it will try to run an executable produced by the +compiler. If the execution fails, it will enter cross-compilation mode. +Note, however, that it won't guess the build-system type, since this may +require running test programs. Moreover, by the time the compiler test +is performed, it may be too late to modify the build-system type: other +tests may have already been performed. Therefore, whenever you specify +@code{--host}, be sure to specify @code{--build} too. + +@example +./configure --build=i686-pc-linux-gnu --host=m68k-coff +@end example + +@noindent +will enter cross-compilation mode, but @code{configure} will fail if it +can't run the code generated by the specified compiler if you configure +as follows: + +@example +./configure CC=m68k-coff-gcc +@end example + +@code{configure} recognizes short aliases for many system types; for +example, @samp{decstation} can be used instead of +@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called +@code{config.sub} to canonicalize system type aliases. + + + +@node Canonicalizing, Using System Type, Specifying Names, Manual Configuration +@section Getting the Canonical System Type + +The following macros make the system type available to @code{configure} +scripts. + +@ovindex build_alias +@ovindex host_alias +@ovindex target_alias + +The variables @samp{build_alias}, @samp{host_alias}, and +@samp{target_alias} are always exactly the arguments of @option{--build}, +@option{--host}, and @option{--target}; in particular, they are left empty +if the user did not use them, even if the corresponding +@code{AC_CANONICAL} macro was run. Any configure script may use these +variables anywhere. These are the variables that should be used when in +interaction with the user. + +If you need to recognize some special environments based on their system +type, run the following macros to get canonical system names. These +variables are not set before the macro call. + +If you use these macros, you must distribute @code{config.guess} and +@code{config.sub} along with your source code. @xref{Output}, for +information about the @code{AC_CONFIG_AUX_DIR} macro which you can use +to control in which directory @code{configure} looks for those scripts. + + +@defmac AC_CANONICAL_BUILD +@maindex CANONICAL_BUILD +@ovindex build +@ovindex build_cpu +@ovindex build_vendor +@ovindex build_os +Compute the canonical build-system type variable, @code{build}, and its +three individual parts @code{build_cpu}, @code{build_vendor}, and +@code{build_os}. + +If @option{--build} was specified, then @code{build} is the +canonicalization of @code{build_alias} by @command{config.sub}, +otherwise it is determined by the shell script @code{config.guess}. +@end defmac + +@defmac AC_CANONICAL_HOST +@maindex CANONICAL_HOST +@ovindex host +@ovindex host_cpu +@ovindex host_vendor +@ovindex host_os +Compute the canonical host-system type variable, @code{host}, and its +three individual parts @code{host_cpu}, @code{host_vendor}, and +@code{host_os}. + +If @option{--host} was specified, then @code{host} is the +canonicalization of @code{host_alias} by @command{config.sub}, +otherwise it defaults to @code{build}. + +For temporary backward-compatibility, when @option{--host} is specified +by @option{--build} isn't, the build system will be assumed to be the +same as @option{--host}, and @samp{build_alias} will be set to that +value. Eventually, this historically incorrect behavior will go away. + +@end defmac + +@defmac AC_CANONICAL_TARGET +@maindex CANONICAL_TARGET +@ovindex target +@ovindex target_cpu +@ovindex target_vendor +@ovindex target_os +Compute the canonical target-system type variable, @code{target}, and its +three individual parts @code{target_cpu}, @code{target_vendor}, and +@code{target_os}. + +If @option{--target} was specified, then @code{target} is the +canonicalization of @code{target_alias} by @command{config.sub}, +otherwise it defaults to @code{host}. +@end defmac + + +@node Using System Type, , Canonicalizing, 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.ac} to select +system-specific C files. Then, using @code{AC_CONFIG_LINKS}, link those +files which have names based on the system name, to generic names, such +as @file{host.h} or @file{target.c} (@pxref{Configuration Links}). The +@code{case} statement patterns can use shell wild cards 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 + +@noindent +and in @file{configure.ac}, use: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example + +You can also use the host system type to find cross-compilation tools. +@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL} +macro which does that. + + +@c ===================================================== Site Configuration. + +@node Site Configuration, Running configure scripts, 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 +* Pretty Help Strings:: Formatting help string +* 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, Site Configuration +@section Working With External Software + +Some packages require, or can optionally use, other software packages +that 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}=@ovar{arg} +--without-@var{package} +@end example + +For example, @option{--with-gnu-ld} means work with the @sc{gnu} linker +instead of some other linker. @option{--with-x} means work with The X +Window System. + +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}. +@option{--without-@var{package}} is equivalent to +@option{--with-@var{package}=no}. + +@code{configure} scripts do not complain about +@option{--with-@var{package}} options that they do not support. This +behavior permits configuring a source tree containing multiple packages +with a top-level @code{configure} script when the packages support +different options, without spurious error messages about options that +some of the packages support. An unfortunate side effect is that option +spelling errors are not diagnosed. No better approach to this problem +has been suggested so far. + +For each external software package that may be used, @file{configure.ac} +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}, @ovar{action-if-given}, @ovar{action-if-not-given}) +@maindex ARG_WITH +If the user gave @code{configure} the option @option{--with-@var{package}} +or @option{--without-@var{package}}, run shell commands +@var{action-if-given}. If neither option was given, run shell commands +@var{action-if-not-given}. 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-given} in the shell variable @code{withval}, which is +actually just the value of the shell variable @code{with_@var{package}}, +with any @option{-} characters changed into @samp{_}. You may use that +variable instead, if you wish. + +The argument @var{help-string} is a description of the option that +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. + +You should format your @var{help-string} with the macro +@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}). +@end defmac + +@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given}) +@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, Pretty Help Strings, 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}=@ovar{arg} +--disable-@var{feature} +@end example + +These options allow users to choose which optional features to build and +install. @option{--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 @option{--enable-debug=stabs}. If no argument is +given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is +equivalent to @option{--enable-@var{feature}=no}. + +@code{configure} scripts do not complain about +@option{--enable-@var{feature}} options that they do not support. +This behavior permits configuring a source tree containing multiple +packages with a top-level @code{configure} script when the packages +support different options, without spurious error messages about options +that some of the packages support. +An unfortunate side effect is that option spelling errors are not diagnosed. +No better approach to this problem has been suggested so far. + +For each optional feature, @file{configure.ac} 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}, @ovar{action-if-given}, @ovar{action-if-not-given}) +@maindex ARG_ENABLE +If the user gave @code{configure} the option +@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run +shell commands @var{action-if-given}. If neither option was given, run +shell commands @var{action-if-not-given}. 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-given} in the shell variable @code{enableval}, which is +actually just the value of the shell variable +@code{enable_@var{feature}}, with any @option{-} characters changed into +@samp{_}. You may use that variable instead, if you wish. The +@var{help-string} argument is like that of @code{AC_ARG_WITH} +(@pxref{External Software}). + +You should format your @var{help-string} with the macro +@code{AC_HELP_STRING} (@pxref{Pretty Help Strings}). +@end defmac + +@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given}) +@maindex ENABLE +This is an obsolete version of @code{AC_ARG_ENABLE} that does not +support providing a help string. +@end defmac + + +@node Pretty Help Strings, Site Details, Package Options, Site Configuration +@section Making Your Help Strings Look Pretty + +Properly formatting the @samp{help strings} which are used in +@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE} +(@pxref{Package Options}) can be challenging. Specifically, you want +your own @samp{help strings} to line up in the appropriate columns of +@samp{configure --help} just like the standard Autoconf @samp{help +strings} do. This is the purpose of the @code{AC_HELP_STRING} macro. + +@defmac AC_HELP_STRING (@var{left-hand-side}, @var{right-hand-side}) +@maindex HELP_STRING + +Expands into an help string that looks pretty when the user executes +@samp{configure --help}. It is typically used in @code{AC_ARG_WITH} +(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package +Options}). The following example will make this clearer. + +@example +AC_DEFUN(TEST_MACRO, +[AC_ARG_WITH(foo, + AC_HELP_STRING([--with-foo], + [use foo (default is NO)]), + ac_cv_use_foo=$withval, ac_cv_use_foo=no), +AC_CACHE_CHECK(whether to use foo, + ac_cv_use_foo, ac_cv_use_foo=no)]) +@end example + +Please note that the call to @code{AC_HELP_STRING} is @strong{unquoted}. +Then the last few lines of @samp{configure --help} will appear like +this: + +@example +--enable and --with options recognized: + --with-foo use foo (default is NO) +@end example + +The @code{AC_HELP_STRING} macro is particularly helpful when the +@var{left-hand-side} and/or @var{right-hand-side} are composed of macro +arguments, as shown in the following example. + +@example +AC_DEFUN(MY_ARG_WITH, +[AC_ARG_WITH([$1], + AC_HELP_STRING([--with-$1], [use $1 (default is $2)]), + ac_cv_use_$1=$withval, ac_cv_use_$1=no), +AC_CACHE_CHECK(whether to use $1, ac_cv_use_$1, ac_cv_use_$1=$2)]) +@end example +@end defmac + + +@node Site Details, Transforming Names, Pretty Help Strings, 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. Run time configuration 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.ac} 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_TARGET} has been called and a @option{--target} value +is given that differs from the host type (specified with @option{--host}), +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 transform 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, Transforming Names +@subsection Transformation Options + +You can specify name transformations by giving @code{configure} these +command line options: + +@table @option +@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 +@option{--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 +@sc{gnu} programs installed on your system to shadow other programs with +the same name. For example, if you configure @sc{gnu} @code{diff} with +@option{--program-prefix=g}, then when you run @samp{make install} it is +installed as @file{/usr/local/bin/gdiff}. + +As a more sophisticated 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 @sc{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 @option{--program-suffix=2} to install the +programs as @file{/usr/local/bin/autoconf2}, +@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention +that only the binaries are renamed, therefore you'd have problems with +the library files which might overlap. + +@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 + +It is guaranteed that @code{program_transform_name} is never empty, and +that there are no useless separators. Therefore you may safely embed +@code{program_transform_name} within a sed program using @samp{;}: + +@example +transform = @@program_transform_name@@ +transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ +@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 (@pxref{Cache Files}). 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. + +You can examine or override the value set by a command line option to +@code{configure} in a site file; options set shell variables that have +the same names as the options, with any dashes turned into underscores. +The exceptions are that @option{--without-} and @option{--disable-} options +are like giving the corresponding @option{--with-} or @option{--enable-} +option and the value @samp{no}. Thus, @option{--cache-file=localcache} +sets the variable @code{cache_file} to the value @samp{localcache}; +@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable +@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the +variable @code{prefix} to the value @samp{/usr}; etc. + +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 +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 +# +# Change some defaults. +test "$prefix" = NONE && prefix=/usr/share/local/gnu +test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu +test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var +test "$localstatedir" = '$prefix/var' && localstatedir=/var + +# Give Autoconf 2.x generated configure scripts a shared default +# cache file for feature test results, architecture-specific. +if test "$cache_file" = /dev/null; then + cache_file="$prefix/var/config.cache" + # A cache file is only valid for one C compiler. + CC=gcc +fi +@end example + + +@c ============================================== Running configure Scripts. + +@node Running configure scripts, config.status Invocation, Site Configuration, Top +@chapter Running @code{configure} Scripts +@cindex @code{configure} + +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 +* Multiple Architectures:: Compiling for multiple architectures at once +* 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} +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how @code{configure} runs +@end menu + +@include install.texi + + +@c ============================================== Recreating a Configuration + +@node config.status Invocation, Obsolete Constructs, Running configure scripts, Top +@chapter Recreating a Configuration +@cindex @code{config.status} + +The @code{configure} script creates a file named @file{config.status}, +which actually configures, @dfn{instantiates}, the template files. It +also records the configuration options that were specified when the +package was last configured in case reconfiguring is needed. + +Synopsis: +@example +./config.status @var{option}@dots{} [@var{file}@dots{}] +@end example + +It configures the @var{files}, if none are specified, all the templates +are instantiated. The files must be specified without their +dependencies, as in + +@example +./config.status foobar +@end example + +@noindent +not + +@example +./config.status foobar:foo.in:bar.in +@end example + +The supported @var{option}s are: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options, the list of the template +files and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --file=@var{file}[:@var{template}] +Require that @var{file} be instantiated as if +@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both +@var{file} and @var{template} may be @samp{-} in which case the standard +output and/or standard input, respectively, is used. If a +@var{template} filename is relative, it is first looked for in the build +tree, and then in the source tree. @xref{Configuration Actions}, for +more details. + +This option and the following ones 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 +options allow a @file{config.status} file to create files other than the +ones that its @file{configure.ac} specifies, so it can be used for a +different package. + +@item --header=@var{file}[:@var{template}] +Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. + +@item --recheck +Ask @file{config.status} to update itself and exit (no instantiation). +This option is useful if you change @code{configure}, so that the +results of some tests might be different from the previous run. The +@option{--recheck} option re-runs @code{configure} with the same arguments +you used before, plus the @option{--no-create} option, which prevents +@code{configure} from running @file{config.status} and creating +@file{Makefile} and other files, and the @option{--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). +@end table + +@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 @option{--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 + +You can use @file{./config.status} in your Makefiles. For example, in +the dependencies given above (@pxref{Automatic Remaking}), +@file{config.status} is run twice when @file{configure.ac} 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.status config.h + echo > stamp-h + +Makefile: Makefile.in config.status + ./config.status Makefile +@end group +@end example + +The calling convention of @file{config.status} has changed, see +@ref{Obsolete config.status Use}, for details. + + +@c =================================================== Obsolete Constructs + +@node Obsolete Constructs, Questions, config.status Invocation, Top +@chapter Obsolete Constructs + +Autoconf changes, and throughout the years some constructs are obsoleted. +Most of the changes involve the macros, but the tools themselves, or +even some concepts, are now considered obsolete. + +You may completely skip this chapter if you are new to Autoconf, its +intention is mainly to help maintainers updating their packages by +understanding how to move to more modern constructs. + +@menu +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in @file{config.h.in} +* autoupdate Invocation:: Automatic update of @file{configure.ac} +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips +@end menu + +@node Obsolete config.status Use, acconfig.h, Obsolete Constructs, Obsolete Constructs +@section Obsolete @file{config.status} Invocation + +@file{config.status} now supports arguments to specify the files to +instantiate, see @ref{config.status Invocation}, for more details. +Before, environment variables had to be used. + +@defvar CONFIG_COMMANDS +@evindex CONFIG_COMMANDS +The tags of the commands to execute. The default is the arguments given +to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in +@file{configure.ac}. +@end defvar + +@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} and +@code{AC_CONFIG_FILES} in @file{configure.ac}. +@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_HEADERS}; if that +macro was not called, @file{config.status} ignores this variable. +@end defvar + +@defvar CONFIG_LINKS +@evindex CONFIG_LINKS +The symbolic links to establish. The default is the arguments given to +@code{AC_CONFIG_LINKS}; if that macro was not called, +@file{config.status} ignores this variable. +@end defvar + +In @ref{config.status Invocation}, using this old interface, the example +would be: + +@example +@group +config.h: stamp-h +stamp-h: config.h.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ + CONFIG_HEADERS=config.h ./config.status + echo > stamp-h + +Makefile: Makefile.in config.status + CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ + CONFIG_FILES=Makefile ./config.status +@end group +@end example + +@noindent +(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is +no need to set @code{CONFIG_HEADERS} in the @code{make} rules, equally +for @code{CONFIG_COMMANDS} etc.) + + +@node acconfig.h, autoupdate Invocation, Obsolete config.status Use, Obsolete Constructs +@section @file{acconfig.h} + +@cindex @file{acconfig.h} +@cindex @file{config.h.top} +@cindex @file{config.h.bot} + +In order to produce @file{config.h.in}, @command{autoheader} needs to +build or to find templates for each symbol. Modern releases of Autoconf +use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader +Macros}), but in older releases a file, @file{acconfig.h}, contained the +list of needed templates. @code{autoheader} copies comments and +@code{#define} and @code{#undef} statements from @file{acconfig.h} in +the current directory, if present. This file used to be mandatory if +you @code{AC_DEFINE} any additional symbols. + +Modern releases of Autoconf also provide @code{AH_TOP} and +@code{AH_BOTTOM} if you need to prepend/append some information to +@file{config.h.in}. Ancient versions of Autoconf had a similar feature: +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 +even older alternate way to produce the same effect in jurasik versions +of Autoconf 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. + +In former versions of Autoconf, the files used in preparing a software +package for distribution were: +@example +@group +configure.ac --. .------> autoconf* -----> configure + +---+ +[aclocal.m4] --+ `---. +[acsite.m4] ---' | + +--> [autoheader*] -> [config.h.in] +[acconfig.h] ----. | + +-----' +[config.h.top] --+ +[config.h.bot] --' +@end group +@end example + +Use only the @code{AH_} macros, @file{configure.ac} should be +self-contained, and should not depend upon @file{acconfig.h} etc. + + +@node autoupdate Invocation, Obsolete Macros, acconfig.h, Obsolete Constructs +@section Using @code{autoupdate} to Modernize @file{configure.ac} +@cindex @code{autoupdate} + +The @code{autoupdate} program updates a @file{configure.ac} 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{Obsolete Macros}, for a list of the old macros and the corresponding +new names), you can make your @file{configure.ac} 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.ac}, +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.ac} and writes the updated file to the +standard output. + +@noindent +@code{autoupdate} accepts the following options: + +@table @option +@item --help +@itemx -h +Print a summary of the command line options and exit. + +@item --version +@itemx -V +Print the version number of Autoconf and exit. + +@item --verbose +@itemx -v +Report processing steps. + +@item --debug +@itemx -d +Don't remove the temporary files. + +@item --autoconf-dir=@var{dir} +@itemx -A @var{dir} +@evindex AC_MACRODIR +Override the location where the installed Autoconf data files are looked +for. You can also set the @code{AC_MACRODIR} environment variable to a +directory; this option overrides the environment variable. + +This option is rarely needed and dangerous; it is only used when one +plays with different versions of Autoconf simultaneously. + +@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. +@end table + +@node Obsolete Macros, Autoconf 1, autoupdate Invocation, Obsolete Constructs +@section Obsolete Macros + +Several macros are obsoleted in Autoconf, for various reasons (typically +they failed to quote properly, couldn't be extended for more recent +issues etc.). They are still supported, but deprecated: their use +should be avoided. + +During the jump from Autoconf version 1 to version 2, most of the +macros were renamed to use a more uniform and descriptive naming scheme, +but their signature did not change. @xref{Macro Names}, for a +description of the new naming scheme. Below, there is just the mapping +from old names to new names for these macros, the reader is invited to +refer to the definition of the new macro for the signature and the +description. + +@defmac AC_ALLOCA +@maindex ALLOCA +@code{AC_FUNC_ALLOCA} +@end defmac + +@defmac AC_ARG_ARRAY +@maindex ARG_ARRAY +removed because of limited usefulness +@end defmac + +@defmac AC_C_CROSS +@maindex C_CROSS +This macro is obsolete; it does nothing. +@end defmac + +@defmac AC_CANONICAL_SYSTEM +@maindex CANONICAL_SYSTEM +Determine the system type and set output variables to the names of the +canonical system types. @xref{Canonicalizing}, for details about the +variables this macro sets. + +The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or +@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on +the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two +other macros. +@end defmac + +@defmac AC_CHAR_UNSIGNED +@maindex CHAR_UNSIGNED +@code{AC_C_CHAR_UNSIGNED} +@end defmac + +@defmac AC_CHECK_TYPE (@var{type}, @var{default}) +@maindex CHECK_TYPE +Autoconf, up to 2.13, used to provide this version of +@code{AC_CHECK_TYPE}, deprecated because of its flaws. Firstly, although +it is a member of the @code{CHECK} clan, singular sub-family, it does +more than just checking. Second, missing types are not +@code{typedef}'d, they are @code{#define}'d, which can lead to +incompatible code in the case of pointer types. + +This use of @code{AC_CHECK_TYPE} is obsolete and discouraged, see +@ref{Generic Types}, for the description of the current macro. + +If the type @var{type} is not defined, define it to be the C (or C++) +builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}. + +This macro is equivalent to: + +@example +AC_CHECK_TYPE([@var{type}], + [AC_DEFINE([@var{type}], [@var{default}], + [Define to `@var{default}' if <sys/types.h> + does not define.])]) +@end example + +In order to keep backward compatibility, the two versions of +@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics: + +@enumerate +@item +If there are three or four arguments, the modern version is used. + +@item +If the second argument appears to be a C or C++ type, then the +obsolete version is used. This happens if the argument is a C or C++ +@emph{builtin} type or a C identifier ending in @samp{_t}, optionally +followed by one of @samp{[(* } and then by a string of zero or more +characters taken from the set @samp{[]()* _a-zA-Z0-9}. + +@item +If the second argument is spelled with the alphabet of valid C and C++ +types, the user is warned and the modern version is used. + +@item +Otherwise, the modern version is used. +@end enumerate + +@noindent +You are encouraged either to use a valid builtin type, or to use the +equivalent modern code (see above), or better yet, to use +@code{AC_CHECK_TYPES} together with + +@example +#if !HAVE_LOFF_T +typedef loff_t off_t; +#endif +@end example +@end defmac +@c end of AC_CHECK_TYPE + +@defmac AC_CHECKING (@var{feature-description}) +@maindex CHECKING +Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}. +@end defmac + +@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found}, @ovar{action-if-not-found}) +@maindex COMPILE_CHECK +This is an obsolete version of @code{AC_TRY_LINK} (@pxref{Examining +Libraries}), 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 + +@defmac AC_CONST +@maindex CONST +@code{AC_C_CONST} +@end defmac + +@defmac AC_CROSS_CHECK +@maindex CROSS_CHECK +Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing +@code{:-)}. +@end defmac + +@defmac AC_CYGWIN +@maindex CYGWIN +Check for the Cygwin environment in which case the shell variable +@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified +means to check the nature of the host is using +@code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as: + +@example +AC_REQUIRE([AC_CANONICAL_HOST])[]dnl +case $host_os in + *cygwin* ) CYGWIN=yes;; + * ) CYGWIN=no;; +esac +@end example + +Beware that the variable @code{CYGWIN} has a very special meaning when +running CygWin32, and should not be changed. That's yet another reason +not to use this macro. +@end defmac + +@defmac AC_DECL_YYTEXT +@maindex DECL_YYTEXT +Does nothing, now integrated in @code{AC_PROG_LEX}. +@end defmac + +@defmac AC_DIR_HEADER +@maindex DIR_HEADER +@cvindex DIRENT +@cvindex SYSNDIR +@cvindex SYSDIR +@cvindex NDIR +Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT}, +but defines a different set of C preprocessor macros to indicate which +header file is found: + +@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}} +@item Header @tab Old Symbol @tab New Symbol +@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H} +@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H} +@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H} +@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H} +@end multitable +@end defmac + +@defmac AC_DYNIX_SEQ +@maindex DYNIX_SEQ +If on Dynix/PTX (Sequent @sc{unix}), add @option{-lseq} to output variable +@code{LIBS}. This macro used to be defined as + +@example +AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS") +@end example + +@noindent +now it is just @code{AC_FUNC_GETMNTENT}. +@end defmac + +@defmac AC_EXEEXT +@maindex EXEEXT +@ovindex EXEEXT +Defined the output variable @code{EXEEXT} based on the output of the +compiler, which is now done automatically. Typically set to empty +string if Unix and @samp{.exe} if Win32 or OS/2. +@end defmac + +@defmac AC_EMXOS2 +@maindex EMXOS2 +Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 +and sets @code{EMXOS2}. +@end defmac + +@defmac AC_ERROR +@maindex ERROR +@code{AC_MSG_ERROR} +@end defmac + +@defmac AC_FIND_X +@maindex FIND_X +@code{AC_PATH_X} +@end defmac + +@defmac AC_FIND_XTRA +@maindex FIND_XTRA +@code{AC_PATH_XTRA} +@end defmac + +@defmac AC_FUNC_CHECK +@maindex FUNC_CHECK +@code{AC_CHECK_FUNC} +@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}. + +These days portable programs should use @code{waitpid}, not +@code{wait3}, as @code{wait3} is being removed from the Open Group +standards, and will not appear in the next revision of POSIX. +@end defmac + +@defmac AC_GCC_TRADITIONAL +@maindex GCC_TRADITIONAL +@code{AC_PROG_GCC_TRADITIONAL} +@end defmac + +@defmac AC_GETGROUPS_T +@maindex GETGROUPS_T +@code{AC_TYPE_GETGROUPS} +@end defmac + +@defmac AC_GETLOADAVG +@maindex GETLOADAVG +@code{AC_FUNC_GETLOADAVG} +@end defmac + +@defmac AC_HAVE_FUNCS +@maindex HAVE_FUNCS +@code{AC_CHECK_FUNCS} +@end defmac + +@defmac AC_HAVE_HEADERS +@maindex HAVE_HEADERS +@code{AC_CHECK_HEADERS} +@end defmac + +@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) +@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}, @option{-lfoo}, or @samp{libfoo.a}. In +all of those cases, the compiler is passed @option{-lfoo}. However, +@var{library} cannot be a shell variable; it must be a literal name. +@end defmac + +@defmac AC_HAVE_POUNDBANG +@maindex HAVE_POUNDBANG +@code{AC_SYS_INTERPRETER} (different calling convention) +@end defmac + +@defmac AC_HEADER_CHECK +@maindex HEADER_CHECK +@code{AC_CHECK_HEADER} +@end defmac + +@defmac AC_HEADER_EGREP +@maindex HEADER_EGREP +@code{AC_EGREP_HEADER} +@end defmac + +@defmac AC_INIT (@var{unique-file-in-source-dir}) +@maindex INIT +Formerly @code{AC_INIT} used to have a single argument, and was +equivalent to: + +@example +AC_INIT +AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) +@end example +@end defmac + +@defmac AC_INLINE +@maindex INLINE +@code{AC_C_INLINE} +@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}. +Use @samp{AC_CHECK_SIZEOF(int)} instead. +@end defmac + +@defmac AC_IRIX_SUN +@maindex IRIX_SUN +If on IRIX (Silicon Graphics @sc{unix}), add @option{-lsun} to output +@code{LIBS}. 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)}. Up to Autoconf 2.13, it used to be + +@example +AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS") +@end example + +@noindent +now it is defined as + +@example +AC_FUNC_GETMNTENT +AC_CHECK_LIB(sun, getpwnam) +@end example +@end defmac + +@defmac AC_LANG_C +@maindex LANG_C +Same as @samp{AC_LANG(C)}. +@end defmac + +@defmac AC_LANG_CPLUSPLUS +@maindex LANG_CPLUSPLUS +Same as @samp{AC_LANG(C++)}. +@end defmac + +@defmac AC_LANG_FORTRAN77 +@maindex LANG_FORTRAN77 +Same as @samp{AC_LANG(Fortran 77)}. +@end defmac + +@defmac AC_LANG_RESTORE +@maindex LANG_RESTORE +Select the @var{language} that is saved on the top of the stack, as set +by @code{AC_LANG_SAVE}, remove it from the stack, and call +@code{AC_LANG(@var{language})}. +@end defmac + +@defmac AC_LANG_SAVE +@maindex LANG_SAVE +Remember the current language (as set by @code{AC_LANG}) on a stack. +The current language does not change. @code{AC_LANG_PUSH} is preferred. +@end defmac + +@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) +@maindex LINK_FILES +This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated +version of: + +@example +AC_LINK_FILES(config/$machine.h config/$obj_format.h, + host.h object.h) +@end example + +@noindent +is: + +@example +AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) +@end example +@end defmac + +@defmac AC_LN_S +@maindex LN_S +@code{AC_PROG_LN_S} +@end defmac + +@defmac AC_LONG_64_BITS +@maindex LONG_64_BITS +@cvindex LONG_64_BITS +Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. +Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead. +@end defmac + +@defmac AC_LONG_DOUBLE +@maindex LONG_DOUBLE +@code{AC_C_LONG_DOUBLE} +@end defmac + +@defmac AC_LONG_FILE_NAMES +@maindex LONG_FILE_NAMES +@code{AC_SYS_LONG_FILE_NAMES} +@end defmac + +@defmac AC_MAJOR_HEADER +@maindex MAJOR_HEADER +@code{AC_HEADER_MAJOR} +@end defmac + +@defmac AC_MEMORY_H +@maindex MEMORY_H +@cvindex NEED_MEMORY_H +Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were +defined in @file{memory.h}. Today it is equivalent to +@samp{AC_CHECK_HEADERS(memory.h)}. Adjust your code to depend upon +@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}, see @xref{Standard +Symbols}. +@end defmac + +@defmac AC_MINGW32 +@maindex MINGW32 +Similar to @code{AC_CYGWIN} but checks for the MingW32 compiler +environment and sets @code{MINGW32}. +@end defmac + +@defmac AC_MINUS_C_MINUS_O +@maindex MINUS_C_MINUS_O +@code{AC_PROG_CC_C_O} +@end defmac + +@defmac AC_MMAP +@maindex MMAP +@code{AC_FUNC_MMAP} +@end defmac + +@defmac AC_MODE_T +@maindex MODE_T +@code{AC_TYPE_MODE_T} +@end defmac + +@defmac AC_OBJEXT +@maindex OBJEXT +@ovindex OBJEXT +Defined the output variable @code{OBJEXT} based on the output of the +compiler, after .c files have been excluded. Typically set to @samp{o} +if Unix, @samp{obj} if Win32. Now the compiler checking macros handle +this automatically. +@end defmac + +@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) +@maindex OBSOLETE +Make @code{m4} print a message to 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}. + +For instance + +@example +AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl +@end example + +You are encouraged to use @code{AU_DEFUN} instead, since it gives better +services to the user. +@end defmac + +@defmac AC_OFF_T +@maindex OFF_T +@code{AC_TYPE_OFF_T} +@end defmac + +@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}, @ovar{save-defs}) +@maindex OUTPUT +The use of @code{AC_OUTPUT} with argument is deprecated, this obsoleted +interface is equivalent to: + +@example +@group +AC_CONFIG_FILES(@var{file}@dots{}) +AC_CONFIG_COMMANDS([default], + @var{extra-cmds}, @var{init-cmds}) +AC_SETUP_DEFS(@var{save-defs}) +AC_OUTPUT +@end group +@end example + +If you specify @var{save-defs}, autoconf will save the @samp{#define}s in a +different form, for use in the files specified in @code{AC_CONFIG_HEADERS}. +In this case, autoconf substitutes the C-style @samp{#define}s where it finds +@samp{@@DEFS@@}. +This runs faster, and is simpler to maintain +than building a file of @samp{#undef}s, +since autoconf will automatically generate a @samp{#define} for each +@code{AC_DEFINE} that you execute in the @code{configure} script. +The value for @var{save-defs} should be +either @code{cat}, or @code{sort}; +this value is used to filter the list of @samp{#define}s before editing. +Sorted lists are easier to read, +but you may wish to see the definitions in the order that they were +processed. +@end defmac + +@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds}) +@maindex OUTPUT_COMMANDS +Specify additional shell commands to run at the end of +@file{config.status}, and shell commands to initialize any variables +from @code{configure}. This macro may be called multiple times. It is +obsolete, replaced by @code{AC_CONFIG_COMMANDS}. + +Here is an unrealistic example: + +@example +fubar=27 +AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], + fubar=$fubar) +AC_OUTPUT_COMMANDS([echo this is another, extra, bit], + [echo init bit]) +@end example + +Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an +additional key, an important difference is that +@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, while +@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS} +can safely be given macro calls as arguments: + +@example +AC_CONFIG_COMMANDS(foo, [my_FOO()]) +@end example + +@noindent +conversely, where one level of quoting was enough for literal strings +with @code{AC_OUTPUT_COMMANDS}, you need two with +@code{AC_CONFIG_COMMANDS}. The following lines are equivalent: + +@example +@group +AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) +AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]]) +@end group +@end example +@end defmac + +@defmac AC_PID_T +@maindex PID_T +@code{AC_TYPE_PID_T} +@end defmac + +@defmac AC_PREFIX +@maindex PREFIX +@code{AC_PREFIX_PROGRAM} +@end defmac + +@defmac AC_PROGRAMS_CHECK +@maindex PROGRAMS_CHECK +@code{AC_CHECK_PROGS} +@end defmac + +@defmac AC_PROGRAMS_PATH +@maindex PROGRAMS_PATH +@code{AC_PATH_PROGS} +@end defmac + +@defmac AC_PROGRAM_CHECK +@maindex PROGRAM_CHECK +@code{AC_CHECK_PROG} +@end defmac + +@defmac AC_PROGRAM_EGREP +@maindex PROGRAM_EGREP +@code{AC_EGREP_CPP} +@end defmac + +@defmac AC_PROGRAM_PATH +@maindex PROGRAM_PATH +@code{AC_PATH_PROG} +@end defmac + +@defmac AC_REMOTE_TAPE +@maindex REMOTE_TAPE +removed because of limited usefulness +@end defmac + +@defmac AC_RESTARTABLE_SYSCALLS +@maindex RESTARTABLE_SYSCALLS +@code{AC_SYS_RESTARTABLE_SYSCALLS} +@end defmac + +@defmac AC_RETSIGTYPE +@maindex RETSIGTYPE +@code{AC_TYPE_SIGNAL} +@end defmac + +@defmac AC_RSH +@maindex RSH +Removed because of limited usefulness. +@end defmac + +@defmac AC_SCO_INTL +@maindex SCO_INTL +@ovindex LIBS +If on SCO UNIX, add @option{-lintl} to output variable @code{LIBS}. This +macro used to + +@example +AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS") +@end example + +@noindent +now it just calls @code{AC_FUNC_STRFTIME} instead. +@end defmac + +@defmac AC_SETVBUF_REVERSED +@maindex SETVBUF_REVERSED +@code{AC_FUNC_SETVBUF_REVERSED} +@end defmac + +@defmac AC_SET_MAKE +@maindex SET_MAKE +@code{AC_PROG_MAKE_SET} +@end defmac + +@defmac AC_SIZEOF_TYPE +@maindex SIZEOF_TYPE +@code{AC_CHECK_SIZEOF} +@end defmac + +@defmac AC_SIZE_T +@maindex SIZE_T +@code{AC_TYPE_SIZE_T} +@end defmac + +@defmac AC_STAT_MACROS_BROKEN +@maindex STAT_MACROS_BROKEN +@code{AC_HEADER_STAT} +@end defmac + +@defmac AC_STDC_HEADERS +@maindex STDC_HEADERS +@code{AC_HEADER_STDC} +@end defmac + +@defmac AC_STRCOLL +@maindex STRCOLL +@code{AC_FUNC_STRCOLL} +@end defmac + +@defmac AC_ST_BLKSIZE +@maindex ST_BLKSIZE +@code{AC_STRUCT_ST_BLKSIZE} +@end defmac + +@defmac AC_ST_BLOCKS +@maindex ST_BLOCKS +@code{AC_STRUCT_ST_BLOCKS} +@end defmac + +@defmac AC_ST_RDEV +@maindex ST_RDEV +@code{AC_STRUCT_ST_RDEV} +@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}. This macro does +not check if system calls are restarted in general--it tests whether a +signal handler installed with @code{signal} (but not @code{sigaction}) +causes system calls to be restarted. It does not test if system calls +can be restarted when interrupted by signals that have no handler. + +These days portable programs should use @code{sigaction} with +@code{SA_RESTART} if they want restartable system calls. They should +not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a +system call is restartable is a dynamic issue, not a configuration-time +issue. +@end defmac + +@defmac AC_SYS_SIGLIST_DECLARED +@maindex SYS_SIGLIST_DECLARED +@code{AC_DECL_SYS_SIGLIST} +@end defmac + +@defmac AC_TEST_CPP +@maindex TEST_CPP +@code{AC_TRY_CPP} +@end defmac + +@defmac AC_TEST_PROGRAM +@maindex TEST_PROGRAM +@code{AC_TRY_RUN} +@end defmac + +@defmac AC_TIMEZONE +@maindex TIMEZONE +@code{AC_STRUCT_TIMEZONE} +@end defmac + +@defmac AC_TIME_WITH_SYS_TIME +@maindex TIME_WITH_SYS_TIME +@code{AC_HEADER_TIME} +@end defmac + +@defmac AC_UID_T +@maindex UID_T +@code{AC_TYPE_UID_T} +@end defmac + +@defmac AC_UNISTD_H +@maindex UNISTD_H +Same as @samp{AC_CHECK_HEADERS(unistd.h)}. +@end defmac + +@defmac AC_USG +@maindex USG +@cvindex USG +Define @code{USG} if the @sc{bsd} string functions are defined in +@file{strings.h}. You should no longer depend upon @code{USG}, but on +@code{HAVE_STRING_H}, see @xref{Standard Symbols}. +@end defmac + +@defmac AC_UTIME_NULL +@maindex UTIME_NULL +@code{AC_FUNC_UTIME_NULL} +@end defmac + +@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd}) +@maindex VALIDATE_CACHED_SYSTEM_TUPLE +If the cache file is inconsistent with the current host, target and +build system types, it used to execute @var{cmd} or print a default +error message. + +This is now handled by default. +@end defmac + +@defmac AC_VERBOSE (@var{result-description}) +@maindex VERBOSE +@code{AC_MSG_RESULT}. +@end defmac + +@defmac AC_VFORK +@maindex VFORK +@code{AC_FUNC_VFORK} +@end defmac + +@defmac AC_VPRINTF +@maindex VPRINTF +@code{AC_FUNC_VPRINTF} +@end defmac + +@defmac AC_WAIT3 +@maindex WAIT3 +@code{AC_FUNC_WAIT3} +@end defmac + +@defmac AC_WARN +@maindex WARN +@code{AC_MSG_WARN} +@end defmac + +@defmac AC_WORDS_BIGENDIAN +@maindex WORDS_BIGENDIAN +@code{AC_C_BIGENDIAN} +@end defmac + +@defmac AC_XENIX_DIR +@maindex XENIX_DIR +@ovindex LIBS +This macro used to add @option{-lx} to output variable @code{LIBS} if on +Xenix. Also, if @file{dirent.h} is being checked for, added +@option{-ldir} to @code{LIBS}. Now it is merely an alias of +@code{AC_HEADER_DIRENT} instead, plus some code to detect whether +running @sc{xenix} on which you should not depend: + +@example +AC_MSG_CHECKING([for Xenix]) +AC_EGREP_CPP(yes, +[#if defined M_XENIX && !defined M_UNIX + yes +#endif], + [AC_MSG_RESULT([yes]); XENIX=yes], + [AC_MSG_RESULT([no]); XENIX=]) +@end example +@end defmac + +@defmac AC_YYTEXT_POINTER +@maindex YYTEXT_POINTER +@code{AC_DECL_YYTEXT} +@end defmac + +@node Autoconf 1, Autoconf 2.13, Obsolete Macros, Obsolete Constructs +@section 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.ac} 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. + +@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 +* 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, Autoconf 1, Autoconf 1 +@subsection 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{autoconf Invocation}. + +If you distribute @file{install.sh} with your package, rename it to +@file{install-sh} so @code{make} builtin rules won't inadvertently +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}, @file{config.h.bot}, or +@file{acconfig.h}, you still can, but you will have less clutter if you +use the @code{AH_} macros. @xref{Autoheader Macros}. + +@node Changed Makefiles, Changed Macros, Changed File Names, Autoconf 1 +@subsection 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 behavior of replacing those variables without @samp{@@} +characters around them has been removed. + +@node Changed Macros, Changed Results, Changed Makefiles, Autoconf 1 +@subsection 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{Obsolete Macros}, for a table showing the +new names for the old macros. Use the @code{autoupdate} program to +convert your @file{configure.ac} to using the new macro names. +@xref{autoupdate Invocation}. + +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 Changed Results, Changed Macro Writing, Changed Macros, Autoconf 1 +@subsection 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.ac} 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 -l$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 back quotes) 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, Autoconf 1 +@subsection 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 Autoconf 2.13, , Autoconf 1, Obsolete Constructs +@section Upgrading From Version 2.13 + +The introduction of the previous section (@pxref{Autoconf 1}) perfectly +suits this section... + +@quotation +Autoconf version 2.50 is mostly backward compatible with version 2.13. +However, it introduces better ways to do some things, and doesn't +support some of the ugly things in version 2.13. So, depending on how +sophisticated your @file{configure.ac} files are, you might have to do +some manual work in order to upgrade to version 2.50. 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.50; the changes are summarized in the file +@file{NEWS} in the Autoconf distribution. +@end quotation + +@menu +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros +@end menu + +@node Changed Quotation, New Macros, Autoconf 2.13, Autoconf 2.13 +@subsection Changed Quotation + +The most important changes are invisible to you: the implementation of +most macros have completely changed. This allowed more factorization of +the code, better error messages, a higher uniformity of the user's +interface etc. Unfortunately, as a side effect, some construct which +used to (miraculously) work might break starting with Autoconf 2.50. +The most common culprit is bad quotation. + +For instance, in the following example, the message is not properly +quoted: + +@example +AC_INIT +AC_CHECK_HEADERS(foo.h,, +AC_MSG_ERROR(cannot find foo.h, bailing out)) +AC_OUTPUT +@end example + +@noindent +Autoconf 2.13 simply ignores it: + +@example +$ autoconf-2.13; ./configure --silent +creating cache ./config.cache +configure: error: cannot find foo.h +$ +@end example + +@noindent +while Autoconf 2.50 will produce a broken @file{configure}: + +@example +$ autoconf-2.50; ./configure --silent +configure: error: cannot find foo.h +./configure: exit: bad non-numeric arg `bailing' +./configure: exit: bad non-numeric arg `bailing' +$ +@end example + +The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation +too! + +@example +AC_INIT +AC_CHECK_HEADERS(foo.h,, + [AC_MSG_ERROR([cannot find foo.h, bailing out])]) +AC_OUTPUT +@end example + +Many many (and many more) Autoconf macros were lacking proper quotation, +including no less than... @code{AC_DEFUN} itself! + +@example +$ cat configure.in +AC_DEFUN([AC_PROG_INSTALL], +[# My own much better version +]) +AC_INIT +AC_PROG_INSTALL +AC_OUTPUT +$ autoconf-2.13 +autoconf: Undefined macros: +***BUG in Autoconf--please report*** AC_FD_MSG +***BUG in Autoconf--please report*** AC_EPI +configure.in:1:AC_DEFUN([AC_PROG_INSTALL], +configure.in:5:AC_PROG_INSTALL +$ autoconf-2.50 +$ +@end example + + +@node New Macros, , Changed Quotation, Autoconf 2.13 +@subsection New Macros + +@cindex @code{undefined macro: _m4_divert_diversion} + +Because Autoconf has been dormant for years, Automake provided +Autoconf-like macros for a while. Autoconf 2.50 now provides better +versions of these macros, integrated in the @code{AC_} namespace, +instead of @code{AM_}. But in order to ease the upgrading via +@command{autoupdate}, bindings to such @code{AM_} macros are provided. + +Unfortunately Automake did not quote the name of these macros! +Therefore, when @command{m4} find in @file{aclocal.m4} something like +@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)}, @code{AM_TYPE_PTRDIFF_T} is +expanded, replaced with its Autoconf definition. + +Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and will +complain, in its own words: + +@example +$ cat configure.in +AC_INIT +AM_TYPE_PTRDIFF_T +$ aclocal-1.4 +$ autoconf +./aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion +actypes.m4:289: AM_TYPE_PTRDIFF_T is expanded from... +./aclocal.m4:17: the top level +$ +@end example + +Future versions of Automake will simply no longer define most of these +macros, and will properly quote the names of the remaining macros. +But you don't have to wait for it to happen to do the right thing right +now: do not depend upon macros from Automake as it is simply not its job +to provide macros (but the one it requires by itself): + +@example +$ cat configure.in +AC_INIT +AM_TYPE_PTRDIFF_T +$ rm aclocal.m4 +$ autoupdate +autoupdate: `configure.in' is updated +$ cat configure.in +AC_INIT +AC_CHECK_TYPES([ptrdiff_t]) +$ aclocal-1.4 +$ autoconf +$ +@end example + +@c ================================================ Questions About Autoconf. + +@node Questions, History, Obsolete Constructs, 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 M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses @code{configure} instead of Imake +@end menu + +@node Distributing, Why GNU m4, Questions, 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 @sc{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.ac}. @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 M4? + +@display +Why does Autoconf require @sc{gnu} M4? +@end display + +Many M4 implementations have hard-coded limitations on the size and +number of macros that 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 + +Autoconf requires version 1.4 or above of @sc{gnu} M4 because it uses +frozen state files. + +Since only software maintainers need to use Autoconf, and since @sc{gnu} +M4 is simple to configure and install, it seems reasonable to require +@sc{gnu} M4 to be installed also. Many maintainers of @sc{gnu} and +other free software already have most of the @sc{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 @sc{gnu} M4 and @sc{gnu} 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 @sc{gnu} M4 does come with a +@code{configure} script produced by Autoconf, Autoconf is not required +in order to run the script and install @sc{gnu} M4. Autoconf is only +required if you want to change the 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: + +@quotation +Autoconf generated scripts frequently work on machines that 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. + +@sc{gnu} tools are not released this way. Each @sc{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. + +If you view the @sc{gnu} suite as a collection of native tools, then the +problems are similar. But the @sc{gnu} 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 @sc{gnu} coding +standards address the same issues without necessarily imposing the same +restrictions. +@end quotation + + +Here is some further explanation, written by Per Bothner: + +@quotation +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. +@end quotation + + +Paul Eggert elaborates more: + +@quotation +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 +supported 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. +@end quotation + + +Finally, Mark Eichin notes: + +@quotation +Imake isn't all that extensible, either. In order to add new features to +Imake, you need to provide your 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. +@end quotation + + + + +@c ===================================================== History of Autoconf. + +@node History, Environment Variable Index, Questions, 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 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, History +@section Genesis + +In June 1991 I was maintaining many of the @sc{gnu} utilities for the +Free Software Foundation. As they were ported to more platforms and +more programs were added, the number of @option{-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 @sc{gnu} utilities packages. Brian Berliner +also adapted one of my scripts for his @sc{cvs} revision control system. + +Later that summer, I learned that Richard Stallman and Richard Pixley +were developing similar scripts to use in the @sc{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 @sc{gnu} utilities packages to use +@code{configure} scripts, updating them all by hand became impractical. +Rich Murphey, the maintainer of the @sc{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 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 @sc{gnu} extensions to M4.) Also, some of my friends at the +University of Maryland had recently been putting 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 @sc{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 M4 macros +and continued to add features and improve the techniques used in the +checks. Prominent among the testers were Fran@,cois 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 Lance Taylor, who added support for creating a C +header file as an alternative to putting @option{-D} options in a +@file{Makefile}, so he could use Autoconf for his @sc{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 @sc{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 @sc{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 M4 implementations. +@sc{unix} @code{m4} started to dump core because of the length of the +macros that Autoconf defined, and several bugs showed up in @sc{gnu} +@code{m4} as well. Eventually, we realized that we needed to use some +features that only @sc{gnu} M4 has. 4.3@sc{bsd} @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. Fran@,cois Pinard made it diagnose +invalid arguments. Jim Blandy bravely coerced it into configuring +@sc{gnu} Emacs, laying the groundwork for several later improvements. +Roland McGrath got it to configure the @sc{gnu} C Library, wrote the +@code{autoheader} script to automate the creation of C header file +templates, and added a @option{--verbose} option to @code{configure}. +Noah Friedman added the @option{--autoconf-dir} 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}, @option{--host}, and +@option{--target}; making links to files; and running @code{configure} +scripts in subdirectories. Adding these features enabled Ken to convert +@sc{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 Fran@,cois Pinard, I made +the macros not interrupt each others' messages. (That feature revealed +some performance bottlenecks in @sc{gnu} @code{m4}, which he hastily +corrected!) I reorganized the documentation around problems people want +to solve. And I began a test suite, because experience had shown that +Autoconf has a pronounced tendency to regress when we change it. + +Again, several alpha testers gave invaluable feedback, especially +Fran@,cois 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.) + + +@c ========================================================== Appendices + +@node Environment Variable Index, Output Variable Index, History, 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, Autoconf 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 Autoconf Macro Index, M4 Macro Index, Preprocessor Symbol Index, Top +@unnumbered Autoconf 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 + +@node M4 Macro Index, Concept Index, Autoconf Macro Index, Top +@unnumbered M4 Macro Index + +This is an alphabetical list of the M4, M4sugar, and M4sh macros. To +make the list easier to use, the macros are listed without their +preceding @samp{m4_} or @samp{AS_}. + +@printindex ms + +@node Concept Index, , M4 Macro Index, Top +@unnumbered Concept Index + +This is an alphabetical list of the files, tools, and concepts +introduced in this document. + +@printindex cp + +@contents +@bye + +@c Local Variables: +@c ispell-local-dictionary: "american" +@c End: |