diff options
Diffstat (limited to 'doc/autoconf.info')
| -rw-r--r-- | doc/autoconf.info | 10852 |
1 files changed, 10852 insertions, 0 deletions
diff --git a/doc/autoconf.info b/doc/autoconf.info new file mode 100644 index 0000000..d64dd17 --- /dev/null +++ b/doc/autoconf.info @@ -0,0 +1,10852 @@ +This is autoconf.info, produced by makeinfo version 6.7 from +autoconf.texi. + +INFO-DIR-SECTION GNU admin +START-INFO-DIR-ENTRY +* Autoconf: (autoconf). Create source code configuration scripts +END-INFO-DIR-ENTRY + +INFO-DIR-SECTION Individual utilities +START-INFO-DIR-ENTRY +* autoscan: (autoconf)autoscan Invocation. + Semi-automatic '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 'configure' scripts +* configure: (autoconf)configure Invocation. + Configuring a package +* config.status: (autoconf)config.status Invocation. + Recreating a configuration +END-INFO-DIR-ENTRY + +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 '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. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: autoconf.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) + +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 2.52.20231210, for Autoconf version +2.52.20231210. + +* 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 '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 + + +The GNU build system + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + +Making 'configure' Scripts + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic 'configure.ac' writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple 'configure' scripts + +Writing '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 '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 '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 'configure' runs +* Printing Messages:: Notifying 'configure' users + +Caching Results + +* Cache Variable Names:: Shell variables used in caches +* Cache Files:: Files '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 '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 à 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 'configure' local defaults + +Transforming Program Names When Installing + +* Transformation Options:: 'configure' options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: 'Makefile' uses of transforming names + +Running 'configure' Scripts + +* Basic Installation:: Instructions for typical cases +* Compilers and Options:: Selecting compilers and optimization +* 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 'configure' +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how 'configure' runs + +Obsolete Constructs + +* Obsolete config.status Use:: Different calling convention +* acconfig.h:: Additional entries in 'config.h.in' +* autoupdate Invocation:: Automatic update of '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 '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 'configure' scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses 'configure' instead of Imake + +History of Autoconf + +* Genesis:: Prehistory and naming of 'configure' +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + + + +File: autoconf.info, Node: Introduction, Next: The GNU build system, Prev: Top, Up: Top + +1 Introduction +************** + + A physicist, an engineer, and a computer scientist were discussing the + nature of God. "Surely a Physicist," said the physicist, "because + early in the Creation, God made Light; and you know, Maxwell's + equations, the dual nature of electromagnetic waves, the relativistic + consequences..." "An Engineer!," said the engineer, "because +before making Light, God split the Chaos into Land and Water; it takes a + hell of an engineer to handle that big amount of mud, and orderly + separation of solids from liquids..." The computer scientist + shouted: "And the Chaos, where do you think it was coming from, hmm?" + + --Anonymous + + Autoconf is a tool for producing shell scripts that automatically +configure software source code packages to adapt to many kinds of +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 UNIX variants. +There is no need to maintain files that list the features supported by +each release of each variant of UNIX. + + For each software package that Autoconf is used with, it creates a +configuration script from a template file that lists the system features +that the package needs or can use. After the shell code to recognize +and respond to a system feature has been written, Autoconf allows it to +be shared by many software packages that can use (or need) that feature. +If it later turns out that the shell code needs adjustment for some +reason, it needs to be changed in only one place; all of the +configuration scripts can be regenerated automatically to take advantage +of the updated code. + + The Metaconfig package is similar in purpose to Autoconf, but the +scripts it produces require manual user intervention, which is quite +inconvenient when configuring large source trees. Unlike Metaconfig +scripts, Autoconf scripts can support cross-compiling, if some care is +taken in writing them. + + Autoconf does not solve all problems related to making portable +software packages--for a more complete solution, it should be used in +concert with other GNU build tools like Automake and Libtool. These +other tools take on jobs like the creation of a portable, recursive +'Makefile' with all of the standard targets, linking of shared +libraries, and so on. *Note The GNU build system::, for more +information. + + Autoconf imposes some restrictions on the names of macros used with +'#if' in C programs (*note Preprocessor Symbol Index::). + + Autoconf requires GNU M4 in order to generate the scripts. It uses +features that some UNIX versions of M4, including GNU M4 1.3, do not +have. You must use version 1.4 or later of GNU M4. + + *Note Autoconf 1::, for information about upgrading from version 1. +*Note History::, for the story of Autoconf's development. *Note +Questions::, for answers to some common questions about Autoconf. + + See the Autoconf web page(1) for up-to-date information, details on +the mailing lists, pointers to a list of known bugs, etc. + + Mail suggestions to the Autoconf mailing list <autoconf@gnu.org>. + + Bug reports should be preferably submitted to the Autoconf Gnats +database(2), or sent to the Autoconf Bugs mailing list +<bug-autoconf@gnu.org>. If possible, first check that your bug is not +already solved in current development versions, and that it has not been +reported yet. Be sure to include all the needed information and a short +'configure.ac' that demonstrates the problem. + + Autoconf's development tree is accessible via CVS; see the Autoconf +web page for details. There is also a CVSweb interface to the Autoconf +development tree(3). Patches relative to the current CVS version can be +sent for review to the Autoconf Patches mailing list +<autoconf-patches@gnu.org>. + + 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 +Autoconf Macro Archive(4), which is kindly run by Peter Simons +<simons@computer.org>. + + ---------- Footnotes ---------- + + (1) Autoconf web page, +<http://www.gnu.org/software/autoconf/autoconf.html>. + + (2) Autoconf Gnats database, +<http://sources.redhat.com/cgi-bin/gnatsweb.pl?database=autoconf>. + + (3) CVSweb interface to the Autoconf development tree, +<http://subversions.gnu.org/cgi-bin/cvsweb/autoconf/>. + + (4) Autoconf Macro Archive, +<http://www.gnu.org/software/ac-archive/>. + + +File: autoconf.info, Node: The GNU build system, Next: Making configure Scripts, Prev: Introduction, Up: Top + +2 The GNU build system +********************** + +Autoconf solves an important problem--reliable discovery of +system-specific build and runtime information--but this is only one +piece of the puzzle for the development of portable software. To this +end, the GNU project has developed a suite of integrated utilities to +finish the job Autoconf started: the GNU build system, whose most +important components are Autoconf, Automake, and Libtool. In this +chapter, we introduce you to those tools, point you to sources of more +information, and try to convince you to use the entire GNU build system +for your software. + +* Menu: + +* Automake:: Escaping Makefile hell +* Libtool:: Building libraries portably +* Pointers:: More info on the GNU build system + + +File: autoconf.info, Node: Automake, Next: Libtool, Prev: The GNU build system, Up: The GNU build system + +2.1 Automake +============ + +The ubiquity of 'make' means that a 'Makefile' is almost the only viable +way to distribute automatic build rules for software, but one quickly +runs into '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 'make' on many systems. On top of all this is the manual +labor required to implement the many standard targets that users have +come to expect ('make install', 'make distclean', 'make uninstall', +etc.). Since you are, of course, using Autoconf, you also have to +insert repetitive code in your 'Makefile.in' to recognize '@CC@', +'@CFLAGS@', and other substitutions provided by 'configure'. Into this +mess steps "Automake". + + Automake allows you to specify your build needs in a 'Makefile.am' +file with a vastly simpler and more powerful syntax than that of a plain +'Makefile', and then generates a portable 'Makefile.in' for use with +Autoconf. For example, the 'Makefile.am' to build and install a simple +"Hello world" program might look like: + + bin_PROGRAMS = hello + hello_SOURCES = hello.c + +The resulting 'Makefile.in' (~400 lines) automatically supports all the +standard targets, the substitutions provided by Autoconf, automatic +dependency tracking, 'VPATH' building, and so on. 'make' will build the +'hello' program, and 'make install' will install it in '/usr/local/bin' +(or whatever prefix was given to 'configure', if not '/usr/local'). + + Automake may require that additional tools be present on the +_developer's_ machine. For example, the '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 'make dist', however, produces a +'hello-1.0.tar.gz' package (or whatever the program/version is) with a +'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... + + +File: autoconf.info, Node: Libtool, Next: Pointers, Prev: Automake, Up: The GNU build system + +2.2 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 _shared_ (dynamically-linked) libraries, which can +be used by multiple programs without duplication on disk or in memory +and can be updated independently of the linked programs. Producing +shared libraries portably, however, is the stuff of nightmares--each +system has its own incompatible tools, compiler flags, and magic +incantations. Fortunately, GNU provides a solution: "Libtool". + + Libtool handles all the requirements of building shared libraries for +you, and at this time seems to be the _only_ way to do so with any +portability. It also handles many other headaches, such as: the +interaction of '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. + + +File: autoconf.info, Node: Pointers, Prev: Libtool, Up: The GNU build system + +2.3 Pointers +============ + +Developers who are used to the simplicity of 'make' for small projects +on a single system might be daunted at the prospect of learning to use +Automake and Autoconf. As your software is distributed to more and more +users, however, you 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. + + - Web + + The home pages for Autoconf(1), and Libtool(2). + + - Books + + The book 'GNU Autoconf, Automake and Libtool'(3) describes the + complete GNU build environment. You can also find the entire book + on-line at "The Goat Book" home page(4). + + - Tutorials and Examples + + The Autoconf Developer Page(5) maintains links to a number of + Autoconf/Automake tutorials online, and also links to the Autoconf + Macro Archive(6). + + ---------- Footnotes ---------- + + (1) Autoconf, <http://www.gnu.org/software/autoconf/>. + + (2) Libtool, <http://www.gnu.org/software/libtool/>. + + (3) 'GNU Autoconf, Automake and Libtool', by G. V. Vaughan, B. +Elliston, T. Tromey, and I. L. Taylor. New Riders, 2000, ISBN +1578701902. + + (4) "The Goat Book" home page, <http://sources.redhat.com/autobook/>. + + (5) Autoconf Developer Page, <http://sources.redhat.com/autoconf/>. + + (6) Autoconf Macro Archive, +<http://www.gnu.org/software/ac-archive/>. + + +File: autoconf.info, Node: Making configure Scripts, Next: Setup, Prev: The GNU build system, Up: Top + +3 Making 'configure' Scripts +**************************** + +The configuration scripts that Autoconf produces are by convention +called 'configure'. When run, 'configure' creates several files, +replacing configuration parameters in them with appropriate values. The +files that 'configure' creates are: + + - one or more 'Makefile' files, one in each subdirectory of the + package (*note Makefile Substitutions::); + + - optionally, a C header file, the name of which is configurable, + containing '#define' directives (*note Configuration Headers::); + + - a shell script called 'config.status' that, when run, will recreate + the files listed above (*note config.status Invocation::); + + - an optional shell script normally called 'config.cache' (created + when using 'configure --config-cache') that saves the results of + running many of the tests (*note Cache Files::); + + - a file called 'config.log' containing any messages produced by + compilers, to help debugging if 'configure' makes a mistake. + + To create a 'configure' script with Autoconf, you need to write an +Autoconf input file 'configure.ac' (or 'configure.in') and run +'autoconf' on it. If you write your own feature tests to supplement +those that come with Autoconf, you might also write files called +'aclocal.m4' and 'acsite.m4'. If you use a C header file to contain +'#define' directives, you might also run 'autoheader', and you will +distribute the generated file 'config.h.in' with the package. + + Here is a diagram showing how the files that can be used in +configuration are produced. Programs that are executed are suffixed by +'*'. Optional files are enclosed in square brackets ('[]'). 'autoconf' +and 'autoheader' also read the installed Autoconf macro files (by +reading 'autoconf.m4'). + +Files used in preparing a software package for distribution: + your source files --> [autoscan*] --> [configure.scan] --> configure.ac + + configure.ac --. + | .------> autoconf* -----> configure + [aclocal.m4] --+---+ + | `-----> [autoheader*] --> [config.h.in] + [acsite.m4] ---' + + Makefile.in -------------------------------> Makefile.in + +Files used in configuring a software package: + .-------------> [config.cache] + configure* ------------+-------------> config.log + | + [config.h.in] -. v .-> [config.h] -. + +--> config.status* -+ +--> make* + Makefile.in ---' `-> Makefile ---' + +* Menu: + +* Writing configure.ac:: What to put in an Autoconf input file +* autoscan Invocation:: Semi-automatic 'configure.ac' writing +* ifnames Invocation:: Listing the conditionals in source code +* autoconf Invocation:: How to create configuration scripts +* autoreconf Invocation:: Remaking multiple 'configure' scripts + + +File: autoconf.info, Node: Writing configure.ac, Next: autoscan Invocation, Prev: Making configure Scripts, Up: Making configure Scripts + +3.1 Writing 'configure.ac' +========================== + +To produce a 'configure' script for a software package, create a file +called 'configure.ac' that contains invocations of the Autoconf macros +that test the system features your package needs or can use. Autoconf +macros already exist to check for many features; see *note Existing +Tests::, for their descriptions. For most other features, you can use +Autoconf template macros to produce custom checks; see *note Writing +Tests::, for information about them. For especially tricky or +specialized features, 'configure.ac' might need to contain some +hand-crafted shell commands; see *note Portable Shell::. The 'autoscan' +program can give you a good start in writing 'configure.ac' (*note +autoscan Invocation::, for more information). + + Previous versions of Autoconf promoted the name 'configure.in', which +is somewhat ambiguous (the tool needed to produce this file is not +described by its extension), and introduces a slight confusion with +'config.h.in' and so on (for which '.in' means "to be processed by +'configure'"). Using 'configure.ac' is now preferred. + +* Menu: + +* Shell Script Compiler:: Autoconf as solution of a problem +* Autoconf Language:: Programming in Autoconf +* configure.ac Layout:: Standard organization of configure.ac + + +File: autoconf.info, Node: Shell Script Compiler, Next: Autoconf Language, Prev: Writing configure.ac, Up: Writing configure.ac + +3.1.1 A Shell Script Compiler +----------------------------- + +Just as for any other computer language, in order to properly program +'configure.ac' in Autoconf you must understand _what_ problem the +language tries to address and _how_ it does so. + + The problem Autoconf addresses is that the world is a mess. After +all, you are using Autoconf in order to have your package compile easily +on all sorts of different systems, some of them being extremely hostile. +Autoconf itself bears the price for these differences: 'configure' must +run on all those systems, and thus 'configure' must limit itself to +their lowest common denominator of features. + + Naturally, you might then think of shell scripts; who needs +'autoconf'? A set of properly written shell functions is enough to make +it easy to write 'configure' scripts by hand. Sigh! Unfortunately, +shell functions do not belong to the least common denominator; +therefore, where you would like to define a function and use it ten +times, you would instead need to copy its body ten times. + + So, what is really needed is some kind of compiler, 'autoconf', that +takes an Autoconf program, 'configure.ac', and transforms it into a +portable shell script, 'configure'. + + How does 'autoconf' perform this task? + + There are two obvious possibilities: creating a brand new language or +extending an existing one. The former option is 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 'sh' (Bourne shell) language. + + Autoconf does the latter: it is a layer on top of 'sh'. It was +therefore most convenient to implement 'autoconf' as a macro expander: a +program that repeatedly performs "macro expansions" on text input, +replacing macro calls with macro bodies and producing a pure 'sh' script +in the end. Instead of implementing a dedicated Autoconf macro +expander, it is natural to use an existing general-purpose macro +language, such as M4, and implement the extensions as a set of M4 +macros. + + +File: autoconf.info, Node: Autoconf Language, Next: configure.ac Layout, Prev: Shell Script Compiler, Up: Writing configure.ac + +3.1.2 The Autoconf Language +--------------------------- + +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 '[' and ']', 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 _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: + + AC_CHECK_HEADER([stdio.h], + [AC_DEFINE([HAVE_STDIO_H])], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) + +is quoted properly. You may safely simplify its quotation to: + + AC_CHECK_HEADER(stdio.h, + [AC_DEFINE(HAVE_STDIO_H)], + [AC_MSG_ERROR([Sorry, can't do anything for you])]) + +Notice that the argument of '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: + + AC_CHECK_HEADER(stdio.h, + AC_DEFINE(HAVE_STDIO_H), + AC_MSG_ERROR([Sorry, can't do anything for you])) + + In other cases, you may have to use text that also resembles a macro +call. You must quote that text even when it is not passed as a macro +argument: + + echo "Hard rock was here! --[AC_DC]" + +which will result in + + echo "Hard rock was here! --AC_DC" + +When you use the same text in a macro argument, you must therefore have +an extra quotation level (since one is stripped away by the macro +substitution). In general, then, it is a good idea to _use double +quoting for all literal string arguments_: + + AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) + + You are now able to understand one of the constructs of Autoconf that +has been continually misunderstood... The rule of thumb is that +_whenever you expect macro expansion, expect quote expansion_; i.e., +expect one level of quotes to be lost. For instance: + + AC_COMPILE_IFELSE([char b[10];],, [AC_MSG_ERROR([you lose])]) + +is incorrect: here, the first argument of 'AC_COMPILE_IFELSE' is 'char +b[10];' and will be expanded once, which results in 'char b10;'. (There +was an idiom common in Autoconf's past to address this issue via the M4 +'changequote' primitive, but do not use it!) Let's take a closer look: +the author meant the first argument to be understood as a literal, and +therefore it must be quoted twice: + + AC_COMPILE_IFELSE([[char b[10];]],, [AC_MSG_ERROR([you lose])]) + +Voilà, you actually produce 'char b[10];' this time! + + The careful reader will notice that, according to these guidelines, +the "properly" quoted '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 [ARG] (not to be confused with the quote characters). You +may just leave them empty, or use '[]' to make the emptiness of the +argument explicit, or you may simply omit the trailing commas. The +three lines below are equivalent: + + AC_CHECK_HEADERS(stdio.h, [], [], []) + AC_CHECK_HEADERS(stdio.h,,,) + AC_CHECK_HEADERS(stdio.h) + + It is best to put each macro call on its own line in 'configure.ac'. +Most of the macros don't add extra newlines; they rely on the newline +after the macro call to terminate the commands. This approach makes the +generated 'configure' script a little easier to read by not inserting +lots of blank lines. It is generally safe to set shell variables on the +same line as a macro call, because the shell allows assignments without +intervening newlines. + + You can include comments in 'configure.ac' files by starting them +with the '#'. For example, it is helpful to begin 'configure.ac' files +with a line like this: + + # Process this file with autoconf to produce a configure script. + + +File: autoconf.info, Node: configure.ac Layout, Prev: Autoconf Language, Up: Writing configure.ac + +3.1.3 Standard 'configure.ac' Layout +------------------------------------ + +The order in which 'configure.ac' calls the Autoconf macros is not +important, with a few exceptions. Every 'configure.ac' must contain a +call to 'AC_INIT' before the checks, and a call to 'AC_OUTPUT' at the +end (*note Output::). Additionally, some macros rely on other macros +having been called first, because they check previously set values of +some variables to decide what to do. These macros are noted in the +individual descriptions (*note Existing Tests::), and they also warn you +when 'configure' is created if they are called out of order. + + To encourage consistency, here is a suggested order for calling the +Autoconf macros. Generally speaking, the things near the end of this +list are those that could depend on things earlier in it. For example, +library functions could be affected by types and libraries. + + Autoconf requirements + 'AC_INIT(PACKAGE, VERSION, BUG-REPORT-ADDRESS)' + information on the package + checks for programs + checks for libraries + checks for header files + checks for types + checks for structures + checks for compiler characteristics + checks for library functions + checks for system services + 'AC_CONFIG_FILES([FILE...])' + 'AC_OUTPUT' + + +File: autoconf.info, Node: autoscan Invocation, Next: ifnames Invocation, Prev: Writing configure.ac, Up: Making configure Scripts + +3.2 Using 'autoscan' to Create 'configure.ac' +============================================= + +The 'autoscan' program can help you create and/or maintain a +'configure.ac' file for a software package. 'autoscan' examines source +files in the directory tree rooted at a directory given as a command +line argument, or the current directory if none is given. It searches +the source files for common portability problems and creates a file +'configure.scan' which is a preliminary 'configure.ac' for that package, +and checks a possibly existing 'configure.ac' for completeness. + + When using 'autoscan' to create a 'configure.ac', you should manually +examine 'configure.scan' before renaming it to 'configure.ac'; it will +probably need some adjustments. Occasionally, 'autoscan' outputs a +macro in the wrong order relative to another macro, so that 'autoconf' +produces a warning; you need to move such macros manually. Also, if you +want the package to use a configuration header file, you must add a call +to 'AC_CONFIG_HEADERS' (*note Configuration Headers::). You might also +have to change or add some '#if' directives to your program in order to +make it work with Autoconf (*note ifnames Invocation::, for information +about a program that can help with that job). + + When using 'autoscan' to maintain a 'configure.ac', simply consider +adding its suggestions. The file 'autoscan.log' will contain detailed +information on why a macro is requested. + + 'autoscan' uses several data files (installed along with Autoconf) to +determine which macros to output when it finds particular symbols in a +package's source files. These data files all have the same format: each +line consists of a symbol, whitespace, and the Autoconf macro to output +if that symbol is encountered. Lines starting with '#' are comments. + + 'autoscan' is only installed if you already have Perl installed. +'autoscan' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Print the names of the files it examines and the potentially + interesting symbols it finds in them. This output can be + voluminous. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the '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. + + +File: autoconf.info, Node: ifnames Invocation, Next: autoconf Invocation, Prev: autoscan Invocation, Up: Making configure Scripts + +3.3 Using 'ifnames' to List Conditionals +======================================== + +'ifnames' can help you write 'configure.ac' for a software package. It +prints the identifiers that the package already uses in C preprocessor +conditionals. If a package has already been set up to have some +portability, 'ifnames' can thus help you figure out what its 'configure' +needs to check for. It may help fill in some gaps in a 'configure.ac' +generated by 'autoscan' (*note autoscan Invocation::). + + 'ifnames' scans all of the C source files named on the command line +(or the standard input, if none are given) and writes to the standard +output a sorted list of all the identifiers that appear in those files +in '#if', '#elif', '#ifdef', or '#ifndef' directives. It prints each +identifier on a line, followed by a space-separated list of the files in +which that identifier occurs. + +'ifnames' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + + +File: autoconf.info, Node: autoconf Invocation, Next: autoreconf Invocation, Prev: ifnames Invocation, Up: Making configure Scripts + +3.4 Using 'autoconf' to Create 'configure' +========================================== + +To create 'configure' from 'configure.ac', run the 'autoconf' program +with no arguments. 'autoconf' processes 'configure.ac' with the 'm4' +macro processor, using the Autoconf macros. If you give 'autoconf' an +argument, it reads that file instead of 'configure.ac' and writes the +configuration script to the standard output instead of to 'configure'. +If you give 'autoconf' the argument '-', it reads from the standard +input instead of 'configure.ac' and writes the configuration script to +the standard output. + + The Autoconf macros are defined in several files. Some of the files +are distributed with Autoconf; 'autoconf' reads them first. Then it +looks for the optional file 'acsite.m4' in the directory that contains +the distributed Autoconf macro files, and for the optional file +'aclocal.m4' in the current directory. Those files can contain your +site's or the package's own Autoconf macro definitions (*note Writing +Autoconf Macros::, for more information). If a macro is defined in more +than one of the files that 'autoconf' reads, the last definition it +reads overrides the earlier ones. + + 'autoconf' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Report processing steps. + +'--debug' +'-d' + Don't remove the temporary files. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the '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. + +'--localdir=DIR' +'-l DIR' + Look for the package file 'aclocal.m4' in directory DIR instead of + in the current directory. + +'--output=FILE' +'-o FILE' + Save output (script or trace) to FILE. The file '-' stands for the + standard output. + +'--warnings=CATEGORY' +'-W CATEGORY' + Report the warnings related to CATEGORY (which can actually be a + comma separated list). *Note Reporting Messages::, macro + 'AC_DIAGNOSE', for a comprehensive list of categories. Special + values include: + + 'all' + report all the warnings + + 'none' + report none + + 'error' + treats warnings as errors + + 'no-CATEGORY' + disable warnings falling into CATEGORY + + Warnings about 'syntax' are enabled by default, and the environment + variable 'WARNINGS', a comma separated list of categories, is + honored. 'autoconf -W CATEGORY' will actually behave as if you had + run: + + autoconf --warnings=syntax,$WARNINGS,CATEGORY + + If you want to disable 'autoconf''s defaults and 'WARNINGS', but + (for example) enable the warnings about obsolete constructs, you + would use '-W none,obsolete'. + + 'autoconf' displays a back trace for errors, but not for warnings; + if you want them, just pass '-W error'. For instance, on this + 'configure.ac': + + AC_DEFUN([INNER], + [AC_TRY_RUN([true])]) + + AC_DEFUN([OUTER], + [INNER]) + + AC_INIT + OUTER + + you get: + + $ 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 + +'--trace=MACRO[:FORMAT]' +'-t MACRO[:FORMAT]' + Do not create the 'configure' script, but list the calls to MACRO + according to the FORMAT. Multiple '--trace' arguments can be used + to list several macros. Multiple '--trace' arguments for a single + macro are not cumulative; instead, you should just make FORMAT as + long as needed. + + The FORMAT is a regular string, with newlines if desired, and + several special escape codes. It defaults to '$f:$l:$n:$%'; see + below for details on the FORMAT. + +'--initialization' +'-i' + By default, '--trace' does not trace the initialization of the + Autoconf macros (typically the 'AC_DEFUN' definitions). This + results in a noticeable speedup, but can be disabled by this + option. + + It is often necessary to check the content of a 'configure.ac' file, +but parsing it yourself is extremely fragile and error-prone. It is +suggested that you rely upon '--trace' to scan 'configure.ac'. + + The FORMAT of '--trace' can use the following special escapes: + +'$$' + The character '$'. + +'$f' + The filename from which MACRO is called. + +'$l' + The line number from which MACRO is called. + +'$d' + The depth of the MACRO call. This is an M4 technical detail that + you probably don't want to know about. + +'$n' + The name of the MACRO. + +'$NUM' + The NUMth argument of the call to MACRO. + +'$@' +'$SEP@' +'${SEPARATOR}@' + All the arguments passed to MACRO, separated by the character SEP + or the string SEPARATOR (',' by default). Each argument is quoted, + i.e. enclosed in a pair of square brackets. + +'$*' +'$SEP*' +'${SEPARATOR}*' + As above, but the arguments are not quoted. + +'$%' +'$SEP%' +'${SEPARATOR}%' + As above, but the arguments are not quoted, all new line characters + in the arguments are smashed, and the default separator is ':'. + + The escape '$%' produces single-line trace outputs (unless you put + newlines in the 'separator'), while '$@' and '$*' do not. + + For instance, to find the list of variables that are substituted, +use: + + $ autoconf -t AC_SUBST + configure.ac:2:AC_SUBST:ECHO_C + configure.ac:2:AC_SUBST:ECHO_N + configure.ac:2:AC_SUBST:ECHO_T + More traces deleted + +The example below highlights the difference between '$@', '$*', and +*$%*. + + $ cat configure.ac + AC_DEFINE(This, is, [an + [example]]) + $ autoconf -t 'AC_DEFINE:@: $@ + *: $* + $: $%' + @: [This],[is],[an + [example]] + *: This,is,an + [example] + $: This:is:an [example] + +The FORMAT gives you a lot of freedom: + + $ autoconf -t 'AC_SUBST:$$ac_subst{"$1"} = "$f:$l";' + $ac_subst{"ECHO_C"} = "configure.ac:2"; + $ac_subst{"ECHO_N"} = "configure.ac:2"; + $ac_subst{"ECHO_T"} = "configure.ac:2"; + More traces deleted + +A long SEPARATOR can be used to improve the readability of complex +structures, and to ease its parsing (for instance when no single +character is suitable as a separator)): + + $ autoconf -t 'AM_MISSING_PROG:${|:::::|}*' + AUTOCONF|:::::|autoconf|:::::|$missing_dir + More traces deleted + + +File: autoconf.info, Node: autoreconf Invocation, Prev: autoconf Invocation, Up: Making configure Scripts + +3.5 Using 'autoreconf' to Update 'configure' Scripts +==================================================== + +If you have a lot of Autoconf-generated 'configure' scripts, the +'autoreconf' program can save you some work. It runs 'autoconf' (and +'autoheader', where appropriate) repeatedly to remake the Autoconf +'configure' scripts and configuration header templates in the directory +tree rooted at the current directory. By default, it only remakes those +files that are older than their 'configure.ac' or (if present) +'aclocal.m4'. Since 'autoheader' does not change the timestamp of its +output file if the file wouldn't be changing, this is not necessarily +the minimum amount of work. If you install a new version of Autoconf, +you can make 'autoreconf' remake _all_ of the files by giving it the +'--force' option. + + If you give 'autoreconf' the '--autoconf-dir=DIR' or '--localdir=DIR' +options, it passes them down to 'autoconf' and 'autoheader' (with +relative paths adjusted properly). + + 'autoreconf' does not support having, in the same directory tree, +both directories that are parts of a larger package (sharing +'aclocal.m4' and 'acconfig.h') and directories that are independent +packages (each with their own 'aclocal.m4' and 'acconfig.h'). It +assumes that they are all part of the same package if you use +'--localdir', or that each directory is a separate package if you don't +use it. This restriction may be removed in the future. + + *Note Automatic Remaking::, for 'Makefile' rules to automatically +remake 'configure' scripts when their source files change. That method +handles the timestamps of configuration header templates properly, but +does not pass '--autoconf-dir=DIR' or '--localdir=DIR'. + +'autoreconf' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' + Print the name of each directory where 'autoreconf' runs 'autoconf' + (and 'autoheader', if appropriate). + +'--debug' +'-d' + Don't remove the temporary files. + +'--force' +'-f' + Remake even 'configure' scripts and configuration headers that are + newer than their input files ('configure.ac' and, if present, + 'aclocal.m4'). + +'--install' +'-i' + Copy missing auxiliary files. This option is similar to the option + '--add-missing' in other tools. + +'--symlink' +'-s' + Instead of copying missing auxiliary files, install symbolic links. + +'--localdir=DIR' +'-l DIR' + Have 'autoconf' and 'autoheader' look for the package files + 'aclocal.m4' and ('autoheader' only) 'acconfig.h' (but not + 'FILE.top' and 'FILE.bot') in directory DIR instead of in the + directory containing each 'configure.ac'. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the '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. + +'--m4dir=DIR' +'-M DIR' + Specify location of additional macro files ('m4' by default). + + +File: autoconf.info, Node: Setup, Next: Existing Tests, Prev: Making configure Scripts, Up: Top + +4 Initialization and Output Files +********************************* + +Autoconf-generated 'configure' scripts need some information about how +to initialize, such as how to find the package's source files; and about +the output files to produce. The following sections describe +initialization and the creation of output files. + +* Menu: + +* Notices:: Copyright, version numbers in '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 '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 + + +File: autoconf.info, Node: Notices, Next: Input, Prev: Setup, Up: Setup + +4.1 Notices in 'configure' +========================== + +The following macros manage version numbers for 'configure' scripts. +Using them is optional. + + -- Macro: AC_PREREQ (VERSION) + Ensure that a recent enough version of Autoconf is being used. If + the version of Autoconf being used to create 'configure' is earlier + than VERSION, print an error message to the standard error output + and do not create 'configure'. For example: + + AC_PREREQ(2.52.20231210) + + This macro is the only macro that may be used before 'AC_INIT', but + for consistency, you are invited not to do so. + + -- Macro: AC_COPYRIGHT (COPYRIGHT-NOTICE) + State that, in addition to the Free Software Foundation's copyright + on the Autoconf macros, parts of your 'configure' are covered by + the COPYRIGHT-NOTICE. + + The COPYRIGHT-NOTICE will show up in both the head of 'configure' + and in 'configure --version'. + + -- Macro: AC_REVISION (REVISION-INFO) + Copy revision stamp REVISION-INFO into the 'configure' script, with + any dollar signs or double-quotes removed. This macro lets you put + a revision stamp from 'configure.ac' into 'configure' without RCS + or 'cvs' changing it when you check in 'configure'. That way, you + can determine easily which revision of 'configure.ac' a particular + 'configure' corresponds to. + + For example, this line in 'configure.ac': + + AC_REVISION($Revision: 1.77 $) + + produces this in 'configure': + + #! /bin/sh + # From configure.ac Revision: 1.30 + + +File: autoconf.info, Node: Input, Next: Output, Prev: Notices, Up: Setup + +4.2 Finding 'configure' Input +============================= + +Every 'configure' script must call 'AC_INIT' before doing anything else. +The only other required macro is 'AC_OUTPUT' (*note Output::). + + -- Macro: AC_INIT (PACKAGE, VERSION, [BUG-REPORT-ADDRESS]) + Process any command-line arguments and perform various + initializations and verifications. Set the name of the PACKAGE and + its VERSION. The optional argument BUG-REPORT-ADDRESS should be + the email to which users should send bug reports. + + -- Macro: AC_CONFIG_SRCDIR (UNIQUE-FILE-IN-SOURCE-DIR) + UNIQUE-FILE-IN-SOURCE-DIR is some file that is in the package's + source directory; 'configure' checks for this file's existence to + make sure that the directory that it is told contains the source + code in fact does. Occasionally people accidentally specify the + wrong directory with '--srcdir'; this is a safety check. *Note + configure Invocation::, for more information. + + Packages that do manual configuration or use the 'install' program +might need to tell 'configure' where to find some other shell scripts by +calling 'AC_CONFIG_AUX_DIR', though the default places it looks are +correct for most cases. + + -- Macro: AC_CONFIG_AUX_DIR (DIR) + Use the auxiliary build tools (e.g., 'install-sh', 'config.sub', + 'config.guess', Cygnus 'configure', Automake and Libtool scripts + etc.) that are in directory DIR. These are auxiliary files used + in configuration. DIR can be either absolute or relative to + 'SRCDIR'. The default is 'SRCDIR' or 'SRCDIR/..' or + 'SRCDIR/../..', whichever is the first that contains 'install-sh'. + The other files are not checked for, so that using + 'AC_PROG_INSTALL' does not automatically require distributing the + other auxiliary files. It checks for 'install.sh' also, but that + name is obsolete because some 'make' have a rule that creates + 'install' from it if there is no 'Makefile'. + + +File: autoconf.info, Node: Output, Next: Configuration Actions, Prev: Input, Up: Setup + +4.3 Outputting Files +==================== + +Every Autoconf-generated 'configure' script must finish by calling +'AC_OUTPUT'. It is the macro that generates 'config.status', which will +create the 'Makefile's and any other files resulting from configuration. +The only other required macro is 'AC_INIT' (*note Input::). + + -- Macro: AC_OUTPUT + Generate 'config.status' and launch it. Call this macro once, at + the end of 'configure.ac'. + + 'config.status' will take all the configuration actions: all the + output files (see *note Configuration Files::, macro + 'AC_CONFIG_FILES'), header files (see *note Configuration + Headers::, macro 'AC_CONFIG_HEADERS'), commands (see *note + Configuration Commands::, macro 'AC_CONFIG_COMMANDS'), links (see + *note Configuration Links::, macro 'AC_CONFIG_LINKS'), + subdirectories to configure (see *note Subdirectories::, macro + 'AC_CONFIG_SUBDIRS') are honored. + + Historically, the usage of 'AC_OUTPUT' was somewhat different. *Note +Obsolete Macros::, for a description of the arguments that 'AC_OUTPUT' +used to support. + + If you run 'make' on subdirectories, you should run it using the +'make' variable 'MAKE'. Most versions of 'make' set 'MAKE' to the name +of the 'make' program plus any options it was given. (But many do not +include in it the values of any variables set on the command line, so +those are not passed on automatically.) Some old versions of 'make' do +not set this variable. The following macro allows you to use it even +with those versions. + + -- Macro: AC_PROG_MAKE_SET + If 'make' predefines the variable 'MAKE', define output variable + 'SET_MAKE' to be empty. Otherwise, define 'SET_MAKE' to contain + 'MAKE=make'. Calls 'AC_SUBST' for 'SET_MAKE'. + + To use this macro, place a line like this in each 'Makefile.in' that +runs 'MAKE' on other directories: + + @SET_MAKE@ + + +File: autoconf.info, Node: Configuration Actions, Next: Configuration Files, Prev: Output, Up: Setup + +4.4 Taking Configuration Actions +================================ + +'configure' is designed so that it appears to do everything itself, but +there is actually a hidden slave: 'config.status'. 'configure' is in +charge of examining your system, but it is 'config.status' that actually +takes the proper actions based on the results of 'configure'. The most +typical task of 'config.status' is to _instantiate_ files. + + This section describes the common behavior of the four standard +instantiating macros: 'AC_CONFIG_FILES', 'AC_CONFIG_HEADERS', +'AC_CONFIG_COMMANDS' and 'AC_CONFIG_LINKS'. They all have this +prototype: + + AC_CONFIG_FOOS(TAG..., [COMMANDS], [INIT-CMDS]) + +where the arguments are: + +TAG... + A whitespace-separated list of tags, which are typically the names + of the files to instantiate. + +COMMANDS + Shell commands output literally into 'config.status', and + associated with a tag that the user can use to tell 'config.status' + which the commands to run. The commands are run each time a TAG + request is given to 'config.status'; typically, each time the file + 'TAG' is created. + +INIT-CMDS + Shell commands output _unquoted_ near the beginning of + 'config.status', and executed each time 'config.status' runs + (regardless of the tag). Because they are unquoted, for example, + '$var' will be output as the value of 'var'. INIT-CMDS is + typically used by 'configure' to give 'config.status' some + variables it needs to run the COMMANDS. + + All these macros can be called multiple times, with different TAGs, +of course! + + You are encouraged to use literals as TAGS. In particular, you +should avoid + + ... && my_foos="$my_foos fooo" + ... && my_foos="$my_foos foooo" + AC_CONFIG_FOOS($my_foos) + +and use this instead: + + ... && AC_CONFIG_FOOS(fooo) + ... && AC_CONFIG_FOOS(foooo) + + The macro 'AC_CONFIG_FILES' and 'AC_CONFIG_HEADERS' use specials +TAGs: they may have the form 'OUTPUT' or 'OUTPUT:INPUTS'. The file +OUTPUT is instantiated from its templates, INPUTS if specified, +defaulting to 'OUTPUT.in'. + + For instance 'AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk)' +asks for the creation of 'Makefile' that will be the expansion of the +output variables in the concatenation of 'boiler/top.mk' and +'boiler/bot.mk'. + + The special value '-' might be used to denote the standard output +when used in OUTPUT, or the standard input when used in the INPUTS. You +most probably don't need to use this in 'configure.ac', but it is +convenient when using the command line interface of './config.status', +see *note config.status Invocation::, for more details. + + The INPUTS may be absolute or relative filenames. In the latter case +they are first looked for in the build tree, and then in the source +tree. + + +File: autoconf.info, Node: Configuration Files, Next: Makefile Substitutions, Prev: Configuration Actions, Up: Setup + +4.5 Creating Configuration Files +================================ + +Be sure to read the previous section, *note Configuration Actions::. + + -- Macro: AC_CONFIG_FILES (FILE..., [CMDS], [INIT-CMDS]) + Make 'AC_OUTPUT' create each 'FILE' by copying an input file (by + default 'FILE.in'), substituting the output variable values. This + macro is one of the instantiating macros, see *note Configuration + Actions::. *Note Makefile Substitutions::, for more information on + using output variables. *Note Setting Output Variables::, for more + information on creating them. This macro creates the directory + that the file is in if it doesn't exist. Usually, 'Makefile's are + created this way, but other files, such as '.gdbinit', can be + specified as well. + + Typical calls to 'AC_CONFIG_FILES' look like this: + + AC_CONFIG_FILES(Makefile src/Makefile man/Makefile X/Imakefile) + AC_CONFIG_FILES(autoconf, chmod +x autoconf) + + You can override an input file name by appending to FILE a + colon-separated list of input files. Examples: + + AC_CONFIG_FILES(Makefile:boiler/top.mk:boiler/bot.mk + lib/Makefile:boiler/lib.mk) + + Doing this allows you to keep your file names acceptable to MS-DOS, + or to prepend and/or append boilerplate to the file. + + +File: autoconf.info, Node: Makefile Substitutions, Next: Configuration Headers, Prev: Configuration Files, Up: Setup + +4.6 Substitutions in Makefiles +============================== + +Each subdirectory in a distribution that contains something to be +compiled or installed should come with a file 'Makefile.in', from which +'configure' will create a 'Makefile' in that directory. To create a +'Makefile', 'configure' performs a simple variable substitution, +replacing occurrences of '@VARIABLE@' in 'Makefile.in' with the value +that 'configure' has determined for that variable. Variables that are +substituted into output files in this way are called "output variables". +They are ordinary shell variables that are set in 'configure'. To make +'configure' substitute a particular variable into the output files, the +macro 'AC_SUBST' must be called with that variable name as an argument. +Any occurrences of '@VARIABLE@' for other variables are left unchanged. +*Note Setting Output Variables::, for more information on creating +output variables with 'AC_SUBST'. + + A software package that uses a 'configure' script should be +distributed with a file 'Makefile.in', but no 'Makefile'; that way, the +user has to properly configure the package for the local system before +compiling it. + + *Note Makefile Conventions: (standards)Makefile Conventions, for more +information on what to put in '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 + + +File: autoconf.info, Node: Preset Output Variables, Next: Installation Directory Variables, Prev: Makefile Substitutions, Up: Makefile Substitutions + +4.6.1 Preset Output Variables +----------------------------- + +Some output variables are preset by the Autoconf macros. Some of the +Autoconf macros set additional output variables, which are mentioned in +the descriptions for those macros. *Note Output Variable Index::, for a +complete list of output variables. *Note Installation Directory +Variables::, for the list of the preset ones related to installation +directories. Below are listed the other preset ones. They all are +precious variables (*note Setting Output Variables::, 'AC_ARG_VAR'). + + -- Variable: CFLAGS + Debugging and optimization options for the C compiler. If it is + not set in the environment when 'configure' runs, the default value + is set when you call 'AC_PROG_CC' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + C features. + + -- Variable: configure_input + A comment saying that the file was generated automatically by + 'configure' and giving the name of the input file. 'AC_OUTPUT' + adds a comment line containing this variable to the top of every + 'Makefile' it creates. For other files, you should reference this + variable in a comment at the top of each input file. For example, + an input shell script should begin like this: + + #! /bin/sh + # @configure_input@ + + The presence of that line also reminds people editing the file that + it needs to be processed by 'configure' in order to be used. + + -- Variable: CPPFLAGS + Header file search directory ('-IDIR') and any other miscellaneous + options for the C and C++ preprocessors and compilers. If it is + not set in the environment when 'configure' runs, the default value + is empty. 'configure' uses this variable when compiling or + preprocessing programs to test for C and C++ features. + + -- Variable: CXXFLAGS + Debugging and optimization options for the C++ compiler. If it is + not set in the environment when 'configure' runs, the default value + is set when you call 'AC_PROG_CXX' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + C++ features. + + -- Variable: DEFS + '-D' options to pass to the C compiler. If 'AC_CONFIG_HEADERS' is + called, 'configure' replaces '@DEFS@' with '-DHAVE_CONFIG_H' + instead (*note Configuration Headers::). This variable is not + defined while 'configure' is performing its tests, only when + creating the output files. *Note Setting Output Variables::, for + how to check the results of previous tests. + + -- Variable: ECHO_C + -- Variable: ECHO_N + -- Variable: ECHO_T + How does one suppress the trailing newline from 'echo' for + question-answer message pairs? These variables provide a way: + + echo $ECHO_N "And the winner is... $ECHO_C" + sleep 100000000000 + echo "${ECHO_T}dead." + + Some old and uncommon 'echo' implementations offer no means to + achieve this, in which case 'ECHO_T' is set to tab. You might not + want to use it. + + -- Variable: FFLAGS + Debugging and optimization options for the Fortran 77 compiler. If + it is not set in the environment when 'configure' runs, the default + value is set when you call 'AC_PROG_F77' (or empty if you don't). + 'configure' uses this variable when compiling programs to test for + Fortran 77 features. + + -- Variable: LDFLAGS + Stripping ('-s'), path ('-L'), and any other miscellaneous options + for the linker. Don't use this variable to pass library names + ('-l') to the linker, use 'LIBS' instead. If it is not set in the + environment when 'configure' runs, the default value is empty. + 'configure' uses this variable when linking programs to test for C, + C++ and Fortran 77 features. + + -- Variable: LIBS + '-l' options to pass to the linker. The default value is empty, + but some Autoconf macros may prepend extra libraries to this + variable if those libraries are found and provide necessary + functions, see *note Libraries::. 'configure' uses this variable + when linking programs to test for C, C++ and Fortran 77 features. + + -- Variable: srcdir + The directory that contains the source code for that 'Makefile'. + + -- Variable: top_srcdir + The top-level source code directory for the package. In the + top-level directory, this is the same as 'srcdir'. + + +File: autoconf.info, Node: Installation Directory Variables, Next: Build Directories, Prev: Preset Output Variables, Up: Makefile Substitutions + +4.6.2 Installation Directory Variables +-------------------------------------- + +The following variables specify the directories where the package will +be installed, see *note Variables for Installation Directories: +(standards)Directory Variables, for more information. See the end of +this section for details on when and how to use these variables. + + -- Variable: bindir + The directory for installing executables that users run. + + -- Variable: datadir + The directory for installing read-only architecture-independent + data. + + -- Variable: exec_prefix + The installation prefix for architecture-dependent files. By + default it's the same as PREFIX. You should avoid installing + anything directly to EXEC_PREFIX. However, the default value for + directories containing architecture-dependent files should be + relative to EXEC_PREFIX. + + -- Variable: includedir + The directory for installing C header files. + + -- Variable: infodir + The directory for installing documentation in Info format. + + -- Variable: libdir + The directory for installing object code libraries. + + -- Variable: libexecdir + The directory for installing executables that other programs run. + + -- Variable: localstatedir + The directory for installing modifiable single-machine data. + + -- Variable: mandir + The top-level directory for installing documentation in man format. + + -- Variable: oldincludedir + The directory for installing C header files for non-gcc compilers. + + -- Variable: prefix + The common installation prefix for all files. If EXEC_PREFIX is + defined to a different value, PREFIX is used only for + architecture-independent files. + + -- Variable: sbindir + The directory for installing executables that system administrators + run. + + -- Variable: sharedstatedir + The directory for installing modifiable architecture-independent + data. + + -- Variable: sysconfdir + The directory for installing read-only single-machine data. + + Most of these variables have values that rely on 'prefix' or +'exec_prefix'. It is on purpose that the directory output variables +keep them unexpanded: typically '@datadir@' will be replaced by +'${prefix}/share', not '/usr/local/share'. + + This behavior is mandated by the GNU coding standards, so that when +the user runs: + +'make' + she can still specify a different prefix from the one specified to + 'configure', in which case, if needed, the package shall hard code + dependencies to her late desires. + +'make install' + she can specify a different installation location, in which case + the package _must_ still depend on the location which was compiled + in (i.e., never recompile when 'make install' is run). This is an + extremely important feature, as many people may decide to install + all the files of a package grouped together, and then install links + from the final locations to there. + + In order to support these features, it is essential that 'datadir' +remains being defined as '${prefix}/share' to depend upon the current +value of 'prefix'. + + A corollary is that you should not use these variables but in +Makefiles. For instance, instead of trying to evaluate 'datadir' in +'configure' and hardcoding it in Makefiles using e.g. +'AC_DEFINE_UNQUOTED(DATADIR, "$datadir")', you should add +'-DDATADIR="$(datadir)"' to your 'CPPFLAGS'. + + Similarly you should not rely on 'AC_OUTPUT_FILES' to replace +'datadir' and friends in your shell scripts and other files, rather let +'make' manage their replacement. For instance Autoconf ships templates +of its shell scripts ending with '.sh', and uses this Makefile snippet: + + .sh: + rm -f $@ $@.tmp + sed 's,@datadir\@,$(pkgdatadir),g' $< >$@.tmp + chmod +x $@.tmp + mv $@.tmp $@ + + Three things are noteworthy: + +'@datadir\@' + The backslash prevents 'configure' from replacing '@datadir@' in + the sed expression itself. + +'$(pkgdatadir)' + Don't use '@pkgdatadir@'! Use the matching makefile variable + instead. + +',' + Don't use '/' in the sed expression(s) since most probably the + variables you use, such as '$(pkgdatadir)', will contain some. + + +File: autoconf.info, Node: Build Directories, Next: Automatic Remaking, Prev: Installation Directory Variables, Up: Makefile Substitutions + +4.6.3 Build Directories +----------------------- + +You can support compiling a software package for several architectures +simultaneously from the same copy of the source code. The object files +for each architecture are kept in their own directory. + + To support doing this, 'make' uses the 'VPATH' variable to find the +files that are in the source directory. GNU 'make' and most other +recent 'make' programs can do this. Older 'make' programs do not +support 'VPATH'; when using them, the source code must be in the same +directory as the object files. + + To support 'VPATH', each 'Makefile.in' should contain two lines that +look like: + + srcdir = @srcdir@ + VPATH = @srcdir@ + + Do not set 'VPATH' to the value of another variable, for example +'VPATH = $(srcdir)', because some versions of 'make' do not do variable +substitutions on the value of 'VPATH'. + + 'configure' substitutes in the correct value for 'srcdir' when it +produces 'Makefile'. + + Do not use the 'make' variable '$<', which expands to the file name +of the file in the source directory (found with 'VPATH'), except in +implicit rules. (An implicit rule is one such as '.c.o', which tells +how to create a '.o' file from a '.c' file.) Some versions of 'make' do +not set '$<' in explicit rules; they expand it to an empty value. + + Instead, 'Makefile' command lines should always refer to source files +by prefixing them with '$(srcdir)/'. For example: + + time.info: time.texinfo + $(MAKEINFO) $(srcdir)/time.texinfo + + +File: autoconf.info, Node: Automatic Remaking, Prev: Build Directories, Up: Makefile Substitutions + +4.6.4 Automatic Remaking +------------------------ + +You can put rules like the following in the top-level 'Makefile.in' for +a package to automatically update the configuration information when you +change the configuration files. This example includes all of the +optional files, such as 'aclocal.m4' and those related to configuration +header files. Omit from the 'Makefile.in' rules for any of these files +that your package does not use. + + The '$(srcdir)/' prefix is included because of limitations in the +'VPATH' mechanism. + + The 'stamp-' files are necessary because the timestamps of +'config.h.in' and 'config.h' will not be changed if remaking them does +not change their contents. This feature avoids unnecessary +recompilation. You should include the file 'stamp-h.in' your package's +distribution, so 'make' will consider 'config.h.in' up to date. Don't +use 'touch' (*note Limitations of Usual Tools::), rather use 'echo' +(using 'date' would cause needless differences, hence CVS conflicts +etc.). + + $(srcdir)/configure: configure.ac aclocal.m4 + cd $(srcdir) && autoconf + + # autoheader might not change config.h.in, so touch a stamp file. + $(srcdir)/config.h.in: stamp-h.in + $(srcdir)/stamp-h.in: configure.ac aclocal.m4 + cd $(srcdir) && autoheader + echo timestamp > $(srcdir)/stamp-h.in + + config.h: stamp-h + stamp-h: config.h.in config.status + ./config.status + + Makefile: Makefile.in config.status + ./config.status + + config.status: configure + ./config.status --recheck + +(Be careful if you copy these lines directly into your Makefile, as you +will need to convert the indented lines to start with the tab +character.) + + In addition, you should use 'AC_CONFIG_FILES(stamp-h, echo timestamp +> stamp-h)' so 'config.status' will ensure that 'config.h' is considered +up to date. *Note Output::, for more information about 'AC_OUTPUT'. + + *Note config.status Invocation::, for more examples of handling +configuration-related dependencies. + + +File: autoconf.info, Node: Configuration Headers, Next: Configuration Commands, Prev: Makefile Substitutions, Up: Setup + +4.7 Configuration Header Files +============================== + +When a package tests more than a few C preprocessor symbols, the command +lines to pass '-D' options to the compiler can get quite long. This +causes two problems. One is that the 'make' output is hard to visually +scan for errors. More seriously, the command lines can exceed the +length limits of some operating systems. As an alternative to passing +'-D' options to the compiler, 'configure' scripts can create a C header +file containing '#define' directives. The 'AC_CONFIG_HEADERS' macro +selects this kind of output. It should be called right after 'AC_INIT'. + + The package should '#include' the configuration header file before +any other header files, to prevent inconsistencies in declarations (for +example, if it redefines 'const'). Use '#include <config.h>' instead of +'#include "config.h"', and pass the C compiler a '-I.' option (or +'-I..'; whichever directory contains 'config.h'). That way, even if the +source directory is configured itself (perhaps to make a distribution), +other build directories can also be configured without finding the +'config.h' from the source directory. + + -- Macro: AC_CONFIG_HEADERS (HEADER ..., [CMDS], [INIT-CMDS]) + This macro is one of the instantiating macros, see *note + Configuration Actions::. Make 'AC_OUTPUT' create the file(s) in + the whitespace-separated list HEADER containing C preprocessor + '#define' statements, and replace '@DEFS@' in generated files with + '-DHAVE_CONFIG_H' instead of the value of 'DEFS'. The usual name + for HEADER is 'config.h'. + + If HEADER already exists and its contents are identical to what + 'AC_OUTPUT' would put in it, it is left alone. Doing this allows + some changes in configuration without needlessly causing object + files that depend on the header file to be recompiled. + + Usually the input file is named 'HEADER.in'; however, you can + override the input file name by appending to HEADER, a + colon-separated list of input files. Examples: + + AC_CONFIG_HEADERS(config.h:config.hin) + AC_CONFIG_HEADERS(defines.h:defs.pre:defines.h.in:defs.post) + + Doing this allows you to keep your file names acceptable to MS-DOS, + or to prepend and/or append boilerplate to the file. + + *Note Configuration Actions::, for more details on HEADER. + +* Menu: + +* Header Templates:: Input for the configuration headers +* autoheader Invocation:: How to create configuration templates +* Autoheader Macros:: How to specify CPP templates + + +File: autoconf.info, Node: Header Templates, Next: autoheader Invocation, Prev: Configuration Headers, Up: Configuration Headers + +4.7.1 Configuration Header Templates +------------------------------------ + +Your distribution should contain a template file that looks as you want +the final header file to look, including comments, with '#undef' +statements which are used as hooks. For example, suppose your +'configure.ac' makes these calls: + + AC_CONFIG_HEADERS(conf.h) + AC_CHECK_HEADERS(unistd.h) + +Then you could have code like the following in 'conf.h.in'. On systems +that have 'unistd.h', 'configure' will '#define' 'HAVE_UNISTD_H' to 1. +On other systems, the whole line will be commented out (in case the +system predefines that symbol). + + /* Define as 1 if you have unistd.h. */ + #undef HAVE_UNISTD_H + + You can then decode the configuration header using the preprocessor +directives: + + #include <conf.h> + + #if HAVE_UNISTD_H + # include <unistd.h> + #else + /* We are in trouble. */ + #endif + + The use of old form templates, with '#define' instead of '#undef' is +strongly discouraged. + + Since it is a tedious task to keep a template header up to date, you +may use 'autoheader' to generate it, see *note autoheader Invocation::. + + +File: autoconf.info, Node: autoheader Invocation, Next: Autoheader Macros, Prev: Header Templates, Up: Configuration Headers + +4.7.2 Using 'autoheader' to Create 'config.h.in' +------------------------------------------------ + +The 'autoheader' program can create a template file of C '#define' +statements for 'configure' to use. If 'configure.ac' invokes +'AC_CONFIG_HEADERS(FILE)', 'autoheader' creates 'FILE.in'; if multiple +file arguments are given, the first one is used. Otherwise, +'autoheader' creates 'config.h.in'. + + In order to do its job, 'autoheader' needs you to document all of the +symbols that you might use; i.e., there must be at least one 'AC_DEFINE' +or one 'AC_DEFINE_UNQUOTED' using its third argument for each symbol +(*note Defining Symbols::). An additional constraint is that the first +argument of '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 'autoheader' is needed: after all, why would +'configure' need to "patch" a 'config.h.in' to produce a 'config.h' +instead of just creating 'config.h' from scratch? Well, when everything +rocks, the answer is just that we are wasting our time maintaining +'autoheader': generating 'config.h' directly is all that is needed. +When things go wrong, however, you'll be thankful for the existence of +'autoheader'. + + The fact that the symbols are documented is important in order to +_check_ that 'config.h' makes sense. The fact that there is a well +defined list of symbols that should be '#define''d (or not) is also +important for people who are porting packages to environments where +'configure' cannot be run: they just have to _fill in the blanks_. + + But let's come back to the point: 'autoheader''s invocation... + + If you give 'autoheader' an argument, it uses that file instead of +'configure.ac' and writes the header file to the standard output instead +of to 'config.h.in'. If you give 'autoheader' an argument of '-', it +reads the standard input instead of 'configure.ac' and writes the header +file to the standard output. + + 'autoheader' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--debug' +'-d' + Don't remove the temporary files. + +'--verbose' +'-v' + Report processing steps. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the '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. + +'--localdir=DIR' +'-l DIR' + Look for the package files 'aclocal.m4' and 'acconfig.h' (but not + 'FILE.top' and 'FILE.bot') in directory DIR instead of in the + current directory. + +'--warnings=CATEGORY' +'-W CATEGORY' + Report the warnings related to CATEGORY (which can actually be a + comma separated list). Current categories include: + + 'obsolete' + report the uses of obsolete constructs + + 'all' + report all the warnings + + 'none' + report none + + 'error' + treats warnings as errors + + 'no-CATEGORY' + disable warnings falling into CATEGORY + + +File: autoconf.info, Node: Autoheader Macros, Prev: autoheader Invocation, Up: Configuration Headers + +4.7.3 Autoheader Macros +----------------------- + +'autoheader' scans 'configure.ac' and figures out which C preprocessor +symbols it might define. It knows how to generate templates for symbols +defined by 'AC_CHECK_HEADERS', 'AC_CHECK_FUNCS' etc., but if you +'AC_DEFINE' any additional symbol, you must define a template for it. +If there are missing templates, 'autoheader' fails with an error +message. + + The simplest way to create a template for a SYMBOL is to supply the +DESCRIPTION argument to an 'AC_DEFINE(SYMBOL)'; see *note Defining +Symbols::. You may also use one of the following macros. + + -- Macro: AH_VERBATIM (KEY, TEMPLATE) + Tell 'autoheader' to include the TEMPLATE as-is in the header + template file. This TEMPLATE is associated with the KEY, which is + used to sort all the different templates and guarantee their + uniqueness. It should be the symbol that can be 'AC_DEFINE''d. + + For example: + + AH_VERBATIM([_GNU_SOURCE], + [/* Enable GNU extensions on systems that have them. */ + #ifndef _GNU_SOURCE + # define _GNU_SOURCE + #endif]) + + -- Macro: AH_TEMPLATE (KEY, DESCRIPTION) + Tell 'autoheader' to generate a template for KEY. This macro + generates standard templates just like 'AC_DEFINE' when a + DESCRIPTION is given. + + For example: + + AH_TEMPLATE([CRAY_STACKSEG_END], + [Define to one of _getb67, GETB67, getb67 + for Cray-2 and Cray-YMP systems. This + function is required for alloca.c support + on those systems.]) + + will generate the following template, with the description properly + justified. + + /* Define to one of _getb67, GETB67, getb67 for Cray-2 and + Cray-YMP systems. This function is required for alloca.c + support on those systems. */ + #undef CRAY_STACKSEG_END + + -- Macro: AH_TOP (TEXT) + Include TEXT at the top of the header template file. + + -- Macro: AH_BOTTOM (TEXT) + Include TEXT at the bottom of the header template file. + + +File: autoconf.info, Node: Configuration Commands, Next: Configuration Links, Prev: Configuration Headers, Up: Setup + +4.8 Running Arbitrary Configuration Commands +============================================ + +You execute arbitrary commands either before, during and after +'config.status' is run. The three following macros accumulate the +commands to run when they are called multiple times. +'AC_CONFIG_COMMANDS' replaces the obsolete macro 'AC_OUTPUT_COMMANDS', +see *note Obsolete Macros::, for details. + + -- Macro: AC_CONFIG_COMMANDS (TAG..., [CMDS], [INIT-CMDS]) + Specify additional shell commands to run at the end of + 'config.status', and shell commands to initialize any variables + from 'configure'. Associate the commands to the TAG. Since + typically the CMDS create a file, TAG should naturally be the name + of that file. This macro is one of the instantiating macros, see + *note Configuration Actions::. + + Here is an unrealistic example: + fubar=42 + AC_CONFIG_COMMANDS(fubar, + [echo this is extra $fubar, and so on.], + [fubar=$fubar]) + + Here is a better one: + AC_CONFIG_COMMANDS(time-stamp, [date >time-stamp]) + + -- Macro: AC_CONFIG_COMMANDS_PRE (CMDS) + Execute the CMDS right before creating 'config.status'. A typical + use is computing values derived from variables built during the + execution of 'configure': + + AC_CONFIG_COMMANDS_PRE( + [LTLIBOBJS=`echo $LIBOBJS | sed 's/\.o/\.lo/g'` + AC_SUBST(LTLIBOBJS)]) + + -- Macro: AC_CONFIG_COMMANDS_POST (CMDS) + Execute the CMDS right after creating 'config.status'. + + +File: autoconf.info, Node: Configuration Links, Next: Subdirectories, Prev: Configuration Commands, Up: Setup + +4.9 Creating Configuration Links +================================ + +You may find it convenient to create links whose destinations depend +upon results of tests. One can use 'AC_CONFIG_COMMANDS' but the +creation of relative symbolic links can be delicate when the package is +built in another directory than its sources. + + -- Macro: AC_CONFIG_LINKS (DEST:SOURCE..., [CMDS], [INIT-CMDS]) + Make 'AC_OUTPUT' link each of the existing files SOURCE to the + corresponding link name DEST. Makes a symbolic link if possible, + otherwise a hard link. The DEST and SOURCE names should be + relative to the top level source or build directory. This macro is + one of the instantiating macros, see *note Configuration Actions::. + + For example, this call: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + creates in the current directory 'host.h' as a link to + 'SRCDIR/config/$machine.h', and 'object.h' as a link to + 'SRCDIR/config/$obj_format.h'. + + The tempting value '.' for DEST is invalid: it makes it impossible + for 'config.status' to guess the links to establish. + + One can then run: + ./config.status host.h object.h + to create the links. + + +File: autoconf.info, Node: Subdirectories, Next: Default Prefix, Prev: Configuration Links, Up: Setup + +4.10 Configuring Other Packages in Subdirectories +================================================= + +In most situations, calling 'AC_OUTPUT' is sufficient to produce +'Makefile's in subdirectories. However, 'configure' scripts that +control more than one independent package can use 'AC_CONFIG_SUBDIRS' to +run 'configure' scripts for other packages in subdirectories. + + -- Macro: AC_CONFIG_SUBDIRS (DIR ...) + Make 'AC_OUTPUT' run 'configure' in each subdirectory DIR in the + given whitespace-separated list. Each DIR should be a literal, + i.e., please do not use: + + if test "$package_foo_enabled" = yes; then + $my_subdirs="$my_subdirs foo" + fi + AC_CONFIG_SUBDIRS($my_subdirs) + + because this prevents './configure --help=recursive' from + displaying the options of the package 'foo'. Rather, you should + write: + + if test "$package_foo_enabled" = yes then; + AC_CONFIG_SUBDIRS(foo) + fi + + If a given DIR is not found, no error is reported, so a 'configure' + script can configure whichever parts of a large source tree are + present. If a given DIR contains 'configure.gnu', it is run + instead of 'configure'. This is for packages that might use a + non-autoconf script 'Configure', which can't be called through a + wrapper 'configure' since it would be the same file on + case-insensitive filesystems. Likewise, if a DIR contains + 'configure.ac' but no 'configure', the Cygnus 'configure' script + found by 'AC_CONFIG_AUX_DIR' is used. + + The subdirectory 'configure' scripts are given the same command + line options that were given to this 'configure' script, with minor + changes if needed (e.g., to adjust a relative path for the cache + file or source directory). This macro also sets the output + variable 'subdirs' to the list of directories 'DIR ...'. + 'Makefile' rules can use this variable to determine which + subdirectories to recurse into. This macro may be called multiple + times. + + +File: autoconf.info, Node: Default Prefix, Prev: Subdirectories, Up: Setup + +4.11 Default Prefix +=================== + +By default, 'configure' sets the prefix for files it installs to +'/usr/local'. The user of 'configure' can select a different prefix +using the '--prefix' and '--exec-prefix' options. There are two ways to +change the default: when creating 'configure', and when running it. + + Some software packages might want to install in a directory besides +'/usr/local' by default. To accomplish that, use the +'AC_PREFIX_DEFAULT' macro. + + -- Macro: AC_PREFIX_DEFAULT (PREFIX) + Set the default installation prefix to PREFIX instead of + '/usr/local'. + + It may be convenient for users to have 'configure' guess the +installation prefix from the location of a related program that they +have already installed. If you wish to do that, you can call +'AC_PREFIX_PROGRAM'. + + -- Macro: AC_PREFIX_PROGRAM (PROGRAM) + If the user did not specify an installation prefix (using the + '--prefix' option), guess a value for it by looking for PROGRAM in + 'PATH', the way the shell does. If PROGRAM is found, set the + prefix to the parent of the directory containing PROGRAM; otherwise + leave the prefix specified in 'Makefile.in' unchanged. For + example, if PROGRAM is 'gcc' and the 'PATH' contains + '/usr/local/gnu/bin/gcc', set the prefix to '/usr/local/gnu'. + + +File: autoconf.info, Node: Existing Tests, Next: Writing Tests, Prev: Setup, Up: Top + +5 Existing Tests +**************** + +These macros test for particular system features that packages might +need or want to use. If you need to test for a kind of feature that +none of these macros check for, you can probably do it by calling +primitive test macros with appropriate arguments (*note Writing +Tests::). + + These tests print messages telling the user which feature they're +checking for, and what they find. They cache their results for future +'configure' runs (*note Caching Results::). + + Some of these macros set output variables. *Note Makefile +Substitutions::, for how to get their values. The phrase "define NAME" +is used below as a shorthand to mean "define C preprocessor symbol NAME +to the value 1". *Note 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 + + +File: autoconf.info, Node: Common Behavior, Next: Alternative Programs, Prev: Existing Tests, Up: Existing Tests + +5.1 Common Behavior +=================== + +Much effort has been expended to make Autoconf easy to learn. The most +obvious way to reach this goal is simply to enforce standard interfaces +and behaviors, avoiding exceptions as much as possible. Because of +history and inertia, unfortunately, there are still too many exceptions +in Autoconf; nevertheless, this section describes some of the common +rules. + +* Menu: + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + + +File: autoconf.info, Node: Standard Symbols, Next: Default Includes, Prev: Common Behavior, Up: Common Behavior + +5.1.1 Standard Symbols +---------------------- + +All the generic macros that 'AC_DEFINE' a symbol as a result of their +test transform their ARGUMENTs to a standard alphabet. First, ARGUMENT +is converted to upper case and any asterisks ('*') are each converted to +'P'. Any remaining characters that are not alphanumeric are converted +to underscores. + + For instance, + + AC_CHECK_TYPES(struct $Expensive*) + +will define the symbol 'HAVE_STRUCT__EXPENSIVEP' if the check succeeds. + + +File: autoconf.info, Node: Default Includes, Prev: Standard Symbols, Up: Common Behavior + +5.1.2 Default Includes +---------------------- + +Several tests depend upon a set of header files. Since these headers +are not universally available, tests actually have to provide a set of +protected includes, such as: + + #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 + +Unless you know exactly what you are doing, you should avoid using +unconditional includes, and check the existence of the headers you +include beforehand (*note Header Files::). + + Most generic macros provide the following default set of includes: + + #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 + + 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 'AC_HEADERS_STDC', nor check for 'stdlib.h' etc. + + These headers are checked for in the same order as they are included. +For instance, on some systems 'string.h' and 'strings.h' both exist, but +conflict. Then 'HAVE_STRING_H' will be defined, but 'HAVE_STRINGS_H' +won't. + + +File: autoconf.info, Node: Alternative Programs, Next: Files, Prev: Common Behavior, Up: Existing Tests + +5.2 Alternative Programs +======================== + +These macros check for the presence or behavior of particular programs. +They are used to choose between several alternative programs and to +decide what to do once one has been chosen. If there is no macro +specifically defined to check for a program you need, and you don't need +to check for any special properties of it, then you can use one of the +general program-check macros. + +* Menu: + +* Particular Programs:: Special handling to find certain programs +* Generic Programs:: How to find other programs + + +File: autoconf.info, Node: Particular Programs, Next: Generic Programs, Prev: Alternative Programs, Up: Alternative Programs + +5.2.1 Particular Program Checks +------------------------------- + +These macros check for particular programs--whether they exist, and in +some cases whether they support certain features. + + -- Macro: AC_PROG_AWK + Check for 'mawk', 'gawk', 'nawk', and 'awk', in that order, and set + output variable 'AWK' to the first one that is found. It tries + 'mawk' first because that is reported to be the fastest + implementation. + + -- Macro: AC_PROG_EGREP + Check for 'grep -E', 'egrep' in that order, and set output variable + 'EGREP' to the first one that is found. + + -- Macro: AC_PROG_FGREP + Check for 'grep -F', 'fgrep' in that order, and set output variable + 'FGREP' to the first one that is found. + + -- Macro: AC_PROG_GREP + Check for 'grep', 'ggrep' in that order, and set output variable + 'GREP' to the first one that is found. + + -- Macro: AC_PROG_INSTALL + Set output variable 'INSTALL' to the path of a BSD compatible + 'install' program, if one is found in the current 'PATH'. + Otherwise, set 'INSTALL' to 'DIR/install-sh -c', checking the + directories specified to 'AC_CONFIG_AUX_DIR' (or its default + directories) to determine DIR (*note Output::). Also set the + variables 'INSTALL_PROGRAM' and 'INSTALL_SCRIPT' to '${INSTALL}' + and 'INSTALL_DATA' to '${INSTALL} -m 644'. + + This macro screens out various instances of 'install' known not to + work. It prefers to find a C program rather than a shell script, + for speed. Instead of 'install-sh', it can also use 'install.sh', + but that name is obsolete because some 'make' programs have a rule + that creates 'install' from it if there is no 'Makefile'. + + Autoconf comes with a copy of 'install-sh' that you can use. If + you use 'AC_PROG_INSTALL', you must include either 'install-sh' or + 'install.sh' in your distribution, or 'configure' will produce an + error message saying it can't find them--even if the system you're + on has a good 'install' program. This check is a safety measure to + prevent you from accidentally leaving that file out, which would + prevent your package from installing on systems that don't have a + BSD-compatible 'install' program. + + If you need to use your own installation program because it has + features not found in standard 'install' programs, there is no + reason to use 'AC_PROG_INSTALL'; just put the file name of your + program into your 'Makefile.in' files. + + -- Macro: AC_PROG_LEX + If 'flex' is found, set output variable 'LEX' to 'flex' and + 'LEXLIB' to '-lfl', if that library is in a standard place. + Otherwise set 'LEX' to 'lex' and 'LEXLIB' to '-ll'. + + Define 'YYTEXT_POINTER' if 'yytext' is a 'char *' instead of a + 'char []'. Also set output variable 'LEX_OUTPUT_ROOT' to the base + of the file name that the lexer generates; usually 'lex.yy', but + sometimes something else. These results vary according to whether + 'lex' or 'flex' is being used. + + You are encouraged to use Flex in your sources, since it is both + more pleasant to use than plain Lex and the C source it produces is + portable. In order to ensure portability, however, you must either + provide a function 'yywrap' or, if you don't use it (e.g., your + scanner has no '#include'-like feature), simply include a + '%noyywrap' statement in the scanner's source. Once this done, the + scanner is portable (unless _you_ felt free to use nonportable + constructs) and does not depend on any library. In this case, and + in this case only, it is suggested that you use this Autoconf + snippet: + + AC_PROG_LEX + if test "$LEX" != flex; then + LEX="$SHELL $missing_dir/missing flex" + AC_SUBST(LEX_OUTPUT_ROOT, lex.yy) + AC_SUBST(LEXLIB, '') + fi + + The shell script 'missing' can be found in the Automake + distribution. + + To ensure backward compatibility, Automake's 'AM_PROG_LEX' invokes + (indirectly) this macro twice, which will cause an annoying but + benign "'AC_PROG_LEX' invoked multiple times" warning. Future + versions of Automake will fix this issue, meanwhile, just ignore + this message. + + -- Macro: AC_PROG_LN_S + If 'ln -s' works on the current file system (the operating system + and file system support symbolic links), set the output variable + 'LN_S' to 'ln -s'; otherwise, if 'ln' works, set 'LN_S' to 'ln' and + otherwise set it to 'cp -p'. + + If you make a link a directory other than the current directory, + its meaning depends on whether 'ln' or 'ln -s' is used. To safely + create links using '$(LN_S)', either find out which form is used + and adjust the arguments, or always invoke 'ln' in the directory + where the link is to be created. + + In other words, it does not work to do: + $(LN_S) foo /x/bar + + Instead, do: + + (cd /x && $(LN_S) foo bar) + + -- Macro: AC_PROG_RANLIB + Set output variable 'RANLIB' to 'ranlib' if 'ranlib' is found, and + otherwise to ':' (do nothing). + + -- Macro: AC_PROG_YACC + If 'byacc' is found, set 'YACC' to 'byacc'. Otherwise, if 'bison' + is found, set output variable 'YACC' to 'bison -y'. Finally, if + neither 'byacc' or 'bison' is found, set 'YACC' to 'yacc'. + + +File: autoconf.info, Node: Generic Programs, Prev: Particular Programs, Up: Alternative Programs + +5.2.2 Generic Program and File Checks +------------------------------------- + +These macros are used to find programs not covered by the "particular" +test macros. If you need to check the behavior of a program as well as +find out whether it is present, you have to write your own test for it +(*note Writing Tests::). By default, these macros use the environment +variable 'PATH'. If you need to check for a program that might not be +in the user's 'PATH', you can pass a modified path to use instead, like +this: + + AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, + $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) + + You are strongly encouraged to declare the VARIABLE passed to +'AC_CHECK_PROG' etc. as precious, *Note Setting Output Variables::, +'AC_ARG_VAR', for more details. + + -- Macro: AC_CHECK_PROG (VARIABLE, PROG-TO-CHECK-FOR, VALUE-IF-FOUND, + [VALUE-IF-NOT-FOUND], [PATH], [REJECT]) + Check whether program PROG-TO-CHECK-FOR exists in 'PATH'. If it is + found, set VARIABLE to VALUE-IF-FOUND, otherwise to + VALUE-IF-NOT-FOUND, if given. Always pass over REJECT (an absolute + file name) even if it is the first found in the search path; in + that case, set VARIABLE using the absolute file name of the + PROG-TO-CHECK-FOR found that is not REJECT. If VARIABLE was + already set, do nothing. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_CHECK_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Check for each program in the whitespace-separated list + PROGS-TO-CHECK-FOR exists on the 'PATH'. If it is found, set + VARIABLE to the name of that program. Otherwise, continue checking + the next program in the list. If none of the programs in the list + are found, set VARIABLE to VALUE-IF-NOT-FOUND; if + VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not + changed. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_CHECK_TOOL (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROG', but first looks for PROG-TO-CHECK-FOR with a + prefix of the host type as determined by 'AC_CANONICAL_HOST', + followed by a dash (*note Canonicalizing::). For example, if the + user runs 'configure --host=i386-gnu', then this call: + AC_CHECK_TOOL(RANLIB, ranlib, :) + sets 'RANLIB' to 'i386-gnu-ranlib' if that program exists in + 'PATH', or otherwise to 'ranlib' if that program exists in 'PATH', + or to ':' if neither program exists. + + -- Macro: AC_CHECK_TOOLS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_TOOL', each of the tools in the list + PROGS-TO-CHECK-FOR are checked with a prefix of the host type as + determined by 'AC_CANONICAL_HOST', followed by a dash (*note + Canonicalizing::). If none of the tools can be found with a + prefix, then the first one without a prefix is used. If a tool is + found, set VARIABLE to the name of that program. If none of the + tools in the list are found, set VARIABLE to VALUE-IF-NOT-FOUND; if + VALUE-IF-NOT-FOUND is not specified, the value of VARIABLE is not + changed. Calls 'AC_SUBST' for VARIABLE. + + -- Macro: AC_PATH_PROG (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROG', but set VARIABLE to the entire path of + PROG-TO-CHECK-FOR if found. + + -- Macro: AC_PATH_PROGS (VARIABLE, PROGS-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_PROGS', but if any of PROGS-TO-CHECK-FOR are found, + set VARIABLE to the entire path of the program found. + + -- Macro: AC_PATH_TOOL (VARIABLE, PROG-TO-CHECK-FOR, + [VALUE-IF-NOT-FOUND], [PATH]) + Like 'AC_CHECK_TOOL', but set VARIABLE to the entire path of the + program if it is found. + + +File: autoconf.info, Node: Files, Next: Libraries, Prev: Alternative Programs, Up: Existing Tests + +5.3 Files +========= + +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. + + -- Macro: AC_CHECK_FILE (FILE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Check whether file FILE exists on the native system. If it is + found, execute ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, + if given. + + -- Macro: AC_CHECK_FILES (FILES, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Executes 'AC_CHECK_FILE' once for each file listed in FILES. + Additionally, defines 'HAVE_FILE' (*note Standard Symbols::) for + each file found. + + +File: autoconf.info, Node: Libraries, Next: Library Functions, Prev: Files, Up: Existing Tests + +5.4 Library Files +================= + +The following macros check for the presence of certain C, C++ or Fortran +77 library archive files. + + -- Macro: AC_CHECK_LIB (LIBRARY, FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + Depending on the current language(*note Language Choice::), try to + ensure that the C, C++, or Fortran 77 function FUNCTION is + available by checking whether a test program can be linked with the + library LIBRARY to get the function. LIBRARY is the base name of + the library; e.g., to check for '-lmp', use 'mp' as the LIBRARY + argument. + + ACTION-IF-FOUND is a list of shell commands to run if the link with + the library succeeds; ACTION-IF-NOT-FOUND is a list of shell + commands to run if the link fails. If ACTION-IF-FOUND is not + specified, the default action will prepend '-lLIBRARY' to 'LIBS' + and define 'HAVE_LIBLIBRARY' (in all capitals). This macro is + intended to support building of '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 'LIBS' is generated is important to reliable + detection of libraries. + + If linking with LIBRARY results in unresolved symbols that would be + resolved by linking with additional libraries, give those libraries + as the OTHER-LIBRARIES argument, separated by spaces: e.g. '-lXt + -lX11'. Otherwise, this macro will fail to detect that LIBRARY is + present, because linking the test program will always fail with + unresolved symbols. The OTHER-LIBRARIES argument should be limited + to cases where it is desirable to test for one library in the + presence of another that is not already in 'LIBS'. + + -- Macro: AC_SEARCH_LIBS (FUNCTION, SEARCH-LIBS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + Search for a library defining FUNCTION if it's not already + available. This equates to calling 'AC_TRY_LINK_FUNC' first with + no libraries, then for each library listed in SEARCH-LIBS. + + Add '-lLIBRARY' to 'LIBS' for the first library found to contain + FUNCTION, and run ACTION-IF-FOUND. If the function is not found, + run ACTION-IF-NOT-FOUND. + + If linking with LIBRARY results in unresolved symbols that would be + resolved by linking with additional libraries, give those libraries + as the OTHER-LIBRARIES argument, separated by spaces: e.g. '-lXt + -lX11'. Otherwise, this macro will fail to detect that FUNCTION is + present, because linking the test program will always fail with + unresolved symbols. + + +File: autoconf.info, Node: Library Functions, Next: Header Files, Prev: Libraries, Up: Existing Tests + +5.5 Library Functions +===================== + +The following macros check for particular C library functions. If there +is no macro specifically defined to check for a function you need, and +you don't need to check for any special properties of it, then you can +use one of the general function-check macros. + +* Menu: + +* Function Portability:: Pitfalls with usual functions +* Particular Functions:: Special handling to find certain functions +* Generic Functions:: How to find other functions + + +File: autoconf.info, Node: Function Portability, Next: Particular Functions, Prev: Library Functions, Up: Library Functions + +5.5.1 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 + +'unlink' + The POSIX spec says that '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 '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. + + +File: autoconf.info, Node: Particular Functions, Next: Generic Functions, Prev: Function Portability, Up: Library Functions + +5.5.2 Particular Function Checks +-------------------------------- + +These macros check for particular C functions--whether they exist, and +in some cases how they respond when given certain arguments. + + -- Macro: AC_FUNC_ALLOCA + Check how to get 'alloca'. Tries to get a builtin version by + checking for 'alloca.h' or the predefined C preprocessor macros + '__GNUC__' and '_AIX'. If this macro finds 'alloca.h', it defines + '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 + 'HAVE_ALLOCA'. Otherwise, it sets the output variable 'ALLOCA' to + 'alloca.o' and defines 'C_ALLOCA' (so programs can periodically + call 'alloca(0)' to garbage collect). This variable is separate + from 'LIBOBJS' so multiple programs can share the value of 'ALLOCA' + without needing to create an actual library, in case only some of + them use the code in 'LIBOBJS'. + + This macro does not try to get 'alloca' from the System V R3 + 'libPW' or the System V R4 'libucb' because those libraries contain + some incompatible functions that cause trouble. Some versions do + not even contain 'alloca' or contain a buggy version. If you still + want to use their 'alloca', use 'ar' to extract 'alloca.o' from + them instead of compiling 'alloca.c'. + + Source files that use 'alloca' should start with a piece of code + like the following, to declare it properly. In some versions of + AIX, the declaration of 'alloca' must precede everything else + except for comments and preprocessor directives. The '#pragma' + directive is indented so that pre-ANSI C compilers will ignore it, + rather than choke on it. + + /* 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 + + -- Macro: AC_FUNC_CHOWN + If the 'chown' function is available and works (in particular, it + should accept '-1' for 'uid' and 'gid'), define 'HAVE_CHOWN'. + + -- Macro: AC_FUNC_CLOSEDIR_VOID + If the 'closedir' function does not return a meaningful value, + define 'CLOSEDIR_VOID'. Otherwise, callers ought to check its + return value for an error indicator. + + -- Macro: AC_FUNC_ERROR_AT_LINE + If the 'error_at_line' function is not found, require an + 'AC_LIBOBJ' replacement of 'error'. + + -- Macro: AC_FUNC_FNMATCH + If the 'fnmatch' function is available and works (unlike the one on + Solaris 2.4), define 'HAVE_FNMATCH'. + + -- Macro: AC_FUNC_FORK + This macro checks for the 'fork' and 'vfork' functions. If a + working 'fork' is found, define 'HAVE_WORKING_FORK'. This macro + checks whether 'fork' is just a stub by trying to run it. + + If 'vfork.h' is found, define 'HAVE_VFORK_H'. If a working 'vfork' + is found, define 'HAVE_WORKING_VFORK'. Otherwise, define 'vfork' + to be 'fork' for backward compatibility with previous versions of + 'autoconf'. This macro checks for several known errors in + implementations of 'vfork' and considers the system to not have a + working 'vfork' if it detects any of them. It is not considered to + be an implementation error if a child's invocation of 'signal' + modifies the parent's signal handler, since child processes rarely + change their signal handlers. + + Since this macro defines 'vfork' only for backward compatibility + with previous versions of 'autoconf' you're encouraged to define it + yourself in new code: + #if !HAVE_WORKING_VFORK + # define vfork fork + #endif + + -- Macro: AC_FUNC_FSEEKO + If the 'fseeko' function is available, define 'HAVE_FSEEKO'. + Define '_LARGEFILE_SOURCE' if necessary. + + -- Macro: AC_FUNC_GETGROUPS + If the 'getgroups' function is available and works (unlike on + Ultrix 4.3, where 'getgroups (0, 0)' always fails), define + 'HAVE_GETGROUPS'. Set 'GETGROUPS_LIBS' to any libraries needed to + get that function. This macro runs 'AC_TYPE_GETGROUPS'. + + -- Macro: AC_FUNC_GETLOADAVG + Check how to get the system load averages. If the system has the + 'getloadavg' function, define 'HAVE_GETLOADAVG', and set + 'GETLOADAVG_LIBS' to any libraries needed to get that function. + Also add 'GETLOADAVG_LIBS' to 'LIBS'. + + Otherwise, require an 'AC_LIBOBJ' replacement ('getloadavg.c') of + 'getloadavg', and possibly define several other C preprocessor + macros and output variables: + + 1. Define 'C_GETLOADAVG'. + + 2. Define 'SVR4', 'DGUX', 'UMAX', or 'UMAX4_3' if on those + systems. + + 3. If 'nlist.h' is found, define 'NLIST_STRUCT'. + + 4. If 'struct nlist' has an 'n_un.n_name' member, define + 'HAVE_STRUCT_NLIST_N_UN_N_NAME'. The obsolete symbol + 'NLIST_NAME_UNION' is still defined, but do not depend upon + it. + + 5. Programs may need to be installed setgid (or setuid) for + 'getloadavg' to work. In this case, define + 'GETLOADAVG_PRIVILEGED', set the output variable 'NEED_SETGID' + to 'true' (and otherwise to 'false'), and set 'KMEM_GROUP' to + the name of the group that should own the installed program. + + -- Macro: AC_FUNC_GETMNTENT + Check for 'getmntent' in the 'sun', 'seq', and 'gen' libraries, for + Irix 4, PTX, and Unixware, respectively. Then, if 'getmntent' is + available, define 'HAVE_GETMNTENT'. + + -- Macro: AC_FUNC_GETPGRP + If 'getpgrp' takes no argument (the POSIX.1 version), define + 'GETPGRP_VOID'. Otherwise, it is the BSD version, which takes a + process ID as an argument. This macro does not check whether + 'getpgrp' exists at all; if you need to work in that situation, + first call 'AC_CHECK_FUNC' for 'getpgrp'. + + -- Macro: AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK + If 'link' is a symbolic link, then 'lstat' should treat 'link/' the + same as 'link/.'. However, many older 'lstat' implementations + incorrectly ignore trailing slashes. + + It is safe to assume that if 'lstat' incorrectly ignores trailing + slashes, then other symbolic-link-aware functions like 'unlink' and + 'unlink' also incorrectly ignore trailing slashes. + + If 'lstat' behaves properly, define + 'LSTAT_FOLLOWS_SLASHED_SYMLINK', otherwise require an 'AC_LIBOBJ' + replacement of 'lstat'. + + -- Macro: AC_FUNC_MALLOC + If the 'malloc' works correctly ('malloc (0)' returns a valid + pointer), define 'HAVE_MALLOC'. + + -- Macro: AC_FUNC_MEMCMP + If the '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 + 'AC_LIBOBJ' replacement for 'memcmp'. + + -- Macro: AC_FUNC_MKTIME + If the 'mktime' function is not available, or does not work + correctly, require an 'AC_LIBOBJ' replacement for 'mktime'. + + -- Macro: AC_FUNC_MMAP + If the 'mmap' function exists and works correctly, define + 'HAVE_MMAP'. Only checks private fixed mapping of already-mapped + memory. + + -- Macro: AC_FUNC_OBSTACK + If the obstacks are found, define 'HAVE_OBSTACK', else require an + 'AC_LIBOBJ' replacement for 'obstack'. + + -- Macro: AC_FUNC_SELECT_ARGTYPES + Determines the correct type to be passed for each of the 'select' + function's arguments, and defines those types in + 'SELECT_TYPE_ARG1', 'SELECT_TYPE_ARG234', and 'SELECT_TYPE_ARG5' + respectively. 'SELECT_TYPE_ARG1' defaults to 'int', + 'SELECT_TYPE_ARG234' defaults to 'int *', and 'SELECT_TYPE_ARG5' + defaults to 'struct timeval *'. + + -- Macro: AC_FUNC_SETPGRP + If 'setpgrp' takes no argument (the POSIX.1 version), define + 'SETPGRP_VOID'. Otherwise, it is the BSD version, which takes two + process IDs as arguments. This macro does not check whether + 'setpgrp' exists at all; if you need to work in that situation, + first call 'AC_CHECK_FUNC' for 'setpgrp'. + + -- Macro: AC_FUNC_STAT + -- Macro: AC_FUNC_LSTAT + Determine whether 'stat' or 'lstat' have the bug that it succeeds + when given the zero-length file name argument. The 'stat' and + 'lstat' from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do this. + + If it does, then define 'HAVE_STAT_EMPTY_STRING_BUG' (or + 'HAVE_LSTAT_EMPTY_STRING_BUG') and ask for an 'AC_LIBOBJ' + replacement of it. + + -- Macro: AC_FUNC_SETVBUF_REVERSED + If 'setvbuf' takes the buffering type as its second argument and + the buffer pointer as the third, instead of the other way around, + define 'SETVBUF_REVERSED'. + + -- Macro: AC_FUNC_STRCOLL + If the 'strcoll' function exists and works correctly, define + 'HAVE_STRCOLL'. This does a bit more than + 'AC_CHECK_FUNCS(strcoll)', because some systems have incorrect + definitions of 'strcoll' that should not be used. + + -- Macro: AC_FUNC_STRTOD + If the 'strtod' function does not exist or doesn't work correctly, + ask for an 'AC_LIBOBJ' replacement of 'strtod'. In this case, + because 'strtod.c' is likely to need 'pow', set the output variable + 'POW_LIB' to the extra library needed. + + -- Macro: AC_FUNC_STRERROR_R + If 'strerror_r' is available, define 'HAVE_STRERROR_R'. If its + implementation correctly returns a 'char *', define + 'HAVE_WORKING_STRERROR_R'. On at least DEC UNIX 4.0[A-D] and HP-UX + B.10.20, 'strerror_r' returns 'int'. Actually, this tests only + whether it returns a scalar or an array, but that should be enough. + This is used by the common 'error.c'. + + -- Macro: AC_FUNC_STRFTIME + Check for 'strftime' in the 'intl' library, for SCO UNIX. Then, if + 'strftime' is available, define 'HAVE_STRFTIME'. + + -- Macro: AC_FUNC_UTIME_NULL + If 'utime(FILE, NULL)' sets FILE's timestamp to the present, define + 'HAVE_UTIME_NULL'. + + -- Macro: AC_FUNC_VPRINTF + If 'vprintf' is found, define 'HAVE_VPRINTF'. Otherwise, if + '_doprnt' is found, define 'HAVE_DOPRNT'. (If 'vprintf' is + available, you may assume that 'vfprintf' and 'vsprintf' are also + available.) + + +File: autoconf.info, Node: Generic Functions, Prev: Particular Functions, Up: Library Functions + +5.5.3 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 '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 (*note Writing +Tests::). + + -- Macro: AC_CHECK_FUNC (FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + If C function FUNCTION is available, run shell commands + ACTION-IF-FOUND, otherwise ACTION-IF-NOT-FOUND. If you just want + to define a symbol if the function is available, consider using + 'AC_CHECK_FUNCS' instead. This macro checks for functions with C + linkage even when 'AC_LANG(C++)' has been called, since C is more + standardized than C++. (*note Language Choice::, for more + information about selecting the language for checks.) + + -- Macro: AC_CHECK_FUNCS (FUNCTION..., [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + For each FUNCTION in the whitespace-separated argument list, define + 'HAVE_FUNCTION' (in all capitals) if it is available. If + 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 + 'break' to break out of the loop on the first match. If + ACTION-IF-NOT-FOUND is given, it is executed when one of the + functions is not found. + + 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 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 ('AC_REPLACE_FUNCS') to check for and +replace the function if needed. + + -- Macro: AC_LIBOBJ (FUNCTION) + Specify that 'FUNCTION.c' must be included in the executables to + replace a missing or broken implementation of FUNCTION. + + Technically, it adds 'FUNCTION.$ac_objext' to the output variable + 'LIBOBJS' and calls 'AC_LIBSOURCE' for 'FUNCTION.c'. You should + not directly change 'LIBOBJS', since this is not traceable. + + -- Macro: AC_LIBSOURCE (FILE) + Specify that FILE might be needed to compile the project. If you + need to know what files might be needed by a 'configure.ac', you + should trace 'AC_LIBSOURCE'. FILE must be a literal. + + This macro is called automatically from 'AC_LIBOBJ', but you must + call it explicitly if you pass a shell variable to 'AC_LIBOBJ'. In + that case, since shell variables cannot be traced statically, you + must pass to 'AC_LIBSOURCE' any possible files that the shell + variable might cause 'AC_LIBOBJ' to need. For example, if you want + to pass a variable '$foo_or_bar' to 'AC_LIBOBJ' that holds either + '"foo"' or '"bar"', you should do: + + AC_LIBSOURCE(foo.c) + AC_LIBSOURCE(bar.c) + AC_LIBOBJ($foo_or_bar) + + There is usually a way to avoid this, however, and you are + encouraged to simply call 'AC_LIBOBJ' with literal arguments. + + Note that this macro replaces the obsolete 'AC_LIBOBJ_DECL', with + slightly different semantics: the old macro took the function name, + e.g. 'foo', as its argument rather than the file name. + + -- Macro: AC_LIBSOURCES (FILES) + Like 'AC_LIBSOURCE', but accepts one or more FILES in a + comma-separated M4 list. Thus, the above example might be + rewritten: + + AC_LIBSOURCES([foo.c, bar.c]) + AC_LIBOBJ($foo_or_bar) + + -- Macro: AC_REPLACE_FUNCS (FUNCTION...) + Like 'AC_CHECK_FUNCS', but uses 'AC_LIBOBJ(FUNCTION)' as + ACTION-IF-NOT-FOUND. You can declare your replacement function by + enclosing the prototype in '#if !HAVE_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. + + +File: autoconf.info, Node: Header Files, Next: Declarations, Prev: Library Functions, Up: Existing Tests + +5.6 Header Files +================ + +The following macros check for the presence of certain C header files. +If there is no macro specifically defined to check for a header file you +need, and you don't need to check for any special properties of it, then +you can use one of the general header-file check macros. + +* Menu: + +* Particular Headers:: Special handling to find certain headers +* Generic Headers:: How to find other headers + + +File: autoconf.info, Node: Particular Headers, Next: Generic Headers, Prev: Header Files, Up: Header Files + +5.6.1 Particular Header Checks +------------------------------ + +These macros check for particular system header files--whether they +exist, and in some cases whether they declare certain symbols. + + -- Macro: AC_HEADER_DIRENT + Check for the following header files. For the first one that is + found and defines 'DIR', define the listed C preprocessor macro: + + 'dirent.h' 'HAVE_DIRENT_H' + 'sys/ndir.h' 'HAVE_SYS_NDIR_H' + 'sys/dir.h' 'HAVE_SYS_DIR_H' + 'ndir.h' 'HAVE_NDIR_H' + + The directory-library declarations in your source code should look + something like the following: + + #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 + + Using the above declarations, the program would declare variables + to be of type 'struct dirent', not 'struct direct', and would + access the length of a directory entry name by passing a pointer to + a 'struct dirent' to the 'NAMLEN' macro. + + This macro also checks for the SCO Xenix 'dir' and 'x' libraries. + + -- Macro: AC_HEADER_MAJOR + If 'sys/types.h' does not define 'major', 'minor', and 'makedev', + but 'sys/mkdev.h' does, define 'MAJOR_IN_MKDEV'; otherwise, if + 'sys/sysmacros.h' does, define 'MAJOR_IN_SYSMACROS'. + + -- Macro: AC_HEADER_STAT + If the macros 'S_ISDIR', 'S_ISREG' et al. defined in 'sys/stat.h' + do not work properly (returning false positives), define + 'STAT_MACROS_BROKEN'. This is the case on Tektronix UTekV, Amdahl + UTS and Motorola System V/88. + + -- Macro: AC_HEADER_STDC + Define 'STDC_HEADERS' if the system has ANSI C header files. + Specifically, this macro checks for 'stdlib.h', 'stdarg.h', + 'string.h', and 'float.h'; if the system has those, it probably has + the rest of the ANSI C header files. This macro also checks + whether 'string.h' declares 'memchr' (and thus presumably the other + 'mem' functions), whether 'stdlib.h' declare 'free' (and thus + presumably 'malloc' and other related functions), and whether the + 'ctype.h' macros work on characters with the high bit set, as ANSI + C requires. + + Use 'STDC_HEADERS' instead of '__STDC__' to determine whether the + system has ANSI-compliant header files (and probably C library + functions) because many systems that have GCC do not have ANSI C + header files. + + On systems without ANSI C headers, there is so much variation that + it is probably easier to declare the functions you use than to + figure out exactly what the system header files declare. Some + systems contain a mix of functions ANSI and BSD; some are mostly + ANSI but lack 'memmove'; some define the BSD functions as macros in + 'string.h' or 'strings.h'; some have only the BSD functions but + 'string.h'; some declare the memory functions in 'memory.h', some + in 'string.h'; etc. It is probably sufficient to check for one + string function and one memory function; if the library has the + ANSI versions of those then it probably has most of the others. If + you put the following in 'configure.ac': + + AC_HEADER_STDC + AC_CHECK_FUNCS(strchr memcpy) + + then, in your code, you can put declarations like this: + + #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 + + If you use a function like 'memchr', 'memset', 'strtok', or + 'strspn', which have no BSD equivalent, then macros won't suffice; + you must provide an implementation of each function. An easy way + to incorporate your implementations only when needed (since the + ones in system C libraries may be hand optimized) is to, taking + 'memchr' for example, put it in 'memchr.c' and use + 'AC_REPLACE_FUNCS(memchr)'. + + -- Macro: AC_HEADER_SYS_WAIT + If 'sys/wait.h' exists and is compatible with POSIX.1, define + 'HAVE_SYS_WAIT_H'. Incompatibility can occur if 'sys/wait.h' does + not exist, or if it uses the old BSD 'union wait' instead of 'int' + to store a status value. If 'sys/wait.h' is not POSIX.1 + compatible, then instead of including it, define the POSIX.1 macros + with their usual interpretations. Here is an example: + + #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 + + '_POSIX_VERSION' is defined when 'unistd.h' is included on POSIX.1 +systems. If there is no 'unistd.h', it is definitely not a POSIX.1 +system. However, some non-POSIX.1 systems do have 'unistd.h'. + + The way to check if the system supports POSIX.1 is: + + #if HAVE_UNISTD_H + # include <sys/types.h> + # include <unistd.h> + #endif + + #ifdef _POSIX_VERSION + /* Code for POSIX.1 systems. */ + #endif + + -- Macro: AC_HEADER_TIME + If a program may include both 'time.h' and 'sys/time.h', define + 'TIME_WITH_SYS_TIME'. On some older systems, 'sys/time.h' includes + 'time.h', but '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, 'struct timeval' or + 'struct timezone' as well as 'struct tm'. It is best used in + conjunction with 'HAVE_SYS_TIME_H', which can be checked for using + 'AC_CHECK_HEADERS(sys/time.h)'. + + #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 + + -- Macro: AC_HEADER_TIOCGWINSZ + If the use of 'TIOCGWINSZ' requires '<sys/ioctl.h>', then define + 'GWINSZ_IN_SYS_IOCTL'. Otherwise 'TIOCGWINSZ' can be found in + '<termios.h>'. + + Use: + + #if HAVE_TERMIOS_H + # include <termios.h> + #endif + + #if GWINSZ_IN_SYS_IOCTL + # include <sys/ioctl.h> + #endif + + +File: autoconf.info, Node: Generic Headers, Prev: Particular Headers, Up: Header Files + +5.6.2 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 (*note Writing Tests::). + + -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + If the system header file HEADER-FILE is usable, execute shell + commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND. + If you just want to define a symbol if the header file is + available, consider using 'AC_CHECK_HEADERS' instead. + + The meaning of "usable" depends upon the content of INCLUDES: + + if INCLUDES is empty + check whether + + HEADER-FILE + + can be _preprocessed_ without error. + + if INCLUDE is set + Check whether + + INCLUDES + #include <HEADER-FILE> + + can be _compiled_ without error. You may use + 'AC_CHECK_HEADER' (and 'AC_CHECK_HEADERS') to check whether + two headers are compatible. + + You may pass any kind of dummy content for INCLUDES, such as a + single space, a comment, to check whether HEADER-FILE compiles with + success. + + -- Macro: AC_CHECK_HEADERS (HEADER-FILE..., [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each given system header file HEADER-FILE in the + whitespace-separated argument list that exists, define + 'HAVE_HEADER-FILE' (in all capitals). If 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 'break' to break out of the + loop on the first match. If 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 'AC_CHECK_HEADER' to + understand the influence of INCLUDES. + + +File: autoconf.info, Node: Declarations, Next: Structures, Prev: Header Files, Up: Existing Tests + +5.7 Declarations +================ + +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 (*note Generic +Declarations::) or, for more complex tests, you may use 'AC_TRY_COMPILE' +(*note Examining Syntax::). + +* Menu: + +* Particular Declarations:: Macros to check for certain declarations +* Generic Declarations:: How to find other declarations + + +File: autoconf.info, Node: Particular Declarations, Next: Generic Declarations, Prev: Declarations, Up: Declarations + +5.7.1 Particular Declaration Checks +----------------------------------- + +The following macros check for certain declarations. + + -- Macro: AC_DECL_SYS_SIGLIST + Define 'SYS_SIGLIST_DECLARED' if the variable 'sys_siglist' is + declared in a system header file, either 'signal.h' or 'unistd.h'. + + +File: autoconf.info, Node: Generic Declarations, Prev: Particular Declarations, Up: Declarations + +5.7.2 Generic Declaration Checks +-------------------------------- + +These macros are used to find declarations not covered by the +"particular" test macros. + + -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + If SYMBOL (a function or a variable) is not declared in INCLUDES + and a declaration is needed, run the shell commands + ACTION-IF-NOT-FOUND, otherwise ACTION-IF-FOUND. If no INCLUDES are + specified, the default includes are used (*note Default + Includes::). + + This macro actually tests whether it is valid to use 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. + + -- Macro: AC_CHECK_DECLS (SYMBOLS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each of the SYMBOLS (_comma_-separated list), define + 'HAVE_DECL_SYMBOL' (in all capitals) to '1' if SYMBOL is declared, + otherwise to '0'. If ACTION-IF-NOT-FOUND is given, it is + additional shell code to execute when one of the function + declarations is needed, otherwise ACTION-IF-FOUND is executed. + + This macro uses an m4 list as first argument: + AC_CHECK_DECLS(strdup) + AC_CHECK_DECLS([strlen]) + AC_CHECK_DECLS([malloc, realloc, calloc, free]) + + Unlike the other 'AC_CHECK_*S' macros, when a SYMBOL is not + declared, 'HAVE_DECL_SYMBOL' is defined to '0' instead of leaving + 'HAVE_DECL_SYMBOL' undeclared. When you are _sure_ that the check + was performed, use 'HAVE_DECL_SYMBOL' just like any other result of + Autoconf: + + #if !HAVE_DECL_SYMBOL + extern char *symbol; + #endif + + If the test may have not been performed, however, because it is + safer _not_ to declare a symbol than to use a declaration that + conflicts with the system's one, you should use: + + #if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC + char *malloc (size_t *s); + #endif + + 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. + + +File: autoconf.info, Node: Structures, Next: Types, Prev: Declarations, Up: Existing Tests + +5.8 Structures +============== + +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 +(*note Generic Structures::) or, for more complex tests, you may use +'AC_TRY_COMPILE' (*note Examining Syntax::). + +* Menu: + +* Particular Structures:: Macros to check for certain structure members +* Generic Structures:: How to find other structure members + + +File: autoconf.info, Node: Particular Structures, Next: Generic Structures, Prev: Structures, Up: Structures + +5.8.1 Particular Structure Checks +--------------------------------- + +The following macros check for certain structures or structure members. + + -- Macro: AC_STRUCT_ST_BLKSIZE + If 'struct stat' contains an 'st_blksize' member, define + 'HAVE_STRUCT_STAT_ST_BLKSIZE'. The former name, 'HAVE_ST_BLKSIZE' + is to be avoided, as its support will cease in the future. This + macro is obsoleted, and should be replaced by + + AC_CHECK_MEMBERS([struct stat.st_blksize]) + + -- Macro: AC_STRUCT_ST_BLOCKS + If 'struct stat' contains an 'st_blocks' member, define + 'HAVE_STRUCT STAT_ST_BLOCKS'. Otherwise, require an 'AC_LIBOBJ' + replacement of 'fileblocks'. The former name, 'HAVE_ST_BLOCKS' is + to be avoided, as its support will cease in the future. + + -- Macro: AC_STRUCT_ST_RDEV + If 'struct stat' contains an 'st_rdev' member, define + 'HAVE_STRUCT_STAT_ST_RDEV'. The former name for this macro, + '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: + AC_CHECK_MEMBERS([struct stat.st_rdev]) + + -- Macro: AC_STRUCT_TM + If 'time.h' does not define 'struct tm', define 'TM_IN_SYS_TIME', + which means that including 'sys/time.h' had better define 'struct + tm'. + + -- Macro: AC_STRUCT_TIMEZONE + Figure out how to get the current timezone. If 'struct tm' has a + 'tm_zone' member, define 'HAVE_STRUCT_TM_TM_ZONE' (and the + obsoleted 'HAVE_TM_ZONE'). Otherwise, if the external array + 'tzname' is found, define 'HAVE_TZNAME'. + + +File: autoconf.info, Node: Generic Structures, Prev: Particular Structures, Up: Structures + +5.8.2 Generic Structure Checks +------------------------------ + +These macros are used to find structure members not covered by the +"particular" test macros. + + -- Macro: AC_CHECK_MEMBER (AGGREGATE.MEMBER, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check whether MEMBER is a member of the aggregate AGGREGATE. If no + INCLUDES are specified, the default includes are used (*note + Default Includes::). + + AC_CHECK_MEMBER(struct passwd.pw_gecos,, + [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], + [#include <pwd.h>]) + + You can use this macro for sub-members: + + AC_CHECK_MEMBER(struct top.middle.bot) + + -- Macro: AC_CHECK_MEMBERS (MEMBERS, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check for the existence of each 'AGGREGATE.MEMBER' of MEMBERS using + the previous macro. When MEMBER belongs to AGGREGATE, define + 'HAVE_AGGREGATE_MEMBER' (in all capitals, with spaces and dots + replaced by underscores). + + This macro uses m4 lists: + AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) + + +File: autoconf.info, Node: Types, Next: Compilers and Preprocessors, Prev: Structures, Up: Existing Tests + +5.9 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 + + +File: autoconf.info, Node: Particular Types, Next: Generic Types, Prev: Types, Up: Types + +5.9.1 Particular Type Checks +---------------------------- + +These macros check for particular C types in 'sys/types.h', 'stdlib.h' +and others, if they exist. + + -- Macro: AC_TYPE_GETGROUPS + Define 'GETGROUPS_T' to be whichever of 'gid_t' or 'int' is the + base type of the array argument to 'getgroups'. + + -- Macro: AC_TYPE_MODE_T + Equivalent to 'AC_CHECK_TYPE(mode_t, int)'. + + -- Macro: AC_TYPE_OFF_T + Equivalent to 'AC_CHECK_TYPE(off_t, long)'. + + -- Macro: AC_TYPE_PID_T + Equivalent to 'AC_CHECK_TYPE(pid_t, int)'. + + -- Macro: AC_TYPE_SIGNAL + If 'signal.h' declares 'signal' as returning a pointer to a + function returning 'void', define 'RETSIGTYPE' to be 'void'; + otherwise, define it to be 'int'. + + Define signal handlers as returning type 'RETSIGTYPE': + + RETSIGTYPE + hup_handler () + { + ... + } + + -- Macro: AC_TYPE_SIZE_T + Equivalent to 'AC_CHECK_TYPE(size_t, unsigned)'. + + -- Macro: AC_TYPE_UID_T + If 'uid_t' is not defined, define 'uid_t' to be 'int' and 'gid_t' + to be 'int'. + + +File: autoconf.info, Node: Generic Types, Prev: Particular Types, Up: Types + +5.9.2 Generic Type Checks +------------------------- + +These macros are used to check for types not covered by the "particular" +test macros. + + -- Macro: AC_CHECK_TYPE (TYPE, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + Check whether TYPE is defined. It may be a compiler builtin type + or defined by the [INCLUDES] (*note Default Includes::). + + -- Macro: AC_CHECK_TYPES (TYPES, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [INCLUDES]) + For each TYPE of the TYPES that is defined, define 'HAVE_TYPE' (in + all capitals). If no INCLUDES are specified, the default includes + are used (*note Default Includes::). If ACTION-IF-FOUND is given, + it is additional shell code to execute when one of the types is + found. If ACTION-IF-NOT-FOUND is given, it is executed when one of + the types is not found. + + This macro uses m4 lists: + AC_CHECK_TYPES(ptrdiff_t) + AC_CHECK_TYPES([unsigned long long, uintmax_t]) + + Autoconf, up to 2.13, used to provide to another version of +'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 +'AC_CHECK_TYPE', see *note Obsolete Macros::. + + +File: autoconf.info, Node: Compilers and Preprocessors, Next: System Services, Prev: Types, Up: Existing Tests + +5.10 Compilers and Preprocessors +================================ + +All the tests for compilers ('AC_PROG_CC', 'AC_PROG_CXX', 'AC_PROG_F77') +define the output variable 'EXEEXT' based on the output of the compiler, +typically to the empty string if Unix and '.exe' if Win32 or OS/2. + + They also define the output variable 'OBJEXT' based on the output of +the compiler, after .c files have been excluded, typically to 'o' if +Unix, '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. *Note 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 + + +File: autoconf.info, Node: Generic Compiler Characteristics, Next: C Compiler, Prev: Compilers and Preprocessors, Up: Compilers and Preprocessors + +5.10.1 Generic Compiler Characteristics +--------------------------------------- + + -- Macro: AC_CHECK_SIZEOF (TYPE, [UNUSED], [INCLUDES]) + Define 'SIZEOF_TYPE' (*note Standard Symbols::) to be the size in + bytes of TYPE. If 'type' is unknown, it gets a size of 0. If no + INCLUDES are specified, the default includes are used (*note + Default Includes::). If you provide INCLUDE, make sure to include + 'stdio.h' which is required for this macro to run. + + This macro now works even when cross-compiling. The UNUSED + argument was used when cross-compiling. + + For example, the call + + AC_CHECK_SIZEOF(int *) + + defines 'SIZEOF_INT_P' to be 8 on DEC Alpha AXP systems. + + +File: autoconf.info, Node: C Compiler, Next: C++ Compiler, Prev: Generic Compiler Characteristics, Up: Compilers and Preprocessors + +5.10.2 C Compiler Characteristics +--------------------------------- + + -- Macro: AC_PROG_CC ([COMPILER-SEARCH-LIST]) + Determine a C compiler to use. If 'CC' is not already set in the + environment, check for 'gcc' and 'cc', then for other C compilers. + Set output variable '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 'AC_PROG_CC' + like this: + + AC_PROG_CC(cl egcs gcc cc) + + If using the GNU C compiler, set shell variable 'GCC' to 'yes'. If + output variable 'CFLAGS' was not already set, set it to '-g -O2' + for the GNU C compiler ('-O2' on systems where GCC does not accept + '-g'), or '-g' for other compilers. + + -- Macro: AC_PROG_CC_C_O + If the C compiler does not accept the '-c' and '-o' options + simultaneously, define 'NO_MINUS_C_MINUS_O'. This macro actually + tests both the compiler found by 'AC_PROG_CC', and, if different, + the first 'cc' in the path. The test fails if one fails. This + macro was created for GNU Make to choose the default C compilation + rule. + + -- Macro: AC_PROG_CC_STDC + If the C compiler is not in ANSI C mode by default, try to add an + option to output variable 'CC' to make it so. This macro tries + various options that select ANSI C on some system or another. It + considers the compiler to be in 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 ANSI C; if not, the shell + variable 'ac_cv_prog_cc_stdc' is set to 'no'. If you wrote your + source code in ANSI C, you can make an un-ANSIfied copy of it by + using the program 'ansi2knr', which comes with Automake. + + -- Macro: AC_PROG_CPP + Set output variable 'CPP' to a command that runs the C + preprocessor. If '$CC -E' doesn't work, '/lib/cpp' is used. It is + only portable to run 'CPP' on files with a '.c' extension. + + If the current language is C (*note Language Choice::), many of the + specific test macros use the value of 'CPP' indirectly by calling + 'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or + '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. + + The following macros check for C compiler or machine architecture +features. To check for characteristics not listed here, use +'AC_TRY_COMPILE' (*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run +Time::) + + -- Macro: AC_C_BIGENDIAN + If words are stored with the most significant byte first (like + Motorola and SPARC, but not Intel and VAX, CPUs), define + 'WORDS_BIGENDIAN'. + + -- Macro: AC_C_CONST + If the C compiler does not fully support the ANSI C qualifier + 'const', define 'const' to be empty. Some C compilers that do not + define '__STDC__' do support 'const'; some compilers that define + '__STDC__' do not completely support 'const'. Programs can simply + use 'const' as if every C compiler supported it; for those that + don't, the '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 'const', because C and C++ treat 'const' differently. For + example: + + const int foo; + + is valid in C but not in C++. These differences unfortunately + cannot be papered over by defining 'const' to be empty. + + If 'autoconf' detects this situation, it leaves '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. + + -- Macro: AC_C_VOLATILE + If the C compiler does not understand the keyword 'volatile', + define 'volatile' to be empty. Programs can simply use 'volatile' + as if every C compiler supported it; for those that do not, the + 'Makefile' or configuration header will define it as empty. + + If the correctness of your program depends on the semantics of + 'volatile', simply defining it to be empty does, in a sense, break + your code. However, given that the compiler does not support + 'volatile', you are at its mercy anyway. At least your program + will compile, when it wouldn't before. + + In general, the 'volatile' keyword is a feature of ANSI C, so you + might expect that 'volatile' is available only when '__STDC__' is + defined. However, Ultrix 4.3's native compiler does support + volatile, but does not defined '__STDC__'. + + -- Macro: AC_C_INLINE + If the C compiler supports the keyword 'inline', do nothing. + Otherwise define 'inline' to '__inline__' or '__inline' if it + accepts one of those, otherwise define 'inline' to be empty. + + -- Macro: AC_C_CHAR_UNSIGNED + If the C type 'char' is unsigned, define '__CHAR_UNSIGNED__', + unless the C compiler predefines it. + + -- Macro: AC_C_LONG_DOUBLE + If the C compiler supports the 'long double' type, define + 'HAVE_LONG_DOUBLE'. Some C compilers that do not define '__STDC__' + do support the 'long double' type; some compilers that define + '__STDC__' do not support 'long double'. + + -- Macro: AC_C_STRINGIZE + If the C preprocessor supports the stringizing operator, define + 'HAVE_STRINGIZE'. The stringizing operator is '#' and is found in + macros such as this: + + #define x(y) #y + + -- Macro: AC_C_PROTOTYPES + Check to see if function prototypes are understood by the compiler. + If so, define 'PROTOTYPES'. In the case the compiler does not + handle prototypes, you should use 'ansi2knr', which comes with the + Automake distribution, to unprotoize function definitions. For + function prototypes, you should first define 'PARAMS': + + #ifndef PARAMS + # if PROTOTYPES + # define PARAMS(protos) protos + # else /* no PROTOTYPES */ + # define PARAMS(protos) () + # endif /* no PROTOTYPES */ + #endif + + then use it this way: + + size_t my_strlen PARAMS ((const char *)); + + -- Macro: AC_PROG_GCC_TRADITIONAL + Add '-traditional' to output variable 'CC' if using the GNU C + compiler and 'ioctl' does not work properly without '-traditional'. + That usually happens when the fixed header files have not been + installed on an old system. Since recent versions of the GNU C + compiler fix the header files automatically when installed, this is + becoming a less prevalent problem. + + +File: autoconf.info, Node: C++ Compiler, Next: Fortran 77 Compiler, Prev: C Compiler, Up: Compilers and Preprocessors + +5.10.3 C++ Compiler Characteristics +----------------------------------- + + -- Macro: AC_PROG_CXX ([COMPILER-SEARCH-LIST]) + Determine a C++ compiler to use. Check if the environment variable + 'CXX' or 'CCC' (in that order) is set; if so, then set output + variable 'CXX' to its value. + + Otherwise, if the macro is invoked without an argument, then search + for a C++ compiler under the likely names (first 'g++' and 'c++' + then other names). If none of those checks succeed, then as a last + resort set 'CXX' to '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 'AC_PROG_CXX' like this: + + AC_PROG_CXX(cl KCC CC cxx cc++ xlC aCC c++ g++ egcs gcc) + + If using the GNU C++ compiler, set shell variable 'GXX' to 'yes'. + If output variable 'CXXFLAGS' was not already set, set it to '-g + -O2' for the GNU C++ compiler ('-O2' on systems where G++ does not + accept '-g'), or '-g' for other compilers. + + -- Macro: AC_PROG_CXXCPP + Set output variable 'CXXCPP' to a command that runs the C++ + preprocessor. If '$CXX -E' doesn't work, '/lib/cpp' is used. It + is only portable to run 'CXXCPP' on files with a '.c', '.C', or + '.cc' extension. + + If the current language is C++ (*note Language Choice::), many of + the specific test macros use the value of 'CXXCPP' indirectly by + calling 'AC_TRY_CPP', 'AC_CHECK_HEADER', 'AC_EGREP_HEADER', or + '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++. + + +File: autoconf.info, Node: Fortran 77 Compiler, Prev: C++ Compiler, Up: Compilers and Preprocessors + +5.10.4 Fortran 77 Compiler Characteristics +------------------------------------------ + + -- Macro: AC_PROG_F77 ([COMPILER-SEARCH-LIST]) + Determine a Fortran 77 compiler to use. If 'F77' is not already + set in the environment, then check for 'g77' and 'f77', and then + some other names. Set the output variable '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 'AC_PROG_F77' like this: + + AC_PROG_F77(fl32 f77 fort77 xlf cf77 g77 f90 xlf90) + + If using 'g77' (the GNU Fortran 77 compiler), then 'AC_PROG_F77' + will set the shell variable 'G77' to 'yes'. If the output variable + 'FFLAGS' was not already set in the environment, then set it to '-g + -02' for 'g77' (or '-O2' where 'g77' does not accept '-g'). + Otherwise, set 'FFLAGS' to '-g' for all other Fortran 77 compilers. + + -- Macro: AC_PROG_F77_C_O + Test if the Fortran 77 compiler accepts the options '-c' and '-o' + simultaneously, and define 'F77_NO_MINUS_C_MINUS_O' if it does not. + + The following macros check for Fortran 77 compiler characteristics. +To check for characteristics not listed here, use 'AC_TRY_COMPILE' +(*note Examining Syntax::) or 'AC_TRY_RUN' (*note Run Time::), making +sure to first set the current language to Fortran 77 'AC_LANG(Fortran +77)' (*note Language Choice::). + + -- Macro: AC_F77_LIBRARY_LDFLAGS + Determine the linker flags (e.g. '-L' and '-l') for the "Fortran + 77 intrinsic and run-time libraries" that are required to + successfully link a Fortran 77 program or shared library. The + output variable '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 (*note (automake)Mixing Fortran 77 + With C and C++::). + + 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 + 'AC_F77_LIBRARY_LDFLAGS' was created to determine these Fortran 77 + libraries. + + The macro 'AC_F77_DUMMY_MAIN' or 'AC_F77_MAIN' will probably also + be necessary to link C/C++ with Fortran; see below. + + -- Macro: AC_F77_DUMMY_MAIN ([ACTION-IF-FOUND], [ACTION-IF-NOT-FOUND]) + With many compilers, the Fortran libraries detected by + 'AC_F77_LIBRARY_LDFLAGS' provide their own 'main' entry function + that initializes things like Fortran I/O, and which then calls a + user-provided entry function named e.g. 'MAIN__' to run the user's + program. The 'AC_F77_DUMMY_MAIN' or '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 'main' and skip + the Fortran library initializations. In this case, however, one + may still need to provide a dummy 'MAIN__' routine in order to + prevent linking errors on some systems. 'AC_F77_DUMMY_MAIN' + detects whether any such routine is _required_ for linking, and + what its name is; the shell variable 'F77_DUMMY_MAIN' holds this + name, 'unknown' when no solution was found, and 'none' when no such + dummy main is needed. + + By default, ACTION-IF-FOUND defines 'F77_DUMMY_MAIN' to the name of + this routine (e.g. 'MAIN__') _if_ it is required. + [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: + + #ifdef F77_DUMMY_MAIN + # ifdef __cplusplus + extern "C" + # endif + int F77_DUMMY_MAIN() { return 1; } + #endif + + Note that 'AC_F77_DUMMY_MAIN' is called automatically from + 'AC_F77_WRAPPERS'; there is generally no need to call it explicitly + unless one wants to change the default actions. + + -- Macro: AC_F77_MAIN + As discussed above for 'AC_F77_DUMMY_MAIN', many Fortran libraries + allow you to provide an entry point called e.g. 'MAIN__' instead + of the usual 'main', which is then called by a 'main' function in + the Fortran libraries that initializes things like Fortran I/O. The + 'AC_F77_MAIN' macro detects whether it is _possible_ to utilize + such an alternate main function, and defines 'F77_MAIN' to the name + of the function. (If no alternate main function name is found, + 'F77_MAIN' is simply defined to 'main'.) + + Thus, when calling Fortran routines from C that perform things like + I/O, one should use this macro and name the "main" function + 'F77_MAIN' instead of 'main'. + + -- Macro: AC_F77_WRAPPERS + Defines C macros 'F77_FUNC(name,NAME)' and '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 'AC_F77_WRAPPERS'. For example, + suppose you have the following Fortran 77 subroutine: + + subroutine foobar(x,y) + double precision x, y + y = 3.14159 * x + return + end + + You would then declare its prototype in C or C++ as: + + #define FOOBAR_F77 F77_FUNC(foobar,FOOBAR) + #ifdef __cplusplus + extern "C" /* prevent C++ name mangling */ + #endif + void FOOBAR_F77(double *x, double *y); + + Note that we pass both the lowercase and uppercase versions of the + function name to 'F77_FUNC' so that it can select the right one. + Note also that all parameters to Fortran 77 routines are passed as + pointers (*note (automake)Mixing Fortran 77 With C and C++::). + + 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 'F77_FUNC' macro is defined. + + Now, to call that routine from a C program, we would do something + like: + + { + double x = 2.7183, y; + FOOBAR_F77(&x, &y); + } + + If the Fortran 77 identifier contains an underscore (e.g. + 'foo_bar'), you should use 'F77_FUNC_' instead of 'F77_FUNC' (with + the same arguments). This is because some Fortran 77 compilers + mangle names differently if they contain an underscore. + + -- Macro: AC_F77_FUNC (NAME, [SHELLVAR]) + Given an identifier NAME, set the shell variable SHELLVAR to hold + the mangled version NAME according to the rules of the Fortran 77 + linker (see also 'AC_F77_WRAPPERS'). SHELLVAR is optional; if it + is not supplied, the shell variable will be simply 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++. + + +File: autoconf.info, Node: System Services, Next: UNIX Variants, Prev: Compilers and Preprocessors, Up: Existing Tests + +5.11 System Services +==================== + +The following macros check for operating system services or +capabilities. + + -- Macro: AC_PATH_X + Try to locate the X Window System include files and libraries. If + the user gave the command line options '--x-includes=DIR' and + '--x-libraries=DIR', use those directories. If either or both were + not given, get the missing values by running 'xmkmf' on a trivial + 'Imakefile' and examining the 'Makefile' that it produces. If that + fails (such as if 'xmkmf' is not present), look for them in several + directories where they often reside. If either method is + successful, set the shell variables 'x_includes' and '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 + '--without-x', set the shell variable 'no_x' to 'yes'; otherwise + set it to the empty string. + + -- Macro: AC_PATH_XTRA + An enhanced version of 'AC_PATH_X'. It adds the C compiler flags + that X needs to output variable 'X_CFLAGS', and the X linker flags + to 'X_LIBS'. Define '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 'X_EXTRA_LIBS'. And it checks for special X11R6 + libraries that need to be linked with before '-lX11', and adds any + found to the output variable 'X_PRE_LIBS'. + + -- Macro: AC_SYS_INTERPRETER + Check whether the system supports starting scripts with a line of + the form '#! /bin/csh' to select the interpreter to use for the + script. After running this macro, shell code in 'configure.ac' can + check the shell variable 'interpval'; it will be set to 'yes' if + the system supports '#!', 'no' if not. + + -- Macro: AC_SYS_LARGEFILE + Arrange for large-file support(1). 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 'CC'. + Define '_FILE_OFFSET_BITS' and '_LARGE_FILES' if necessary. + + Large-file support can be disabled by configuring with the + '--disable-largefile' option. + + If you use this macro, check that your program works even when + 'off_t' is longer than 'long', since this is common when large-file + support is enabled. For example, it is not correct to print an + arbitrary 'off_t' value 'X' with 'printf ("%ld", (long) X)'. + + -- Macro: AC_SYS_LONG_FILE_NAMES + If the system supports file names longer than 14 characters, define + 'HAVE_LONG_FILE_NAMES'. + + -- Macro: AC_SYS_POSIX_TERMIOS + Check to see if POSIX termios headers and functions are available + on the system. If so, set the shell variable + 'am_cv_sys_posix_termios' to 'yes'. If not, set the variable to + 'no'. + + ---------- Footnotes ---------- + + (1) large-file support, +<http://www.sas.com/standards/large.file/x_open.20Mar96.html>. + + +File: autoconf.info, Node: UNIX Variants, Prev: System Services, Up: Existing Tests + +5.12 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. + + -- Macro: AC_AIX + If on AIX, define '_ALL_SOURCE'. Allows the use of some BSD + functions. Should be called before any macros that run the C + compiler. + + -- Macro: AC_ISC_POSIX + If on a POSIXized ISC UNIX, define '_POSIX_SOURCE' and add '-posix' + (for the GNU C compiler) or '-Xp' (for other C compilers) to output + variable 'CC'. This allows the use of POSIX facilities. Must be + called after 'AC_PROG_CC' and before any other macros that run the + C compiler. + + -- Macro: AC_MINIX + If on Minix, define '_MINIX' and '_POSIX_SOURCE' and define + '_POSIX_1_SOURCE' to be 2. This allows the use of POSIX + facilities. Should be called before any macros that run the C + compiler. + + +File: autoconf.info, Node: Writing Tests, Next: Results, Prev: Existing Tests, Up: Top + +6 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 (*note 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. *Note 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 + + +File: autoconf.info, Node: Examining Declarations, Next: Examining Syntax, Prev: Writing Tests, Up: Writing Tests + +6.1 Examining Declarations +========================== + +The macro '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. + + -- Macro: AC_TRY_CPP (INCLUDES, [ACTION-IF-TRUE], [ACTION-IF-FALSE]) + INCLUDES is C or C++ '#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 + ACTION-IF-TRUE. Otherwise run shell commands ACTION-IF-FALSE. + + This macro uses 'CPPFLAGS', but not 'CFLAGS', because '-g', '-O', + etc. are not valid options to many C preprocessors. + + 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 'AC_EGREP_HEADER' instead of running 'grep' directly on +the header file; on some systems the symbol might be defined in another +header file that the file you are checking '#include's. + + -- Macro: AC_EGREP_HEADER (PATTERN, HEADER-FILE, ACTION-IF-FOUND, + [ACTION-IF-NOT-FOUND]) + If the output of running the preprocessor on the system header file + HEADER-FILE matches the 'egrep' regular expression PATTERN, execute + shell commands ACTION-IF-FOUND, otherwise execute + ACTION-IF-NOT-FOUND. + + To check for C preprocessor symbols, either defined by header files +or predefined by the C preprocessor, use 'AC_EGREP_CPP'. Here is an +example of the latter: + + AC_EGREP_CPP(yes, + [#ifdef _AIX + yes + #endif + ], is_aix=yes, is_aix=no) + + -- Macro: AC_EGREP_CPP (PATTERN, PROGRAM, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + 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 PROGRAM matches the 'egrep' + regular expression PATTERN, execute shell commands ACTION-IF-FOUND, + otherwise execute ACTION-IF-NOT-FOUND. + + This macro calls 'AC_PROG_CPP' or 'AC_PROG_CXXCPP' (depending on + which language is current, *note Language Choice::), if it hasn't + been called already. + + +File: autoconf.info, Node: Examining Syntax, Next: Examining Libraries, Prev: Examining Declarations, Up: Writing Tests + +6.2 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 '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. + + -- Macro: AC_TRY_COMPILE (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Create a C, C++ or Fortran 77 test program (depending on which + language is current, *note Language Choice::), to see whether a + function whose body consists of FUNCTION-BODY can be compiled. + + For C and C++, INCLUDES is any '#include' statements needed by the + code in FUNCTION-BODY (INCLUDES will be ignored if the currently + selected language is Fortran 77). This macro also uses 'CFLAGS' or + 'CXXFLAGS' if either C or C++ is the currently selected language, + as well as 'CPPFLAGS', when compiling. If Fortran 77 is the + currently selected language then 'FFLAGS' will be used when + compiling. + + If the file compiles successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + This macro does not try to link; use 'AC_TRY_LINK' if you need to + do that (*note Examining Libraries::). + + +File: autoconf.info, Node: Examining Libraries, Next: Run Time, Prev: Examining Syntax, Up: Writing Tests + +6.3 Examining Libraries +======================= + +To check for a library, a function, or a global variable, Autoconf +'configure' scripts try to compile and link a small program that uses +it. This is unlike Metaconfig, which by default uses 'nm' or '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 'nm' and '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 'LDFLAGS' in the environment to pass whatever +options the linker needs (for example, '-Wl,-dn' on MIPS RISC/OS). + + 'AC_TRY_LINK' is used to compile test programs to test for functions +and global variables. It is also used by 'AC_CHECK_LIB' to check for +libraries (*note Libraries::), by adding the library being checked for +to 'LIBS' temporarily and trying to link a small program. + + -- Macro: AC_TRY_LINK (INCLUDES, FUNCTION-BODY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Depending on the current language (*note Language Choice::), create + a test program to see whether a function whose body consists of + FUNCTION-BODY can be compiled and linked. + + For C and C++, INCLUDES is any '#include' statements needed by the + code in FUNCTION-BODY (INCLUDES will be ignored if the currently + selected language is Fortran 77). This macro also uses 'CFLAGS' or + 'CXXFLAGS' if either C or C++ is the currently selected language, + as well as 'CPPFLAGS', when compiling. If Fortran 77 is the + currently selected language then 'FFLAGS' will be used when + compiling. However, both 'LDFLAGS' and 'LIBS' will be used during + linking in all cases. + + If the file compiles and links successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + -- Macro: AC_TRY_LINK_FUNC (FUNCTION, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND]) + Depending on the current language (*note Language Choice::), create + a test program to see whether a program whose body consists of a + prototype of and a call to FUNCTION can be compiled and linked. + + If the file compiles and links successfully, run shell commands + ACTION-IF-FOUND, otherwise run ACTION-IF-NOT-FOUND. + + +File: autoconf.info, Node: Run Time, Next: Systemology, Prev: Examining Libraries, Up: Writing Tests + +6.4 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 '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 + + +File: autoconf.info, Node: Test Programs, Next: Guidelines, Prev: Run Time, Up: Run Time + +6.4.1 Running Test Programs +--------------------------- + +Use the following macro if you need to test run-time behavior of the +system while configuring. + + -- Macro: AC_TRY_RUN (PROGRAM, [ACTION-IF-TRUE], [ACTION-IF-FALSE], + [ACTION-IF-CROSS-COMPILING]) + 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 ACTION-IF-TRUE. Otherwise, run shell commands + ACTION-IF-FALSE; the exit status of the program is available in the + shell variable '$?'. This macro uses 'CFLAGS' or 'CXXFLAGS', + 'CPPFLAGS', 'LDFLAGS', and 'LIBS' when compiling. + + If the C compiler being used does not produce executables that run + on the system where 'configure' is being run, then the test program + is not run. If the optional shell commands + ACTION-IF-CROSS-COMPILING are given, they are run instead. + Otherwise, 'configure' prints an error message and exits. + + 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 'AC_TRY_RUN'. 'autoconf' prints a warning +message when creating 'configure' each time it encounters a call to +'AC_TRY_RUN' with no 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 (*note Manual +Configuration::). Alternatively, set up a test results cache file with +the correct values for the host system (*note Caching Results::). + + To provide a default for calls of 'AC_TRY_RUN' that are embedded in +other macros, including a few of the ones that come with Autoconf, you +can call 'AC_PROG_CC' before running them. Then, if the shell variable +'cross_compiling' is set to 'yes', use an alternate method to get the +results instead of calling the macros. + + +File: autoconf.info, Node: Guidelines, Next: Test Functions, Prev: Test Programs, Up: Run Time + +6.4.2 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 'exit', not 'return', from 'main', because +on some systems (old Suns, at least) the argument to 'return' in 'main' +is ignored. + + Test programs can use '#if' or '#ifdef' to check the values of +preprocessor macros defined by tests that have already run. For +example, if you call 'AC_HEADER_STDC', then later on in 'configure.ac' +you can have a test program that includes an ANSI C header file +conditionally: + + #if STDC_HEADERS + # include <stdlib.h> + #endif + + If a test program needs to use or create a data file, give it a name +that starts with 'conftest', such as 'conftest.data'. The 'configure' +script cleans up by running 'rm -rf conftest*' after running test +programs and if the script is interrupted. + + +File: autoconf.info, Node: Test Functions, Prev: Guidelines, Up: Run Time + +6.4.3 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. + + #ifdef __cplusplus + foo (int i) + #else + foo (i) int i; + #endif + + Functions that test programs declare should also be conditionalized +for C++, which requires 'extern "C"' prototypes. Make sure to not +include any header files containing clashing prototypes. + + #ifdef __cplusplus + extern "C" void *malloc (size_t); + #else + char *malloc (); + #endif + + 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 'exit', because GCC version 2 knows that '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, '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 'char'). + + +File: autoconf.info, Node: Systemology, Next: Multiple Cases, Prev: Run Time, Up: Writing Tests + +6.5 Systemology +=============== + +This section aims at presenting some systems and pointers to +documentation. It may help you addressing particular problems reported +by users. + +QNX 4.25 + 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 POSIX certified. More + information is available on the QNX home page(1), including the QNX + man pages(2). + + ---------- Footnotes ---------- + + (1) QNX home page, <www.qnx.com>. + + (2) QNX man pages, <http://support.qnx.com/support/docs/qnx4/>. + + +File: autoconf.info, Node: Multiple Cases, Next: Language Choice, Prev: Systemology, Up: Writing Tests + +6.6 Multiple Cases +================== + +Some operations are accomplished in several possible ways, depending on +the UNIX variant. Checking for them essentially requires a "case +statement". Autoconf does not directly provide one; however, it is easy +to simulate by using a shell variable to keep track of whether a way to +perform the operation has been found yet. + + Here is an example that uses the shell variable 'fstype' to keep +track of whether the remaining cases need to be checked. + + 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]) + + +File: autoconf.info, Node: Language Choice, Prev: Multiple Cases, Up: Writing Tests + +6.7 Language Choice +=================== + +Autoconf-generated '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 +'configure.ac'. + + -- Macro: AC_LANG (LANGUAGE) + Do compilation tests using the compiler, preprocessor and file + extensions for the specified LANGUAGE. + + Supported languages are: + + 'C' + Do compilation tests using 'CC' and 'CPP' and use extension + '.c' for test programs. + + 'C++' + Do compilation tests using 'CXX' and 'CXXCPP' and use + extension '.C' for test programs. + + 'Fortran 77' + Do compilation tests using 'F77' and use extension '.f' for + test programs. + + -- Macro: AC_LANG_PUSH (LANGUAGE) + Remember the current language (as set by 'AC_LANG') on a stack, and + then select the LANGUAGE. Use this macro and 'AC_LANG_POP' in + macros that need to temporarily switch to a particular language. + + -- Macro: AC_LANG_POP ([LANGUAGE]) + Select the language that is saved on the top of the stack, as set + by 'AC_LANG_PUSH', and remove it from the stack. + + If given, LANGUAGE specifies the language we just _quit_. It is a + good idea to specify it when it's known (which should be the + case...), since Autoconf will detect inconsistencies. + + AC_LANG_PUSH(Fortran 77) + # Perform some tests on Fortran 77. + # ... + AC_LANG_POP(Fortran 77) + + -- Macro: AC_REQUIRE_CPP + Ensure that whichever preprocessor would currently be used for + tests has been found. Calls 'AC_REQUIRE' (*note Prerequisite + Macros::) with an argument of either 'AC_PROG_CPP' or + 'AC_PROG_CXXCPP', depending on which language is current. + + +File: autoconf.info, Node: Results, Next: Programming in M4, Prev: Writing Tests, Up: Top + +7 Results of Tests +****************** + +Once '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 '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 'configure' runs +* Printing Messages:: Notifying 'configure' users + + +File: autoconf.info, Node: Defining Symbols, Next: Setting Output Variables, Prev: Results, Up: Results + +7.1 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 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED'. + + By default, 'AC_OUTPUT' places the symbols defined by these macros +into the output variable 'DEFS', which contains an option +'-DSYMBOL=VALUE' for each symbol defined. Unlike in Autoconf version 1, +there is no variable 'DEFS' defined while '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: + + 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 + + If 'AC_CONFIG_HEADERS' has been called, then instead of creating +'DEFS', 'AC_OUTPUT' creates a header file by substituting the correct +values into '#define' statements in a template file. *Note +Configuration Headers::, for more information about this kind of output. + + -- Macro: AC_DEFINE (VARIABLE, [VALUE], [DESCRIPTION]) + Define C preprocessor variable VARIABLE. If VALUE is given, set + VARIABLE to that value (verbatim), otherwise set it to 1. VALUE + should not contain literal newlines, and if you are not using + 'AC_CONFIG_HEADERS' it should not contain any '#' characters, as + '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 + '[' or ']'), use 'AC_DEFINE_UNQUOTED' instead. DESCRIPTION is only + useful if you are using 'AC_CONFIG_HEADERS'. In this case, + DESCRIPTION is put into the generated 'config.h.in' as the comment + before the macro define. The following example defines the C + preprocessor variable 'EQUATION' to be the string constant '"$a > + $b"': + + AC_DEFINE(EQUATION, "$a > $b") + + -- Macro: AC_DEFINE_UNQUOTED (VARIABLE, [VALUE], [DESCRIPTION]) + Like 'AC_DEFINE', but three shell expansions are + performed--once--on VARIABLE and VALUE: variable expansion ('$'), + command substitution ('`'), and backslash escaping ('\'). Single + and double quote characters in the value have no special meaning. + Use this macro instead of 'AC_DEFINE' when VARIABLE or VALUE is a + shell variable. Examples: + + AC_DEFINE_UNQUOTED(config_machfile, "$machfile") + AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) + AC_DEFINE_UNQUOTED($ac_tr_hdr) + + Due to the syntactical bizarreness of the Bourne shell, do not use +semicolons to separate 'AC_DEFINE' or 'AC_DEFINE_UNQUOTED' calls from +other macro calls or shell code; that can cause syntax errors in the +resulting 'configure' script. Use either spaces or newlines. That is, +do this: + + AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4) LIBS="$LIBS -lelf"]) + +or this: + + AC_CHECK_HEADER(elf.h, + [AC_DEFINE(SVR4) + LIBS="$LIBS -lelf"]) + +instead of this: + + AC_CHECK_HEADER(elf.h, [AC_DEFINE(SVR4); LIBS="$LIBS -lelf"]) + + +File: autoconf.info, Node: Setting Output Variables, Next: Caching Results, Prev: Defining Symbols, Up: Results + +7.2 Setting Output Variables +============================ + +Another way to record the results of tests is to set "output variables", +which are shell variables whose values are substituted into files that +'configure' outputs. The two macros below create new output variables. +*Note Preset Output Variables::, for a list of output variables that are +always available. + + -- Macro: AC_SUBST (VARIABLE, [VALUE]) + Create an output variable from a shell variable. Make 'AC_OUTPUT' + substitute the variable VARIABLE into output files (typically one + or more 'Makefile's). This means that 'AC_OUTPUT' will replace + instances of '@VARIABLE@' in input files with the value that the + shell variable VARIABLE has when 'AC_OUTPUT' is called. This value + of VARIABLE should not contain literal newlines. + + If VALUE is given, in addition assign it to 'variable'. + + -- Macro: AC_SUBST_FILE (VARIABLE) + Another way to create an output variable from a shell variable. + Make 'AC_OUTPUT' insert (without substitutions) the contents of the + file named by shell variable VARIABLE into output files. This + means that 'AC_OUTPUT' will replace instances of '@VARIABLE@' in + output files (such as 'Makefile.in') with the contents of the file + that the shell variable VARIABLE names when 'AC_OUTPUT' is called. + Set the variable to '/dev/null' for cases that do not have a file + to insert. + + This macro is useful for inserting 'Makefile' fragments containing + special dependencies or other 'make' directives for particular host + or target types into 'Makefile's. For example, 'configure.ac' + could contain: + + AC_SUBST_FILE(host_frag) + host_frag=$srcdir/conf/sun4.mh + + and then a 'Makefile.in' could contain: + + @host_frag@ + + Running 'configure' in different environments can be extremely +dangerous. If for instance the user runs 'CC=bizarre-cc ./configure', +then the cache, 'config.h' and many other output files will depend upon +'bizarre-cc' being the C compiler. If for some reason the user runs +'/configure' again, or if it is run via './config.status --recheck', +(*Note Automatic Remaking::, and *note config.status Invocation::), then +the configuration can be inconsistent, composed of results depending +upon two different compilers. + + Such variables are named "precious variables", and can be declared as +such by 'AC_ARG_VAR'. + + -- Macro: AC_ARG_VAR (VARIABLE, DESCRIPTION) + Declare VARIABLE is a precious variable, and include its + DESCRIPTION in the variable section of './configure --help'. + + Being precious means that + - VARIABLE is 'AC_SUBST''d. + + - VARIABLE is kept in the cache including if it was not + specified on the './configure' command line. Indeed, while + 'configure' can notice the definition of 'CC' in './configure + CC=bizarre-cc', it is impossible to notice it in + 'CC=bizarre-cc ./configure', which, unfortunately, is what + most users do. + + - VARIABLE is checked for consistency between two 'configure' + runs. For instance: + + $ ./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 + + and similarly if the variable is unset, or if its content is + changed. + + - VARIABLE is kept during automatic reconfiguration (*note + config.status Invocation::) as if it had been passed as a + command line argument, including when no cache is used: + + $ 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 + + +File: autoconf.info, Node: Caching Results, Next: Printing Messages, Prev: Setting Output Variables, Up: Results + +7.3 Caching Results +=================== + +To avoid checking for the same features repeatedly in various +'configure' scripts (or in repeated runs of one script), 'configure' can +optionally save the results of many checks in a "cache file" (*note +Cache Files::). If a '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, 'configure' can then +run much faster than if it had to perform all of the checks every time. + + -- Macro: AC_CACHE_VAL (CACHE-ID, COMMANDS-TO-SET-IT) + Ensure that the results of the check identified by CACHE-ID are + available. If the results of the check were in the cache file that + was read, and 'configure' was not given the '--quiet' or '--silent' + option, print a message saying that the result was cached; + otherwise, run the shell commands 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 'configure' creates its output files. + *Note Cache Variable Names::, for how to choose the name of the + CACHE-ID variable. + + The COMMANDS-TO-SET-IT _must have no side effects_ except for + setting the variable CACHE-ID, see below. + + -- Macro: AC_CACHE_CHECK (MESSAGE, CACHE-ID, COMMANDS-TO-SET-IT) + A wrapper for '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 'AC_MSG_CHECKING' for + MESSAGE, then 'AC_CACHE_VAL' with the CACHE-ID and COMMANDS + arguments, and 'AC_MSG_RESULT' with CACHE-ID. + + The COMMANDS-TO-SET-IT _must have no side effects_ except for + setting the variable CACHE-ID, see below. + + It is very common to find buggy macros using 'AC_CACHE_VAL' or +'AC_CACHE_CHECK', because people are tempted to call 'AC_DEFINE' in the +COMMANDS-TO-SET-IT. Instead, the code that _follows_ the call to +'AC_CACHE_VAL' should call 'AC_DEFINE', by examining the value of the +cache variable. For instance, the following macro is broken: + + 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]) + ]) + +This fails if the cache is enabled: the second time this macro is run, +'TRUE_WORKS' _will not be defined_. The proper implementation is: + + 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 + ]) + + Also, COMMANDS-TO-SET-IT should not print any messages, for example +with 'AC_MSG_CHECKING'; do that before calling '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 'configure' uses for caching +* Cache Checkpointing:: Loading and saving the cache file + + +File: autoconf.info, Node: Cache Variable Names, Next: Cache Files, Prev: Caching Results, Up: Caching Results + +7.3.1 Cache Variable Names +-------------------------- + +The names of cache variables should have the following format: + + PACKAGE-PREFIX_cv_VALUE-TYPE_SPECIFIC-VALUE_[ADDITIONAL-OPTIONS] + +for example, 'ac_cv_header_stat_broken' or 'ac_cv_prog_gcc_traditional'. +The parts of the variable name are: + +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 'ac'. + +'_cv_' + Indicates that this shell variable is a cache value. This string + _must_ be present in the variable name, including the leading + underscore. + +VALUE-TYPE + A convention for classifying cache values, to produce a rational + naming system. The values used in Autoconf are listed in *note + Macro Names::. + +SPECIFIC-VALUE + Which member of the class of cache values this test applies to. + For example, which function ('alloca'), program ('gcc'), or output + variable ('INSTALL'). + +ADDITIONAL-OPTIONS + Any particular behavior of the specific member that this test + applies to. For example, 'broken' or 'set'. This part of the name + may be omitted if it does not apply. + + The values assigned to cache variables may not contain newlines. +Usually, their values will be boolean ('yes' or 'no') or the names of +files or functions; so this is not an important restriction. + + +File: autoconf.info, Node: Cache Files, Next: Cache Checkpointing, Prev: Cache Variable Names, Up: Caching Results + +7.3.2 Cache Files +----------------- + +A cache file is a shell script that caches the results of configure +tests run on one system so they can be shared between configure scripts +and configure runs. It is not useful on other systems. If its contents +are invalid for some reason, the user may delete or edit it. + + By default, 'configure' uses no cache file (technically, it uses +'--cache-file=/dev/null'), to avoid problems caused by accidental use of +stale cache files. + + To enable caching, 'configure' accepts '--config-cache' (or '-C') to +cache results in the file 'config.cache'. Alternatively, +'--cache-file=FILE' specifies that FILE be the cache file. The cache +file is created if it does not exist already. When 'configure' calls +'configure' scripts in subdirectories, it uses the '--cache-file' +argument so that they share the same cache. *Note Subdirectories::, for +information on configuring subdirectories with the 'AC_CONFIG_SUBDIRS' +macro. + + 'config.status' only pays attention to the cache file if it is given +the '--recheck' option, which makes it rerun '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 (*note 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 +'configure' script. (Running '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. + + +File: autoconf.info, Node: Cache Checkpointing, Prev: Cache Files, Up: Caching Results + +7.3.3 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 '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. + + -- Macro: AC_CACHE_LOAD + Loads values from existing cache file, or creates a new cache file + if a cache file is not found. Called automatically from 'AC_INIT'. + + -- Macro: AC_CACHE_SAVE + Flushes all cached values to the cache file. Called automatically + from 'AC_OUTPUT', but it can be quite useful to call + 'AC_CACHE_SAVE' at key points in configure.ac. + + For instance: + + ... AC_INIT, etc. ... + # Checks for programs. + AC_PROG_CC + AC_PROG_GCC_TRADITIONAL + ... more program checks ... + AC_CACHE_SAVE + + # Checks for libraries. + AC_CHECK_LIB(nsl, gethostbyname) + AC_CHECK_LIB(socket, connect) + ... more lib checks ... + AC_CACHE_SAVE + + # Might abort... + AM_PATH_GTK(1.0.2,, (exit 1); exit) + AM_PATH_GTKMM(0.9.5,, (exit 1); exit) + ... AC_OUTPUT, etc. ... + + +File: autoconf.info, Node: Printing Messages, Prev: Caching Results, Up: Results + +7.4 Printing Messages +===================== + +'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 'echo' shell command. +'configure' scripts should rarely need to run '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 'autoconf' is run, see *note +Reporting Messages::. + + -- Macro: AC_MSG_CHECKING (FEATURE-DESCRIPTION) + Notify the user that 'configure' is checking for a particular + feature. This macro prints a message that starts with 'checking ' + and ends with '...' and no newline. It must be followed by a call + to 'AC_MSG_RESULT' to print the result of the check and the + newline. The FEATURE-DESCRIPTION should be something like 'whether + the Fortran compiler accepts C++ comments' or 'for c89'. + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION) + Notify the user of the results of a check. RESULT-DESCRIPTION is + almost always the value of the cache variable for the check, + typically 'yes', 'no', or a file name. This macro should follow a + call to 'AC_MSG_CHECKING', and the RESULT-DESCRIPTION should be the + completion of the message printed by the call to 'AC_MSG_CHECKING'. + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_NOTICE (MESSAGE) + Deliver the 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., + + AC_MSG_NOTICE([checking if stack overflow is detectable]) + + This macro prints nothing if 'configure' is run with the '--quiet' + or '--silent' option. + + -- Macro: AC_MSG_ERROR (ERROR-DESCRIPTION, [EXIT-STATUS]) + Notify the user of an error that prevents 'configure' from + completing. This macro prints an error message to the standard + error output and exits 'configure' with EXIT-STATUS (1 by default). + ERROR-DESCRIPTION should be something like 'invalid value $HOME for + \$HOME'. + + The ERROR-DESCRIPTION should start with a lower-case letter, and + "cannot" is preferred to "can't". + + -- Macro: AC_MSG_WARN (PROBLEM-DESCRIPTION) + Notify the 'configure' user of a possible problem. This macro + prints the message to the standard error output; 'configure' + continues running afterward, so macros that call 'AC_MSG_WARN' + should provide a default (back-up) behavior for the situations they + warn about. PROBLEM-DESCRIPTION should be something like 'ln -s + seems to make hard links'. + + +File: autoconf.info, Node: Programming in M4, Next: Writing Autoconf Macros, Prev: Results, Up: Top + +8 Programming in M4 +******************* + +Autoconf is written on top of two layers: "M4sugar", which provides +convenient macros for pure M4 programming, and "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, _anything that is not documented must not be used_. + +* Menu: + +* M4 Quotation:: Protecting macros from unwanted expansion +* Programming in M4sugar:: Convenient pure M4 macros + + +File: autoconf.info, Node: M4 Quotation, Next: Programming in M4sugar, Prev: Programming in M4, Up: Programming in M4 + +8.1 M4 Quotation +================ + +The most common brokenness of existing macros is an improper quotation. +This section, which users of Autoconf can skip, but which macro writers +_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 + + +File: autoconf.info, Node: Active Characters, Next: One Macro Call, Prev: M4 Quotation, Up: M4 Quotation + +8.1.1 Active Characters +----------------------- + +To fully understand where proper quotation is important, you first need +to know what are the special characters in Autoconf: '#' introduces a +comment inside which no macro expansion is performed, ',' separates +arguments, '[' and ']' are the quotes themselves, and finally '(' and +')' (which '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: + + # define([def], ine) + =># define([def], ine) + + Each time there can be a macro expansion, there is a quotation +expansion; i.e., one level of quotes is stripped: + + int tab[10]; + =>int tab10; + [int tab[10];] + =>int tab[10]; + + Without this in mind, the reader will try hopelessly to use her macro +'array': + + define([array], [int tab[10];]) + array + =>int tab10; + [array] + =>array + +How can you correctly output the intended results(1)? + + ---------- Footnotes ---------- + + (1) Using 'defn'. + + +File: autoconf.info, Node: One Macro Call, Next: Quotation and Nested Macros, Prev: Active Characters, Up: M4 Quotation + +8.1.2 One Macro Call +-------------------- + +Let's proceed on the interaction between active characters and macros +with this small macro, which just returns its first argument: + + define([car], [$1]) + +The two pairs of quotes above are not part of the arguments of 'define'; +rather, they are understood by the top level when it tries to find the +arguments of 'define'. Therefore, it is equivalent to write: + + define(car, $1) + +But, while it is acceptable for a '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: + + car(foo, bar, baz) + =>foo + [car(foo, bar, baz)] + =>car(foo, bar, baz) + + Let's pay attention to the special characters: + + car(#) + error->EOF in argument list + + The closing parenthesis is hidden in the comment; with a hypothetical +quoting, the top level understood it this way: + + car([#)] + +Proper quotation, of course, fixes the problem: + + car([#]) + =># + + The reader will easily understand the following examples: + + car(foo, bar) + =>foo + car([foo, bar]) + =>foo, bar + car((foo, bar)) + =>(foo, bar) + car([(foo], [bar)]) + =>(foo + car([], []) + => + car([[]], [[]]) + =>[] + + With this in mind, we can explore the cases where macros invoke +macros... + + +File: autoconf.info, Node: Quotation and Nested Macros, Next: Quadrigraphs, Prev: One Macro Call, Up: M4 Quotation + +8.1.3 Quotation and Nested Macros +--------------------------------- + +The examples below use the following macros: + + define([car], [$1]) + define([active], [ACT, IVE]) + define([array], [int tab[10]]) + + Each additional embedded macro call introduces other possible +interesting quotations: + + car(active) + =>ACT + car([active]) + =>ACT, IVE + car([[active]]) + =>active + + In the first case, the top level looks for the arguments of 'car', +and finds 'active'. Because 'm4' evaluates its arguments before +applying the macro, 'active' is expanded, which results in: + + car(ACT, IVE) + =>ACT + +In the second case, the top level gives 'active' as first and only +argument of 'car', which results in: + + active + =>ACT, IVE + +i.e., the argument is evaluated _after_ the macro that invokes it. In +the third case, 'car' receives '[active]', which results in: + + [active] + =>active + +exactly as we already saw above. + + The example above, applied to a more realistic example, gives: + + car(int tab[10];) + =>int tab10; + car([int tab[10];]) + =>int tab10; + car([[int tab[10];]]) + =>int tab[10]; + +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 '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 'car' macro, and +second after the 'car' macro expands to the first argument. + + As the author of the Autoconf macro 'car', you then consider it to be +incorrect that your users have to double-quote the arguments of 'car', +so you "fix" your macro. Let's call it 'qar' for quoted car: + + define([qar], [[$1]]) + +and check that 'qar' is properly fixed: + + qar([int tab[10];]) + =>int tab[10]; + +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 _unquoted_ macro call: + + qar(active) + =>ACT + +where she wanted to reproduce what she used to do with 'car': + + car([active]) + =>ACT, IVE + +Worse yet: she wants to use a macro that produces a set of 'cpp' macros: + + define([my_includes], [#include <stdio.h>]) + car([my_includes]) + =>#include <stdio.h> + qar(my_includes) + error->EOF in argument list + + This macro, '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 'm4' before they are given +to the macro, often not in the way the users expect. Also, because +'qar' behaves differently from the other macros, it's an exception that +should be avoided in Autoconf. + + +File: autoconf.info, Node: Quadrigraphs, Next: Quotation Rule Of Thumb, Prev: Quotation and Nested Macros, Up: M4 Quotation + +8.1.4 Quadrigraphs +------------------ + +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 '[^[]', which matches any character other than '['. 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 +"quadrigraphs": + +'@<:@' + '[' +'@:>@' + ']' +'@S|@' + '$' +'@%:@' + '#' + + Quadrigraphs are replaced at a late stage of the translation process, +after 'm4' is run, so they do not get in the way of M4 quoting. For +example, the string '[^@<:@]', if properly quoted, will appear as '[^[]' +in the 'configure' script. + + +File: autoconf.info, Node: Quotation Rule Of Thumb, Prev: Quadrigraphs, Up: M4 Quotation + +8.1.5 Quotation Rule Of Thumb +----------------------------- + +To conclude, the quotation rule of thumb is: + + _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 _the +arguments_! + + It is common to read Autoconf programs with snippets like: + + 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) + +which is incredibly useless since 'AC_TRY_LINK' is _already_ double +quoting, so you just need: + + 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]) + +The M4-fluent reader will note that these two examples are rigorously +equivalent, since 'm4' swallows both the 'changequote(<<, >>)' and '<<' +'>>' when it "collects" the arguments: these quotes are not part of the +arguments! + + Simplified, the example above is just doing this: + + changequote(<<, >>)dnl + <<[]>> + changequote([, ])dnl + +instead of simply: + + [[]] + + With macros that do not double quote their arguments (which is the +rule), double-quote the (risky) literals: + + 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]) + + See *Note Quadrigraphs::, for what to do if you run into a hopeless +case where quoting does not suffice. + + When you create a '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 '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 'configure' script will contain unexpanded +macros. The 'autoconf' program checks for this problem by doing 'grep +AC_ configure'. + + +File: autoconf.info, Node: Programming in M4sugar, Prev: M4 Quotation, Up: Programming in M4 + +8.2 Programming in 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 + + +File: autoconf.info, Node: Redefined M4 Macros, Next: Forbidden Patterns, Prev: Programming in M4sugar, Up: Programming in M4sugar + +8.2.1 Redefined M4 Macros +------------------------- + +All the M4 native macros are moved in the 'm4_' pseudo-namespace, e.g., +M4sugar renames 'define' as 'm4_define' etc. There is one exception: +'dnl' kept its original name, and no 'm4_dnl' is defined. + + M4sugar redefines some M4 macros, and made them slightly incompatible +with their native equivalent. + + -- Macro: m4_defn (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. See 'm4_undefine'. + + -- Macro: m4_undefine (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. Use + + m4_ifdef([MACRO], [m4_undefine([MACRO])]) + + to recover the behavior of the builtin. + + -- Macro: m4_popdef (MACRO) + Contrary to the M4 builtin, this macro fails if MACRO is not + defined. See 'm4_undefine'. + + +File: autoconf.info, Node: Forbidden Patterns, Prev: Redefined M4 Macros, Up: Programming in M4sugar + +8.2.2 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 'configure' script includes tokens such as +'AC_DEFINE', or 'dnl', then most probably something went wrong +(typically a macro was not evaluated because of over quotation). + + M4sugar forbids all the tokens matching '^m4_' and '^dnl$'. + + -- Macro: m4_pattern_forbid (PATTERN) + Declare no token matching 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 '#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 + '#'-comments should document the output, not the input, documented + vy 'dnl'-comments). + + Of course, you might encounter exceptions to these generic rules, for +instance you might have to refer to '$m4_flags'. + + -- Macro: m4_pattern_allow (PATTERN) + Any token matching PATTERN is allowed, including if it matches an + 'm4_pattern_forbid' pattern. + + +File: autoconf.info, Node: Writing Autoconf Macros, Next: Portable Shell, Prev: Programming in M4, Up: Top + +9 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 '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 à la Autoconf + + +File: autoconf.info, Node: Macro Definitions, Next: Macro Names, Prev: Writing Autoconf Macros, Up: Writing Autoconf Macros + +9.1 Macro Definitions +===================== + +Autoconf macros are defined using the 'AC_DEFUN' macro, which is similar +to the M4 builtin 'define' macro. In addition to defining a macro, +'AC_DEFUN' adds to it some code that is used to constrain the order in +which macros are called (*note Prerequisite Macros::). + + An Autoconf macro definition looks like this: + + AC_DEFUN(MACRO-NAME, MACRO-BODY) + + You can refer to any arguments passed to the macro as '$1', '$2', +etc. *Note How to define new macros: (m4.info)Definitions, for more +complete information on writing M4 macros. + + Be sure to properly quote both the MACRO-BODY _and_ the 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: + + # AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) + # -------------------------------------- + define([AC_MSG_ERROR], + [{ _AC_ECHO([configure: error: $1], 2); exit m4_default([$2], 1); }]) + + Comments about the macro should be left in the header comment. Most +other comments will make their way into 'configure', so just keep using +'#' to introduce comments. + + If you have some very special comments about pure M4 code, comments +that make no sense in 'configure' and in the header comment, then use +the builtin 'dnl': it causes 'm4' to discard the text through the next +newline. + + Keep in mind that 'dnl' is rarely needed to introduce comments; 'dnl' +is more useful to get rid of the newlines following macros that produce +no output, such as 'AC_REQUIRE'. + + +File: autoconf.info, Node: Macro Names, Next: Reporting Messages, Prev: Macro Definitions, Up: Writing Autoconf Macros + +9.2 Macro Names +=============== + +All of the Autoconf macros have all-uppercase names starting with '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 '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 (*note Cache Variable Names::, for more +information on them). + + The first word of the name after '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. + +'C' + C language builtin features. +'DECL' + Declarations of C variables in header files. +'FUNC' + Functions in libraries. +'GROUP' + UNIX group owners of files. +'HEADER' + Header files. +'LIB' + C libraries. +'PATH' + The full path names to files, including programs. +'PROG' + The base names of programs. +'MEMBER' + Members of aggregates. +'SYS' + Operating system features. +'TYPE' + C builtin or declared types. +'VAR' + C variables in libraries. + + 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, 'AC_FUNC_UTIME_NULL' checks the behavior +of the 'utime' function when called with a 'NULL' pointer. + + An internal macro should have a name that starts with an underscore; +Autoconf internals should therefore start with '_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, 'AC_PATH_X' has internal macros '_AC_PATH_X_XMKMF' and +'_AC_PATH_X_DIRECT'. + + +File: autoconf.info, Node: Reporting Messages, Next: Dependencies Between Macros, Prev: Macro Names, Up: Writing Autoconf Macros + +9.3 Reporting Messages +====================== + +When macros statically diagnose abnormal situations, benign or fatal, +they should report them using these macros. For dynamic issues, i.e., +when 'configure' is run, see *note Printing Messages::. + + -- Macro: AC_DIAGNOSE (CATEGORY, MESSAGE) + Report MESSAGE as a warning (or as an error if requested by the + user) if it falls into the CATEGORY. You are encouraged to use + standard categories, which currently include: + + 'all' + messages that don't fall into one of the following category. + Use of an empty CATEGORY is equivalent. + + 'cross' + related to cross compilation issues. + + 'obsolete' + use of an obsolete construct. + + 'syntax' + dubious syntactic constructs, incorrectly ordered macro calls. + + -- Macro: AC_WARNING (MESSAGE) + Equivalent to 'AC_DIAGNOSE([syntax], MESSAGE)', but you are + strongly encouraged to use a finer grained category. + + -- Macro: AC_FATAL (MESSAGE) + Report a severe error MESSAGE, and have 'autoconf' die. + + When the user runs 'autoconf -W error', warnings from 'AC_DIAGNOSE' +and 'AC_WARNING' are reported as error, see *note autoconf Invocation::. + + +File: autoconf.info, Node: Dependencies Between Macros, Next: Obsoleting Macros, Prev: Reporting Messages, Up: Writing Autoconf Macros + +9.4 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 + + +File: autoconf.info, Node: Prerequisite Macros, Next: Suggested Ordering, Prev: Dependencies Between Macros, Up: Dependencies Between Macros + +9.4.1 Prerequisite Macros +------------------------- + +A macro that you write might need to use values that have previously +been computed by other macros. For example, 'AC_DECL_YYTEXT' examines +the output of 'flex' or 'lex', so it depends on 'AC_PROG_LEX' having +been called first to set the shell variable 'LEX'. + + Rather than forcing the user of the macros to keep track of the +dependencies between them, you can use the 'AC_REQUIRE' macro to do it +automatically. 'AC_REQUIRE' can ensure that a macro is only called if +it is needed, and only called once. + + -- Macro: AC_REQUIRE (MACRO-NAME) + If the M4 macro MACRO-NAME has not already been called, call it + (without any arguments). Make sure to quote MACRO-NAME with square + brackets. MACRO-NAME must have been defined using 'AC_DEFUN' or + else contain a call to 'AC_PROVIDE' to indicate that it has been + called. + + 'AC_REQUIRE' must be used inside an 'AC_DEFUN''d macro; it must not + be called from the top level. + + '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 _before_ the body of the former. +In particular, 'AC_REQUIRE(FOO)' is not replaced with the body of 'FOO'. +For instance, this definition of macros: + + AC_DEFUN([TRAVOLTA], + [test "$body_temparature_in_celsius" -gt "38" && + dance_floor=occupied]) + AC_DEFUN([NEWTON_JOHN], + [test "$hair_style" = "curly" && + dance_floor=occupied]) + + AC_DEFUN([RESERVE_DANCE_FLOOR], + [if date | grep '^Sat.*pm' >/dev/null 2>&1; then + AC_REQUIRE([TRAVOLTA]) + AC_REQUIRE([NEWTON_JOHN]) + fi]) + +with this 'configure.ac' + + AC_INIT + RESERVE_DANCE_FLOOR + if test "$dance_floor" = occupied; then + AC_MSG_ERROR([cannot pick up here, let's move]) + fi + +will not leave you with a better chance to meet a kindred soul at other +times than Saturday night since it expands into: + + 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 + + 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: + + if ...; then + AC_REQUIRE([SOME_CHECK]) + fi + ... + SOME_CHECK + + You are encouraged to put all 'AC_REQUIRE's at the beginning of a +macro. You can use 'dnl' to avoid the empty lines they leave. + + +File: autoconf.info, Node: Suggested Ordering, Prev: Prerequisite Macros, Up: Dependencies Between Macros + +9.4.2 Suggested Ordering +------------------------ + +Some macros should be run before another macro if both are called, but +neither _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 'AC_BEFORE' macro to warn users when macros +with this kind of dependency appear out of order in a 'configure.ac' +file. The warning occurs when creating 'configure' from 'configure.ac', +not when running 'configure'. + + For example, 'AC_PROG_CPP' checks whether the C compiler can run the +C preprocessor when given the '-E' option. It should therefore be +called after any macros that change which C compiler is being used, such +as 'AC_PROG_CC'. So 'AC_PROG_CC' contains: + + AC_BEFORE([$0], [AC_PROG_CPP])dnl + +This warns the user if a call to 'AC_PROG_CPP' has already occurred when +'AC_PROG_CC' is called. + + -- Macro: AC_BEFORE (THIS-MACRO-NAME, CALLED-MACRO-NAME) + Make 'm4' print a warning message to the standard error output if + CALLED-MACRO-NAME has already been called. THIS-MACRO-NAME should + be the name of the macro that is calling 'AC_BEFORE'. The macro + CALLED-MACRO-NAME must have been defined using 'AC_DEFUN' or else + contain a call to 'AC_PROVIDE' to indicate that it has been called. + + +File: autoconf.info, Node: Obsoleting Macros, Next: Coding Style, Prev: Dependencies Between Macros, Up: Writing Autoconf Macros + +9.5 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 "obsolete"; they still work, but are no longer considered the +best thing to do, hence they should be replaced with more modern macros. +Ideally, 'autoupdate' should substitute the old macro calls with their +modern implementation. + + Autoconf provides a simple means to obsolete a macro. + + -- Macro: AU_DEFUN (OLD-MACRO, IMPLEMENTATION, [MESSAGE]) + Define OLD-MACRO as IMPLEMENTATION. The only difference with + 'AC_DEFUN' is that the user will be warned that OLD-MACRO is now + obsolete. + + If she then uses 'autoupdate', the call to OLD-MACRO will be + replaced by the modern IMPLEMENTATION. The additional MESSAGE is + then printed. + + +File: autoconf.info, Node: Coding Style, Prev: Obsoleting Macros, Up: Writing Autoconf Macros + +9.6 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 *note Autoconf Language::, and *note 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 _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 (*note Macro Names::), +you are unlikely to generate conflicts. Nevertheless, when you need to +set a special value, _avoid using a regular macro name_; rather, use an +"impossible" name. For instance, up to version 2.13, the macro +'AC_SUBST' used to remember what SYMBOLs were already defined by setting +'AC_SUBST_SYMBOL', which is a regular macro name. But since there is a +macro named 'AC_SUBST_FILE', it was just impossible to 'AC_SUBST(FILE)'! +In this case, 'AC_SUBST(SYMBOL)' or '_AC_SUBST(SYMBOL)' should have been +used (yes, with the parentheses)...or better yet, high-level macros such +as '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 '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. + + Do not use '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 'configure'. There are +exceptional cases where you do want to comment special M4 constructs, in +which case '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 + + 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])]) + +write + + 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])]) + +or even + + 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])]) + + When using 'AC_TRY_RUN' or any macro that cannot work when +cross-compiling, provide a pessimistic value (typically 'no'). + + Feel free to use various tricks to prevent auxiliary tools, such as +syntax-highlighting editors, from behaving improperly. For instance, +instead of: + + patsubst([$1], [$"]) + +use + + patsubst([$1], [$""]) + +so that Emacsen do not open a endless "string" at the first quote. For +the same reasons, avoid: + + test $[#] != 0 + +and use: + + test $[@%:@] != 0 + +Otherwise, the closing bracket would be hidden inside a '#'-comment, +breaking the bracket-matching highlighting from Emacsen. Note the +preferred style to escape from M4: '$[1]', '$[@]', etc. Do not escape +when it is unneeded. Common examples of useless quotation are '[$]$1' +(write '$$1'), '[$]var' (use '$var'), etc. If you add portability +issues to the picture, you'll prefer '${1+"$[@]"}' to '"[$]@"', and +you'll prefer do something better than hacking Autoconf ':-)'. + + When using 'sed', don't use '-e' except for indenting purpose. With +the 's' command, the preferred separator is '/' unless '/' itself is +used in the command, in which case you should use ','. + + *Note Macro Definitions::, for details on how to define a macro. If +a macro doesn't use 'AC_REQUIRE' and it is expected to never be the +object of an 'AC_REQUIRE' directive, then use 'define'. In case of +doubt, use 'AC_DEFUN'. All the 'AC_REQUIRE' statements should be at the +beginning of the macro, '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 '])' 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 +'configure'; normally, that is not a problem, but if you want to remove +it you can use '[]dnl' on the last line. You can similarly use '[]dnl' +after a macro call to remove its newline. '[]dnl' is recommended +instead of 'dnl' to ensure that M4 does not interpret the 'dnl' as being +attached to the preceding text or macro output. For example, instead +of: + + AC_DEFUN([AC_PATH_X], + [AC_MSG_CHECKING([for X]) + AC_REQUIRE_CPP() + # ...omitted... + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) + fi]) + +you would write: + + AC_DEFUN([AC_PATH_X], + [AC_REQUIRE_CPP()[]dnl + AC_MSG_CHECKING([for X]) + # ...omitted... + AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) + fi[]dnl + ])# AC_PATH_X + + 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 +'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: + + 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]) + +and the new way: + + # _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 + + +File: autoconf.info, Node: Portable Shell, Next: Manual Configuration, Prev: Writing Autoconf Macros, Up: Top + +10 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 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 'unset' is not +supported by all shells! Also, include a space after the exclamation +point in interpreter specifications, like this: + + #! /usr/bin/perl + +If you omit the space before the path, then 4.2BSD based systems (such +as Sequent DYNIX) will ignore the line, because they interpret '#! /' as +a 4-byte magic number. + + The set of external programs you should run in a 'configure' script +is fairly small. *Note Utilities in Makefiles: (standards)Utilities in +Makefiles, 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 *note 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 + + +File: autoconf.info, Node: Shellology, Next: Here-Documents, Prev: Portable Shell, Up: Portable Shell + +10.1 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. + +Ash + 'ash' is often used on GNU/Linux and 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 GNU/Linux + distributions. + + To be compatible with Ash 0.2: + + - don't use '$?' after expanding empty or unset variables: + + foo= + false + $foo + echo "Don't use it: $?" + + - don't use command substitution within variable expansion: + + cat ${FOO=`bar`} + + - beware that single builtin substitutions are not performed by + a sub shell, hence their effect applies to the current shell! + *Note Shell Substitutions::, item "Command Substitution". + +Bash + To detect whether you are running 'bash', test if 'BASH_VERSION' is + set. To disable its extensions and require POSIX compatibility, + run 'set -o posix'. *Note Bash POSIX Mode: (bash)Bash POSIX Mode, + for details. + +'/usr/xpg4/bin/sh' on Solaris + The POSIX-compliant Bourne shell on a Solaris system is + '/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. + +Zsh + To detect whether you are running 'zsh', test if 'ZSH_VERSION' is + set. By default 'zsh' is _not_ compatible with the Bourne shell: + you have to run 'emulate sh' and set 'NULLCMD' to ':'. *Note + Compatibility: (zsh)Compatibility, for details. + + Zsh 3.0.8 is the native '/bin/sh' on Mac OS X 10.0.3. + + The following discussion between Russ Allbery and Robert Lipe is +worth reading: + +Russ Allbery: + + The GNU assumption that '/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 POSIX shell. + Thus, vendors who have taken this route will _never_ (OK..."never + say never") replace the Bourne shell (as '/bin/sh') with a POSIX + shell. + +Robert Lipe: + + This is exactly the problem. While most (at least most System V's) + do have a bourne shell that accepts shell functions most vendor + '/bin/sh' programs are not the POSIX shell. + + So while most modern systems do have a shell _somewhere_ that meets + the POSIX standard, the challenge is to find it. + + +File: autoconf.info, Node: Here-Documents, Next: File Descriptors, Prev: Shellology, Up: Portable Shell + +10.2 Here-Documents +=================== + +Don't rely on '\' being preserved just because it has no special meaning +together with the next symbol. in the native '/bin/sh' on OpenBSD 2.7 +'\"' expands to '"' in here-documents with unquoted delimiter. As a +general rule, if '\\' expands to '\' use '\\' to get '\'. + + With OpenBSD 2.7's '/bin/sh' + + $ cat <<EOF + > \" \\ + > EOF + " \ + +and with Bash: + + bash-2.04$ cat <<EOF + > \" \\ + > EOF + \" \ + + 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 'bash ./configure' +rather than plain './configure'. + + Some shells can be extremely inefficient when there are a lot of +here-documents inside a single statement. For instance if your +'configure.ac' includes something like: + + if <cross_compiling>; then + assume this and that + else + check this + check that + check something else + ... + on and on forever + ... + fi + + A shell parses the whole 'if'/'fi' construct, creating temporary +files for each here document in it. Some shells create links for such +here-documents on every '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 'if'/'fi', or creating multiple 'if'/'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. + + +File: autoconf.info, Node: File Descriptors, Next: File System Conventions, Prev: Here-Documents, Up: Portable Shell + +10.3 File Descriptors +===================== + +Some file descriptors shall not be used, since some systems, admittedly +arcane, use them for special purpose: + +3 + some systems may open it to '/dev/tty'. + +4 + used on the Kubota Titan. + + Don't redirect several times the same file descriptor, as you are +doomed to failure under Ultrix. + + 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. + +In each case the expected result is of course 'fullness' containing +'matter' and 'void' being empty. + + Don't try to redirect the standard error of a command substitution: +it must be done _inside_ the command substitution: when running ': `cd +/zorglub` 2>/dev/null' expect the error message to escape, while ': `cd +/zorglub 2>/dev/null`' works properly. + + It is worth noting that Zsh (but not Ash nor Bash) makes it possible +in assignments though: '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: + + $ 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' + # Traces on startup files deleted here. + $ cat stderr + +zsh:1> eval echo foo >&2 + +zsh:1> echo foo + foo + +You'll appreciate the various levels of detail... + + One workaround is to grep out uninteresting lines, hoping not to +remove good ones... + + +File: autoconf.info, Node: File System Conventions, Next: Shell Substitutions, Prev: File Descriptors, Up: Portable Shell + +10.4 File System Conventions +============================ + +While 'autoconf' and friends will usually be run on some Unix variety, +it can and will be used on other systems, most notably DOS variants. +This impacts several assumptions regarding file and path names. + +For example, the following code: + + case $foo_dir in + /*) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; + esac + +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: + + case $foo_dir in + [\\/]* | ?:[\\/]* ) # Absolute + ;; + *) + foo_dir=$dots$foo_dir ;; + esac + +Make sure you quote the brackets if appropriate and keep the backslash +as first character (*note 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 +'$ac_path_separator' instead (or the 'PATH_SEPARATOR' output variable). +'autoconf' sets this to the appropriate value (':' or ';') when it +starts up. + + File names need extra care as well. While DOS-based environments +that are Unixy enough to run '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 doschk(1) package. + + A short overview follows; problems are marked with SFN/LFN to +indicate where they apply: SFN means the issues are only relevant to +plain DOS, not to DOS boxes under Windows, while LFN identifies problems +that exist even under Windows. + +No multiple dots (SFN) + DOS cannot handle multiple dots in filenames. This is an + especially important thing to remember when building a portable + configure script, as 'autoconf' uses a .in suffix for template + files. + + This is perfectly OK on Unices: + + AC_CONFIG_HEADER(config.h) + AC_CONFIG_FILES([source.c foo.bar]) + AC_OUTPUT + + but it causes problems on DOS, as it requires 'config.h.in', + 'source.c.in' and 'foo.bar.in'. To make your package more portable + to DOS-based environments, you should use this instead: + + AC_CONFIG_HEADER(config.h:config.hin) + AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) + AC_OUTPUT + +No leading dot (SFN) + DOS cannot handle filenames that start with a dot. This is usually + not a very important issue for 'autoconf'. + +Case insensitivity (LFN) + DOS is case insensitive, so you cannot, for example, have both a + file called 'INSTALL' and a directory called 'install'. This also + affects 'make'; if there's a file called 'INSTALL' in the + directory, 'make install' will do nothing (unless the 'install' + target is marked as PHONY). + +The 8+3 limit (SFN) + Because the 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 'foobar-part1.c', 'foobar-part2.c' and + 'foobar-prettybird.c' all resolve to the same filename + ('FOOBAR-P.C'). The same goes for 'foo.bar' and '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 SFN and LFN environments, it also means the + above problem applies there as well. + +Invalid characters + Some characters are invalid in DOS filenames, and should therefore + be avoided. In a LFN environment, these are '/', '\', '?', '*', + ':', '<', '>', '|' and '"'. In a SFN environment, other characters + are also invalid. These include '+', ',', '[' and ']'. + + ---------- Footnotes ---------- + + (1) doschk, <ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz>. + + +File: autoconf.info, Node: Shell Substitutions, Next: Assignments, Prev: File System Conventions, Up: Portable Shell + +10.5 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 'case'. +For instance, the following code: + + case "$given_srcdir" in + .) top_srcdir="`echo "$dots" | sed 's,/$,,'`" + *) top_srcdir="$dots$given_srcdir" ;; + esac + +is more readable when written as: + + case $given_srcdir in + .) top_srcdir=`echo "$dots" | sed 's,/$,,'` + *) top_srcdir=$dots$given_srcdir ;; + esac + +and in fact it is even _more_ portable: in the first case of the first +attempt, the computation of 'top_srcdir' is not portable, since not all +shells properly understand '"`..."..."...`"'. Worse yet, not all shells +understand '"`...\"...\"...`"' the same way. There is just no portable +way to use double-quoted strings inside double-quoted backquoted +expressions (pfew!). + +'$@' + One of the most famous shell-portability issues is related to + '"$@"': 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 '${1+"$@"}'. + +'${VAR:-VALUE}' + Old BSD shells, including the Ultrix 'sh', don't accept the colon + for any shell substitution, and complain and die. + +'${VAR=LITERAL}' + Be sure to quote: + + : ${var='Some words'} + + otherwise some shells, such as on Digital Unix V 5.0, will die + because of a "bad substitution". + + Solaris' '/bin/sh' has a frightening bug in its interpretation of + this. Imagine you need set a variable to a string containing '}'. + This '}' character confuses Solaris' '/bin/sh' when the affected + variable was already set. This bug can be exercised by running: + + $ unset foo + $ foo=${foo='}'} + $ echo $foo + } + $ foo=${foo='}' # no error; this hints to what the bug is + $ echo $foo + } + $ foo=${foo='}'} + $ echo $foo + }} + ^ ugh! + + It seems that '}' is interpreted as matching '${', even though it + is enclosed in single quotes. The problem doesn't happen using + double quotes. + +'${VAR=EXPANDED-VALUE}' + On Ultrix, running + + default="yu,yaa" + : ${var="$default"} + + will set VAR to '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 + '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: + + $ cat -v <<EOF + $var + EOF + + and + + $ set | grep '^var=' | cat -v + + One classic incarnation of this bug is: + + default="a b c" + : ${list="$default"} + for c in $list; do + echo $c + done + + You'll get 'a b c' on a single line. Why? Because there are no + spaces in '$list': there are '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 ': + ${list=$default}'; i.e., if you _don't_ quote. The bad news is + then that QNX 4.25 then sets LIST to the _last_ item of DEFAULT! + + The portable way out consists in using a double assignment, to + switch the 8th bit twice on Ultrix: + + list=${list="$default"} + + ...but beware of the '}' bug from Solaris (see above). For safety, + use: + + test "${var+set}" = set || var={VALUE} + +'`COMMANDS`' + 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 'cd' is silent, do not + use 'test -z "`cd /`"' because the following can happen: + + $ pwd + /tmp + $ test -n "`cd /`" && pwd + / + + The result of 'foo=`exit 1`' is left as an exercise to the reader. + +'$(COMMANDS)' + This construct is meant to replace '`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: + + $ showrev -c /bin/sh | grep version + Command version: SunOS 5.8 Generic 109324-02 February 2001 + $ echo $(echo blah) + syntax error: `(' unexpected + + nor does IRIX 6.5's Bourne shell: + $ uname -a + IRIX firebird-image 6.5 07151432 IP22 + $ echo $(echo blah) + $(echo blah) + + +File: autoconf.info, Node: Assignments, Next: Special Shell Variables, Prev: Shell Substitutions, Up: Portable Shell + +10.6 Assignments +================ + +When setting several variables in a row, be aware that the order of the +evaluation is undefined. For instance 'foo=1 foo=2; echo $foo' gives +'1' with sh on Solaris, but '2' with Bash. You must use ';' to enforce +the order: '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: + + $ false || foo=bar; echo $? + 1 + $ false || foo=`:`; echo $? + 0 + +and to make things even worse, QNX 4.25 just sets the exit status to 0 +in any case: + + $ foo=`exit 1`; echo $? + 0 + + To assign default values, follow this algorithm: + + 1. If the default value is a literal and does not contain any closing + brace, use: + + : ${var='my literal'} + + 2. 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: + + : ${var="$default"} + + 3. 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: + + var=${var="$default"} + + 4. If the default value contains a closing brace, then use: + + test "${var+set}" = set || var='${indirection}' + + In most cases 'var=${var="$default"}' is fine, but in case of doubt, +just use the latter. *Note Shell Substitutions::, items '${VAR:-VALUE}' +and '${VAR=VALUE}' for the rationale. + + +File: autoconf.info, Node: Special Shell Variables, Next: Limitations of Builtins, Prev: Assignments, Up: Portable Shell + +10.7 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 'unset' is +not portable (*note Limitations of Builtins::) and a fallback value is +needed. We list these values below. + +'CDPATH' + When this variable is set 'cd' is verbose, so idioms such as + 'abs=`cd $rel && pwd`' break because 'abs' receives the path twice. + + Setting 'CDPATH' to the empty value is not enough for most shells. + A simple colon is enough except for 'zsh', which prefers a leading + dot: + + 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 % + + (of course we could just 'unset' 'CDPATH', since it also behaves + properly if set to the empty string). + + Life wouldn't be so much fun if 'bash' and 'zsh' had the same + behavior: + + bash-2.02 % (CDPATH=:. cd foo) + bash-2.02 % (CDPATH=.: cd foo) + /tmp/foo + + Therefore, a portable solution to neutralize 'CDPATH' is + + CDPATH=${ZSH_VERSION+.}: + + Note that since 'zsh' supports 'unset', you may unset 'CDPATH' + using ':' as a fallback, see *note Limitations of Builtins::. + +'IFS' + Don't set the first character of 'IFS' to backslash. Indeed, + Bourne shells use the first character (backslash) when joining the + components in '"$@"' and some shells then re-interpret (!) the + backslash escapes, so you can end up with backspace and other + strange characters. + +'LANG' +'LC_ALL' +'LC_TIME' +'LC_CTYPE' +'LANGUAGE' +'LC_COLLATE' +'LC_NUMERIC' +'LC_MESSAGES' + + These must not be set unconditionally because not all systems + understand e.g. 'LANG=C' (notably SCO). Fixing 'LC_MESSAGES' + prevents Solaris 'sh' from translating var values in 'set'! Non-C + 'LC_CTYPE' values break the ctype check. Fixing 'LC_COLLATE' makes + scripts more portable in some cases. For example, it causes the + regular expression '[a-z]' to match only lower-case letters on + ASCII platforms. However, '[a-z]' does not work in general even + when 'LC_COLLATE' is fixed; for example, it does not work for + EBCDIC platforms. For maximum portability, you should use regular + expressions like '[abcdefghijklmnopqrstuvwxyz]' that list + characters explicitly instead of relying on ranges. + + _If_ one of these variables is set, you should try to unset it, + using 'C' as a fall back value. see *note Limitations of + Builtins::, builtin 'unset', for more details. + +'NULLCMD' + When executing the command '>foo', 'zsh' executes '$NULLCMD >foo'. + The Bourne shell considers 'NULLCMD' is ':', while 'zsh', even in + Bourne shell compatibility mode, sets 'NULLCMD' to 'cat'. If you + forgot to set 'NULLCMD', your script might be suspended waiting for + data on its standard input. + +'status' + This variable is an alias to '$?' for 'zsh' (at least 3.1.6), hence + read-only. Do not use it. + +'PATH_SEPARATOR' + On DJGPP systems, the 'PATH_SEPARATOR' variable can be set to + either ':' or ';' to control the path separator 'bash' uses to set + up certain environment variables (such as 'PATH'). Since this only + works inside bash, you want autoconf to detect the regular DOS path + separator ';', so it can be safely substituted in files that may + not support ';' as path separator. So either unset this variable + or set it to ';'. + +'RANDOM' + Many shells provide '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 IRIX 6.5 the value changes all the + time. This can be observed by using 'set'. + + +File: autoconf.info, Node: Limitations of Builtins, Next: Limitations of Usual Tools, Prev: Special Shell Variables, Up: Portable Shell + +10.8 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 'echo +"$word"' can give unexpected results when 'word' starts with a dash. It +is often possible to avoid this problem using 'echo "x$word"', taking +the 'x' into account later in the pipe. + +'!' + You can't use '!', you'll have to rewrite your code. + +'break' + The use of 'break 2', etcetera, is safe. + +'case' + You don't need to quote the argument; no splitting is performed. + + You don't need the final ';;', but you should use it. + + Because of a bug in its 'fnmatch', 'bash' fails to properly handle + backslashes in character classes: + + bash-2.02$ case /tmp in [/\\]*) echo OK;; esac + bash-2.02$ + + This is extremely unfortunate, since you are likely to use this + code to handle UNIX or MS-DOS absolute paths. To work around this + bug, always put the backslash first: + + bash-2.02$ case '\TMP' in [\\/]*) echo OK;; esac + OK + bash-2.02$ case /tmp in [\\/]*) echo OK;; esac + OK + +'echo' + The simple 'echo' is probably the most surprising source of + portability troubles. It is not possible to use 'echo' portably + unless both options and escape sequences are omitted. New + applications which are not aiming at portability should use + 'printf' instead of 'echo'. + + Don't expect any option. *Note Preset Output Variables::, 'ECHO_N' + etc. for a means to simulate '-c'. + + Do not use backslashes in the arguments, as there is no consensus + on their handling. On 'echo '\n' | wc -l', the 'sh' of Digital + Unix 4.0, MIPS RISC/OS 4.52, answer 2, but the Solaris' 'sh', Bash + and Zsh (in 'sh' emulation mode) report 1. Please note that the + problem is truly 'echo': all the shells understand ''\n'' as the + string composed of a backslash and an 'n'. + + Because of these problems, do not pass a string containing + arbitrary characters to 'echo'. For example, 'echo "$foo"' is safe + if you know that FOO's value cannot contain backslashes and cannot + start with '-', but otherwise you should use a here-document like + this: + + cat <<EOF + $foo + EOF + +'exit' + The default value of 'exit' is supposed to be '$?'; unfortunately, + some shells, such as the DJGPP port of Bash 2.04, just perform + 'exit 0'. + + 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$ + + Using 'exit $?' restores the expected behavior. + + Some shell scripts, such as those generated by '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 'sh', an exit trap + ignores the 'exit' command's status. In these shells, a trap + cannot determine whether it was invoked by plain 'exit' or by 'exit + 1'. Instead of calling 'exit' directly, use the 'AC_MSG_ERROR' + macro that has a workaround for this problem. + +'export' + The builtin 'export' dubs "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 '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: + + #! /bin/sh + echo $FOO + FOO=bar + echo $FOO + exec /bin/sh $0 + + when run with 'FOO=foo' in the environment, these shells will print + alternately 'foo' and 'bar', although it should only print 'foo' + and then a sequence of 'bar's. + + Therefore you should 'export' again each environment variable that + you update. + +'false' + Don't expect 'false' to exit with status 1: in the native Bourne + shell of Solaris 8, it exits with status 255. + +'for' + To loop over positional arguments, use: + + for arg + do + echo "$arg" + done + + You may _not_ leave the 'do' on the same line as 'for', since some + shells improperly grok: + + for arg; do + echo "$arg" + done + + If you want to explicitly refer to the positional arguments, given + the '$@' bug (*note Shell Substitutions::), use: + + for arg in ${1+"$@"}; do + echo "$arg" + done + +'if' + Using '!' is not portable. Instead of: + + if ! cmp -s file file.new; then + mv file.new file + fi + + use: + + if cmp -s file file.new; then :; else + mv file.new file + fi + + There are shells that do not reset the exit status from an 'if': + + $ if (exit 42); then true; fi; echo $? + 42 + + whereas a proper shell should have printed '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: + + if test -f "$file"; then + install "$file" "$dest" + else + : + fi + +'set' + This builtin faces the usual problem with arguments starting with a + dash. Modern shells such as Bash or Zsh understand '--' to specify + the end of the options (any argument after '--' is a parameters, + even '-x' for instance), but most shells simply stop the option + processing as soon as a non-option argument is found. Therefore, + use 'dummy' or simply 'x' to end the option processing, and use + 'shift' to pop it out: + + set x $my_list; shift + +'shift' + Not only is 'shift'ing a bad idea when there is nothing left to + shift, but in addition it is not portable: the shell of MIPS + RISC/OS 4.52 refuses to do it. + +'test' + The 'test' program is the way to perform many file and string + tests. It is often invoked by the alternate name '[', 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 'test', combine them with + the shell operators '&&' and '||' instead of using the 'test' + operators '-a' and '-o'. On System V, the precedence of '-a' and + '-o' is wrong relative to the unary operators; consequently, POSIX + does not specify them, so using them is nonportable. If you + combine '&&' and '||' in the same statement, keep in mind that they + have equal precedence. + + You may use '!' with 'test', but not with 'if': 'test ! -r foo || + exit 1'. + +'test' (files) + To enable '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 'test -f' or 'test -r'. Do not use 'test -x', because 4.3BSD + does not have it. Do not use 'test -e' either, because Solaris 2.5 + does not have it. + +'test' (strings) + Avoid 'test "STRING"', in particular if STRING might start with a + dash, since 'test' might interpret its argument as an option (e.g., + 'STRING = "-n"'). + + Contrary to a common belief, 'test -n STRING' and 'test -z STRING' + *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 STRING looks like an operator: + + $ test -n = + test: argument expected + + If there are risks, use 'test "xSTRING" = x' or 'test "xSTRING" != + x' instead. + + It is frequent to find variations of the following idiom: + + test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && + ACTION + + to take an action when a token matches a given pattern. Such + constructs should always be avoided by using: + + echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && + ACTION + + Use 'case' where possible since it is faster, being a shell + builtin: + + case $ac_feature in + *[!-a-zA-Z0-9_]*) ACTION;; + esac + + Alas, negated character classes are probably not portable, although + no shell is known to not support the POSIX.2 syntax '[!...]' (when + in interactive mode, 'zsh' is confused by the '[!...]' syntax and + looks for an event in its history because of '!'). Many shells do + not support the alternative syntax '[^...]' (Solaris, Digital Unix, + etc.). + + One solution can be: + + expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + ACTION + + or better yet + + expr "x$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && + ACTION + + 'expr "XFOO" : "XBAR"' is more robust than 'echo "XFOO" | grep + "^XBAR"', because it avoids problems when 'FOO' contains + backslashes. + +'trap' + It is safe to trap at least the signals 1, 2, 13 and 15. You can + also trap 0, i.e., have the 'trap' run when the script ends (either + via an explicit 'exit', or the end of the script). + + Although POSIX is not absolutely clear on this point, it is widely + admitted that when entering the trap '$?' 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 'exit', what is + the _last_ command run: that before 'exit', or 'exit' itself?" + + Bash considers 'exit' to be the last command, while Zsh and Solaris + 8 'sh' consider that when the trap is run it is _still_ in the + 'exit', hence it is the previous exit status that the trap + receives: + + $ cat trap.sh + trap 'echo $?' 0 + (exit 42); exit 0 + $ zsh trap.sh + 42 + $ bash trap.sh + 0 + + The portable solution is then simple: when you want to 'exit 42', + run '(exit 42); exit 42', the first '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: '$?' is reset to 0 + by empty lines if the code is inside 'trap'. + + $ trap 'false + + echo $?' 0 + $ exit + 0 + + Fortunately, this bug only affects 'trap'. + +'true' + Don't worry: as far as we know 'true' is portable. Nevertheless, + it's not always a builtin (e.g., Bash 1.x), and the portable shell + community tends to prefer using ':'. This has a funny side effect: + when asked whether 'false' is more portable than 'true' Alexandre + Oliva answered: + + In a sense, yes, because if it doesn't exist, the shell will + produce an exit status of failure, which is correct for + 'false', but not for 'true'. + +'unset' + You cannot assume the support of 'unset', nevertheless, because it + is extremely useful to disable embarrassing variables such as + 'CDPATH' or 'LANG', you can test for its existence and use it + _provided_ you give a neutralizing value when 'unset' is not + supported: + + if (unset FOO) >/dev/null 2>&1; then + unset=unset + else + unset=false + fi + $unset CDPATH || CDPATH=: + + *Note Special Shell Variables::, for some neutralizing values. + Also, see *note Limitations of Builtins::, documentation of + 'export', for the case of environment variables. + + +File: autoconf.info, Node: Limitations of Usual Tools, Next: Limitations of Make, Prev: Limitations of Builtins, Up: Portable Shell + +10.9 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. + +'awk' + Don't leave white spaces before the parentheses in user functions + calls, GNU awk will reject it: + + $ 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! + + If you want your program to be deterministic, don't depend on 'for' + on arrays: + + $ 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 + + Some AWK, such as HPUX 11.0's native one, have regex engines + fragile to inner anchors: + + $ 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 + + Either do not depend on such patterns (i.e., use '/^(.*foo|bar)/', + or use a simple test to reject such AWK. + +'cat' + Don't rely on any option. The option '-v', which displays + non-printing characters, _seems_ portable, though. + +'cc' + When a compilation such as 'cc foo.c -o foo' fails, some compilers + (such as CDS on Reliant UNIX) leave a 'foo.o'. + +'cmp' + 'cmp' performs a raw data comparison of two files, while 'diff' + compares two text files. Therefore, if you might compare DOS + files, even if only checking whether two files are different, use + 'diff' to avoid spurious differences due to differences of newline + encoding. + +'cp' + SunOS 'cp' does not support '-f', although its 'mv' does. It's + possible to deduce why 'mv' and 'cp' are different with respect to + '-f'. 'mv' prompts by default before overwriting a read-only file. + 'cp' does not. Therefore, 'mv' requires a '-f' option, but 'cp' + does not. 'mv' and 'cp' behave differently with respect to + read-only files because the simplest form of 'cp' cannot overwrite + a read-only file, but the simplest form of 'mv' can. This is + because 'cp' opens the target for write access, whereas 'mv' simply + calls 'link' (or, in newer systems, 'rename'). + +'diff' + Option '-u' is nonportable. + + Some implementations, such as Tru64's, fail when comparing to + '/dev/null'. Use an empty file instead. + +'dirname' + Not all hosts have 'dirname', but it is reasonably easy to emulate, + e.g.: + + dir=`expr "x$file" : 'x\(.*\)/[^/]*' \| + '.' : '.' + + But there are a few subtilities, e.g., under UN*X, should '//1' + give '/'? Paul Eggert answers: + + No, under some older flavors of Unix, leading '//' is a + special path name: it refers to a "super-root" and is used to + access other machines' files. Leading '///', '////', etc. + are equivalent to '/'; but leading '//' 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 + '//'. It says that the behavior of dirname on path names of + the form '//([^/]+/*)?' is implementation defined. In these + cases, GNU 'dirname' returns '/', but it's more portable to + return '//' as this works even on those older flavors of Unix. + + I have heard rumors that this special treatment of '//' may be + dropped in future versions of POSIX, but for now it's still + the standard. + +'egrep' + The empty alternative is not portable, use '?' instead. For + instance with Digital Unix v5.0: + + > 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 + + 'egrep' also suffers the limitations of 'grep'. + +'expr' + No 'expr' keyword starts with 'x', so use 'expr x"WORD" : 'xREGEX'' + to keep 'expr' from misinterpreting WORD. + + Don't use 'length', 'substr', 'match' and 'index'. + +'expr' ('|') + You can use '|'. Although POSIX does require that 'expr ''' return + the empty string, it does not specify the result when you '|' + together the empty string (or zero) with the empty string. For + example: + + expr '' \| '' + + GNU/Linux and POSIX.2-1992 return the empty string for this case, + but traditional Unix returns '0' (Solaris is one such example). In + the latest 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: + + expr bar : foo \| foo : bar + + Avoid this portability problem by avoiding the empty string. + +'expr' (':') + Don't use '\?', '\+' and '\|' in patterns, they are not supported + on Solaris. + + The POSIX.2-1992 standard is ambiguous as to whether 'expr a : b' + (and 'expr 'a' : '\(b\)'') output '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 QNX + 4.25 native 'expr' returns '0'. + + You may believe that one means to get a uniform behavior would be + to use the empty string as a default value: + + expr a : b \| '' + + unfortunately this behaves exactly as the original expression, see + the ''expr' (':')' entry for more information. + + Older 'expr' implementations (e.g. SunOS 4 'expr' and Solaris 8 + '/usr/ucb/expr') have a silly length limit that causes 'expr' to + fail if the matched substring is longer than 120 bytes. In this + case, you might want to fall back on 'echo|sed' if 'expr' fails. + + Don't leave, there is some more! + + The QNX 4.25 'expr', in addition of preferring '0' to the empty + string, has a funny behavior in its exit status: it's always 1 when + parentheses are used! + + $ 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 + + In practice this can be a big problem if you are ready to catch + failures of 'expr' programs with some other method (such as using + 'sed'), since you may get twice the result. For instance + + $ expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/' + + will output 'a' on most hosts, but 'aa' on QNX 4.25. A simple work + around consists in testing 'expr' and use a variable set to 'expr' + or to 'false' according to the result. + +'find' + The option '-maxdepth' seems to be GNU specific. Tru64 v5.1, + NetBSD 1.5 and Solaris 2.5 'find' commands do not understand it. + +'grep' + Don't use 'grep -s' to suppress output, because '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 'grep' to '/dev/null'. Check the exit status of 'grep' + to determine whether it found a match. + + Don't use multiple regexps with '-e', as some 'grep' will only + honor the last pattern (eg., IRIX 6.5 and Solaris 2.5.1). Anyway, + Stardent Vistra SVR4 'grep' lacks '-e'... Instead, use alternation + and 'egrep'. + +'ln' + Don't rely on 'ln' having a '-f' option. Symbolic links are not + available on old systems, use 'ln' as a fall back. + + For versions of the DJGPP before 2.04, '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 'ln -s file link' will generate 'link.exe', + which will attempt to call 'file.exe' if run. But this feature + only works for executables, so 'cp -p' is used instead for these + systems. DJGPP versions 2.04 and later have full symlink support. + +'mv' + The only portable options are '-f' and '-i'. + + Moving individual files between file systems is portable (it was in + V6), but it is not always atomic: when doing 'mv new existing', + there's a critical section where neither the old nor the new + version of 'existing' actually exists. + + Moving directories across mount points is not portable, use 'cp' + and 'rm'. + +'sed' + Patterns should not include the separator (unless escaped), even as + part of a character class. In conformance with POSIX, the Cray + 'sed' will reject 's/[^/]*$//': use 's,[^/]*$,,'. + + Sed scripts should not use branch labels longer than 8 characters + and should not contain comments. + + Don't include extra ';', as some 'sed', such as NetBSD 1.4.2's, try + to interpret the second as a command: + + $ echo a | sed 's/x/x/;;s/x/x/' + sed: 1: "s/x/x/;;s/x/x/": invalid command code ; + + Input should have reasonably long lines, since some 'sed' have an + input buffer limited to 4000 bytes. + + Alternation, '\|', is common but not portable. Anchors ('^' and + '$') inside groups are not portable. + + Nested groups are extremely portable, but there is at least one + 'sed' (System V/68 Base Operating System R3V7.1) that does not + support it. + + Of course the 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: + + sed -e INSTRUCTION-1 \ + -e INSTRUCTION-2 + + as opposed to + + sed INSTRUCTION-1;INSTRUCTION-2 + + Contrary to yet another urban legend, you may portably use '&' in + the replacement part of the 's' command to mean "what was matched". + +'sed' ('t') + Some old systems have 'sed' that "forget" to reset their 't' flag + when starting a new cycle. For instance on MIPS RISC/OS, and on + IRIX 5.3, if you run the following 'sed' script (the line numbers + are not actual part of the texts): + + s/keep me/kept/g # a + t end # b + s/.*/deleted/g # c + : end # d + + on + + delete me # 1 + delete me # 2 + keep me # 3 + delete me # 4 + + you get + + deleted + delete me + kept + deleted + + instead of + + deleted + deleted + kept + deleted + + 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 '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 'delete me' instead of '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 't' in 'sed'. + Firstly, always remember that 't' jumps if _some_ substitution + succeeded, not only the immediately preceding substitution, + therefore, always use a fake 't clear; : clear' to reset the t flag + where indeed. + + Secondly, you cannot rely on 'sed' to clear the flag at each new + cycle. + + One portable implementation of the script above is: + + t clear + : clear + s/keep me/kept/g + t end + s/.*/deleted/g + : end + +'touch' + On some old BSD systems, 'touch' or any command that results in an + empty file does not update the timestamps, so use a command like + 'echo' as a workaround. + + GNU 'touch' 3.16r (and presumably all before that) fails to work on + SunOS 4.1.3 when the empty file is on an NFS-mounted 4.2 volume. + + +File: autoconf.info, Node: Limitations of Make, Prev: Limitations of Usual Tools, Up: Portable Shell + +10.10 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... + +Leading underscore in macro names + Some Make don't support leading underscores in macro names, such as + on NEWS-OS 4.2R. + + $ 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 + +'VPATH' + Don't use it! For instance any assignment to 'VPATH' causes Sun + 'make' to only execute the first set of double-colon rules. + + +File: autoconf.info, Node: Manual Configuration, Next: Site Configuration, Prev: Portable Shell, Up: Top + +11 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 +'configure' check the output of the '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 + + +File: autoconf.info, Node: Specifying Names, Next: Canonicalizing, Prev: Manual Configuration, Up: Manual Configuration + +11.1 Specifying the System Type +=============================== + +Like other GNU 'configure' scripts, Autoconf-generated 'configure' +scripts can make decisions based on a canonical name for the system +type, which has the form: 'CPU-VENDOR-OS', where OS can be 'SYSTEM' or +'KERNEL-SYSTEM' + + 'configure' can usually guess the canonical name for the type of +system it's running on. To do so it runs a script called +'config.guess', which infers the name using the 'uname' command or +symbols predefined by the C preprocessor. + + Alternately, the user can specify the system type with command line +arguments to '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(1): + +'--build=BUILD-TYPE' + the type of system on which the package is being configured and + compiled. + +'--host=HOST-TYPE' + the type of system on which the package will run. + +'--target=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. + + They all default to the result of running 'config.guess', unless you +specify either '--build' or '--host'. In this case, the default becomes +the system type you specified. If you specify both, and they're +different, '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 'config.guess', prefer +'--build' over '--host'. In the future, '--host' will not override the +name of the build system type. Also, if you specify '--host', but not +'--build', when '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 '--host', be +sure to specify '--build' too. + + ./configure --build=i686-pc-linux-gnu --host=m68k-coff + +will enter cross-compilation mode, but 'configure' will fail if it can't +run the code generated by the specified compiler if you configure as +follows: + + ./configure CC=m68k-coff-gcc + + 'configure' recognizes short aliases for many system types; for +example, 'decstation' can be used instead of 'mips-dec-ultrix4.2'. +'configure' runs a script called 'config.sub' to canonicalize system +type aliases. + + ---------- Footnotes ---------- + + (1) For backward compatibility, '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. + + ./configure --host=alpha-netbsd sparc-gnu + + +File: autoconf.info, Node: Canonicalizing, Next: Using System Type, Prev: Specifying Names, Up: Manual Configuration + +11.2 Getting the Canonical System Type +====================================== + +The following macros make the system type available to 'configure' +scripts. + + The variables 'build_alias', 'host_alias', and 'target_alias' are +always exactly the arguments of '--build', '--host', and '--target'; in +particular, they are left empty if the user did not use them, even if +the corresponding '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 'config.guess' and +'config.sub' along with your source code. *Note Output::, for +information about the 'AC_CONFIG_AUX_DIR' macro which you can use to +control in which directory 'configure' looks for those scripts. + + -- Macro: AC_CANONICAL_BUILD + Compute the canonical build-system type variable, 'build', and its + three individual parts 'build_cpu', 'build_vendor', and 'build_os'. + + If '--build' was specified, then 'build' is the canonicalization of + 'build_alias' by 'config.sub', otherwise it is determined by the + shell script 'config.guess'. + + -- Macro: AC_CANONICAL_HOST + Compute the canonical host-system type variable, 'host', and its + three individual parts 'host_cpu', 'host_vendor', and 'host_os'. + + If '--host' was specified, then 'host' is the canonicalization of + 'host_alias' by 'config.sub', otherwise it defaults to 'build'. + + For temporary backward-compatibility, when '--host' is specified by + '--build' isn't, the build system will be assumed to be the same as + '--host', and 'build_alias' will be set to that value. Eventually, + this historically incorrect behavior will go away. + + -- Macro: AC_CANONICAL_TARGET + Compute the canonical target-system type variable, 'target', and + its three individual parts 'target_cpu', 'target_vendor', and + 'target_os'. + + If '--target' was specified, then 'target' is the canonicalization + of 'target_alias' by 'config.sub', otherwise it defaults to 'host'. + + +File: autoconf.info, Node: Using System Type, Prev: Canonicalizing, Up: Manual Configuration + +11.3 Using the System Type +========================== + +How do you use a canonical system type? Usually, you use it in one or +more 'case' statements in 'configure.ac' to select system-specific C +files. Then, using 'AC_CONFIG_LINKS', link those files which have names +based on the system name, to generic names, such as 'host.h' or +'target.c' (*note Configuration Links::). The 'case' statement patterns +can use shell wild cards to group several cases together, like in this +fragment: + + case "$target" in + i386-*-mach* | i386-*-gnu*) + obj_format=aout emulation=mach bfd_gas=yes ;; + i960-*-bout) obj_format=bout ;; + esac + +and in 'configure.ac', use: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + You can also use the host system type to find cross-compilation +tools. *Note Generic Programs::, for information about the +'AC_CHECK_TOOL' macro which does that. + + +File: autoconf.info, Node: Site Configuration, Next: Running configure scripts, Prev: Manual Configuration, Up: Top + +12 Site Configuration +********************* + +'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 '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 'configure' local defaults + + +File: autoconf.info, Node: External Software, Next: Package Options, Prev: Site Configuration, Up: Site Configuration + +12.1 Working With External Software +=================================== + +Some packages require, or can optionally use, other software packages +that are already installed. The user can give 'configure' command line +options to specify which such external software to use. The options +have one of these forms: + + --with-PACKAGE=[ARG] + --without-PACKAGE + + For example, '--with-gnu-ld' means work with the GNU linker instead +of some other linker. '--with-x' means work with The X Window System. + + The user can give an argument by following the package name with '=' +and the argument. Giving an argument of 'no' is for packages that are +used by default; it says to _not_ use the package. An argument that is +neither 'yes' nor '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 'yes'. '--without-PACKAGE' is equivalent to '--with-PACKAGE=no'. + + 'configure' scripts do not complain about '--with-PACKAGE' options +that they do not support. This behavior permits configuring a source +tree containing multiple packages with a top-level '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, 'configure.ac' +should call 'AC_ARG_WITH' to detect whether the 'configure' user asked +to use it. Whether each package is used or not by default, and which +arguments are valid, is up to you. + + -- Macro: AC_ARG_WITH (PACKAGE, HELP-STRING, [ACTION-IF-GIVEN], + [ACTION-IF-NOT-GIVEN]) + If the user gave 'configure' the option '--with-PACKAGE' or + '--without-PACKAGE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name 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 + ACTION-IF-GIVEN in the shell variable 'withval', which is actually + just the value of the shell variable 'with_PACKAGE', with any '-' + characters changed into '_'. You may use that variable instead, if + you wish. + + The argument HELP-STRING is a description of the option that looks + like this: + --with-readline support fancy command line editing + + HELP-STRING may be more than one line long, if more detail is + needed. Just make sure the columns line up in 'configure --help'. + Avoid tabs in the help string. You'll need to enclose it in '[' + and ']' in order to produce the leading spaces. + + You should format your HELP-STRING with the macro 'AC_HELP_STRING' + (*note Pretty Help Strings::). + + -- Macro: AC_WITH (PACKAGE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) + This is an obsolete version of 'AC_ARG_WITH' that does not support + providing a help string. + + +File: autoconf.info, Node: Package Options, Next: Pretty Help Strings, Prev: External Software, Up: Site Configuration + +12.2 Choosing Package Options +============================= + +If a software package has optional compile-time features, the user can +give 'configure' command line options to specify whether to compile +them. The options have one of these forms: + + --enable-FEATURE=[ARG] + --disable-FEATURE + + These options allow users to choose which optional features to build +and install. '--enable-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 '=' +and the argument. Giving an argument of 'no' requests that the feature +_not_ be made available. A feature with an argument looks like +'--enable-debug=stabs'. If no argument is given, it defaults to 'yes'. +'--disable-FEATURE' is equivalent to '--enable-FEATURE=no'. + + 'configure' scripts do not complain about '--enable-FEATURE' options +that they do not support. This behavior permits configuring a source +tree containing multiple packages with a top-level '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, 'configure.ac' should call 'AC_ARG_ENABLE' +to detect whether the 'configure' user asked to include it. Whether +each feature is included or not by default, and which arguments are +valid, is up to you. + + -- Macro: AC_ARG_ENABLE (FEATURE, HELP-STRING, [ACTION-IF-GIVEN], + [ACTION-IF-NOT-GIVEN]) + If the user gave 'configure' the option '--enable-FEATURE' or + '--disable-FEATURE', run shell commands ACTION-IF-GIVEN. If + neither option was given, run shell commands ACTION-IF-NOT-GIVEN. + The name 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 + ACTION-IF-GIVEN in the shell variable 'enableval', which is + actually just the value of the shell variable 'enable_FEATURE', + with any '-' characters changed into '_'. You may use that + variable instead, if you wish. The HELP-STRING argument is like + that of 'AC_ARG_WITH' (*note External Software::). + + You should format your HELP-STRING with the macro 'AC_HELP_STRING' + (*note Pretty Help Strings::). + + -- Macro: AC_ENABLE (FEATURE, ACTION-IF-GIVEN, [ACTION-IF-NOT-GIVEN]) + This is an obsolete version of 'AC_ARG_ENABLE' that does not + support providing a help string. + + +File: autoconf.info, Node: Pretty Help Strings, Next: Site Details, Prev: Package Options, Up: Site Configuration + +12.3 Making Your Help Strings Look Pretty +========================================= + +Properly formatting the 'help strings' which are used in 'AC_ARG_WITH' +(*note External Software::) and 'AC_ARG_ENABLE' (*note Package +Options::) can be challenging. Specifically, you want your own 'help +strings' to line up in the appropriate columns of 'configure --help' +just like the standard Autoconf 'help strings' do. This is the purpose +of the 'AC_HELP_STRING' macro. + + -- Macro: AC_HELP_STRING (LEFT-HAND-SIDE, RIGHT-HAND-SIDE) + + Expands into an help string that looks pretty when the user + executes 'configure --help'. It is typically used in 'AC_ARG_WITH' + (*note External Software::) or 'AC_ARG_ENABLE' (*note Package + Options::). The following example will make this clearer. + + 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)]) + + Please note that the call to 'AC_HELP_STRING' is *unquoted*. Then + the last few lines of 'configure --help' will appear like this: + + --enable and --with options recognized: + --with-foo use foo (default is NO) + + The 'AC_HELP_STRING' macro is particularly helpful when the + LEFT-HAND-SIDE and/or RIGHT-HAND-SIDE are composed of macro + arguments, as shown in the following 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)]) + + +File: autoconf.info, Node: Site Details, Next: Transforming Names, Prev: Pretty Help Strings, Up: Site Configuration + +12.4 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 _only by users_, not by programs. The location of the file can +either be based on the '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. *Note Variables for +Installation Directories: (standards)Directory Variables, for more +information on where to put data files. + + +File: autoconf.info, Node: Transforming Names, Next: Site Defaults, Prev: Site Details, Up: Site Configuration + +12.5 Transforming Program Names When Installing +=============================================== + +Autoconf supports changing the names of programs when installing them. +In order to use these transformations, 'configure.ac' must call the +macro 'AC_ARG_PROGRAM'. + + -- Macro: AC_ARG_PROGRAM + Place in output variable 'program_transform_name' a sequence of + 'sed' commands for changing the names of installed programs. + + If any of the options described below are given to 'configure', + program names are transformed accordingly. Otherwise, if + 'AC_CANONICAL_TARGET' has been called and a '--target' value is + given that differs from the host type (specified with '--host'), + the target type followed by a dash is used as a prefix. Otherwise, + no program name transformation is done. + +* Menu: + +* Transformation Options:: 'configure' options to transform names +* Transformation Examples:: Sample uses of transforming names +* Transformation Rules:: 'Makefile' uses of transforming names + + +File: autoconf.info, Node: Transformation Options, Next: Transformation Examples, Prev: Transforming Names, Up: Transforming Names + +12.5.1 Transformation Options +----------------------------- + +You can specify name transformations by giving 'configure' these command +line options: + +'--program-prefix=PREFIX' + prepend PREFIX to the names; + +'--program-suffix=SUFFIX' + append SUFFIX to the names; + +'--program-transform-name=EXPRESSION' + perform 'sed' substitution EXPRESSION on the names. + + +File: autoconf.info, Node: Transformation Examples, Next: Transformation Rules, Prev: Transformation Options, Up: Transforming Names + +12.5.2 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 +'--target=i960-vxworks' is normally installed as 'i960-vxworks-as', +rather than 'as', which could be confused with a native Sun 4 assembler. + + You can force a program name to begin with 'g', if you don't want GNU +programs installed on your system to shadow other programs with the same +name. For example, if you configure GNU 'diff' with +'--program-prefix=g', then when you run 'make install' it is installed +as '/usr/local/bin/gdiff'. + + As a more sophisticated example, you could use + + --program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' + + to prepend 'g' to most of the program names in a source tree, +excepting those like 'gdb' that already have one and those like 'less' +and 'lesskey' that aren't GNU programs. (That is assuming that you have +a source tree containing those programs that is set up to use this +feature.) + + One way to install multiple versions of some programs simultaneously +is to append a version number to the name of one or both. For example, +if you want to keep Autoconf version 1 around for awhile, you can +configure Autoconf version 2 using '--program-suffix=2' to install the +programs as '/usr/local/bin/autoconf2', '/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. + + +File: autoconf.info, Node: Transformation Rules, Prev: Transformation Examples, Up: Transforming Names + +12.5.3 Transformation Rules +--------------------------- + +Here is how to use the variable 'program_transform_name' in a +'Makefile.in': + + transform = @program_transform_name@ + install: all + $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog | \ + sed '$(transform)'` + + uninstall: + rm -f $(bindir)/`echo myprog | sed '$(transform)'` + +If you have more than one program to install, you can do it in a loop: + + 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 + + It is guaranteed that 'program_transform_name' is never empty, and +that there are no useless separators. Therefore you may safely embed +'program_transform_name' within a sed program using ';': + + transform = @program_transform_name@ + transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ + + Whether to do the transformations on documentation files (Texinfo or +'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 'man' pages sometimes do conflict with +system documentation. As a compromise, it is probably best to do name +transformations on 'man' pages but not on Texinfo manuals. + + +File: autoconf.info, Node: Site Defaults, Prev: Transforming Names, Up: Site Configuration + +12.6 Setting Site Defaults +========================== + +Autoconf-generated 'configure' scripts allow your site to provide +default values for some configuration values. You do this by creating +site- and system-wide initialization files. + + If the environment variable 'CONFIG_SITE' is set, 'configure' uses +its value as the name of a shell script to read. Otherwise, it reads +the shell script 'PREFIX/share/config.site' if it exists, then +'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 '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 +'configure' scripts run on that system (*note Cache Files::). If you +set a default cache file in a site file, it is a good idea to also set +the output variable '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 +'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 '--without-' and '--disable-' options are like +giving the corresponding '--with-' or '--enable-' option and the value +'no'. Thus, '--cache-file=localcache' sets the variable 'cache_file' to +the value 'localcache'; '--enable-warnings=no' or '--disable-warnings' +sets the variable 'enable_warnings' to the value 'no'; '--prefix=/usr' +sets the variable 'prefix' to the value '/usr'; etc. + + Site files are also good places to set default values for other +output variables, such as '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 PREFIX or EXEC_PREFIX (wherever +you locate the site file), you can set them in the site file if you +specify it with the '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 +'PREFIX/etc/config.site'. To find out the names of the cache variables +you need to set, look for shell variables with '_cv_' in their names in +the affected '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 'prefix' +and 'cache_file' have their default values (as set near the top of +'configure') before changing them. + + Here is a sample file '/usr/share/local/gnu/share/config.site'. The +command 'configure --prefix=/usr/share/local/gnu' would read this file +(if 'CONFIG_SITE' is not set to a different file). + + # 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 + + +File: autoconf.info, Node: Running configure scripts, Next: config.status Invocation, Prev: Site Configuration, Up: Top + +13 Running 'configure' Scripts +****************************** + +Below are instructions on how to configure a package that uses a +'configure' script, suitable for inclusion as an 'INSTALL' file in the +package. A plain-text version of '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 'configure' +* Environment Variables:: Defining environment variables. +* configure Invocation:: Changing how 'configure' runs + + +File: autoconf.info, Node: Basic Installation, Next: Compilers and Options, Up: Running configure scripts + +13.1 Basic Installation +======================= + +These are generic installation instructions. + + The 'configure' shell script attempts to guess correct values for +various system-dependent variables used during compilation. It uses +those values to create a 'Makefile' in each directory of the package. +It may also create one or more '.h' files containing system-dependent +definitions. Finally, it creates a shell script 'config.status' that +you can run in the future to recreate the current configuration, and a +file 'config.log' containing compiler output (useful mainly for +debugging 'configure'). + + It can also use an optional file (typically called 'config.cache' and +enabled with '--cache-file=config.cache' or simply '-C') that saves the +results of its tests to speed up reconfiguring. (Caching is disabled by +default to prevent problems with accidental use of stale cache files.) + + If you need to do unusual things to compile the package, please try +to figure out how 'configure' could check whether to do them, and mail +diffs or instructions to the address given in the 'README' so they can +be considered for the next release. If you are using the cache, and at +some point 'config.cache' contains results you don't want to keep, you +may remove or edit it. + + The file 'configure.ac' (or 'configure.in') is used to create +'configure' by a program called 'autoconf'. You only need +'configure.ac' if you want to change it or regenerate 'configure' using +a newer version of 'autoconf'. + +The simplest way to compile this package is: + + 1. 'cd' to the directory containing the package's source code and type + './configure' to configure the package for your system. If you're + using 'csh' on an old version of System V, you might need to type + 'sh ./configure' instead to prevent 'csh' from trying to execute + 'configure' itself. + + Running 'configure' takes awhile. While running, it prints some + messages telling which features it is checking for. + + 2. Type 'make' to compile the package. + + 3. Optionally, type 'make check' to run any self-tests that come with + the package. + + 4. Type 'make install' to install the programs and any data files and + documentation. + + 5. You can remove the program binaries and object files from the + source code directory by typing 'make clean'. To also remove the + files that 'configure' created (so you can compile the package for + a different kind of computer), type 'make distclean'. There is + also a 'make maintainer-clean' target, but that is intended mainly + for the package's developers. If you use it, you may have to get + all sorts of other programs in order to regenerate files that came + with the distribution. + + +File: autoconf.info, Node: Compilers and Options, Next: Multiple Architectures, Prev: Basic Installation, Up: Running configure scripts + +13.2 Compilers and Options +========================== + +Some systems require unusual options for compilation or linking that the +'configure' script does not know about. Run './configure --help' for +details on some of the pertinent environment variables. + + You can give 'configure' initial values for variables by setting them +in the environment. You can do that on the command line like this: + + ./configure CC=c89 CFLAGS=-O2 LIBS=-lposix + + *Note Environment Variables::, for more details. + + +File: autoconf.info, Node: Multiple Architectures, Next: Installation Names, Prev: Compilers and Options, Up: Running configure scripts + +13.3 Compiling For Multiple Architectures +========================================= + +You can compile the package for more than one kind of computer at the +same time, by placing the object files for each architecture in their +own directory. To do this, you must use a version of 'make' that +supports the 'VPATH' variable, such as GNU 'make'. 'cd' to the +directory where you want the object files and executables to go and run +the 'configure' script. 'configure' automatically checks for the source +code in the directory that 'configure' is in and in '..'. + + If you have to use a 'make' that does not support the 'VPATH' +variable, you have to compile the package for one architecture at a time +in the source code directory. After you have installed the package for +one architecture, use 'make distclean' before reconfiguring for another +architecture. + + +File: autoconf.info, Node: Installation Names, Next: Optional Features, Prev: Multiple Architectures, Up: Running configure scripts + +13.4 Installation Names +======================= + +By default, 'make install' will install the package's files in +'/usr/local/bin', '/usr/local/man', etc. You can specify an +installation prefix other than '/usr/local' by giving 'configure' the +option '--prefix=PATH'. + + You can specify separate installation prefixes for +architecture-specific files and architecture-independent files. If you +give 'configure' the option '--exec-prefix=PATH', the package will use +PATH as the prefix for installing programs and libraries. Documentation +and other data files will still use the regular prefix. + + In addition, if you use an unusual directory layout you can give +options like '--bindir=PATH' to specify different values for particular +kinds of files. Run 'configure --help' for a list of the directories +you can set and what kinds of files go in them. + + If the package supports it, you can cause programs to be installed +with an extra prefix or suffix on their names by giving 'configure' the +option '--program-prefix=PREFIX' or '--program-suffix=SUFFIX'. + + +File: autoconf.info, Node: Optional Features, Next: System Type, Prev: Installation Names, Up: Running configure scripts + +13.5 Optional Features +====================== + +Some packages pay attention to '--enable-FEATURE' options to +'configure', where FEATURE indicates an optional part of the package. +They may also pay attention to '--with-PACKAGE' options, where PACKAGE +is something like 'gnu-as' or 'x' (for the X Window System). The +'README' should mention any '--enable-' and '--with-' options that the +package recognizes. + + For packages that use the X Window System, 'configure' can usually +find the X include and library files automatically, but if it doesn't, +you can use the 'configure' options '--x-includes=DIR' and +'--x-libraries=DIR' to specify their locations. + + +File: autoconf.info, Node: System Type, Next: Sharing Defaults, Prev: Optional Features, Up: Running configure scripts + +13.6 Specifying the System Type +=============================== + +There may be some features 'configure' cannot figure out automatically, +but needs to determine by the type of host the package will run on. +Usually 'configure' can figure that out, but if it prints a message +saying it cannot guess the host type, give it the '--build=TYPE' option. +TYPE can either be a short name for the system type, such as 'sun4', or +a canonical name which has the form: + + CPU-COMPANY-SYSTEM + +where SYSTEM can have one of these forms: + + OS + KERNEL-OS + + See the file 'config.sub' for the possible values of each field. If +'config.sub' isn't included in this package, then this package doesn't +need to know the host type. + + If you are _building_ compiler tools for cross-compiling, you should +use the '--target=TYPE' option to select the type of system they will +produce code for. + + If you want to _use_ a cross compiler, that generates code for a +platform different from the build platform, you should specify the host +platform (i.e., that on which the generated programs will eventually be +run) with '--host=TYPE'. In this case, you should also specify the +build platform with '--build=TYPE', because, in this case, it may not be +possible to guess the build platform (it sometimes involves compiling +and running simple test programs, and this can't be done if the compiler +is a cross compiler). + + +File: autoconf.info, Node: Sharing Defaults, Next: Environment Variables, Prev: System Type, Up: Running configure scripts + +13.7 Sharing Defaults +===================== + +If you want to set default values for 'configure' scripts to share, you +can create a site shell script called 'config.site' that gives default +values for variables like 'CC', 'cache_file', and 'prefix'. 'configure' +looks for 'PREFIX/share/config.site' if it exists, then +'PREFIX/etc/config.site' if it exists. Or, you can set the +'CONFIG_SITE' environment variable to the location of the site script. +A warning: not all 'configure' scripts look for a site script. + + +File: autoconf.info, Node: Environment Variables, Next: configure Invocation, Prev: Sharing Defaults, Up: Running configure scripts + +13.8 Environment Variables +========================== + +Variables not defined in a site shell script can be set in the +environment passed to configure. However, some packages may run +configure again during the build, and the customized values of these +variables may be lost. In order to avoid this problem, you should set +them in the 'configure' command line, using 'VAR=value'. For example: + + ./configure CC=/usr/local2/bin/gcc + +will cause the specified gcc to be used as the C compiler (unless it is +overridden in the site shell script). + + +File: autoconf.info, Node: configure Invocation, Prev: Environment Variables, Up: Running configure scripts + +13.9 'configure' Invocation +=========================== + +'configure' recognizes the following options to control how it operates. + +'--help' +'-h' + Print a summary of the options to 'configure', and exit. + +'--version' +'-V' + Print the version of Autoconf used to generate the 'configure' + script, and exit. + +'--cache-file=FILE' + Enable the cache: use and save the results of the tests in FILE, + traditionally 'config.cache'. FILE defaults to '/dev/null' to + disable caching. + +'--config-cache' +'-C' + Alias for '--cache-file=config.cache'. + +'--quiet' +'--silent' +'-q' + Do not print messages saying which checks are being made. To + suppress all normal output, redirect it to '/dev/null' (any error + messages will still be shown). + +'--srcdir=DIR' + Look for the package's source code in directory DIR. Usually + 'configure' can determine that directory automatically. + +'configure' also accepts some other, not widely useful, options. Run +'configure --help' for more details. + + +File: autoconf.info, Node: config.status Invocation, Next: Obsolete Constructs, Prev: Running configure scripts, Up: Top + +14 Recreating a Configuration +***************************** + +The 'configure' script creates a file named 'config.status', which +actually configures, "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: + ./config.status OPTION... [FILE...] + + It configures the FILES, if none are specified, all the templates are +instantiated. The files must be specified without their dependencies, +as in + + ./config.status foobar + +not + + ./config.status foobar:foo.in:bar.in + + The supported OPTIONs are: + +'--help' +'-h' + Print a summary of the command line options, the list of the + template files and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--debug' +'-d' + Don't remove the temporary files. + +'--file=FILE[:TEMPLATE]' + Require that FILE be instantiated as if + 'AC_CONFIG_FILES(FILE:TEMPLATE)' was used. Both FILE and TEMPLATE + may be '-' in which case the standard output and/or standard input, + respectively, is used. If a TEMPLATE filename is relative, it is + first looked for in the build tree, and then in the source tree. + *Note Configuration Actions::, for more details. + + This option and the following ones provide one way for separately + distributed packages to share the values computed by '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 'config.status' file to create files other + than the ones that its 'configure.ac' specifies, so it can be used + for a different package. + +'--header=FILE[:TEMPLATE]' + Same as '--file' above, but with 'AC_CONFIG_HEADERS'. + +'--recheck' + Ask 'config.status' to update itself and exit (no instantiation). + This option is useful if you change 'configure', so that the + results of some tests might be different from the previous run. + The '--recheck' option re-runs 'configure' with the same arguments + you used before, plus the '--no-create' option, which prevents + 'configure' from running 'config.status' and creating 'Makefile' + and other files, and the '--no-recursion' option, which prevents + 'configure' from running other 'configure' scripts in + subdirectories. (This is so other 'Makefile' rules can run + 'config.status' when it changes; *note Automatic Remaking::, for an + example). + + 'config.status' checks several optional environment variables that +can alter its behavior: + + -- Variable: CONFIG_SHELL + The shell with which to run 'configure' for the '--recheck' option. + It must be Bourne-compatible. The default is '/bin/sh'. + + -- Variable: CONFIG_STATUS + The file name to use for the shell script that records the + configuration. The default is './config.status'. This variable is + useful when one package uses parts of another and the 'configure' + scripts shouldn't be merged because they are maintained separately. + + You can use './config.status' in your Makefiles. For example, in the +dependencies given above (*note Automatic Remaking::), 'config.status' +is run twice when 'configure.ac' has changed. If that bothers you, you +can make each run only regenerate the files for that rule: + 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 + + The calling convention of 'config.status' has changed, see *note +Obsolete config.status Use::, for details. + + +File: autoconf.info, Node: Obsolete Constructs, Next: Questions, Prev: config.status Invocation, Up: Top + +15 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 'config.h.in' +* autoupdate Invocation:: Automatic update of 'configure.ac' +* Obsolete Macros:: Backward compatibility macros +* Autoconf 1:: Tips for upgrading your files +* Autoconf 2.13:: Some fresher tips + + +File: autoconf.info, Node: Obsolete config.status Use, Next: acconfig.h, Prev: Obsolete Constructs, Up: Obsolete Constructs + +15.1 Obsolete 'config.status' Invocation +======================================== + +'config.status' now supports arguments to specify the files to +instantiate, see *note config.status Invocation::, for more details. +Before, environment variables had to be used. + + -- Variable: CONFIG_COMMANDS + The tags of the commands to execute. The default is the arguments + given to 'AC_OUTPUT' and 'AC_CONFIG_COMMANDS' in 'configure.ac'. + + -- Variable: CONFIG_FILES + The files in which to perform '@VARIABLE@' substitutions. The + default is the arguments given to 'AC_OUTPUT' and 'AC_CONFIG_FILES' + in 'configure.ac'. + + -- Variable: CONFIG_HEADERS + The files in which to substitute C '#define' statements. The + default is the arguments given to 'AC_CONFIG_HEADERS'; if that + macro was not called, 'config.status' ignores this variable. + + -- Variable: CONFIG_LINKS + The symbolic links to establish. The default is the arguments + given to 'AC_CONFIG_LINKS'; if that macro was not called, + 'config.status' ignores this variable. + + In *note config.status Invocation::, using this old interface, the +example would be: + + 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 + +(If 'configure.ac' does not call 'AC_CONFIG_HEADERS', there is no need +to set 'CONFIG_HEADERS' in the 'make' rules, equally for +'CONFIG_COMMANDS' etc.) + + +File: autoconf.info, Node: acconfig.h, Next: autoupdate Invocation, Prev: Obsolete config.status Use, Up: Obsolete Constructs + +15.2 'acconfig.h' +================= + +In order to produce 'config.h.in', 'autoheader' needs to build or to +find templates for each symbol. Modern releases of Autoconf use +'AH_VERBATIM' and 'AH_TEMPLATE' (*note Autoheader Macros::), but in +older releases a file, 'acconfig.h', contained the list of needed +templates. 'autoheader' copies comments and '#define' and '#undef' +statements from 'acconfig.h' in the current directory, if present. This +file used to be mandatory if you 'AC_DEFINE' any additional symbols. + + Modern releases of Autoconf also provide 'AH_TOP' and 'AH_BOTTOM' if +you need to prepend/append some information to 'config.h.in'. Ancient +versions of Autoconf had a similar feature: if './acconfig.h' contains +the string '@TOP@', 'autoheader' copies the lines before the line +containing '@TOP@' into the top of the file that it generates. +Similarly, if './acconfig.h' contains the string '@BOTTOM@', +'autoheader' copies the lines after that line to the end of the file it +generates. Either or both of those strings may be omitted. An even +older alternate way to produce the same effect in jurasik versions of +Autoconf is to create the files 'FILE.top' (typically 'config.h.top') +and/or 'FILE.bot' in the current directory. If they exist, 'autoheader' +copies them to the beginning and end, respectively, of its output. + + In former versions of Autoconf, the files used in preparing a +software package for distribution were: + configure.ac --. .------> autoconf* -----> configure + +---+ + [aclocal.m4] --+ `---. + [acsite.m4] ---' | + +--> [autoheader*] -> [config.h.in] + [acconfig.h] ----. | + +-----' + [config.h.top] --+ + [config.h.bot] --' + + Use only the 'AH_' macros, 'configure.ac' should be self-contained, +and should not depend upon 'acconfig.h' etc. + + +File: autoconf.info, Node: autoupdate Invocation, Next: Obsolete Macros, Prev: acconfig.h, Up: Obsolete Constructs + +15.3 Using 'autoupdate' to Modernize 'configure.ac' +=================================================== + +The 'autoupdate' program updates a '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. *Note Macro Names::, for a +description of the new scheme. Although the old names still work (*note +Obsolete Macros::, for a list of the old macros and the corresponding +new names), you can make your '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. + + If given no arguments, 'autoupdate' updates 'configure.ac', backing +up the original version with the suffix '~' (or the value of the +environment variable 'SIMPLE_BACKUP_SUFFIX', if that is set). If you +give 'autoupdate' an argument, it reads that file instead of +'configure.ac' and writes the updated file to the standard output. + +'autoupdate' accepts the following options: + +'--help' +'-h' + Print a summary of the command line options and exit. + +'--version' +'-V' + Print the version number of Autoconf and exit. + +'--verbose' +'-v' + Report processing steps. + +'--debug' +'-d' + Don't remove the temporary files. + +'--autoconf-dir=DIR' +'-A DIR' + Override the location where the installed Autoconf data files are + looked for. You can also set the '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. + +'--localdir=DIR' +'-l DIR' + Look for the package file 'aclocal.m4' in directory DIR instead of + in the current directory. + + +File: autoconf.info, Node: Obsolete Macros, Next: Autoconf 1, Prev: autoupdate Invocation, Up: Obsolete Constructs + +15.4 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. *Note 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. + + -- Macro: AC_ALLOCA + 'AC_FUNC_ALLOCA' + + -- Macro: AC_ARG_ARRAY + removed because of limited usefulness + + -- Macro: AC_C_CROSS + This macro is obsolete; it does nothing. + + -- Macro: AC_CANONICAL_SYSTEM + Determine the system type and set output variables to the names of + the canonical system types. *Note Canonicalizing::, for details + about the variables this macro sets. + + The user is encouraged to use either 'AC_CANONICAL_BUILD', or + 'AC_CANONICAL_HOST', or 'AC_CANONICAL_TARGET', depending on the + needs. Using 'AC_CANONICAL_TARGET' is enough to run the two other + macros. + + -- Macro: AC_CHAR_UNSIGNED + 'AC_C_CHAR_UNSIGNED' + + -- Macro: AC_CHECK_TYPE (TYPE, DEFAULT) + Autoconf, up to 2.13, used to provide this version of + 'AC_CHECK_TYPE', deprecated because of its flaws. Firstly, + although it is a member of the 'CHECK' clan, singular sub-family, + it does more than just checking. Second, missing types are not + 'typedef''d, they are '#define''d, which can lead to incompatible + code in the case of pointer types. + + This use of 'AC_CHECK_TYPE' is obsolete and discouraged, see *note + Generic Types::, for the description of the current macro. + + If the type TYPE is not defined, define it to be the C (or C++) + builtin type DEFAULT; e.g., 'short' or 'unsigned'. + + This macro is equivalent to: + + AC_CHECK_TYPE([TYPE], + [AC_DEFINE([TYPE], [DEFAULT], + [Define to `DEFAULT' if <sys/types.h> + does not define.])]) + + In order to keep backward compatibility, the two versions of + 'AC_CHECK_TYPE' are implemented, selected by a simple heuristics: + + 1. If there are three or four arguments, the modern version is + used. + + 2. 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++ _builtin_ type or a C identifier ending in '_t', + optionally followed by one of '[(* ' and then by a string of + zero or more characters taken from the set '[]()* _a-zA-Z0-9'. + + 3. 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. + + 4. Otherwise, the modern version is used. + + You are encouraged either to use a valid builtin type, or to use + the equivalent modern code (see above), or better yet, to use + 'AC_CHECK_TYPES' together with + + #if !HAVE_LOFF_T + typedef loff_t off_t; + #endif + + -- Macro: AC_CHECKING (FEATURE-DESCRIPTION) + Same as 'AC_MSG_NOTICE([checking FEATURE-DESCRIPTION...]'. + + -- Macro: AC_COMPILE_CHECK (ECHO-TEXT, INCLUDES, FUNCTION-BODY, + ACTION-IF-FOUND, [ACTION-IF-NOT-FOUND]) + This is an obsolete version of 'AC_TRY_LINK' (*note Examining + Libraries::), with the addition that it prints 'checking for + ECHO-TEXT' to the standard output first, if ECHO-TEXT is non-empty. + Use 'AC_MSG_CHECKING' and 'AC_MSG_RESULT' instead to print messages + (*note Printing Messages::). + + -- Macro: AC_CONST + 'AC_C_CONST' + + -- Macro: AC_CROSS_CHECK + Same as 'AC_C_CROSS', which is obsolete too, and does nothing + ':-)'. + + -- Macro: AC_CYGWIN + Check for the Cygwin environment in which case the shell variable + 'CYGWIN' is set to 'yes'. Don't use this macro, the dignified + means to check the nature of the host is using 'AC_CANONICAL_HOST'. + As a matter of fact this macro is defined as: + + AC_REQUIRE([AC_CANONICAL_HOST])[]dnl + case $host_os in + *cygwin* ) CYGWIN=yes;; + * ) CYGWIN=no;; + esac + + Beware that the variable 'CYGWIN' has a very special meaning when + running CygWin32, and should not be changed. That's yet another + reason not to use this macro. + + -- Macro: AC_DECL_YYTEXT + Does nothing, now integrated in 'AC_PROG_LEX'. + + -- Macro: AC_DIR_HEADER + Like calling 'AC_FUNC_CLOSEDIR_VOID' and'AC_HEADER_DIRENT', but + defines a different set of C preprocessor macros to indicate which + header file is found: + + Header Old Symbol New Symbol + 'dirent.h' 'DIRENT' 'HAVE_DIRENT_H' + 'sys/ndir.h' 'SYSNDIR' 'HAVE_SYS_NDIR_H' + 'sys/dir.h' 'SYSDIR' 'HAVE_SYS_DIR_H' + 'ndir.h' 'NDIR' 'HAVE_NDIR_H' + + -- Macro: AC_DYNIX_SEQ + If on Dynix/PTX (Sequent UNIX), add '-lseq' to output variable + 'LIBS'. This macro used to be defined as + + AC_CHECK_LIB(seq, getmntent, LIBS="-lseq $LIBS") + + now it is just 'AC_FUNC_GETMNTENT'. + + -- Macro: AC_EXEEXT + Defined the output variable 'EXEEXT' based on the output of the + compiler, which is now done automatically. Typically set to empty + string if Unix and '.exe' if Win32 or OS/2. + + -- Macro: AC_EMXOS2 + Similar to 'AC_CYGWIN' but checks for the EMX environment on OS/2 + and sets 'EMXOS2'. + + -- Macro: AC_ERROR + 'AC_MSG_ERROR' + + -- Macro: AC_FIND_X + 'AC_PATH_X' + + -- Macro: AC_FIND_XTRA + 'AC_PATH_XTRA' + + -- Macro: AC_FUNC_CHECK + 'AC_CHECK_FUNC' + + -- Macro: AC_FUNC_WAIT3 + If 'wait3' is found and fills in the contents of its third argument + (a 'struct rusage *'), which HP-UX does not do, define + 'HAVE_WAIT3'. + + These days portable programs should use 'waitpid', not 'wait3', as + 'wait3' is being removed from the Open Group standards, and will + not appear in the next revision of POSIX. + + -- Macro: AC_GCC_TRADITIONAL + 'AC_PROG_GCC_TRADITIONAL' + + -- Macro: AC_GETGROUPS_T + 'AC_TYPE_GETGROUPS' + + -- Macro: AC_GETLOADAVG + 'AC_FUNC_GETLOADAVG' + + -- Macro: AC_HAVE_FUNCS + 'AC_CHECK_FUNCS' + + -- Macro: AC_HAVE_HEADERS + 'AC_CHECK_HEADERS' + + -- Macro: AC_HAVE_LIBRARY (LIBRARY, [ACTION-IF-FOUND], + [ACTION-IF-NOT-FOUND], [OTHER-LIBRARIES]) + This macro is equivalent to calling 'AC_CHECK_LIB' with a FUNCTION + argument of 'main'. In addition, LIBRARY can be written as any of + 'foo', '-lfoo', or 'libfoo.a'. In all of those cases, the compiler + is passed '-lfoo'. However, LIBRARY cannot be a shell variable; it + must be a literal name. + + -- Macro: AC_HAVE_POUNDBANG + 'AC_SYS_INTERPRETER' (different calling convention) + + -- Macro: AC_HEADER_CHECK + 'AC_CHECK_HEADER' + + -- Macro: AC_HEADER_EGREP + 'AC_EGREP_HEADER' + + -- Macro: AC_INIT (UNIQUE-FILE-IN-SOURCE-DIR) + Formerly 'AC_INIT' used to have a single argument, and was + equivalent to: + + AC_INIT + AC_CONFIG_SRCDIR(UNIQUE-FILE-IN-SOURCE-DIR) + + -- Macro: AC_INLINE + 'AC_C_INLINE' + + -- Macro: AC_INT_16_BITS + If the C type 'int' is 16 bits wide, define 'INT_16_BITS'. Use + 'AC_CHECK_SIZEOF(int)' instead. + + -- Macro: AC_IRIX_SUN + If on IRIX (Silicon Graphics UNIX), add '-lsun' to output 'LIBS'. + If you were using it to get 'getmntent', use 'AC_FUNC_GETMNTENT' + instead. If you used it for the NIS versions of the password and + group functions, use 'AC_CHECK_LIB(sun, getpwnam)'. Up to Autoconf + 2.13, it used to be + + AC_CHECK_LIB(sun, getmntent, LIBS="-lsun $LIBS") + + now it is defined as + + AC_FUNC_GETMNTENT + AC_CHECK_LIB(sun, getpwnam) + + -- Macro: AC_LANG_C + Same as 'AC_LANG(C)'. + + -- Macro: AC_LANG_CPLUSPLUS + Same as 'AC_LANG(C++)'. + + -- Macro: AC_LANG_FORTRAN77 + Same as 'AC_LANG(Fortran 77)'. + + -- Macro: AC_LANG_RESTORE + Select the LANGUAGE that is saved on the top of the stack, as set + by 'AC_LANG_SAVE', remove it from the stack, and call + 'AC_LANG(LANGUAGE)'. + + -- Macro: AC_LANG_SAVE + Remember the current language (as set by 'AC_LANG') on a stack. + The current language does not change. 'AC_LANG_PUSH' is preferred. + + -- Macro: AC_LINK_FILES (SOURCE..., DEST...) + This is an obsolete version of 'AC_CONFIG_LINKS'. An updated + version of: + + AC_LINK_FILES(config/$machine.h config/$obj_format.h, + host.h object.h) + + is: + + AC_CONFIG_LINKS(host.h:config/$machine.h + object.h:config/$obj_format.h) + + -- Macro: AC_LN_S + 'AC_PROG_LN_S' + + -- Macro: AC_LONG_64_BITS + Define 'LONG_64_BITS' if the C type 'long int' is 64 bits wide. + Use the generic macro 'AC_CHECK_SIZEOF([long int])' instead. + + -- Macro: AC_LONG_DOUBLE + 'AC_C_LONG_DOUBLE' + + -- Macro: AC_LONG_FILE_NAMES + 'AC_SYS_LONG_FILE_NAMES' + + -- Macro: AC_MAJOR_HEADER + 'AC_HEADER_MAJOR' + + -- Macro: AC_MEMORY_H + Used to define 'NEED_MEMORY_H' if the 'mem' functions were defined + in 'memory.h'. Today it is equivalent to + 'AC_CHECK_HEADERS(memory.h)'. Adjust your code to depend upon + 'HAVE_MEMORY_H', not 'NEED_MEMORY_H', see *Note Standard Symbols::. + + -- Macro: AC_MINGW32 + Similar to 'AC_CYGWIN' but checks for the MingW32 compiler + environment and sets 'MINGW32'. + + -- Macro: AC_MINUS_C_MINUS_O + 'AC_PROG_CC_C_O' + + -- Macro: AC_MMAP + 'AC_FUNC_MMAP' + + -- Macro: AC_MODE_T + 'AC_TYPE_MODE_T' + + -- Macro: AC_OBJEXT + Defined the output variable 'OBJEXT' based on the output of the + compiler, after .c files have been excluded. Typically set to 'o' + if Unix, 'obj' if Win32. Now the compiler checking macros handle + this automatically. + + -- Macro: AC_OBSOLETE (THIS-MACRO-NAME, [SUGGESTION]) + Make 'm4' print a message to the standard error output warning that + THIS-MACRO-NAME is obsolete, and giving the file and line number + where it was called. THIS-MACRO-NAME should be the name of the + macro that is calling 'AC_OBSOLETE'. If 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 THIS-MACRO-NAME. + + For instance + + AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl + + You are encouraged to use 'AU_DEFUN' instead, since it gives better + services to the user. + + -- Macro: AC_OFF_T + 'AC_TYPE_OFF_T' + + -- Macro: AC_OUTPUT ([FILE]..., [EXTRA-CMDS], [INIT-CMDS], [SAVE-DEFS]) + The use of 'AC_OUTPUT' with argument is deprecated, this obsoleted + interface is equivalent to: + + AC_CONFIG_FILES(FILE...) + AC_CONFIG_COMMANDS([default], + EXTRA-CMDS, INIT-CMDS) + AC_SETUP_DEFS(SAVE-DEFS) + AC_OUTPUT + + If you specify SAVE-DEFS, autoconf will save the '#define's in a + different form, for use in the files specified in + 'AC_CONFIG_HEADERS'. In this case, autoconf substitutes the + C-style '#define's where it finds '@DEFS@'. This runs faster, and + is simpler to maintain than building a file of '#undef's, since + autoconf will automatically generate a '#define' for each + 'AC_DEFINE' that you execute in the 'configure' script. The value + for SAVE-DEFS should be either 'cat', or 'sort'; this value is used + to filter the list of '#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. + + -- Macro: AC_OUTPUT_COMMANDS (EXTRA-CMDS, [INIT-CMDS]) + Specify additional shell commands to run at the end of + 'config.status', and shell commands to initialize any variables + from 'configure'. This macro may be called multiple times. It is + obsolete, replaced by 'AC_CONFIG_COMMANDS'. + + Here is an unrealistic 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]) + + Aside from the fact that 'AC_CONFIG_COMMANDS' requires an + additional key, an important difference is that + 'AC_OUTPUT_COMMANDS' is quoting its arguments twice, while + 'AC_CONFIG_COMMANDS'. This means that 'AC_CONFIG_COMMANDS' can + safely be given macro calls as arguments: + + AC_CONFIG_COMMANDS(foo, [my_FOO()]) + + conversely, where one level of quoting was enough for literal + strings with 'AC_OUTPUT_COMMANDS', you need two with + 'AC_CONFIG_COMMANDS'. The following lines are equivalent: + + AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) + AC_CONFIG_COMMANDS(default, [[echo "Square brackets: []"]]) + + -- Macro: AC_PID_T + 'AC_TYPE_PID_T' + + -- Macro: AC_PREFIX + 'AC_PREFIX_PROGRAM' + + -- Macro: AC_PROGRAMS_CHECK + 'AC_CHECK_PROGS' + + -- Macro: AC_PROGRAMS_PATH + 'AC_PATH_PROGS' + + -- Macro: AC_PROGRAM_CHECK + 'AC_CHECK_PROG' + + -- Macro: AC_PROGRAM_EGREP + 'AC_EGREP_CPP' + + -- Macro: AC_PROGRAM_PATH + 'AC_PATH_PROG' + + -- Macro: AC_REMOTE_TAPE + removed because of limited usefulness + + -- Macro: AC_RESTARTABLE_SYSCALLS + 'AC_SYS_RESTARTABLE_SYSCALLS' + + -- Macro: AC_RETSIGTYPE + 'AC_TYPE_SIGNAL' + + -- Macro: AC_RSH + Removed because of limited usefulness. + + -- Macro: AC_SCO_INTL + If on SCO UNIX, add '-lintl' to output variable 'LIBS'. This macro + used to + + AC_CHECK_LIB(intl, strftime, LIBS="-lintl $LIBS") + + now it just calls 'AC_FUNC_STRFTIME' instead. + + -- Macro: AC_SETVBUF_REVERSED + 'AC_FUNC_SETVBUF_REVERSED' + + -- Macro: AC_SET_MAKE + 'AC_PROG_MAKE_SET' + + -- Macro: AC_SIZEOF_TYPE + 'AC_CHECK_SIZEOF' + + -- Macro: AC_SIZE_T + 'AC_TYPE_SIZE_T' + + -- Macro: AC_STAT_MACROS_BROKEN + 'AC_HEADER_STAT' + + -- Macro: AC_STDC_HEADERS + 'AC_HEADER_STDC' + + -- Macro: AC_STRCOLL + 'AC_FUNC_STRCOLL' + + -- Macro: AC_ST_BLKSIZE + 'AC_STRUCT_ST_BLKSIZE' + + -- Macro: AC_ST_BLOCKS + 'AC_STRUCT_ST_BLOCKS' + + -- Macro: AC_ST_RDEV + 'AC_STRUCT_ST_RDEV' + + -- Macro: AC_SYS_RESTARTABLE_SYSCALLS + If the system automatically restarts a system call that is + interrupted by a signal, define 'HAVE_RESTARTABLE_SYSCALLS'. This + macro does not check if system calls are restarted in general-it + tests whether a signal handler installed with 'signal' (but not + '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 'sigaction' with + 'SA_RESTART' if they want restartable system calls. They should + not rely on 'HAVE_RESTARTABLE_SYSCALLS', since nowadays whether a + system call is restartable is a dynamic issue, not a + configuration-time issue. + + -- Macro: AC_SYS_SIGLIST_DECLARED + 'AC_DECL_SYS_SIGLIST' + + -- Macro: AC_TEST_CPP + 'AC_TRY_CPP' + + -- Macro: AC_TEST_PROGRAM + 'AC_TRY_RUN' + + -- Macro: AC_TIMEZONE + 'AC_STRUCT_TIMEZONE' + + -- Macro: AC_TIME_WITH_SYS_TIME + 'AC_HEADER_TIME' + + -- Macro: AC_UID_T + 'AC_TYPE_UID_T' + + -- Macro: AC_UNISTD_H + Same as 'AC_CHECK_HEADERS(unistd.h)'. + + -- Macro: AC_USG + Define 'USG' if the BSD string functions are defined in + 'strings.h'. You should no longer depend upon 'USG', but on + 'HAVE_STRING_H', see *Note Standard Symbols::. + + -- Macro: AC_UTIME_NULL + 'AC_FUNC_UTIME_NULL' + + -- Macro: AC_VALIDATE_CACHED_SYSTEM_TUPLE ([CMD]) + If the cache file is inconsistent with the current host, target and + build system types, it used to execute CMD or print a default error + message. + + This is now handled by default. + + -- Macro: AC_VERBOSE (RESULT-DESCRIPTION) + 'AC_MSG_RESULT'. + + -- Macro: AC_VFORK + 'AC_FUNC_VFORK' + + -- Macro: AC_VPRINTF + 'AC_FUNC_VPRINTF' + + -- Macro: AC_WAIT3 + 'AC_FUNC_WAIT3' + + -- Macro: AC_WARN + 'AC_MSG_WARN' + + -- Macro: AC_WORDS_BIGENDIAN + 'AC_C_BIGENDIAN' + + -- Macro: AC_XENIX_DIR + This macro used to add '-lx' to output variable 'LIBS' if on Xenix. + Also, if 'dirent.h' is being checked for, added '-ldir' to 'LIBS'. + Now it is merely an alias of 'AC_HEADER_DIRENT' instead, plus some + code to detect whether running XENIX on which you should not + depend: + + 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=]) + + -- Macro: AC_YYTEXT_POINTER + 'AC_DECL_YYTEXT' + + +File: autoconf.info, Node: Autoconf 1, Next: Autoconf 2.13, Prev: Obsolete Macros, Up: Obsolete Constructs + +15.5 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 '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 +'configure' scripts could benefit from some of the new features in +version 2; the changes are summarized in the file 'NEWS' in the Autoconf +distribution. + +* Menu: + +* Changed File Names:: Files you might rename +* Changed Makefiles:: New things to put in '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 + + +File: autoconf.info, Node: Changed File Names, Next: Changed Makefiles, Prev: Autoconf 1, Up: Autoconf 1 + +15.5.1 Changed File Names +------------------------- + +If you have an 'aclocal.m4' installed with Autoconf (as opposed to in a +particular package's source directory), you must rename it to +'acsite.m4'. *Note autoconf Invocation::. + + If you distribute 'install.sh' with your package, rename it to +'install-sh' so 'make' builtin rules won't inadvertently create a file +called 'install' from it. 'AC_PROG_INSTALL' looks for the script under +both names, but it is best to use the new name. + + If you were using 'config.h.top', 'config.h.bot', or 'acconfig.h', +you still can, but you will have less clutter if you use the 'AH_' +macros. *Note Autoheader Macros::. + + +File: autoconf.info, Node: Changed Makefiles, Next: Changed Macros, Prev: Changed File Names, Up: Autoconf 1 + +15.5.2 Changed Makefiles +------------------------ + +Add '@CFLAGS@', '@CPPFLAGS@', and '@LDFLAGS@' in your 'Makefile.in' +files, so they can take advantage of the values of those variables in +the environment when 'configure' is run. Doing this isn't necessary, +but it's a convenience for users. + + Also add '@configure_input@' in a comment to each input file for +'AC_OUTPUT', so that the output files will contain a comment saying they +were produced by 'configure'. Automatically selecting the right comment +syntax for all the kinds of files that people call 'AC_OUTPUT' on became +too much work. + + Add 'config.log' and 'config.cache' to the list of files you remove +in 'distclean' targets. + + If you have the following in 'Makefile.in': + + prefix = /usr/local + exec_prefix = $(prefix) + +you must change it to: + + prefix = @prefix@ + exec_prefix = @exec_prefix@ + +The old behavior of replacing those variables without '@' characters +around them has been removed. + + +File: autoconf.info, Node: Changed Macros, Next: Changed Results, Prev: Changed Makefiles, Up: Autoconf 1 + +15.5.3 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. *Note Obsolete Macros::, for a table +showing the new names for the old macros. Use the 'autoupdate' program +to convert your 'configure.ac' to using the new macro names. *Note +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 'autoconf', you may safely ignore them, +but your '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 'echo' or 'AC_VERBOSE' (perhaps via +'AC_COMPILE_CHECK'), your 'configure' script's output will look better +if you switch to 'AC_MSG_CHECKING' and 'AC_MSG_RESULT'. *Note Printing +Messages::. Those macros work best in conjunction with cache variables. +*Note Caching Results::. + + +File: autoconf.info, Node: Changed Results, Next: Changed Macro Writing, Prev: Changed Macros, Up: Autoconf 1 + +15.5.4 Changed Results +---------------------- + +If you were checking the results of previous tests by examining the +shell variable 'DEFS', you need to switch to checking the values of the +cache variables for those tests. 'DEFS' no longer exists while +'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 'AC_DEFINE' is called. *Note Cache Variable Names::. + + For example, here is a 'configure.ac' fragment written for Autoconf +version 1: + + 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 + + Here is a way to write it for version 2: + + 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 + + If you were working around bugs in '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. +*Note Setting Output Variables::. + + All of the boolean shell variables set by Autoconf macros now use +'yes' for the true value. Most of them use '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 't' for +true, you need to change your tests. + + +File: autoconf.info, Node: Changed Macro Writing, Prev: Changed Results, Up: Autoconf 1 + +15.5.5 Changed Macro Writing +---------------------------- + +When defining your own macros, you should now use 'AC_DEFUN' instead of +'define'. 'AC_DEFUN' automatically calls 'AC_PROVIDE' and ensures that +macros called via 'AC_REQUIRE' do not interrupt other macros, to prevent +nested 'checking...' messages on the screen. There's no actual harm in +continuing to use the older way, but it's less convenient and +attractive. *Note 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. + + +File: autoconf.info, Node: Autoconf 2.13, Prev: Autoconf 1, Up: Obsolete Constructs + +15.6 Upgrading From Version 2.13 +================================ + +The introduction of the previous section (*note Autoconf 1::) perfectly +suits this section... + + 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 '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 'configure' scripts could benefit + from some of the new features in version 2.50; the changes are + summarized in the file 'NEWS' in the Autoconf distribution. + +* Menu: + +* Changed Quotation:: Broken code which used to work +* New Macros:: Interaction with foreign macros + + +File: autoconf.info, Node: Changed Quotation, Next: New Macros, Prev: Autoconf 2.13, Up: Autoconf 2.13 + +15.6.1 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: + + AC_INIT + AC_CHECK_HEADERS(foo.h,, + AC_MSG_ERROR(cannot find foo.h, bailing out)) + AC_OUTPUT + +Autoconf 2.13 simply ignores it: + + $ autoconf-2.13; ./configure --silent + creating cache ./config.cache + configure: error: cannot find foo.h + $ + +while Autoconf 2.50 will produce a broken 'configure': + + $ 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' + $ + + The message needs to be quoted, and the 'AC_MSG_ERROR' invocation +too! + + AC_INIT + AC_CHECK_HEADERS(foo.h,, + [AC_MSG_ERROR([cannot find foo.h, bailing out])]) + AC_OUTPUT + + Many many (and many more) Autoconf macros were lacking proper +quotation, including no less than... 'AC_DEFUN' itself! + + $ 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 + $ + + +File: autoconf.info, Node: New Macros, Prev: Changed Quotation, Up: Autoconf 2.13 + +15.6.2 New Macros +----------------- + +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 'AC_' namespace, instead of +'AM_'. But in order to ease the upgrading via 'autoupdate', bindings to +such 'AM_' macros are provided. + + Unfortunately Automake did not quote the name of these macros! +Therefore, when 'm4' find in 'aclocal.m4' something like +'AC_DEFUN(AM_TYPE_PTRDIFF_T, ...)', 'AM_TYPE_PTRDIFF_T' is expanded, +replaced with its Autoconf definition. + + Fortunately Autoconf catches pre-'AC_INIT' expansions, and will +complain, in its own words: + + $ 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 + $ + + 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): + + $ 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 + $ + + +File: autoconf.info, Node: Questions, Next: History, Prev: Obsolete Constructs, Up: Top + +16 Questions About Autoconf +*************************** + +Several questions about Autoconf come up occasionally. Here some of +them are addressed. + +* Menu: + +* Distributing:: Distributing 'configure' scripts +* Why GNU m4:: Why not use the standard M4? +* Bootstrapping:: Autoconf and GNU M4 require each other? +* Why Not Imake:: Why GNU uses 'configure' instead of Imake + + +File: autoconf.info, Node: Distributing, Next: Why GNU m4, Prev: Questions, Up: Questions + +16.1 Distributing 'configure' Scripts +===================================== + + What are the restrictions on distributing 'configure' + scripts that Autoconf generates? How does that affect my + programs that use them? + + There are no restrictions on how the configuration scripts that +Autoconf produces may be distributed or used. In Autoconf version 1, +they were covered by the GNU General Public License. We still encourage +software authors to distribute their work under terms like those of the +GPL, but doing so is not required to use Autoconf. + + Of the other files that might be used with 'configure', 'config.h.in' +is under whatever copyright you use for your 'configure.ac'. +'config.sub' and 'config.guess' have an exception to the GPL when they +are used with an Autoconf-generated 'configure' script, which permits +you to distribute them under the same terms as the rest of your package. +'install-sh' is from the X Consortium and is not copyrighted. + + +File: autoconf.info, Node: Why GNU m4, Next: Bootstrapping, Prev: Distributing, Up: Questions + +16.2 Why Require GNU M4? +======================== + + Why does Autoconf require GNU M4? + + 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: + + builtin + indir + patsubst + __file__ + __line__ + + Autoconf requires version 1.4 or above of GNU M4 because it uses +frozen state files. + + Since only software maintainers need to use Autoconf, and since GNU +M4 is simple to configure and install, it seems reasonable to require +GNU M4 to be installed also. Many maintainers of GNU and other free +software already have most of the GNU utilities installed, since they +prefer them. + + +File: autoconf.info, Node: Bootstrapping, Next: Why Not Imake, Prev: Why GNU m4, Up: Questions + +16.3 How Can I Bootstrap? +========================= + + If Autoconf requires GNU M4 and GNU M4 has an Autoconf + 'configure' script, how do I bootstrap? It seems like a chicken + and egg problem! + + This is a misunderstanding. Although GNU M4 does come with a +'configure' script produced by Autoconf, Autoconf is not required in +order to run the script and install GNU M4. Autoconf is only required +if you want to change the M4 'configure' script, which few people have +to do (mainly its maintainer). + + +File: autoconf.info, Node: Why Not Imake, Prev: Bootstrapping, Up: Questions + +16.4 Why Not Imake? +=================== + + Why not use Imake instead of 'configure' scripts? + + Several people have written addressing this question, so I include +adaptations of their explanations here. + + The following answer is based on one written by Richard Pixley: + + Autoconf generated scripts frequently work on machines 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. + + GNU tools are not released this way. Each GNU tool has a + maintainer; these maintainers are scattered across the world. + Using a common database would be a maintenance nightmare. Autoconf + may appear to be this kind of database, but in fact it is not. + Instead of listing host dependencies, it lists program + requirements. + + If you view the GNU suite as a collection of native tools, then the + problems are similar. But the 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 GNU coding + standards address the same issues without necessarily imposing the + same restrictions. + + Here is some further explanation, written by Per Bothner: + + One of the advantages of Imake is that it easy to generate large + Makefiles using 'cpp''s '#include' and macro mechanisms. However, + 'cpp' is not programmable: it has limited conditional facilities, + and no looping. And 'cpp' cannot inspect its environment. + + All of these problems are solved by using 'sh' instead of 'cpp'. + The shell is fully programmable, has macro substitution, can + execute (or source) other shell scripts, and can inspect its + environment. + + Paul Eggert elaborates more: + + With Autoconf, installers need not assume that Imake itself is + already installed and working well. This may not seem like much of + an advantage to people who are accustomed to Imake. But on many + hosts Imake is not installed or the default installation is not + working well, and requiring Imake to install a package hinders the + acceptance of that package on those hosts. For example, the Imake + template and configuration files might not be installed properly on + a host, or the Imake build procedure might wrongly assume that all + source files are in one big directory tree, or the Imake + configuration might assume one compiler whereas the package or the + installer needs to use another, or there might be a version + mismatch between the Imake expected by the package and the Imake + 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 + 'make' and the installer's C preprocessor. The fundamental problem + here is that the C preprocessor was designed to preprocess C + programs, not 'Makefile's. This is much less of a problem with + Autoconf, which uses the general-purpose preprocessor 'm4', and + where the package's author (rather than the installer) does the + preprocessing in a standard way. + + Finally, Mark Eichin notes: + + Imake isn't all that extensible, either. In order to add new + features to Imake, you need to provide 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 'configure': 'Imakefile's + tend to be much shorter (likewise, less redundant) than + '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 'post.in' + and 'pre.in' '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 'configure' setups. + + +File: autoconf.info, Node: History, Next: Environment Variable Index, Prev: Questions, Up: Top + +17 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 _are_ wondering, then let +there be light... + +* Menu: + +* Genesis:: Prehistory and naming of 'configure' +* Exodus:: The plagues of M4 and Perl +* Leviticus:: The priestly code of portability arrives +* Numbers:: Growth and contributors +* Deuteronomy:: Approaching the promises of easy configuration + + +File: autoconf.info, Node: Genesis, Next: Exodus, Prev: History, Up: History + +17.1 Genesis +============ + +In June 1991 I was maintaining many of the GNU utilities for the Free +Software Foundation. As they were ported to more platforms and more +programs were added, the number of '-D' options that users had to select +in the '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 +'configure' script worked well enough that the next month I adapted it +(by hand) to create similar 'configure' scripts for several other GNU +utilities packages. Brian Berliner also adapted one of my scripts for +his CVS revision control system. + + Later that summer, I learned that Richard Stallman and Richard Pixley +were developing similar scripts to use in the GNU compiler tools; so I +adapted my 'configure' scripts to support their evolving interface: +using the file name 'Makefile.in' as the templates; adding '+srcdir', +the first option (of many); and creating 'config.status' files. + + +File: autoconf.info, Node: Exodus, Next: Leviticus, Prev: Genesis, Up: History + +17.2 Exodus +=========== + +As I got feedback from users, I incorporated many improvements, using +Emacs to search and replace, cut and paste, similar changes in each of +the scripts. As I adapted more GNU utilities packages to use +'configure' scripts, updating them all by hand became impractical. Rich +Murphey, the maintainer of the GNU graphics utilities, sent me mail +saying that the '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 'configure' scripts to the abundance +and ease of Autoconf began. + + Cygnus '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 +'configure', where there is a single 'configure' script that reads +pieces of '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 'configure' made from each '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 '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 '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 '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 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 'tvtwm', and I was interested in trying out a new language. + + +File: autoconf.info, Node: Leviticus, Next: Numbers, Prev: Exodus, Up: History + +17.3 Leviticus +============== + +Since my 'configure' scripts determine the system's capabilities +automatically, with no interactive user intervention, I decided to call +the program that generates them Autoconfig. But with a version number +tacked on, that name would be too long for old UNIX file systems, so I +shortened it to Autoconf. + + In the fall of 1991 I called together a group of fellow questers +after the Holy Grail of portability (er, that is, alpha testers) to give +me feedback as I encapsulated pieces of my handwritten scripts in M4 +macros and continued to add features and improve the techniques used in +the checks. Prominent among the testers were François Pinard, who came +up with the idea of making an 'autoconf' shell script to run '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 '-D' options in a 'Makefile', so he could use +Autoconf for his UUCP package. The alpha testers cheerfully adjusted +their files again and again as the names and calling conventions of the +Autoconf macros changed from release to release. They all contributed +many specific checks, great ideas, and bug fixes. + + +File: autoconf.info, Node: Numbers, Next: Deuteronomy, Prev: Leviticus, Up: History + +17.4 Numbers +============ + +In July 1992, after months of alpha testing, I released Autoconf 1.0, +and converted many GNU packages to use it. I was surprised by how +positive the reaction to it was. More people started using it than I +could keep track of, including people working on software that wasn't +part of the GNU Project (such as TCL, FSP, and Kerberos V5). Autoconf +continued to improve rapidly, as many people using the 'configure' +scripts reported problems they encountered. + + Autoconf turned out to be a good torture test for M4 implementations. +UNIX 'm4' started to dump core because of the length of the macros that +Autoconf defined, and several bugs showed up in GNU 'm4' as well. +Eventually, we realized that we needed to use some features that only +GNU M4 has. 4.3BSD '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çois Pinard made it diagnose +invalid arguments. Jim Blandy bravely coerced it into configuring GNU +Emacs, laying the groundwork for several later improvements. Roland +McGrath got it to configure the GNU C Library, wrote the 'autoheader' +script to automate the creation of C header file templates, and added a +'--verbose' option to 'configure'. Noah Friedman added the +'--autoconf-dir' option and 'AC_MACRODIR' environment variable. (He +also coined the term "autoconfiscate" to mean "adapt a software package +to use Autoconf".) Roland and Noah improved the quoting protection in +'AC_DEFINE' and fixed many bugs, especially when I got sick of dealing +with portability problems from February through June, 1993. + + +File: autoconf.info, Node: Deuteronomy, Prev: Numbers, Up: History + +17.5 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 +'configure' that Autoconf had lacked, largely by adapting the relevant +parts of Cygnus 'configure' with the help of david zuhn and Ken Raeburn. +These features include support for using 'config.sub', 'config.guess', +'--host', and '--target'; making links to files; and running 'configure' +scripts in subdirectories. Adding these features enabled Ken to convert +GNU '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 '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 '.in' extension on the file names, which produced file +names like 'config.h.in' containing two dots. Jim Avera did an +extensive examination of the problems with quoting in 'AC_DEFINE' and +'AC_SUBST'; his insights led to significant improvements. Richard +Stallman asked that compiler output be sent to 'config.log' instead of +'/dev/null', to help people debug the Emacs '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çois Pinard, +I made the macros not interrupt each others' messages. (That feature +revealed some performance bottlenecks in GNU '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çois 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.) + + +File: autoconf.info, Node: Environment Variable Index, Next: Output Variable Index, Prev: History, Up: Top + +Environment Variable Index +************************** + +This is an alphabetical list of the environment variables that Autoconf +checks. + + +* Menu: + +* AC_MACRODIR: autoscan Invocation. (line 54) +* AC_MACRODIR <1>: autoconf Invocation. (line 45) +* AC_MACRODIR <2>: autoreconf Invocation. + (line 77) +* AC_MACRODIR <3>: autoheader Invocation. + (line 62) +* AC_MACRODIR <4>: autoupdate Invocation. + (line 42) +* CDPATH: Special Shell Variables. + (line 13) +* CONFIG_COMMANDS: Obsolete config.status Use. + (line 11) +* CONFIG_FILES: Obsolete config.status Use. + (line 15) +* CONFIG_HEADERS: Obsolete config.status Use. + (line 20) +* CONFIG_LINKS: Obsolete config.status Use. + (line 25) +* CONFIG_SHELL: config.status Invocation. + (line 75) +* CONFIG_SITE: Site Defaults. (line 10) +* CONFIG_STATUS: config.status Invocation. + (line 79) +* IFS: Special Shell Variables. + (line 45) +* LANG: Special Shell Variables. + (line 59) +* LANGUAGE: Special Shell Variables. + (line 59) +* LC_ALL: Special Shell Variables. + (line 59) +* LC_COLLATE: Special Shell Variables. + (line 59) +* LC_CTYPE: Special Shell Variables. + (line 59) +* LC_MESSAGES: Special Shell Variables. + (line 59) +* LC_NUMERIC: Special Shell Variables. + (line 59) +* LC_TIME: Special Shell Variables. + (line 59) +* NULLCMD: Special Shell Variables. + (line 77) +* PATH_SEPARATOR: Special Shell Variables. + (line 88) +* RANDOM: Special Shell Variables. + (line 97) +* SIMPLE_BACKUP_SUFFIX: autoupdate Invocation. + (line 16) +* status: Special Shell Variables. + (line 84) +* WARNINGS: autoconf Invocation. (line 65) +* WARNINGS <1>: autoheader Invocation. + (line 78) + + +File: autoconf.info, Node: Output Variable Index, Next: Preprocessor Symbol Index, Prev: Environment Variable Index, Up: Top + +Output Variable Index +********************* + +This is an alphabetical list of the variables that Autoconf can +substitute into files that it creates, typically one or more +'Makefile's. *Note Setting Output Variables::, for more information on +how this is done. + + +* Menu: + +* ALLOCA: Particular Functions. + (line 10) +* AWK: Particular Programs. (line 10) +* bindir: Installation Directory Variables. + (line 12) +* build: Canonicalizing. (line 26) +* build_alias: Canonicalizing. (line 9) +* build_cpu: Canonicalizing. (line 26) +* build_os: Canonicalizing. (line 26) +* build_vendor: Canonicalizing. (line 26) +* CC: C Compiler. (line 7) +* CC <1>: C Compiler. (line 34) +* CC <2>: C Compiler. (line 156) +* CC <3>: System Services. (line 44) +* CC <4>: UNIX Variants. (line 18) +* CFLAGS: Preset Output Variables. + (line 15) +* CFLAGS <1>: C Compiler. (line 7) +* configure_input: Preset Output Variables. + (line 22) +* CPP: C Compiler. (line 47) +* CPPFLAGS: Preset Output Variables. + (line 36) +* cross_compiling: Specifying Names. (line 26) +* CXX: C++ Compiler. (line 7) +* CXXCPP: C++ Compiler. (line 31) +* CXXFLAGS: Preset Output Variables. + (line 43) +* CXXFLAGS <1>: C++ Compiler. (line 7) +* datadir: Installation Directory Variables. + (line 15) +* DEFS: Preset Output Variables. + (line 50) +* ECHO_C: Preset Output Variables. + (line 60) +* ECHO_N: Preset Output Variables. + (line 60) +* ECHO_T: Preset Output Variables. + (line 60) +* EGREP: Particular Programs. (line 16) +* exec_prefix: Installation Directory Variables. + (line 19) +* EXEEXT: Compilers and Preprocessors. + (line 6) +* EXEEXT <1>: Obsolete Macros. (line 145) +* F77: Fortran 77 Compiler. (line 7) +* FFLAGS: Preset Output Variables. + (line 72) +* FFLAGS <1>: Fortran 77 Compiler. (line 7) +* FGREP: Particular Programs. (line 20) +* FLIBS: Fortran 77 Compiler. (line 38) +* GETGROUPS_LIBS: Particular Functions. + (line 97) +* GETLOADAVG_LIBS: Particular Functions. + (line 103) +* GREP: Particular Programs. (line 24) +* host: Canonicalizing. (line 34) +* host_alias: Canonicalizing. (line 9) +* host_cpu: Canonicalizing. (line 34) +* host_os: Canonicalizing. (line 34) +* host_vendor: Canonicalizing. (line 34) +* includedir: Installation Directory Variables. + (line 26) +* infodir: Installation Directory Variables. + (line 29) +* INSTALL: Particular Programs. (line 28) +* INSTALL_DATA: Particular Programs. (line 28) +* INSTALL_PROGRAM: Particular Programs. (line 28) +* INSTALL_SCRIPT: Particular Programs. (line 28) +* KMEM_GROUP: Particular Functions. + (line 103) +* LDFLAGS: Preset Output Variables. + (line 79) +* LEX: Particular Programs. (line 57) +* LEXLIB: Particular Programs. (line 57) +* LEX_OUTPUT_ROOT: Particular Programs. (line 57) +* libdir: Installation Directory Variables. + (line 32) +* libexecdir: Installation Directory Variables. + (line 35) +* LIBOBJS: Particular Functions. + (line 103) +* LIBOBJS <1>: Particular Functions. + (line 160) +* LIBOBJS <2>: Particular Functions. + (line 167) +* LIBOBJS <3>: Generic Functions. (line 44) +* LIBOBJS <4>: Generic Functions. (line 84) +* LIBOBJS <5>: Particular Structures. + (line 17) +* LIBS: Preset Output Variables. + (line 87) +* LIBS <1>: Obsolete Macros. (line 408) +* LIBS <2>: Obsolete Macros. (line 515) +* LN_S: Particular Programs. (line 95) +* localstatedir: Installation Directory Variables. + (line 38) +* mandir: Installation Directory Variables. + (line 41) +* NEED_SETGID: Particular Functions. + (line 103) +* OBJEXT: Compilers and Preprocessors. + (line 10) +* OBJEXT <1>: Obsolete Macros. (line 300) +* oldincludedir: Installation Directory Variables. + (line 44) +* POW_LIB: Particular Functions. + (line 216) +* prefix: Installation Directory Variables. + (line 47) +* program_transform_name: Transforming Names. (line 11) +* RANLIB: Particular Programs. (line 114) +* sbindir: Installation Directory Variables. + (line 52) +* SET_MAKE: Output. (line 37) +* sharedstatedir: Installation Directory Variables. + (line 56) +* srcdir: Preset Output Variables. + (line 94) +* subdirs: Subdirectories. (line 12) +* sysconfdir: Installation Directory Variables. + (line 60) +* target: Canonicalizing. (line 46) +* target_alias: Canonicalizing. (line 9) +* target_cpu: Canonicalizing. (line 46) +* target_os: Canonicalizing. (line 46) +* target_vendor: Canonicalizing. (line 46) +* top_srcdir: Preset Output Variables. + (line 97) +* X_CFLAGS: System Services. (line 26) +* X_EXTRA_LIBS: System Services. (line 26) +* X_LIBS: System Services. (line 26) +* X_PRE_LIBS: System Services. (line 26) +* YACC: Particular Programs. (line 118) + + +File: autoconf.info, Node: Preprocessor Symbol Index, Next: Autoconf Macro Index, Prev: Output Variable Index, Up: Top + +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 '#if' directives. + + +* Menu: + +* _ALL_SOURCE: UNIX Variants. (line 13) +* _FILE_OFFSET_BITS: System Services. (line 44) +* _LARGEFILE_SOURCE: Particular Functions. + (line 93) +* _LARGE_FILES: System Services. (line 44) +* _MINIX: UNIX Variants. (line 25) +* _POSIX_1_SOURCE: UNIX Variants. (line 25) +* _POSIX_SOURCE: UNIX Variants. (line 18) +* _POSIX_SOURCE <1>: UNIX Variants. (line 25) +* _POSIX_VERSION: Particular Headers. (line 130) +* __CHAR_UNSIGNED__: C Compiler. (line 120) +* CLOSEDIR_VOID: Particular Functions. + (line 58) +* const: C Compiler. (line 73) +* C_ALLOCA: Particular Functions. + (line 10) +* C_GETLOADAVG: Particular Functions. + (line 103) +* DGUX: Particular Functions. + (line 103) +* DIRENT: Obsolete Macros. (line 126) +* F77_DUMMY_MAIN: Fortran 77 Compiler. (line 64) +* F77_FUNC: Fortran 77 Compiler. (line 115) +* F77_FUNC_: Fortran 77 Compiler. (line 115) +* F77_MAIN: Fortran 77 Compiler. (line 101) +* F77_NO_MINUS_C_MINUS_O: Fortran 77 Compiler. (line 28) +* GETGROUPS_T: Particular Types. (line 10) +* GETLODAVG_PRIVILEGED: Particular Functions. + (line 103) +* GETPGRP_VOID: Particular Functions. + (line 136) +* gid_t: Particular Types. (line 39) +* GWINSZ_IN_SYS_IOCTL: Particular Headers. (line 167) +* HAVE_ALLOCA_H: Particular Functions. + (line 10) +* HAVE_CONFIG_H: Configuration Headers. + (line 25) +* HAVE_DECL_SYMBOL: Generic Declarations. + (line 23) +* HAVE_DIRENT_H: Particular Headers. (line 10) +* HAVE_DOPRNT: Particular Functions. + (line 238) +* HAVE_FUNCTION: Generic Functions. (line 25) +* HAVE_GETMNTENT: Particular Functions. + (line 131) +* HAVE_HEADER: Generic Headers. (line 43) +* HAVE_LONG_DOUBLE: C Compiler. (line 124) +* HAVE_LONG_FILE_NAMES: System Services. (line 58) +* HAVE_LSTAT_EMPTY_STRING_BUG: Particular Functions. + (line 196) +* HAVE_MMAP: Particular Functions. + (line 171) +* HAVE_NDIR_H: Particular Headers. (line 10) +* HAVE_OBSTACK: Particular Functions. + (line 176) +* HAVE_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 446) +* HAVE_STAT_EMPTY_STRING_BUG: Particular Functions. + (line 196) +* HAVE_STRCOLL: Particular Functions. + (line 210) +* HAVE_STRERROR_R: Particular Functions. + (line 222) +* HAVE_STRFTIME: Particular Functions. + (line 230) +* HAVE_STRINGIZE: C Compiler. (line 130) +* HAVE_STRUCT_STAT_ST_BLKSIZE: Particular Structures. + (line 9) +* HAVE_STRUCT_STAT_ST_BLOCKS: Particular Structures. + (line 17) +* HAVE_STRUCT_STAT_ST_RDEV: Particular Structures. + (line 23) +* HAVE_ST_BLKSIZE: Particular Structures. + (line 9) +* HAVE_ST_BLOCKS: Particular Structures. + (line 17) +* HAVE_ST_RDEV: Particular Structures. + (line 23) +* HAVE_SYS_DIR_H: Particular Headers. (line 10) +* HAVE_SYS_NDIR_H: Particular Headers. (line 10) +* HAVE_SYS_WAIT_H: Particular Headers. (line 112) +* HAVE_TM_ZONE: Particular Structures. + (line 36) +* HAVE_TZNAME: Particular Structures. + (line 36) +* HAVE_UTIME_NULL: Particular Functions. + (line 234) +* HAVE_VFORK_H: Particular Functions. + (line 71) +* HAVE_VPRINTF: Particular Functions. + (line 238) +* HAVE_WAIT3: Obsolete Macros. (line 166) +* HAVE_WORKING_FORK: Particular Functions. + (line 71) +* HAVE_WORKING_STRERROR_R: Particular Functions. + (line 222) +* HAVE_WORKING_VFORK: Particular Functions. + (line 71) +* inline: C Compiler. (line 115) +* INT_16_BITS: Obsolete Macros. (line 217) +* LONG_64_BITS: Obsolete Macros. (line 268) +* LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. + (line 143) +* MAJOR_IN_MKDEV: Particular Headers. (line 46) +* MAJOR_IN_SYSMACROS: Particular Headers. (line 46) +* mode_t: Particular Types. (line 14) +* NDIR: Obsolete Macros. (line 126) +* NEED_MEMORY_H: Obsolete Macros. (line 281) +* NEED_SETGID: Particular Functions. + (line 103) +* NLIST_NAME_UNION: Particular Functions. + (line 103) +* NLIST_STRUCT: Particular Functions. + (line 103) +* NO_MINUS_C_MINUS_O: C Compiler. (line 26) +* off_t: Particular Types. (line 17) +* PARAMS: C Compiler. (line 137) +* pid_t: Particular Types. (line 20) +* PROTOTYPES: C Compiler. (line 137) +* RETSIGTYPE: Particular Types. (line 23) +* SELECT_TYPE_ARG1: Particular Functions. + (line 180) +* SELECT_TYPE_ARG234: Particular Functions. + (line 180) +* SELECT_TYPE_ARG5: Particular Functions. + (line 180) +* SETPGRP_VOID: Particular Functions. + (line 188) +* SETVBUF_REVERSED: Particular Functions. + (line 205) +* size_t: Particular Types. (line 36) +* STDC_HEADERS: Particular Headers. (line 57) +* SVR4: Particular Functions. + (line 103) +* SYSDIR: Obsolete Macros. (line 126) +* SYSNDIR: Obsolete Macros. (line 126) +* SYS_SIGLIST_DECLARED: Particular Declarations. + (line 9) +* TIME_WITH_SYS_TIME: Particular Headers. (line 146) +* TM_IN_SYS_TIME: Particular Structures. + (line 31) +* uid_t: Particular Types. (line 39) +* UMAX: Particular Functions. + (line 103) +* UMAX4_3: Particular Functions. + (line 103) +* USG: Obsolete Macros. (line 482) +* vfork: Particular Functions. + (line 71) +* volatile: C Compiler. (line 98) +* WORDS_BIGENDIAN: C Compiler. (line 68) +* X_DISPLAY_MISSING: System Services. (line 26) +* YYTEXT_POINTER: Particular Programs. (line 57) + + +File: autoconf.info, Node: Autoconf Macro Index, Next: M4 Macro Index, Prev: Preprocessor Symbol Index, Up: Top + +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 'AC_'. + + +* Menu: + +* AH_BOTTOM: Autoheader Macros. (line 56) +* AH_TEMPLATE: Autoheader Macros. (line 32) +* AH_TOP: Autoheader Macros. (line 53) +* AH_VERBATIM: Autoheader Macros. (line 18) +* AIX: UNIX Variants. (line 13) +* ALLOCA: Obsolete Macros. (line 20) +* ARG_ARRAY: Obsolete Macros. (line 23) +* ARG_ENABLE: Package Options. (line 40) +* ARG_PROGRAM: Transforming Names. (line 11) +* ARG_VAR: Setting Output Variables. + (line 57) +* ARG_WITH: External Software. (line 41) +* AU_DEFUN: Obsoleting Macros. (line 18) +* BEFORE: Suggested Ordering. (line 28) +* BOTTOM: Autoheader Macros. (line 56) +* CACHE_CHECK: Caching Results. (line 29) +* CACHE_LOAD: Cache Checkpointing. (line 13) +* CACHE_SAVE: Cache Checkpointing. (line 17) +* CACHE_VAL: Caching Results. (line 15) +* CANONICAL_BUILD: Canonicalizing. (line 26) +* CANONICAL_HOST: Canonicalizing. (line 34) +* CANONICAL_SYSTEM: Obsolete Macros. (line 29) +* CANONICAL_TARGET: Canonicalizing. (line 46) +* CHAR_UNSIGNED: Obsolete Macros. (line 39) +* CHECKING: Obsolete Macros. (line 89) +* CHECK_DECL: Generic Declarations. + (line 11) +* CHECK_DECLS: Generic Declarations. + (line 23) +* CHECK_FILE: Files. (line 13) +* CHECK_FILES: Files. (line 19) +* CHECK_FUNC: Generic Functions. (line 15) +* CHECK_FUNCS: Generic Functions. (line 25) +* CHECK_HEADER: Generic Headers. (line 13) +* CHECK_HEADERS: Generic Headers. (line 43) +* CHECK_LIB: Libraries. (line 11) +* CHECK_MEMBER: Generic Structures. (line 11) +* CHECK_MEMBERS: Generic Structures. (line 25) +* CHECK_PROG: Generic Programs. (line 23) +* CHECK_PROGS: Generic Programs. (line 33) +* CHECK_SIZEOF: Generic Compiler Characteristics. + (line 7) +* CHECK_TOOL: Generic Programs. (line 43) +* CHECK_TOOLS: Generic Programs. (line 54) +* CHECK_TYPE: Generic Types. (line 11) +* CHECK_TYPE <1>: Obsolete Macros. (line 42) +* CHECK_TYPES: Generic Types. (line 16) +* COMPILE_CHECK: Obsolete Macros. (line 93) +* CONFIG_AUX_DIR: Input. (line 29) +* CONFIG_COMMANDS: Configuration Commands. + (line 13) +* CONFIG_FILES: Configuration Files. (line 9) +* CONFIG_HEADERS: Configuration Headers. + (line 25) +* CONFIG_LINKS: Configuration Links. (line 12) +* CONFIG_SRCDIR: Input. (line 16) +* CONFIG_SUBDIRS: Subdirectories. (line 12) +* CONST: Obsolete Macros. (line 100) +* COPYRIGHT: Notices. (line 21) +* CROSS_CHECK: Obsolete Macros. (line 103) +* CYGWIN: Obsolete Macros. (line 107) +* C_BIGENDIAN: C Compiler. (line 68) +* C_CHAR_UNSIGNED: C Compiler. (line 120) +* C_CONST: C Compiler. (line 73) +* C_CROSS: Obsolete Macros. (line 26) +* C_INLINE: C Compiler. (line 115) +* C_LONG_DOUBLE: C Compiler. (line 124) +* C_PROTOTYPES: C Compiler. (line 137) +* C_STRINGIZE: C Compiler. (line 130) +* C_VOLATILE: C Compiler. (line 98) +* DECL_SYS_SIGLIST: Particular Declarations. + (line 9) +* DECL_YYTEXT: Obsolete Macros. (line 123) +* DEFINE: Defining Symbols. (line 29) +* DEFINE_UNQUOTED: Defining Symbols. (line 45) +* DEFUN: Macro Definitions. (line 6) +* DEFUN <1>: Obsoleting Macros. (line 18) +* DIAGNOSE: Reporting Messages. (line 11) +* DIR_HEADER: Obsolete Macros. (line 126) +* DYNIX_SEQ: Obsolete Macros. (line 137) +* EGREP_CPP: Examining Declarations. + (line 46) +* EGREP_HEADER: Examining Declarations. + (line 29) +* EMXOS2: Obsolete Macros. (line 150) +* ENABLE: Package Options. (line 57) +* ERROR: Obsolete Macros. (line 154) +* EXEEXT: Obsolete Macros. (line 145) +* F77_DUMMY_MAIN: Fortran 77 Compiler. (line 64) +* F77_FUNC: Fortran 77 Compiler. (line 169) +* F77_LIBRARY_LDFLAGS: Fortran 77 Compiler. (line 38) +* F77_MAIN: Fortran 77 Compiler. (line 101) +* F77_WRAPPERS: Fortran 77 Compiler. (line 115) +* FATAL: Reporting Messages. (line 33) +* FIND_X: Obsolete Macros. (line 157) +* FIND_XTRA: Obsolete Macros. (line 160) +* FUNC_ALLOCA: Particular Functions. + (line 10) +* FUNC_CHECK: Obsolete Macros. (line 163) +* FUNC_CHOWN: Particular Functions. + (line 54) +* FUNC_CLOSEDIR_VOID: Particular Functions. + (line 58) +* FUNC_ERROR_AT_LINE: Particular Functions. + (line 63) +* FUNC_FNMATCH: Particular Functions. + (line 67) +* FUNC_FORK: Particular Functions. + (line 71) +* FUNC_FSEEKO: Particular Functions. + (line 93) +* FUNC_GETGROUPS: Particular Functions. + (line 97) +* FUNC_GETLOADAVG: Particular Functions. + (line 103) +* FUNC_GETMNTENT: Particular Functions. + (line 131) +* FUNC_GETPGRP: Particular Functions. + (line 136) +* FUNC_LSTAT: Particular Functions. + (line 196) +* FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK: Particular Functions. + (line 143) +* FUNC_MALLOC: Particular Functions. + (line 156) +* FUNC_MEMCMP: Particular Functions. + (line 160) +* FUNC_MKTIME: Particular Functions. + (line 167) +* FUNC_MMAP: Particular Functions. + (line 171) +* FUNC_OBSTACK: Particular Functions. + (line 176) +* FUNC_SELECT_ARGTYPES: Particular Functions. + (line 180) +* FUNC_SETPGRP: Particular Functions. + (line 188) +* FUNC_SETVBUF_REVERSED: Particular Functions. + (line 205) +* FUNC_STAT: Particular Functions. + (line 196) +* FUNC_STRCOLL: Particular Functions. + (line 210) +* FUNC_STRERROR_R: Particular Functions. + (line 222) +* FUNC_STRFTIME: Particular Functions. + (line 230) +* FUNC_STRTOD: Particular Functions. + (line 216) +* FUNC_UTIME_NULL: Particular Functions. + (line 234) +* FUNC_VPRINTF: Particular Functions. + (line 238) +* FUNC_WAIT3: Obsolete Macros. (line 166) +* GCC_TRADITIONAL: Obsolete Macros. (line 175) +* GETGROUPS_T: Obsolete Macros. (line 178) +* GETLOADAVG: Obsolete Macros. (line 181) +* HAVE_FUNCS: Obsolete Macros. (line 184) +* HAVE_HEADERS: Obsolete Macros. (line 187) +* HAVE_LIBRARY: Obsolete Macros. (line 191) +* HAVE_POUNDBANG: Obsolete Macros. (line 198) +* HEADER_CHECK: Obsolete Macros. (line 201) +* HEADER_DIRENT: Particular Headers. (line 10) +* HEADER_EGREP: Obsolete Macros. (line 204) +* HEADER_MAJOR: Particular Headers. (line 46) +* HEADER_STAT: Particular Headers. (line 51) +* HEADER_STDC: Particular Headers. (line 57) +* HEADER_SYS_WAIT: Particular Headers. (line 112) +* HEADER_TIME: Particular Headers. (line 146) +* HEADER_TIOCGWINSZ: Particular Headers. (line 167) +* HELP_STRING: Pretty Help Strings. (line 14) +* INIT: Input. (line 10) +* INIT <1>: Obsolete Macros. (line 207) +* INLINE: Obsolete Macros. (line 214) +* INT_16_BITS: Obsolete Macros. (line 217) +* IRIX_SUN: Obsolete Macros. (line 221) +* ISC_POSIX: UNIX Variants. (line 18) +* LANG_C: Obsolete Macros. (line 235) +* LANG_CPLUSPLUS: Obsolete Macros. (line 238) +* LANG_FORTRAN77: Obsolete Macros. (line 241) +* LANG_POP: Language Choice. (line 37) +* LANG_PUSH: Language Choice. (line 32) +* LANG_RESTORE: Obsolete Macros. (line 244) +* LANG_SAVE: Obsolete Macros. (line 249) +* LIBOBJ: Generic Functions. (line 44) +* LIBSOURCE: Generic Functions. (line 52) +* LIBSOURCES: Generic Functions. (line 76) +* LINK_FILES: Obsolete Macros. (line 253) +* LN_S: Obsolete Macros. (line 265) +* LONG_64_BITS: Obsolete Macros. (line 268) +* LONG_DOUBLE: Obsolete Macros. (line 272) +* LONG_FILE_NAMES: Obsolete Macros. (line 275) +* MAJOR_HEADER: Obsolete Macros. (line 278) +* MEMORY_H: Obsolete Macros. (line 281) +* MINGW32: Obsolete Macros. (line 287) +* MINIX: UNIX Variants. (line 25) +* MINUS_C_MINUS_O: Obsolete Macros. (line 291) +* MMAP: Obsolete Macros. (line 294) +* MODE_T: Obsolete Macros. (line 297) +* MSG_CHECKING: Printing Messages. (line 23) +* MSG_ERROR: Printing Messages. (line 54) +* MSG_NOTICE: Printing Messages. (line 44) +* MSG_RESULT: Printing Messages. (line 34) +* MSG_WARN: Printing Messages. (line 64) +* OBJEXT: Obsolete Macros. (line 300) +* OBSOLETE: Obsolete Macros. (line 306) +* OFF_T: Obsolete Macros. (line 321) +* OUTPUT: Output. (line 12) +* OUTPUT <1>: Obsolete Macros. (line 324) +* OUTPUT_COMMANDS: Obsolete Macros. (line 346) +* OUTPUT_COMMANDS_POST: Configuration Commands. + (line 39) +* OUTPUT_COMMANDS_PRE: Configuration Commands. + (line 30) +* PATH_PROG: Generic Programs. (line 66) +* PATH_PROGS: Generic Programs. (line 71) +* PATH_TOOL: Generic Programs. (line 76) +* PATH_X: System Services. (line 10) +* PATH_XTRA: System Services. (line 26) +* PID_T: Obsolete Macros. (line 375) +* PREFIX: Obsolete Macros. (line 378) +* PREFIX_DEFAULT: Default Prefix. (line 16) +* PREFIX_PROGRAM: Default Prefix. (line 25) +* PREREQ: Notices. (line 10) +* PROGRAMS_CHECK: Obsolete Macros. (line 381) +* PROGRAMS_PATH: Obsolete Macros. (line 384) +* PROGRAM_CHECK: Obsolete Macros. (line 387) +* PROGRAM_EGREP: Obsolete Macros. (line 390) +* PROGRAM_PATH: Obsolete Macros. (line 393) +* PROG_AWK: Particular Programs. (line 10) +* PROG_CC: C Compiler. (line 7) +* PROG_CC_C_O: C Compiler. (line 26) +* PROG_CC_STDC: C Compiler. (line 34) +* PROG_CPP: C Compiler. (line 47) +* PROG_CXX: C++ Compiler. (line 7) +* PROG_CXXCPP: C++ Compiler. (line 31) +* PROG_F77_C_O: Fortran 77 Compiler. (line 28) +* PROG_FORTRAN: Fortran 77 Compiler. (line 7) +* PROG_GCC_TRADITIONAL: C Compiler. (line 156) +* PROG_INSTALL: Particular Programs. (line 28) +* PROG_LEX: Particular Programs. (line 57) +* PROG_LN_S: Particular Programs. (line 95) +* PROG_MAKE_SET: Output. (line 37) +* PROG_RANLIB: Particular Programs. (line 114) +* PROG_YACC: Particular Programs. (line 118) +* REMOTE_TAPE: Obsolete Macros. (line 396) +* REPLACE_FUNCS: Generic Functions. (line 84) +* REQUIRE: Prerequisite Macros. (line 17) +* REQUIRE_CPP: Language Choice. (line 50) +* RESTARTABLE_SYSCALLS: Obsolete Macros. (line 399) +* RETSIGTYPE: Obsolete Macros. (line 402) +* REVISION: Notices. (line 29) +* RSH: Obsolete Macros. (line 405) +* SCO_INTL: Obsolete Macros. (line 408) +* SEARCH_LIBS: Libraries. (line 41) +* SETVBUF_REVERSED: Obsolete Macros. (line 416) +* SET_MAKE: Obsolete Macros. (line 419) +* SIZEOF_TYPE: Obsolete Macros. (line 422) +* SIZE_T: Obsolete Macros. (line 425) +* STAT_MACROS_BROKEN: Particular Headers. (line 51) +* STAT_MACROS_BROKEN <1>: Obsolete Macros. (line 428) +* STDC_HEADERS: Obsolete Macros. (line 431) +* STRCOLL: Obsolete Macros. (line 434) +* STRUCT_ST_BLKSIZE: Particular Structures. + (line 9) +* STRUCT_ST_BLOCKS: Particular Structures. + (line 17) +* STRUCT_ST_RDEV: Particular Structures. + (line 23) +* STRUCT_TIMEZONE: Particular Structures. + (line 36) +* STRUCT_TM: Particular Structures. + (line 31) +* ST_BLKSIZE: Obsolete Macros. (line 437) +* ST_BLOCKS: Obsolete Macros. (line 440) +* ST_RDEV: Obsolete Macros. (line 443) +* SUBST: Setting Output Variables. + (line 13) +* SUBST_FILE: Setting Output Variables. + (line 23) +* SYS_INTERPRETER: System Services. (line 37) +* SYS_LARGEFILE: System Services. (line 44) +* SYS_LONG_FILE_NAMES: System Services. (line 58) +* SYS_POSIX_TERMIOS: System Services. (line 62) +* SYS_RESTARTABLE_SYSCALLS: Obsolete Macros. (line 446) +* SYS_SIGLIST_DECLARED: Obsolete Macros. (line 461) +* TEMPLATE: Autoheader Macros. (line 32) +* TEST_CPP: Obsolete Macros. (line 464) +* TEST_PROGRAM: Obsolete Macros. (line 467) +* TIMEZONE: Obsolete Macros. (line 470) +* TIME_WITH_SYS_TIME: Obsolete Macros. (line 473) +* TOP: Autoheader Macros. (line 53) +* TRY_COMPILE: Examining Syntax. (line 14) +* TRY_CPP: Examining Declarations. + (line 11) +* TRY_LINK: Examining Libraries. (line 33) +* TRY_LINK_FUNC: Examining Libraries. (line 51) +* TRY_RUN: Test Programs. (line 11) +* TYPE_GETGROUPS: Particular Types. (line 10) +* TYPE_MODE_T: Particular Types. (line 14) +* TYPE_OFF_T: Particular Types. (line 17) +* TYPE_PID_T: Particular Types. (line 20) +* TYPE_SIGNAL: Particular Types. (line 23) +* TYPE_SIZE_T: Particular Types. (line 36) +* TYPE_UID_T: Particular Types. (line 39) +* UID_T: Obsolete Macros. (line 476) +* UNISTD_H: Obsolete Macros. (line 479) +* USG: Obsolete Macros. (line 482) +* UTIME_NULL: Obsolete Macros. (line 487) +* VALIDATE_CACHED_SYSTEM_TUPLE: Obsolete Macros. (line 490) +* VERBATIM: Autoheader Macros. (line 18) +* VERBOSE: Obsolete Macros. (line 497) +* VFORK: Obsolete Macros. (line 500) +* VPRINTF: Obsolete Macros. (line 503) +* WAIT3: Obsolete Macros. (line 506) +* WARN: Obsolete Macros. (line 509) +* WARNING: Reporting Messages. (line 29) +* WITH: External Software. (line 67) +* WORDS_BIGENDIAN: Obsolete Macros. (line 512) +* XENIX_DIR: Obsolete Macros. (line 515) +* YYTEXT_POINTER: Obsolete Macros. (line 530) + + +File: autoconf.info, Node: M4 Macro Index, Next: Concept Index, Prev: Autoconf Macro Index, Up: Top + +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 'm4_' or 'AS_'. + + +* Menu: + +* defn: Redefined M4 Macros. (line 14) +* defn <1>: Redefined M4 Macros. (line 26) +* pattern_allow: Forbidden Patterns. (line 28) +* pattern_forbid: Forbidden Patterns. (line 15) +* undefine: Redefined M4 Macros. (line 18) + + +File: autoconf.info, Node: Concept Index, Prev: M4 Macro Index, Up: Top + +Concept Index +************* + +This is an alphabetical list of the files, tools, and concepts +introduced in this document. + + +* Menu: + +* !: Limitations of Builtins. + (line 16) +* "$@": Shell Substitutions. (line 31) +* $(COMMANDS): Shell Substitutions. (line 132) +* ${VAR:-VALUE}: Shell Substitutions. (line 38) +* ${VAR=EXPANDED-VALUE}: Shell Substitutions. (line 71) +* ${VAR=LITERAL}: Shell Substitutions. (line 42) +* /usr/xpg4/bin/sh on Solaris: Shellology. (line 43) +* :: Limitations of Builtins. + (line 312) +* @%:@: Quadrigraphs. (line 6) +* @:>@: Quadrigraphs. (line 6) +* @<:@: Quadrigraphs. (line 6) +* @S|@: Quadrigraphs. (line 6) +* 'COMMANDS': Shell Substitutions. (line 117) +* acconfig.h: acconfig.h. (line 6) +* aclocal.m4: Making configure Scripts. + (line 6) +* Ash: Shellology. (line 13) +* autoconf: autoconf Invocation. (line 6) +* autoheader: autoheader Invocation. + (line 6) +* Automake: Automake. (line 19) +* autoreconf: autoreconf Invocation. + (line 6) +* autoscan: autoscan Invocation. (line 6) +* autoupdate: autoupdate Invocation. + (line 6) +* awk: Limitations of Usual Tools. + (line 10) +* Back trace: autoconf Invocation. (line 93) +* Bash: Shellology. (line 37) +* break: Limitations of Builtins. + (line 19) +* Cache: Caching Results. (line 6) +* Cache variable: Cache Variable Names. + (line 6) +* Cache, enabling: configure Invocation. + (line 18) +* case: Limitations of Builtins. + (line 22) +* cat: Limitations of Usual Tools. + (line 53) +* cmp: Limitations of Usual Tools. + (line 61) +* Command Substitution: Shell Substitutions. (line 117) +* config.h: Configuration Headers. + (line 6) +* config.h.bot: acconfig.h. (line 6) +* config.h.in: Header Templates. (line 6) +* config.h.top: acconfig.h. (line 6) +* config.status: config.status Invocation. + (line 6) +* Configuration Header: Configuration Headers. + (line 6) +* Configuration Header Template: Header Templates. (line 6) +* configure: Making configure Scripts. + (line 6) +* configure <1>: Running configure scripts. + (line 6) +* configure.ac: Making configure Scripts. + (line 27) +* configure.in: Making configure Scripts. + (line 27) +* Copyright Notice: Notices. (line 21) +* cp: Limitations of Usual Tools. + (line 68) +* Declaration, checking: Declarations. (line 6) +* diff: Limitations of Usual Tools. + (line 79) +* dirname: Limitations of Usual Tools. + (line 85) +* dnl: Macro Definitions. (line 35) +* dnl <1>: Coding Style. (line 40) +* echo: Limitations of Builtins. + (line 42) +* egrep: Limitations of Usual Tools. + (line 112) +* Endianness: C Compiler. (line 68) +* exit: Limitations of Builtins. + (line 69) +* export: Limitations of Builtins. + (line 94) +* expr: Limitations of Usual Tools. + (line 126) +* expr <1>: Limitations of Usual Tools. + (line 151) +* expr (|): Limitations of Usual Tools. + (line 132) +* false: Limitations of Builtins. + (line 120) +* File, checking: Files. (line 6) +* for: Limitations of Builtins. + (line 124) +* Function, checking: Particular Functions. + (line 6) +* grep: Limitations of Usual Tools. + (line 204) +* Header, checking: Header Files. (line 6) +* if: Limitations of Builtins. + (line 146) +* ifnames: ifnames Invocation. (line 6) +* Includes, default: Default Includes. (line 6) +* Instantiation: Output. (line 12) +* Language: Language Choice. (line 6) +* Library, checking: Libraries. (line 6) +* Libtool: Libtool. (line 13) +* Links: Configuration Links. (line 12) +* ln: Limitations of Usual Tools. + (line 216) +* M4sugar: Programming in M4sugar. + (line 6) +* Macro invocation stack: autoconf Invocation. (line 93) +* Messages, from autoconf: Reporting Messages. (line 6) +* Messages, from configure: Printing Messages. (line 6) +* mv: Limitations of Usual Tools. + (line 228) +* obstack: Particular Functions. + (line 176) +* POSIX termios headers: System Services. (line 62) +* Previous Variable: Setting Output Variables. + (line 44) +* Programs, checking: Alternative Programs. + (line 6) +* QNX 4.25: Systemology. (line 11) +* quadrigraphs: Quadrigraphs. (line 6) +* quotation: Autoconf Language. (line 6) +* quotation <1>: M4 Quotation. (line 6) +* Revision: Notices. (line 29) +* sed: Limitations of Usual Tools. + (line 239) +* sed (t): Limitations of Usual Tools. + (line 278) +* set: Limitations of Builtins. + (line 175) +* shift: Limitations of Builtins. + (line 186) +* Structure, checking: Structures. (line 6) +* Symbolic links: Limitations of Usual Tools. + (line 216) +* termios POSIX headers: System Services. (line 62) +* test: Limitations of Builtins. + (line 191) +* touch: Limitations of Usual Tools. + (line 338) +* trap: Limitations of Builtins. + (line 272) +* true: Limitations of Builtins. + (line 312) +* undefined macro: _m4_divert_diversion: New Macros. (line 6) +* unset: Limitations of Builtins. + (line 323) +* Variable, Precious: Setting Output Variables. + (line 44) +* Version: Notices. (line 10) +* VPATH: Limitations of Make. (line 31) +* Zsh: Shellology. (line 49) + + + +Tag Table: +Node: Top1982 +Node: Introduction14243 +Ref: Introduction-Footnote-119088 +Ref: Introduction-Footnote-219169 +Ref: Introduction-Footnote-319269 +Ref: Introduction-Footnote-419383 +Node: The GNU build system19458 +Node: Automake20377 +Node: Libtool22803 +Node: Pointers24229 +Ref: Pointers-Footnote-125435 +Ref: Pointers-Footnote-225494 +Ref: Pointers-Footnote-325551 +Ref: Pointers-Footnote-425693 +Ref: Pointers-Footnote-525767 +Ref: Pointers-Footnote-625839 +Node: Making configure Scripts25914 +Node: Writing configure.ac28948 +Node: Shell Script Compiler30414 +Node: Autoconf Language32715 +Node: configure.ac Layout37347 +Node: autoscan Invocation38751 +Node: ifnames Invocation41504 +Node: autoconf Invocation42704 +Node: autoreconf Invocation49781 +Node: Setup53123 +Node: Notices54328 +Node: Input55964 +Node: Output58012 +Node: Configuration Actions59994 +Node: Configuration Files62899 +Node: Makefile Substitutions64365 +Node: Preset Output Variables66048 +Node: Installation Directory Variables70619 +Node: Build Directories74971 +Node: Automatic Remaking76624 +Node: Configuration Headers78779 +Node: Header Templates81482 +Node: autoheader Invocation82760 +Node: Autoheader Macros86228 +Node: Configuration Commands88431 +Node: Configuration Links90117 +Node: Subdirectories91489 +Node: Default Prefix93644 +Node: Existing Tests95041 +Node: Common Behavior96759 +Node: Standard Symbols97421 +Node: Default Includes98022 +Node: Alternative Programs99954 +Node: Particular Programs100640 +Node: Generic Programs106101 +Node: Files110010 +Node: Libraries110905 +Node: Library Functions113770 +Node: Function Portability114393 +Node: Particular Functions115398 +Node: Generic Functions125990 +Node: Header Files130235 +Node: Particular Headers130798 +Node: Generic Headers137767 +Node: Declarations139839 +Node: Particular Declarations140428 +Node: Generic Declarations140851 +Node: Structures143224 +Node: Particular Structures143831 +Node: Generic Structures145553 +Node: Types146797 +Node: Particular Types147317 +Node: Generic Types148487 +Node: Compilers and Preprocessors149859 +Node: Generic Compiler Characteristics150870 +Node: C Compiler151733 +Node: C++ Compiler159074 +Node: Fortran 77 Compiler161317 +Node: System Services169814 +Ref: System Services-Footnote-1172930 +Node: UNIX Variants173021 +Node: Writing Tests174203 +Node: Examining Declarations176135 +Node: Examining Syntax178635 +Node: Examining Libraries180083 +Node: Run Time183095 +Node: Test Programs184076 +Node: Guidelines186343 +Node: Test Functions187542 +Node: Systemology189098 +Ref: Systemology-Footnote-1189726 +Ref: Systemology-Footnote-2189764 +Node: Multiple Cases189832 +Node: Language Choice191089 +Node: Results193124 +Node: Defining Symbols193874 +Node: Setting Output Variables197130 +Node: Caching Results201321 +Node: Cache Variable Names205004 +Node: Cache Files206593 +Node: Cache Checkpointing208623 +Node: Printing Messages209954 +Node: Programming in M4213139 +Node: M4 Quotation213812 +Node: Active Characters214622 +Ref: Active Characters-Footnote-1216000 +Node: One Macro Call216022 +Node: Quotation and Nested Macros217584 +Node: Quadrigraphs220550 +Node: Quotation Rule Of Thumb221475 +Node: Programming in M4sugar224118 +Node: Redefined M4 Macros224626 +Node: Forbidden Patterns225596 +Node: Writing Autoconf Macros226961 +Node: Macro Definitions227762 +Node: Macro Names229570 +Node: Reporting Messages232171 +Node: Dependencies Between Macros233517 +Node: Prerequisite Macros234141 +Node: Suggested Ordering236922 +Node: Obsoleting Macros238441 +Node: Coding Style239564 +Node: Portable Shell246570 +Node: Shellology248656 +Node: Here-Documents251635 +Node: File Descriptors253597 +Node: File System Conventions255605 +Ref: File System Conventions-Footnote-1259725 +Node: Shell Substitutions259799 +Node: Assignments264708 +Node: Special Shell Variables266345 +Node: Limitations of Builtins270391 +Node: Limitations of Usual Tools282719 +Node: Limitations of Make295462 +Node: Manual Configuration296443 +Node: Specifying Names297272 +Ref: Specifying Names-Footnote-1300083 +Node: Canonicalizing300483 +Node: Using System Type302887 +Node: Site Configuration303936 +Node: External Software304769 +Node: Package Options308085 +Node: Pretty Help Strings310953 +Node: Site Details312932 +Node: Transforming Names314167 +Node: Transformation Options315315 +Node: Transformation Examples315819 +Node: Transformation Rules317541 +Node: Site Defaults319377 +Node: Running configure scripts323296 +Node: Basic Installation324313 +Node: Compilers and Options327161 +Node: Multiple Architectures327803 +Node: Installation Names328802 +Node: Optional Features330001 +Node: System Type330785 +Node: Sharing Defaults332311 +Node: Environment Variables332953 +Node: configure Invocation333639 +Node: config.status Invocation334771 +Node: Obsolete Constructs338596 +Node: Obsolete config.status Use339522 +Node: acconfig.h341321 +Node: autoupdate Invocation343337 +Node: Obsolete Macros345299 +Node: Autoconf 1362452 +Node: Changed File Names363518 +Node: Changed Makefiles364293 +Node: Changed Macros365386 +Node: Changed Results366642 +Node: Changed Macro Writing368753 +Node: Autoconf 2.13370028 +Node: Changed Quotation371037 +Node: New Macros372944 +Node: Questions374578 +Node: Distributing375102 +Node: Why GNU m4376173 +Node: Bootstrapping377071 +Node: Why Not Imake377687 +Node: History382392 +Node: Genesis383191 +Node: Exodus384387 +Node: Leviticus387438 +Node: Numbers388972 +Node: Deuteronomy390893 +Node: Environment Variable Index393565 +Node: Output Variable Index397608 +Node: Preprocessor Symbol Index407637 +Node: Autoconf Macro Index418644 +Node: M4 Macro Index441976 +Node: Concept Index442663 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: |