1\input texinfo @c -*-texinfo-*- 2@c %**start of header 3@setfilename autoconf.info 4@settitle Autoconf 5@c For double-sided printing, uncomment: 6@c @setchapternewpage odd 7@c %**end of header 8 9@set EDITION 2.13 10@set VERSION 2.13 11@set UPDATED December 1998 12 13@iftex 14@finalout 15@end iftex 16 17@ifinfo 18@format 19START-INFO-DIR-ENTRY 20* Autoconf: (autoconf). Create source code configuration scripts. 21END-INFO-DIR-ENTRY 22@end format 23 24Autoconf: Creating Automatic Configuration Scripts, by David MacKenzie. 25 26This file documents the GNU Autoconf package for creating scripts to 27configure source code packages using templates and an @code{m4} macro 28package. 29 30Copyright (C) 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc. 31 32Permission is granted to make and distribute verbatim copies of 33this manual provided the copyright notice and this permission notice 34are preserved on all copies. 35 36@ignore 37Permission is granted to process this file through TeX and print the 38results, provided the printed document carries copying permission 39notice identical to this one except for the removal of this paragraph 40(this paragraph not being relevant to the printed manual). 41 42@end ignore 43Permission is granted to copy and distribute modified versions of this 44manual under the conditions for verbatim copying, provided that the entire 45resulting derived work is distributed under the terms of a permission 46notice identical to this one. 47 48Permission is granted to copy and distribute translations of this manual 49into another language, under the above conditions for modified versions, 50except that this permission notice may be stated in a translation approved 51by the Foundation. 52@end ifinfo 53 54@titlepage 55@title Autoconf 56@subtitle Creating Automatic Configuration Scripts 57@subtitle Edition @value{EDITION}, for Autoconf version @value{VERSION} 58@subtitle @value{UPDATED} 59@author by David MacKenzie and Ben Elliston 60@c I think I've rewritten all of Noah and Roland's contributions by now. 61 62@page 63@vskip 0pt plus 1filll 64Copyright @copyright{} 1992, 93, 94, 95, 96, 98 Free Software Foundation, Inc. 65 66Permission is granted to make and distribute verbatim copies of 67this manual provided the copyright notice and this permission notice 68are preserved on all copies. 69 70Permission is granted to copy and distribute modified versions of this 71manual under the conditions for verbatim copying, provided that the entire 72resulting derived work is distributed under the terms of a permission 73notice identical to this one. 74 75Permission is granted to copy and distribute translations of this manual 76into another language, under the above conditions for modified versions, 77except that this permission notice may be stated in a translation approved 78by the Foundation. 79@end titlepage 80 81@c Define an environment variable index. 82@defcodeindex ev 83@c Define an output variable index. 84@defcodeindex ov 85@c Define a CPP variable index. 86@defcodeindex cv 87@c Define a macro index that @@defmac doesn't write to. 88@defcodeindex ma 89 90@node Top, Introduction, (dir), (dir) 91@comment node-name, next, previous, up 92 93@ifinfo 94This file documents the GNU Autoconf package for creating scripts to 95configure source code packages using templates and an @code{m4} macro 96package. This is edition @value{EDITION}, for Autoconf version @value{VERSION}. 97 98@end ifinfo 99 100@c The master menu, created with texinfo-master-menu, goes here. 101 102@menu 103* Introduction:: Autoconf's purpose, strengths, and weaknesses. 104* Making configure Scripts:: How to organize and produce Autoconf scripts. 105* Setup:: Initialization and output. 106* Existing Tests:: Macros that check for particular features. 107* Writing Tests:: How to write new feature checks. 108* Results:: What to do with results from feature checks. 109* Writing Macros:: Adding new macros to Autoconf. 110* Manual Configuration:: Selecting features that can't be guessed. 111* Site Configuration:: Local defaults for @code{configure}. 112* Invoking configure:: How to use the Autoconf output. 113* Invoking config.status:: Recreating a configuration. 114* Questions:: Questions about Autoconf, with answers. 115* Upgrading:: Tips for upgrading from version 1. 116* History:: History of Autoconf. 117* Old Macro Names:: Backward compatibility macros. 118* Environment Variable Index:: Index of environment variables used. 119* Output Variable Index:: Index of variables set in output files. 120* Preprocessor Symbol Index:: Index of C preprocessor symbols defined. 121* Macro Index:: Index of Autoconf macros. 122 123@detailmenu 124 --- The Detailed Node Listing --- 125 126Making @code{configure} Scripts 127 128* Writing configure.in:: What to put in an Autoconf input file. 129* Invoking autoscan:: Semi-automatic @file{configure.in} writing. 130* Invoking ifnames:: Listing the conditionals in source code. 131* Invoking autoconf:: How to create configuration scripts. 132* Invoking autoreconf:: Remaking multiple @code{configure} scripts. 133 134Initialization and Output Files 135 136* Input:: Where Autoconf should find files. 137* Output:: Creating output files. 138* Makefile Substitutions:: Using output variables in @file{Makefile}s. 139* Configuration Headers:: Creating a configuration header file. 140* Subdirectories:: Configuring independent packages together. 141* Default Prefix:: Changing the default installation prefix. 142* Versions:: Version numbers in @code{configure}. 143 144Substitutions in Makefiles 145 146* Preset Output Variables:: Output variables that are always set. 147* Build Directories:: Supporting multiple concurrent compiles. 148* Automatic Remaking:: Makefile rules for configuring. 149 150Configuration Header Files 151 152* Header Templates:: Input for the configuration headers. 153* Invoking autoheader:: How to create configuration templates. 154 155Existing Tests 156 157* Alternative Programs:: Selecting between alternative programs. 158* Libraries:: Library archives that might be missing. 159* Library Functions:: C library functions that might be missing. 160* Header Files:: Header files that might be missing. 161* Structures:: Structures or members that might be missing. 162* Typedefs:: @code{typedef}s that might be missing. 163* C Compiler Characteristics:: 164* Fortran 77 Compiler Characteristics:: 165* System Services:: Operating system services. 166* UNIX Variants:: Special kludges for specific UNIX variants. 167 168Alternative Programs 169 170* Particular Programs:: Special handling to find certain programs. 171* Generic Programs:: How to find other programs. 172 173Library Functions 174 175* Particular Functions:: Special handling to find certain functions. 176* Generic Functions:: How to find other functions. 177 178Header Files 179 180* Particular Headers:: Special handling to find certain headers. 181* Generic Headers:: How to find other headers. 182 183Typedefs 184 185* Particular Typedefs:: Special handling to find certain types. 186* Generic Typedefs:: How to find other types. 187 188Writing Tests 189 190* Examining Declarations:: Detecting header files and declarations. 191* Examining Syntax:: Detecting language syntax features. 192* Examining Libraries:: Detecting functions and global variables. 193* Run Time:: Testing for run-time features. 194* Portable Shell:: Shell script portability pitfalls. 195* Testing Values and Files:: Checking strings and files. 196* Multiple Cases:: Tests for several possible values. 197* Language Choice:: Selecting which language to use for testing. 198 199Checking Run Time Behavior 200 201* Test Programs:: Running test programs. 202* Guidelines:: General rules for writing test programs. 203* Test Functions:: Avoiding pitfalls in test programs. 204 205Results of Tests 206 207* Defining Symbols:: Defining C preprocessor symbols. 208* Setting Output Variables:: Replacing variables in output files. 209* Caching Results:: Speeding up subsequent @code{configure} runs. 210* Printing Messages:: Notifying users of progress or problems. 211 212Caching Results 213 214* Cache Variable Names:: Shell variables used in caches. 215* Cache Files:: Files @code{configure} uses for caching. 216 217Writing Macros 218 219* Macro Definitions:: Basic format of an Autoconf macro. 220* Macro Names:: What to call your new macros. 221* Quoting:: Protecting macros from unwanted expansion. 222* Dependencies Between Macros:: What to do when macros depend on other macros. 223 224Dependencies Between Macros 225 226* Prerequisite Macros:: Ensuring required information. 227* Suggested Ordering:: Warning about possible ordering problems. 228* Obsolete Macros:: Warning about old ways of doing things. 229 230Manual Configuration 231 232* Specifying Names:: Specifying the system type. 233* Canonicalizing:: Getting the canonical system type. 234* System Type Variables:: Variables containing the system type. 235* Using System Type:: What to do with the system type. 236 237Site Configuration 238 239* External Software:: Working with other optional software. 240* Package Options:: Selecting optional features. 241* Site Details:: Configuring site details. 242* Transforming Names:: Changing program names when installing. 243* Site Defaults:: Giving @code{configure} local defaults. 244 245Transforming Program Names When Installing 246 247* Transformation Options:: @code{configure} options to transform names. 248* Transformation Examples:: Sample uses of transforming names. 249* Transformation Rules:: @file{Makefile} uses of transforming names. 250 251Running @code{configure} Scripts 252 253* Basic Installation:: Instructions for typical cases. 254* Compilers and Options:: Selecting compilers and optimization. 255* Multiple Architectures:: Compiling for multiple architectures at once. 256* Installation Names:: Installing in different directories. 257* Optional Features:: Selecting optional features. 258* System Type:: Specifying the system type. 259* Sharing Defaults:: Setting site-wide defaults for @code{configure}. 260* Operation Controls:: Changing how @code{configure} runs. 261 262Questions About Autoconf 263 264* Distributing:: Distributing @code{configure} scripts. 265* Why GNU m4:: Why not use the standard @code{m4}? 266* Bootstrapping:: Autoconf and GNU @code{m4} require each other? 267* Why Not Imake:: Why GNU uses @code{configure} instead of Imake. 268 269Upgrading From Version 1 270 271* Changed File Names:: Files you might rename. 272* Changed Makefiles:: New things to put in @file{Makefile.in}. 273* Changed Macros:: Macro calls you might replace. 274* Invoking autoupdate:: Replacing old macro names in @code{configure.in}. 275* Changed Results:: Changes in how to check test results. 276* Changed Macro Writing:: Better ways to write your own macros. 277 278History of Autoconf 279 280* Genesis:: Prehistory and naming of @code{configure}. 281* Exodus:: The plagues of @code{m4} and Perl. 282* Leviticus:: The priestly code of portability arrives. 283* Numbers:: Growth and contributors. 284* Deuteronomy:: Approaching the promises of easy configuration. 285 286@end detailmenu 287@end menu 288 289@node Introduction, Making configure Scripts, Top, Top 290@chapter Introduction 291 292@display 293A physicist, an engineer, and a computer scientist were 294discussing the nature of God. Surely a Physicist, said the 295physicist, because early in the Creation, God made Light; and you 296know, Maxwell's equations, the dual nature of electro-magnetic 297waves, the relativist consequences@dots{} An Engineer!, said the 298engineer, because before making Light, God split the Chaos into 299Land and Water; it takes a hell of an engineer to handle that big 300amount of mud, and orderly separation of solids from 301liquids@dots{} The computer scientist shouted: And the Chaos, 302where do you think it was coming from, hmm? 303 304---Anonymous 305@end display 306@c (via Franc,ois Pinard) 307 308Autoconf is a tool for producing shell scripts that automatically 309configure software source code packages to adapt to many kinds of 310UNIX-like systems. The configuration scripts produced by Autoconf are 311independent of Autoconf when they are run, so their users do not need to 312have Autoconf. 313 314The configuration scripts produced by Autoconf require no manual user 315intervention when run; they do not normally even need an argument 316specifying the system type. Instead, they test for the presence of each 317feature that the software package they are for might need individually. 318(Before each check, they print a one-line message stating what they are 319checking for, so the user doesn't get too bored while waiting for the 320script to finish.) As a result, they deal well with systems that are 321hybrids or customized from the more common UNIX variants. There is no 322need to maintain files that list the features supported by each release 323of each variant of UNIX. 324 325For each software package that Autoconf is used with, it creates a 326configuration script from a template file that lists the 327system features that the package needs or can use. After the shell code to 328recognize and respond to a system feature has been written, 329Autoconf allows it to be shared by many software packages that can 330use (or need) that feature. If it later turns out that the shell code 331needs adjustment for some reason, it needs to be changed in only one 332place; all of the configuration scripts can be regenerated 333automatically to take advantage of the updated code. 334 335The Metaconfig package is similar in purpose to Autoconf, but 336the scripts it produces require manual user intervention, which is quite 337inconvenient when configuring large source trees. Unlike Metaconfig 338scripts, Autoconf scripts can support cross-compiling, if some care is 339taken in writing them. 340 341There are several jobs related to making portable software packages 342that Autoconf currently does not do. Among these are automatically 343creating @file{Makefile} files with all of the standard targets, and 344supplying replacements for standard library functions and header files on 345systems that lack them. Work is in progress to add those features in 346the future. 347 348Autoconf imposes some restrictions on the names of macros used with 349@code{#ifdef} in C programs (@pxref{Preprocessor Symbol Index}). 350 351Autoconf requires GNU @code{m4} in order to generate the scripts. It 352uses features that some UNIX versions of @code{m4} do not have. It also 353overflows internal limits of some versions of @code{m4}, including GNU 354@code{m4} 1.0. You must use version 1.1 or later of GNU @code{m4}. 355Using version 1.3 or later will be much faster than 1.1 or 1.2. 356 357@xref{Upgrading}, for information about upgrading from version 1. 358@xref{History}, for the story of Autoconf's development. 359@xref{Questions}, for answers to some common questions about Autoconf. 360 361Mail suggestions and bug reports for Autoconf to 362@code{bug-gnu-utils@@prep.ai.mit.edu}. Please include the Autoconf version 363number, which you can get by running @samp{autoconf --version}. 364 365@node Making configure Scripts, Setup, Introduction, Top 366@chapter Making @code{configure} Scripts 367 368The configuration scripts that Autoconf produces are by convention 369called @code{configure}. When run, @code{configure} creates several 370files, replacing configuration parameters in them with appropriate 371values. The files that @code{configure} creates are: 372 373@itemize @bullet 374@item 375one or more @file{Makefile} files, one in each subdirectory of the 376package (@pxref{Makefile Substitutions}); 377 378@item 379optionally, a C header file, the name of which is configurable, 380containing @code{#define} directives (@pxref{Configuration Headers}); 381 382@item 383a shell script called @file{config.status} that, when run, will recreate 384the files listed above (@pxref{Invoking config.status}); 385 386@item 387a shell script called @file{config.cache} that saves the results of 388running many of the tests (@pxref{Cache Files}); 389 390@item 391a file called @file{config.log} containing any messages produced by 392compilers, to help debugging if @code{configure} makes a mistake. 393@end itemize 394 395To create a @code{configure} script with Autoconf, you need to write an 396Autoconf input file @file{configure.in} and run @code{autoconf} on it. 397If you write your own feature tests to supplement those that come with 398Autoconf, you might also write files called @file{aclocal.m4} and 399@file{acsite.m4}. If you use a C header file to contain @code{#define} 400directives, you might also write @file{acconfig.h}, and you will 401distribute the Autoconf-generated file @file{config.h.in} with the 402package. 403 404Here is a diagram showing how the files that can be used in 405configuration are produced. Programs that are executed are suffixed by 406@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). 407@code{autoconf} and @code{autoheader} also read the installed Autoconf 408macro files (by reading @file{autoconf.m4}). 409 410@noindent 411Files used in preparing a software package for distribution: 412@example 413@group 414your source files --> [autoscan*] --> [configure.scan] --> configure.in 415 416configure.in --. .------> autoconf* -----> configure 417 +---+ 418[aclocal.m4] --+ `---. 419[acsite.m4] ---' | 420 +--> [autoheader*] -> [config.h.in] 421[acconfig.h] ----. | 422 +-----' 423[config.h.top] --+ 424[config.h.bot] --' 425 426Makefile.in -------------------------------> Makefile.in 427@end group 428@end example 429 430@noindent 431Files used in configuring a software package: 432@example 433@group 434 .-------------> config.cache 435configure* ------------+-------------> config.log 436 | 437[config.h.in] -. v .-> [config.h] -. 438 +--> config.status* -+ +--> make* 439Makefile.in ---' `-> Makefile ---' 440@end group 441@end example 442 443@menu 444* Writing configure.in:: What to put in an Autoconf input file. 445* Invoking autoscan:: Semi-automatic @file{configure.in} writing. 446* Invoking ifnames:: Listing the conditionals in source code. 447* Invoking autoconf:: How to create configuration scripts. 448* Invoking autoreconf:: Remaking multiple @code{configure} scripts. 449@end menu 450 451@node Writing configure.in, Invoking autoscan, Making configure Scripts, Making configure Scripts 452@section Writing @file{configure.in} 453 454To produce a @code{configure} script for a software package, create a 455file called @file{configure.in} that contains invocations of the 456Autoconf macros that test the system features your package needs or can 457use. Autoconf macros already exist to check for many features; see 458@ref{Existing Tests}, for their descriptions. For most other 459features, you can use Autoconf template macros to produce custom checks; 460see @ref{Writing Tests}, for information about them. For especially 461tricky or specialized features, @file{configure.in} might need to 462contain some hand-crafted shell commands. The @code{autoscan} 463program can give you a good start in writing @file{configure.in} 464(@pxref{Invoking autoscan}, for more information). 465 466The order in which @file{configure.in} calls the Autoconf macros 467is not important, with a few exceptions. Every 468@file{configure.in} must contain a call to @code{AC_INIT} before 469the checks, and a call to @code{AC_OUTPUT} at the end 470(@pxref{Output}). Additionally, some macros rely on other macros 471having been called first, because they check previously set 472values of some variables to decide what to do. These macros are 473noted in the individual descriptions (@pxref{Existing Tests}), 474and they also warn you when creating @code{configure} if they are 475called out of order. 476 477To encourage consistency, here is a suggested order for calling the 478Autoconf macros. Generally speaking, the things near the end of this 479list could depend on things earlier in it. For example, library 480functions could be affected by typedefs and libraries. 481 482@display 483@group 484@code{AC_INIT(@var{file})} 485checks for programs 486checks for libraries 487checks for header files 488checks for typedefs 489checks for structures 490checks for compiler characteristics 491checks for library functions 492checks for system services 493@code{AC_OUTPUT(@r{[}@var{file@dots{}}@r{]})} 494@end group 495@end display 496 497It is best to put each macro call on its own line in 498@file{configure.in}. Most of the macros don't add extra newlines; they 499rely on the newline after the macro call to terminate the commands. 500This approach makes the generated @code{configure} script a little 501easier to read by not inserting lots of blank lines. It is generally 502safe to set shell variables on the same line as a macro call, because 503the shell allows assignments without intervening newlines. 504 505When calling macros that take arguments, there must not be any blank 506space between the macro name and the open parenthesis. Arguments can be 507more than one line long if they are enclosed within the @code{m4} quote 508characters @samp{[} and @samp{]}. If you have a long line such as a 509list of file names, you can generally use a backslash at the end of a 510line to continue it logically on the next line (this is implemented by 511the shell, not by anything special that Autoconf does). 512 513Some macros handle two cases: what to do if the given condition is met, 514and what to do if the condition is not met. In some places you might 515want to do something if a condition is true but do nothing if it's 516false, or vice versa. To omit the true case, pass an empty value for 517the @var{action-if-found} argument to the macro. To omit the false 518case, omit the @var{action-if-not-found} argument to the macro, 519including the comma before it. 520 521You can include comments in @file{configure.in} files by starting them 522with the @code{m4} builtin macro @code{dnl}, which discards text up 523through the next newline. These comments do not appear in the generated 524@code{configure} scripts. For example, it is helpful to begin 525@file{configure.in} files with a line like this: 526 527@example 528dnl Process this file with autoconf to produce a configure script. 529@end example 530 531@node Invoking autoscan, Invoking ifnames, Writing configure.in, Making configure Scripts 532@section Using @code{autoscan} to Create @file{configure.in} 533 534The @code{autoscan} program can help you create a @file{configure.in} 535file for a software package. @code{autoscan} examines source files in 536the directory tree rooted at a directory given as a command line 537argument, or the current directory if none is given. It searches the 538source files for common portability problems and creates a file 539@file{configure.scan} which is a preliminary @file{configure.in} for 540that package. 541 542You should manually examine @file{configure.scan} before renaming it to 543@file{configure.in}; it will probably need some adjustments. 544Occasionally @code{autoscan} outputs a macro in the wrong order relative 545to another macro, so that @code{autoconf} produces a warning; you need 546to move such macros manually. Also, if you want the package to use a 547configuration header file, you must add a call to 548@code{AC_CONFIG_HEADER} (@pxref{Configuration Headers}). You might also 549have to change or add some @code{#if} directives to your program in 550order to make it work with Autoconf (@pxref{Invoking ifnames}, for 551information about a program that can help with that job). 552 553@code{autoscan} uses several data files, which are installed along with the 554distributed Autoconf macro files, to determine which macros to output 555when it finds particular symbols in a package's source files. These 556files all have the same format. Each line consists of a symbol, 557whitespace, and the Autoconf macro to output if that symbol is 558encountered. Lines starting with @samp{#} are comments. 559 560@code{autoscan} is only installed if you already have Perl installed. 561@code{autoscan} accepts the following options: 562 563@table @code 564@item --help 565Print a summary of the command line options and exit. 566 567@item --macrodir=@var{dir} 568@evindex AC_MACRODIR 569Look for the data files in directory @var{dir} instead of the default 570installation directory. You can also set the @code{AC_MACRODIR} 571environment variable to a directory; this option overrides the 572environment variable. 573 574@item --verbose 575Print the names of the files it examines and the potentially interesting 576symbols it finds in them. This output can be voluminous. 577 578@item --version 579Print the version number of Autoconf and exit. 580@end table 581 582@node Invoking ifnames, Invoking autoconf, Invoking autoscan, Making configure Scripts 583@section Using @code{ifnames} to List Conditionals 584 585@code{ifnames} can help when writing a @file{configure.in} for a 586software package. It prints the identifiers that the package already 587uses in C preprocessor conditionals. If a package has already been set 588up to have some portability, this program can help you figure out what 589its @code{configure} needs to check for. It may help fill in some gaps 590in a @file{configure.in} generated by @code{autoscan} (@pxref{Invoking 591autoscan}). 592 593@code{ifnames} scans all of the C source files named on the command line 594(or the standard input, if none are given) and writes to the standard 595output a sorted list of all the identifiers that appear in those files 596in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} 597directives. It prints each identifier on a line, followed by a 598space-separated list of the files in which that identifier occurs. 599 600@noindent 601@code{ifnames} accepts the following options: 602 603@table @code 604@item --help 605@itemx -h 606Print a summary of the command line options and exit. 607 608@item --macrodir=@var{dir} 609@itemx -m @var{dir} 610@evindex AC_MACRODIR 611Look for the Autoconf macro files in directory @var{dir} instead of the 612default installation directory. Only used to get the version number. 613You can also set the @code{AC_MACRODIR} 614environment variable to a directory; this option overrides the 615environment variable. 616 617@item --version 618Print the version number of Autoconf and exit. 619@end table 620 621@node Invoking autoconf, Invoking autoreconf, Invoking ifnames, Making configure Scripts 622@section Using @code{autoconf} to Create @code{configure} 623 624To create @code{configure} from @file{configure.in}, run the 625@code{autoconf} program with no arguments. @code{autoconf} processes 626@file{configure.in} with the @code{m4} macro processor, using the 627Autoconf macros. If you give @code{autoconf} an argument, it reads that 628file instead of @file{configure.in} and writes the configuration script 629to the standard output instead of to @code{configure}. If you give 630@code{autoconf} the argument @samp{-}, it reads the standard input 631instead of @file{configure.in} and writes the configuration script on 632the standard output. 633 634The Autoconf macros are defined in several files. Some of the files are 635distributed with Autoconf; @code{autoconf} reads them first. Then it 636looks for the optional file @file{acsite.m4} in the directory that 637contains the distributed Autoconf macro files, and for the optional file 638@file{aclocal.m4} in the current directory. Those files can contain 639your site's or the package's own Autoconf macro definitions 640(@pxref{Writing Macros}, for more information). If a macro is defined 641in more than one of the files that @code{autoconf} reads, the last 642definition it reads overrides the earlier ones. 643 644@code{autoconf} accepts the following options: 645 646@table @code 647@item --help 648@itemx -h 649Print a summary of the command line options and exit. 650 651@item --localdir=@var{dir} 652@itemx -l @var{dir} 653Look for the package file @file{aclocal.m4} in directory @var{dir} 654instead of in the current directory. 655 656@item --macrodir=@var{dir} 657@itemx -m @var{dir} 658@evindex AC_MACRODIR 659Look for the installed macro files in directory @var{dir}. You can also 660set the @code{AC_MACRODIR} environment variable to a directory; this 661option overrides the environment variable. 662 663@item --version 664Print the version number of Autoconf and exit. 665@end table 666 667@node Invoking autoreconf, , Invoking autoconf, Making configure Scripts 668@section Using @code{autoreconf} to Update @code{configure} Scripts 669 670If you have a lot of Autoconf-generated @code{configure} scripts, the 671@code{autoreconf} program can save you some work. It runs 672@code{autoconf} (and @code{autoheader}, where appropriate) repeatedly to 673remake the Autoconf @code{configure} scripts and configuration header 674templates in the directory tree rooted at the current directory. By 675default, it only remakes those files that are older than their 676@file{configure.in} or (if present) @file{aclocal.m4}. Since 677@code{autoheader} does not change the timestamp of its output file if 678the file wouldn't be changing, this is not necessarily the minimum 679amount of work. If you install a new version of Autoconf, you can make 680@code{autoreconf} remake @emph{all} of the files by giving it the 681@samp{--force} option. 682 683If you give @code{autoreconf} the @samp{--macrodir=@var{dir}} or 684@samp{--localdir=@var{dir}} options, it passes them down to 685@code{autoconf} and @code{autoheader} (with relative paths adjusted 686properly). 687 688@code{autoreconf} does not support having, in the same directory tree, 689both directories that are parts of a larger package (sharing 690@file{aclocal.m4} and @file{acconfig.h}), and directories that are 691independent packages (each with their own @file{aclocal.m4} and 692@file{acconfig.h}). It assumes that they are all part of the same 693package, if you use @samp{--localdir}, or that each directory is a 694separate package, if you don't use it. This restriction may be removed 695in the future. 696 697@xref{Automatic Remaking}, for @file{Makefile} rules to automatically 698remake @code{configure} scripts when their source files change. That 699method handles the timestamps of configuration header templates 700properly, but does not pass @samp{--macrodir=@var{dir}} or 701@samp{--localdir=@var{dir}}. 702 703@noindent 704@code{autoreconf} accepts the following options: 705 706@table @code 707@item --help 708@itemx -h 709Print a summary of the command line options and exit. 710 711@item --force 712@itemx -f 713Remake even @file{configure} scripts and configuration headers that are 714newer than their input files (@file{configure.in} and, if present, 715@file{aclocal.m4}). 716 717@item --localdir=@var{dir} 718@itemx -l @var{dir} 719Have @code{autoconf} and @code{autoheader} look for the package files 720@file{aclocal.m4} and (@code{autoheader} only) @file{acconfig.h} (but 721not @file{@var{file}.top} and @file{@var{file}.bot}) in directory 722@var{dir} instead of in the directory containing each @file{configure.in}. 723 724@item --macrodir=@var{dir} 725@itemx -m @var{dir} 726@evindex AC_MACRODIR 727Look for the Autoconf macro files in directory @var{dir} instead of the 728default installation directory. 729You can also set the @code{AC_MACRODIR} 730environment variable to a directory; this option overrides the 731environment variable. 732 733@item --verbose 734Print the name of each directory where @code{autoreconf} runs 735@code{autoconf} (and @code{autoheader}, if appropriate). 736 737@item --version 738Print the version number of Autoconf and exit. 739@end table 740 741@node Setup, Existing Tests, Making configure Scripts, Top 742@chapter Initialization and Output Files 743 744Autoconf-generated @code{configure} scripts need some information about 745how to initialize, such as how to find the package's source files; and 746about the output files to produce. The following sections describe 747initialization and creating output files. 748 749@menu 750* Input:: Where Autoconf should find files. 751* Output:: Creating output files. 752* Makefile Substitutions:: Using output variables in @file{Makefile}s. 753* Configuration Headers:: Creating a configuration header file. 754* Subdirectories:: Configuring independent packages together. 755* Default Prefix:: Changing the default installation prefix. 756* Versions:: Version numbers in @code{configure}. 757@end menu 758 759@node Input, Output, Setup, Setup 760@section Finding @code{configure} Input 761 762Every @code{configure} script must call @code{AC_INIT} before doing 763anything else. The only other required macro is @code{AC_OUTPUT} 764(@pxref{Output}). 765 766@defmac AC_INIT (@var{unique-file-in-source-dir}) 767@maindex INIT 768Process any command-line arguments and find the source code directory. 769@var{unique-file-in-source-dir} is some file that is in the package's 770source directory; @code{configure} checks for this file's existence to 771make sure that the directory that it is told contains the source code in 772fact does. Occasionally people accidentally specify the wrong directory 773with @samp{--srcdir}; this is a safety check. @xref{Invoking configure}, 774for more information. 775@end defmac 776 777Packages that do manual configuration or use the @code{install} program 778might need to tell @code{configure} where to find some other shell 779scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places 780it looks are correct for most cases. 781 782@defmac AC_CONFIG_AUX_DIR(@var{dir}) 783@maindex CONFIG_AUX_DIR 784Use the @file{install-sh}, @file{config.sub}, @file{config.guess}, and 785Cygnus @code{configure} scripts that are in directory @var{dir}. These 786are auxiliary files used in configuration. @var{dir} can be either 787absolute or relative to @file{@var{srcdir}}. The default is 788@file{@var{srcdir}} or @file{@var{srcdir}/..} or 789@file{@var{srcdir}/../..}, whichever is the first that contains 790@file{install-sh}. The other files are not checked for, so that using 791@code{AC_PROG_INSTALL} does not automatically require distributing the 792other auxiliary files. It checks for @file{install.sh} also, but that 793name is obsolete because some @code{make} programs have a rule that 794creates @file{install} from it if there is no @file{Makefile}. 795@end defmac 796 797@node Output, Makefile Substitutions, Input, Setup 798@section Creating Output Files 799 800Every Autoconf-generated @code{configure} script must finish by calling 801@code{AC_OUTPUT}. It is the macro that creates the @file{Makefile}s and 802optional other files resulting from configuration. The only other 803required macro is @code{AC_INIT} (@pxref{Input}). 804 805@defmac AC_OUTPUT (@r{[}@var{file}@dots{} @r{[}, @var{extra-cmds} @r{[}, @var{init-cmds}@r{]]]}) 806@maindex OUTPUT 807Create output files. Call this macro once, at the end of @file{configure.in}. 808The @var{file}@dots{} argument is a 809whitespace-separated list of output files; it may be empty. This macro 810creates each file @file{@var{file}} by copying an input file (by default 811named @file{@var{file}.in}), substituting the output variable values. 812@c If the file would be unchanged, it is left untouched, to preserve its timestamp. 813@xref{Makefile Substitutions}, for more information on using output variables. 814@xref{Setting Output Variables}, for more information on creating them. This 815macro creates the directory that the file is in if it doesn't exist (but 816not the parents of that directory). Usually, @file{Makefile}s are 817created this way, but other files, such as @file{.gdbinit}, can be 818specified as well. 819 820If @code{AC_CONFIG_HEADER}, @code{AC_LINK_FILES}, or 821@code{AC_CONFIG_SUBDIRS} has been called, this macro also creates the 822files named as their arguments. 823 824A typical call to @code{AC_OUTPUT} looks like this: 825@example 826AC_OUTPUT(Makefile src/Makefile man/Makefile X/Imakefile) 827@end example 828 829You can override an input file name by appending to @var{file} a 830colon-separated list of input files. Examples: 831@example 832AC_OUTPUT(Makefile:templates/top.mk lib/Makefile:templates/lib.mk) 833AC_OUTPUT(Makefile:templates/vars.mk:Makefile.in:templates/rules.mk) 834@end example 835Doing this allows you to keep your file names acceptable to MS-DOS, or 836to prepend and/or append boilerplate to the file. 837 838If you pass @var{extra-cmds}, those commands will be inserted into 839@file{config.status} to be run after all its other processing. If 840@var{init-cmds} are given, they are inserted just before 841@var{extra-cmds}, with shell variable, command, and backslash 842substitutions performed on them in @code{configure}. You can use 843@var{init-cmds} to pass variables from @code{configure} to the 844@var{extra-cmds}. If @code{AC_OUTPUT_COMMANDS} has been called, the 845commands given to it are run just before the commands passed to this macro. 846@end defmac 847 848@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds} @r{[}, @var{init-cmds}@r{]}) 849Specify additional shell commands to run at the end of 850@file{config.status}, and shell commands to initialize any variables 851from @code{configure}. This macro may be called multiple times. 852Here is an unrealistic example: 853 854@example 855fubar=27 856AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], fubar=$fubar) 857AC_OUTPUT_COMMANDS([echo this is another, extra, bit], [echo init bit]) 858@end example 859@end defmac 860 861If you run @code{make} on subdirectories, you should run it using the 862@code{make} variable @code{MAKE}. Most versions of @code{make} set 863@code{MAKE} to the name of the @code{make} program plus any options it 864was given. (But many do not include in it the values of any variables 865set on the command line, so those are not passed on automatically.) 866Some old versions of @code{make} do not set this variable. The 867following macro allows you to use it even with those versions. 868 869@defmac AC_PROG_MAKE_SET 870@maindex PROG_MAKE_SET 871@ovindex SET_MAKE 872If @code{make} predefines the variable @code{MAKE}, define output 873variable @code{SET_MAKE} to be empty. Otherwise, define @code{SET_MAKE} 874to contain @samp{MAKE=make}. Calls @code{AC_SUBST} for @code{SET_MAKE}. 875@end defmac 876 877To use this macro, place a line like this in each @file{Makefile.in} 878that runs @code{MAKE} on other directories: 879 880@example 881@@SET_MAKE@@ 882@end example 883 884@node Makefile Substitutions, Configuration Headers, Output, Setup 885@section Substitutions in Makefiles 886 887Each subdirectory in a distribution that contains something to be 888compiled or installed should come with a file @file{Makefile.in}, from 889which @code{configure} will create a @file{Makefile} in that directory. 890To create a @file{Makefile}, @code{configure} performs a simple variable 891substitution, replacing occurrences of @samp{@@@var{variable}@@} in 892@file{Makefile.in} with the value that @code{configure} has determined 893for that variable. Variables that are substituted into output files in 894this way are called @dfn{output variables}. They are ordinary shell 895variables that are set in @code{configure}. To make @code{configure} 896substitute a particular variable into the output files, the macro 897@code{AC_SUBST} must be called with that variable name as an argument. 898Any occurrences of @samp{@@@var{variable}@@} for other variables are 899left unchanged. @xref{Setting Output Variables}, for more information on 900creating output variables with @code{AC_SUBST}. 901 902A software package that uses a @code{configure} script should be 903distributed with a file @file{Makefile.in}, but no @file{Makefile}; that 904way, the user has to properly configure the package for the local system 905before compiling it. 906 907@xref{Makefile Conventions, , Makefile Conventions, standards, The 908GNU Coding Standards}, for more information on what to put in 909@file{Makefile}s. 910 911@menu 912* Preset Output Variables:: Output variables that are always set. 913* Build Directories:: Supporting multiple concurrent compiles. 914* Automatic Remaking:: Makefile rules for configuring. 915@end menu 916 917@node Preset Output Variables, Build Directories, Makefile Substitutions, Makefile Substitutions 918@subsection Preset Output Variables 919 920Some output variables are preset by the Autoconf macros. Some of the 921Autoconf macros set additional output variables, which are mentioned in 922the descriptions for those macros. @xref{Output Variable Index}, for a 923complete list of output variables. Here is what each of the preset ones 924contains. @xref{Directory Variables, , Variables for Installation Directories, 925standards, The GNU Coding Standards}, for more information about 926the variables with names that end in @samp{dir}. 927 928@defvar bindir 929@ovindex bindir 930The directory for installing executables that users run. 931@end defvar 932 933@defvar configure_input 934@ovindex configure_input 935A comment saying that the file was generated automatically by 936@code{configure} and giving the name of the input file. 937@code{AC_OUTPUT} adds a comment line containing this variable to the top 938of every @file{Makefile} it creates. For other files, you should 939reference this variable in a comment at the top of each input file. For 940example, an input shell script should begin like this: 941 942@example 943#! /bin/sh 944# @@configure_input@@ 945@end example 946 947@noindent 948The presence of that line also reminds people editing the file that it 949needs to be processed by @code{configure} in order to be used. 950@end defvar 951 952@defvar datadir 953@ovindex datadir 954The directory for installing read-only architecture-independent data. 955@end defvar 956 957@defvar exec_prefix 958@ovindex exec_prefix 959The installation prefix for architecture-dependent files. 960@end defvar 961 962@defvar includedir 963@ovindex includedir 964The directory for installing C header files. 965@end defvar 966 967@defvar infodir 968@ovindex infodir 969The directory for installing documentation in Info format. 970@end defvar 971 972@defvar libdir 973@ovindex libdir 974The directory for installing object code libraries. 975@end defvar 976 977@defvar libexecdir 978@ovindex libexecdir 979The directory for installing executables that other programs run. 980@end defvar 981 982@defvar localstatedir 983@ovindex localstatedir 984The directory for installing modifiable single-machine data. 985@end defvar 986 987@defvar mandir 988@ovindex mandir 989The top-level directory for installing documentation in man format. 990@end defvar 991 992@defvar oldincludedir 993@ovindex oldincludedir 994The directory for installing C header files for non-gcc compilers. 995@end defvar 996 997@defvar prefix 998@ovindex prefix 999The installation prefix for architecture-independent files. 1000@end defvar 1001 1002@defvar sbindir 1003@ovindex sbindir 1004The directory for installing executables that system 1005administrators run. 1006@end defvar 1007 1008@defvar sharedstatedir 1009@ovindex sharedstatedir 1010The directory for installing modifiable architecture-independent data. 1011@end defvar 1012 1013@defvar srcdir 1014@ovindex srcdir 1015The directory that contains the source code for that @file{Makefile}. 1016@end defvar 1017 1018@defvar sysconfdir 1019@ovindex sysconfdir 1020The directory for installing read-only single-machine data. 1021@end defvar 1022 1023@defvar top_srcdir 1024@ovindex top_srcdir 1025The top-level source code directory for the package. In the top-level 1026directory, this is the same as @code{srcdir}. 1027@end defvar 1028 1029@defvar CFLAGS 1030@ovindex CFLAGS 1031Debugging and optimization options for the C compiler. If it is not set 1032in the environment when @code{configure} runs, the default value is set 1033when you call @code{AC_PROG_CC} (or empty if you don't). @code{configure} 1034uses this variable when compiling programs to test for C features. 1035@end defvar 1036 1037@defvar CPPFLAGS 1038@ovindex CPPFLAGS 1039Header file search directory (@samp{-I@var{dir}}) and any other 1040miscellaneous options for the C preprocessor and compiler. If it is not 1041set in the environment when @code{configure} runs, the default value is 1042empty. @code{configure} uses this variable when compiling or 1043preprocessing programs to test for C features. 1044@end defvar 1045 1046@defvar CXXFLAGS 1047@ovindex CXXFLAGS 1048Debugging and optimization options for the C++ compiler. If it is not 1049set in the environment when @code{configure} runs, the default value is 1050set when you call @code{AC_PROG_CXX} (or empty if you don't). 1051@code{configure} uses this variable when compiling programs to test for 1052C++ features. 1053@end defvar 1054 1055@defvar FFLAGS 1056@ovindex FFLAGS 1057Debugging and optimization options for the Fortran 77 compiler. If it 1058is not set in the environment when @code{configure} runs, the default 1059value is set when you call @code{AC_PROG_F77} (or empty if you don't). 1060@code{configure} uses this variable when compiling programs to test for 1061Fortran 77 features. 1062@end defvar 1063 1064@defvar DEFS 1065@ovindex DEFS 1066@samp{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADER} 1067is called, @code{configure} replaces @samp{@@DEFS@@} with 1068@samp{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This 1069variable is not defined while @code{configure} is performing its tests, 1070only when creating the output files. @xref{Setting Output Variables}, for 1071how to check the results of previous tests. 1072@end defvar 1073 1074@defvar LDFLAGS 1075@ovindex LDFLAGS 1076Stripping (@samp{-s}) and any other miscellaneous options for the 1077linker. If it is not set in the environment when @code{configure} runs, 1078the default value is empty. @code{configure} uses this variable when 1079linking programs to test for C features. 1080@end defvar 1081 1082@defvar LIBS 1083@ovindex LIBS 1084@samp{-l} and @samp{-L} options to pass to the linker. 1085@end defvar 1086 1087@node Build Directories, Automatic Remaking, Preset Output Variables, Makefile Substitutions 1088@subsection Build Directories 1089 1090You can support compiling a software package for several architectures 1091simultaneously from the same copy of the source code. The object files 1092for each architecture are kept in their own directory. 1093 1094To support doing this, @code{make} uses the @code{VPATH} variable to 1095find the files that are in the source directory. GNU @code{make} and 1096most other recent @code{make} programs can do this. Older @code{make} 1097programs do not support @code{VPATH}; when using them, the source code 1098must be in the same directory as the object files. 1099 1100To support @code{VPATH}, each @file{Makefile.in} should contain two 1101lines that look like: 1102 1103@example 1104srcdir = @@srcdir@@ 1105VPATH = @@srcdir@@ 1106@end example 1107 1108Do not set @code{VPATH} to the value of another variable, for example 1109@samp{VPATH = $(srcdir)}, because some versions of @code{make} do not do 1110variable substitutions on the value of @code{VPATH}. 1111 1112@code{configure} substitutes in the correct value for @code{srcdir} when 1113it produces @file{Makefile}. 1114 1115Do not use the @code{make} variable @code{$<}, which expands to the 1116pathname of the file in the source directory (found with @code{VPATH}), 1117except in implicit rules. (An implicit rule is one such as @samp{.c.o}, 1118which tells how to create a @file{.o} file from a @file{.c} file.) Some 1119versions of @code{make} do not set @code{$<} in explicit rules; they 1120expand it to an empty value. 1121 1122Instead, @file{Makefile} command lines should always refer to source 1123files by prefixing them with @samp{$(srcdir)/}. For example: 1124 1125@example 1126time.info: time.texinfo 1127 $(MAKEINFO) $(srcdir)/time.texinfo 1128@end example 1129 1130@node Automatic Remaking, , Build Directories, Makefile Substitutions 1131@subsection Automatic Remaking 1132 1133You can put rules like the following in the top-level @file{Makefile.in} 1134for a package to automatically update the configuration information when 1135you change the configuration files. This example includes all of the 1136optional files, such as @file{aclocal.m4} and those related to 1137configuration header files. Omit from the @file{Makefile.in} rules any 1138of these files that your package does not use. 1139 1140The @samp{$@{srcdir@}/} prefix is included because of limitations in the 1141@code{VPATH} mechanism. 1142 1143The @file{stamp-} files are necessary because the timestamps of 1144@file{config.h.in} and @file{config.h} will not be changed if remaking 1145them does not change their contents. This feature avoids unnecessary 1146recompilation. You should include the file @file{stamp-h.in} your 1147package's distribution, so @code{make} will consider @file{config.h.in} 1148up to date. On some old BSD systems, @code{touch} or any command that 1149results in an empty file does not update the timestamps, so use a 1150command like @code{echo} as a workaround. 1151@c Using @code{date} would cause needless CVS conflicts. 1152 1153@example 1154@group 1155$@{srcdir@}/configure: configure.in aclocal.m4 1156 cd $@{srcdir@} && autoconf 1157 1158# autoheader might not change config.h.in, so touch a stamp file. 1159$@{srcdir@}/config.h.in: stamp-h.in 1160$@{srcdir@}/stamp-h.in: configure.in aclocal.m4 acconfig.h \ 1161 config.h.top config.h.bot 1162 cd $@{srcdir@} && autoheader 1163 echo timestamp > $@{srcdir@}/stamp-h.in 1164 1165config.h: stamp-h 1166stamp-h: config.h.in config.status 1167 ./config.status 1168 1169Makefile: Makefile.in config.status 1170 ./config.status 1171 1172config.status: configure 1173 ./config.status --recheck 1174@end group 1175@end example 1176 1177In addition, you should pass @samp{echo timestamp > stamp-h} in the 1178@var{extra-cmds} argument to @code{AC_OUTPUT}, so @file{config.status} 1179will ensure that @file{config.h} is considered up to date. 1180@xref{Output}, for more information about @code{AC_OUTPUT}. 1181 1182@xref{Invoking config.status}, for more examples of handling 1183configuration-related dependencies. 1184 1185@node Configuration Headers, Subdirectories, Makefile Substitutions, Setup 1186@section Configuration Header Files 1187 1188When a package tests more than a few C preprocessor symbols, the command 1189lines to pass @samp{-D} options to the compiler can get quite long. 1190This causes two problems. One is that the @code{make} output is hard to 1191visually scan for errors. More seriously, the command lines can exceed 1192the length limits of some operating systems. As an alternative to 1193passing @samp{-D} options to the compiler, @code{configure} scripts can 1194create a C header file containing @samp{#define} directives. The 1195@code{AC_CONFIG_HEADER} macro selects this kind of output. It should be 1196called right after @code{AC_INIT}. 1197 1198The package should @samp{#include} the configuration header file before 1199any other header files, to prevent inconsistencies in declarations (for 1200example, if it redefines @code{const}). Use @samp{#include <config.h>} 1201instead of @samp{#include "config.h"}, and pass the C compiler a 1202@samp{-I.} option (or @samp{-I..}; whichever directory contains 1203@file{config.h}). That way, even if the source directory is configured 1204itself (perhaps to make a distribution), other build directories can 1205also be configured without finding the @file{config.h} from the source 1206directory. 1207 1208@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{}) 1209@maindex CONFIG_HEADER 1210@cvindex HAVE_CONFIG_H 1211Make @code{AC_OUTPUT} create the file(s) in the whitespace-separated 1212list @var{header-to-create} containing C preprocessor @code{#define} 1213statements, and replace @samp{@@DEFS@@} in generated files with 1214@samp{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. The usual 1215name for @var{header-to-create} is @file{config.h}. 1216 1217If @var{header-to-create} already exists and its contents are identical 1218to what @code{AC_OUTPUT} would put in it, it is left alone. Doing this 1219allows some changes in configuration without needlessly causing object 1220files that depend on the header file to be recompiled. 1221 1222Usually the input file is named @file{@var{header-to-create}.in}; 1223however, you can override the input file name by appending to 1224@var{header-to-create}, a colon-separated list of input files. 1225Examples: 1226@example 1227AC_CONFIG_HEADER(defines.h:defines.hin) 1228AC_CONFIG_HEADER(defines.h:defs.pre:defines.h.in:defs.post) 1229@end example 1230@noindent 1231Doing this allows you to keep your file names acceptable to MS-DOS, or 1232to prepend and/or append boilerplate to the file. 1233@end defmac 1234 1235@menu 1236* Header Templates:: Input for the configuration headers. 1237* Invoking autoheader:: How to create configuration templates. 1238@end menu 1239 1240@node Header Templates, Invoking autoheader, Configuration Headers, Configuration Headers 1241@subsection Configuration Header Templates 1242 1243Your distribution should contain a template file that looks as you want 1244the final header file to look, including comments, with default values 1245in the @code{#define} statements. For example, suppose your 1246@file{configure.in} makes these calls: 1247 1248@example 1249AC_CONFIG_HEADER(conf.h) 1250AC_CHECK_HEADERS(unistd.h) 1251@end example 1252 1253@noindent 1254Then you could have code like the following in @file{conf.h.in}. 1255On systems that have @file{unistd.h}, @code{configure} will change the 0 1256to a 1. On other systems, it will leave the line unchanged. 1257 1258@example 1259@group 1260/* Define as 1 if you have unistd.h. */ 1261#define HAVE_UNISTD_H 0 1262@end group 1263@end example 1264 1265Alternately, if your code tests for configuration options using 1266@code{#ifdef} instead of @code{#if}, a default value can be to 1267@code{#undef} the variable instead of to define it to a value. On 1268systems that have @file{unistd.h}, @code{configure} will change the 1269second line to read @samp{#define HAVE_UNISTD_H 1}. On other systems, 1270it will comment that line out (in case the system predefines that 1271symbol). 1272 1273@example 1274@group 1275/* Define if you have unistd.h. */ 1276#undef HAVE_UNISTD_H 1277@end group 1278@end example 1279 1280@node Invoking autoheader, , Header Templates, Configuration Headers 1281@subsection Using @code{autoheader} to Create @file{config.h.in} 1282 1283The @code{autoheader} program can create a template file of C 1284@samp{#define} statements for @code{configure} to use. If 1285@file{configure.in} invokes @code{AC_CONFIG_HEADER(@var{file})}, 1286@code{autoheader} creates @file{@var{file}.in}; if multiple file 1287arguments are given, the first one is used. Otherwise, 1288@code{autoheader} creates @file{config.h.in}. 1289 1290If you give @code{autoheader} an argument, it uses that file instead of 1291@file{configure.in} and writes the header file to the standard output 1292instead of to @file{config.h.in}. If you give @code{autoheader} an 1293argument of @samp{-}, it reads the standard input instead of 1294@file{configure.in} and writes the header file to the standard output. 1295 1296@code{autoheader} scans @file{configure.in} and figures out which C 1297preprocessor symbols it might define. It copies comments and 1298@code{#define} and @code{#undef} statements from a file called 1299@file{acconfig.h}, which comes with and is installed with Autoconf. It 1300also uses a file called @file{acconfig.h} in the current directory, if 1301present. If you @code{AC_DEFINE} any additional symbols, you must 1302create that file with entries for them. For symbols defined by 1303@code{AC_CHECK_HEADERS}, @code{AC_CHECK_FUNCS}, @code{AC_CHECK_SIZEOF}, 1304or @code{AC_CHECK_LIB}, @code{autoheader} generates comments and 1305@code{#undef} statements itself rather than copying them from a file, 1306since the possible symbols are effectively limitless. 1307 1308The file that @code{autoheader} creates contains mainly @code{#define} 1309and @code{#undef} statements and their accompanying comments. If 1310@file{./acconfig.h} contains the string @samp{@@TOP@@}, 1311@code{autoheader} copies the lines before the line containing 1312@samp{@@TOP@@} into the top of the file that it generates. Similarly, 1313if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, 1314@code{autoheader} copies the lines after that line to the end of the 1315file it generates. Either or both of those strings may be omitted. 1316 1317An alternate way to produce the same effect is to create the files 1318@file{@var{file}.top} (typically @file{config.h.top}) and/or 1319@file{@var{file}.bot} in the current directory. If they exist, 1320@code{autoheader} copies them to the beginning and end, respectively, of 1321its output. Their use is discouraged because they have file names that 1322contain two periods, and so can not be stored on MS-DOS; also, they are 1323two more files to clutter up the directory. But if you use the 1324@samp{--localdir=@var{dir}} option to use an @file{acconfig.h} in another 1325directory, they give you a way to put custom boilerplate in each 1326individual @file{config.h.in}. 1327 1328@code{autoheader} accepts the following options: 1329 1330@table @code 1331@item --help 1332@itemx -h 1333Print a summary of the command line options and exit. 1334 1335@item --localdir=@var{dir} 1336@itemx -l @var{dir} 1337Look for the package files @file{aclocal.m4} and @file{acconfig.h} (but 1338not @file{@var{file}.top} and @file{@var{file}.bot}) in directory 1339@var{dir} instead of in the current directory. 1340 1341@item --macrodir=@var{dir} 1342@itemx -m @var{dir} 1343@evindex AC_MACRODIR 1344Look for the installed macro files and @file{acconfig.h} in directory 1345@var{dir}. You can also set the @code{AC_MACRODIR} environment variable 1346to a directory; this option overrides the environment variable. 1347 1348@item --version 1349Print the version number of Autoconf and exit. 1350@end table 1351 1352@node Subdirectories, Default Prefix, Configuration Headers, Setup 1353@section Configuring Other Packages in Subdirectories 1354 1355In most situations, calling @code{AC_OUTPUT} is sufficient to produce 1356@file{Makefile}s in subdirectories. However, @code{configure} scripts 1357that control more than one independent package can use 1358@code{AC_CONFIG_SUBDIRS} to run @code{configure} scripts for other 1359packages in subdirectories. 1360 1361@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) 1362@maindex CONFIG_SUBDIRS 1363@ovindex subdirs 1364Make @code{AC_OUTPUT} run @code{configure} in each subdirectory 1365@var{dir} in the given whitespace-separated list. If a given @var{dir} 1366is not found, no error is reported, so a @code{configure} script can 1367configure whichever parts of a large source tree are present. If a 1368given @var{dir} contains @file{configure.in} but no @code{configure}, 1369the Cygnus @code{configure} script found by @code{AC_CONFIG_AUXDIR} is 1370used. 1371 1372The subdirectory @code{configure} scripts are given the same 1373command line options that were given to this @code{configure} script, 1374with minor changes if needed (e.g., to adjust a relative path for the 1375cache file or source directory). This macro also sets the output 1376variable @code{subdirs} to the list of directories @samp{@var{dir} 1377@dots{}}. @file{Makefile} rules can use this variable to determine 1378which subdirectories to recurse into. This macro may be called multiple 1379times. 1380@end defmac 1381 1382@node Default Prefix, Versions, Subdirectories, Setup 1383@section Default Prefix 1384 1385By default, @code{configure} sets the prefix for files it installs to 1386@file{/usr/local}. The user of @code{configure} can select a different 1387prefix using the @samp{--prefix} and @samp{--exec-prefix} options. 1388There are two ways to change the default: when creating 1389@code{configure}, and when running it. 1390 1391Some software packages might want to install in a directory besides 1392@file{/usr/local} by default. To accomplish that, use the 1393@code{AC_PREFIX_DEFAULT} macro. 1394 1395@defmac AC_PREFIX_DEFAULT (@var{prefix}) 1396Set the default installation prefix to @var{prefix} instead of @file{/usr/local}. 1397@end defmac 1398 1399It may be convenient for users to have @code{configure} guess the 1400installation prefix from the location of a related program that they 1401have already installed. If you wish to do that, you can call 1402@code{AC_PREFIX_PROGRAM}. 1403 1404@defmac AC_PREFIX_PROGRAM (@var{program}) 1405@maindex PREFIX_PROGRAM 1406If the user did not specify an installation prefix (using the 1407@samp{--prefix} option), guess a value for it by looking for 1408@var{program} in @code{PATH}, the way the shell does. If @var{program} 1409is found, set the prefix to the parent of the directory containing 1410@var{program}; otherwise leave the prefix specified in 1411@file{Makefile.in} unchanged. For example, if @var{program} is 1412@code{gcc} and the @code{PATH} contains @file{/usr/local/gnu/bin/gcc}, 1413set the prefix to @file{/usr/local/gnu}. 1414@end defmac 1415 1416@node Versions, , Default Prefix, Setup 1417@section Version Numbers in @code{configure} 1418 1419The following macros manage version numbers for @code{configure} 1420scripts. Using them is optional. 1421 1422@defmac AC_PREREQ (@var{version}) 1423@maindex PREREQ 1424Ensure that a recent enough version of Autoconf is being used. If the 1425version of Autoconf being used to create @code{configure} is earlier 1426than @var{version}, print an error message on the standard error output 1427and do not create @code{configure}. For example: 1428 1429@example 1430AC_PREREQ(1.8) 1431@end example 1432 1433This macro is useful if your @file{configure.in} relies on non-obvious 1434behavior that changed between Autoconf releases. If it merely needs 1435recently added macros, then @code{AC_PREREQ} is less useful, because the 1436@code{autoconf} program already tells the user which macros are not 1437found. The same thing happens if @file{configure.in} is processed by a 1438version of Autoconf older than when @code{AC_PREREQ} was added. 1439@end defmac 1440 1441@defmac AC_REVISION (@var{revision-info}) 1442@maindex REVISION 1443Copy revision stamp @var{revision-info} into the @code{configure} 1444script, with any dollar signs or double-quotes removed. This macro lets 1445you put a revision stamp from @file{configure.in} into @code{configure} 1446without RCS or CVS changing it when you check in @code{configure}. That 1447way, you can determine easily which revision of @file{configure.in} a 1448particular @code{configure} corresponds to. 1449 1450It is a good idea to call this macro before @code{AC_INIT} so that the 1451revision number is near the top of both @file{configure.in} and 1452@code{configure}. To support doing that, the @code{AC_REVISION} output 1453begins with @samp{#! /bin/sh}, like the normal start of a 1454@code{configure} script does. 1455 1456For example, this line in @file{configure.in}: 1457 1458@c The asis prevents RCS from changing the example in the manual. 1459@example 1460AC_REVISION($@asis{Revision: 1.30 }$)dnl 1461@end example 1462 1463@noindent 1464produces this in @code{configure}: 1465 1466@example 1467#! /bin/sh 1468# From configure.in Revision: 1.30 1469@end example 1470@end defmac 1471 1472@node Existing Tests, Writing Tests, Setup, Top 1473@chapter Existing Tests 1474 1475These macros test for particular system features that packages 1476might need or want to use. If you need to test for a kind of feature 1477that none of these macros check for, you can probably do it by calling 1478primitive test macros with appropriate arguments (@pxref{Writing Tests}). 1479 1480These tests print messages telling the user which feature they're 1481checking for, and what they find. They cache their results for future 1482@code{configure} runs (@pxref{Caching Results}). 1483 1484Some of these macros set output variables. @xref{Makefile 1485Substitutions}, for how to get their values. The phrase ``define 1486@var{name}'' is used below as a shorthand to mean ``define C 1487preprocessor symbol @var{name} to the value 1''. @xref{Defining 1488Symbols}, for how to get those symbol definitions into your program. 1489 1490@menu 1491* Alternative Programs:: Selecting between alternative programs. 1492* Libraries:: Library archives that might be missing. 1493* Library Functions:: C library functions that might be missing. 1494* Header Files:: Header files that might be missing. 1495* Structures:: Structures or members that might be missing. 1496* Typedefs:: @code{typedef}s that might be missing. 1497* C Compiler Characteristics:: 1498* Fortran 77 Compiler Characteristics:: 1499* System Services:: Operating system services. 1500* UNIX Variants:: Special kludges for specific UNIX variants. 1501@end menu 1502 1503@node Alternative Programs, Libraries, Existing Tests, Existing Tests 1504@section Alternative Programs 1505 1506These macros check for the presence or behavior of particular programs. 1507They are used to choose between several alternative programs and to 1508decide what to do once one has been chosen. 1509If there is no macro specifically defined to check for a program you need, 1510and you don't need to check for any special properties of 1511it, then you can use one of the general program check macros. 1512 1513@menu 1514* Particular Programs:: Special handling to find certain programs. 1515* Generic Programs:: How to find other programs. 1516@end menu 1517 1518@node Particular Programs, Generic Programs, Alternative Programs, Alternative Programs 1519@subsection Particular Program Checks 1520 1521These macros check for particular programs---whether they exist, and 1522in some cases whether they support certain features. 1523 1524@defmac AC_DECL_YYTEXT 1525@maindex DECL_YYTEXT 1526@cvindex YYTEXT_POINTER 1527@ovindex LEX_OUTPUT_ROOT 1528Define @code{YYTEXT_POINTER} if @code{yytext} is a @samp{char *} instead 1529of a @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to 1530the base of the file name that the lexer generates; usually 1531@file{lex.yy}, but sometimes something else. These results vary 1532according to whether @code{lex} or @code{flex} is being used. 1533@end defmac 1534 1535@defmac AC_PROG_AWK 1536@maindex PROG_AWK 1537@ovindex AWK 1538Check for @code{mawk}, @code{gawk}, @code{nawk}, and @code{awk}, in that 1539order, and set output variable @code{AWK} to the first one that it 1540finds. It tries @code{mawk} first because that is reported to be the 1541fastest implementation. 1542@end defmac 1543 1544@defmac AC_PROG_CC 1545@maindex PROG_CC 1546@ovindex CC 1547@ovindex CFLAGS 1548Determine a C compiler to use. If @code{CC} is not already set in the 1549environment, check for @code{gcc}, and use @code{cc} if that's not found. 1550Set output variable @code{CC} to the name of the compiler found. 1551 1552If using the GNU C compiler, set shell variable @code{GCC} to 1553@samp{yes}, empty otherwise. If output variable @code{CFLAGS} was 1554not already set, set it to @samp{-g -O2} for the GNU C compiler 1555(@samp{-O2} on systems where GCC does not accept @samp{-g}), or @samp{-g} 1556for other compilers. 1557 1558If the C compiler being used does not produce executables that can run 1559on the system where @code{configure} is being run, set the shell 1560variable @code{cross_compiling} to @samp{yes}, otherwise @samp{no}. 1561In other words, this tests whether the build system type is different 1562from the host system type (the target system type is irrelevant to this 1563test). @xref{Manual Configuration}, for more on support for cross compiling. 1564@end defmac 1565 1566@defmac AC_PROG_CC_C_O 1567@maindex PROG_CC_C_O 1568@cvindex NO_MINUS_C_MINUS_O 1569If the C compiler does not accept the @samp{-c} and @samp{-o} options 1570simultaneously, define @code{NO_MINUS_C_MINUS_O}. 1571@end defmac 1572 1573@defmac AC_PROG_CPP 1574@maindex PROG_CPP 1575@ovindex CPP 1576Set output variable @code{CPP} to a command that runs the 1577C preprocessor. If @samp{$CC -E} doesn't work, it uses @file{/lib/cpp}. 1578It is only portable to run @code{CPP} on files with a @file{.c} 1579extension. 1580 1581If the current language is C (@pxref{Language Choice}), many of the 1582specific test macros use the value of @code{CPP} indirectly by calling 1583@code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, @code{AC_EGREP_HEADER}, or 1584@code{AC_EGREP_CPP}. 1585@end defmac 1586 1587@defmac AC_PROG_CXX 1588@maindex PROG_CXX 1589@ovindex CXX 1590@ovindex CXXFLAGS 1591Determine a C++ compiler to use. Check if the environment variable 1592@code{CXX} or @code{CCC} (in that order) is set; if so, set output 1593variable @code{CXX} to its value. Otherwise search for a C++ compiler 1594under likely names (@code{c++}, @code{g++}, @code{gcc}, @code{CC}, 1595@code{cxx}, and @code{cc++}). If none of those checks succeed, as a 1596last resort set @code{CXX} to @code{gcc}. 1597 1598If using the GNU C++ compiler, set shell variable @code{GXX} to 1599@samp{yes}, empty otherwise. If output variable @code{CXXFLAGS} was 1600not already set, set it to @samp{-g -O2} for the GNU C++ compiler 1601(@samp{-O2} on systems where G++ does not accept @samp{-g}), or @samp{-g} 1602for other compilers. 1603 1604If the C++ compiler being used does not produce executables that can run 1605on the system where @code{configure} is being run, set the shell 1606variable @code{cross_compiling} to @samp{yes}, otherwise @samp{no}. 1607In other words, this tests whether the build system type is different 1608from the host system type (the target system type is irrelevant to this 1609test). @xref{Manual Configuration}, for more on support for cross compiling. 1610@end defmac 1611 1612@defmac AC_PROG_CXXCPP 1613@maindex PROG_CXXCPP 1614@ovindex CXXCPP 1615Set output variable @code{CXXCPP} to a command that runs the 1616C++ preprocessor. If @samp{$CXX -E} doesn't work, it uses @file{/lib/cpp}. 1617It is only portable to run @code{CXXCPP} on files with a @file{.c}, 1618@file{.C}, or @file{.cc} extension. 1619 1620If the current language is C++ (@pxref{Language Choice}), many of the 1621specific test macros use the value of @code{CXXCPP} indirectly by 1622calling @code{AC_TRY_CPP}, @code{AC_CHECK_HEADER}, 1623@code{AC_EGREP_HEADER}, or @code{AC_EGREP_CPP}. 1624@end defmac 1625 1626@defmac AC_PROG_F77 1627@maindex PROG_FORTRAN 1628@ovindex F77 1629@ovindex FFLAGS 1630Determine a Fortran 77 compiler to use. If @code{F77} is not already 1631set in the environment, check for @code{g77}, @code{f77} and @code{f2c}, 1632in that order. Set the output variable @code{F77} to the name of the 1633compiler found. 1634 1635If using @code{g77} (the GNU Fortran 77 compiler), then 1636@code{AC_PROG_F77} will set the shell variable @code{G77} to @samp{yes}, 1637and empty otherwise. If the output variable @code{FFLAGS} was not 1638already set in the environment, then set it to @samp{-g -02} for 1639@code{g77} (or @samp{-O2} where @code{g77} does not accept @samp{-g}). 1640Otherwise, set @code{FFLAGS} to @samp{-g} for all other Fortran 77 1641compilers. 1642@end defmac 1643 1644@defmac AC_PROG_F77_C_O 1645@maindex PROG_F77_C_O 1646@cvindex F77_NO_MINUS_C_MINUS_O 1647Test if the Fortran 77 compiler accepts the options @samp{-c} and 1648@samp{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} if it 1649does not. 1650@end defmac 1651 1652@defmac AC_PROG_GCC_TRADITIONAL 1653@maindex PROG_GCC_TRADITIONAL 1654@ovindex CC 1655Add @samp{-traditional} to output variable @code{CC} if using the 1656GNU C compiler and @code{ioctl} does not work properly without 1657@samp{-traditional}. That usually happens when the fixed header files 1658have not been installed on an old system. Since recent versions of the 1659GNU C compiler fix the header files automatically when installed, this 1660is becoming a less prevalent problem. 1661@end defmac 1662 1663@defmac AC_PROG_INSTALL 1664@maindex PROG_INSTALL 1665@ovindex INSTALL 1666@ovindex INSTALL_PROGRAM 1667@ovindex INSTALL_DATA 1668@ovindex INSTALL_SCRIPT 1669Set output variable @code{INSTALL} to the path of a BSD compatible 1670@code{install} program, if one is found in the current @code{PATH}. 1671Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, 1672checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its 1673default directories) to determine @var{dir} (@pxref{Output}). Also set 1674the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to 1675@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. 1676 1677This macro screens out various instances of @code{install} known to not 1678work. It prefers to find a C program rather than a shell script, for 1679speed. Instead of @file{install-sh}, it can also use @file{install.sh}, 1680but that name is obsolete because some @code{make} programs have a rule 1681that creates @file{install} from it if there is no @file{Makefile}. 1682 1683A copy of @file{install-sh} which you may use comes with Autoconf. If 1684you use @code{AC_PROG_INSTALL}, you must include either 1685@file{install-sh} or @file{install.sh} in your distribution, or 1686@code{configure} will produce an error message saying it can't find 1687them---even if the system you're on has a good @code{install} program. 1688This check is a safety measure to prevent you from accidentally leaving 1689that file out, which would prevent your package from installing on 1690systems that don't have a BSD-compatible @code{install} program. 1691 1692If you need to use your own installation program because it has 1693features not found in standard @code{install} programs, there is no 1694reason to use @code{AC_PROG_INSTALL}; just put the pathname of your 1695program into your @file{Makefile.in} files. 1696@end defmac 1697 1698@defmac AC_PROG_LEX 1699@maindex PROG_LEX 1700@ovindex LEX 1701@ovindex LEXLIB 1702If @code{flex} is found, set output variable @code{LEX} to 1703@samp{flex} and @code{LEXLIB} to @samp{-lfl}, if that library is in a 1704standard place. Otherwise set @code{LEX} to @samp{lex} and 1705@code{LEXLIB} to @samp{-ll}. 1706@end defmac 1707 1708@defmac AC_PROG_LN_S 1709@maindex PROG_LN_S 1710@ovindex LN_S 1711If @samp{ln -s} works on the current filesystem (the operating system 1712and filesystem support symbolic links), set output 1713variable @code{LN_S} to @samp{ln -s}, otherwise set it to @samp{ln}. 1714 1715If the link is put in a directory other than the current directory, its 1716meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely 1717create links using @samp{$(LN_S)}, either find out which form is used 1718and adjust the arguments, or always invoke @code{ln} in the directory 1719where the link is to be created. 1720 1721In other words, it does not work to do 1722@example 1723$(LN_S) foo /x/bar 1724@end example 1725 1726Instead, do 1727 1728@example 1729(cd /x && $(LN_S) foo bar) 1730@end example 1731@end defmac 1732 1733@defmac AC_PROG_RANLIB 1734@maindex PROG_RANLIB 1735@ovindex RANLIB 1736Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} 1737is found, otherwise to @samp{:} (do nothing). 1738@end defmac 1739 1740@defmac AC_PROG_YACC 1741@maindex PROG_YACC 1742@ovindex YACC 1743If @code{bison} is found, set output variable @code{YACC} to 1744@samp{bison -y}. Otherwise, if @code{byacc} is found, set @code{YACC} 1745to @samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. 1746@end defmac 1747 1748@node Generic Programs, , Particular Programs, Alternative Programs 1749@subsection Generic Program and File Checks 1750 1751These macros are used to find programs not covered by the particular 1752test macros. If you need to check the behavior of a program as well as 1753find out whether it is present, you have to write your own test for it 1754(@pxref{Writing Tests}). By default, these macros use the environment 1755variable @code{PATH}. If you need to check for a program that might not 1756be in the user's @code{PATH}, you can pass a modified path to use 1757instead, like this: 1758 1759@example 1760AC_PATH_PROG(INETD, inetd, /usr/libexec/inetd, 1761 $PATH:/usr/libexec:/usr/sbin:/usr/etc:etc) 1762@end example 1763 1764@defmac AC_CHECK_FILE (@var{file} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 1765@maindex CHECK_FILE 1766Check whether file @var{file} exists on the native system. 1767If it is found, execute @var{action-if-found}, otherwise do 1768@var{action-if-not-found}, if given. 1769@end defmac 1770 1771@defmac AC_CHECK_FILES (@var{files}@r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 1772@maindex CHECK_FILES 1773Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. 1774Additionally, defines @samp{HAVE@var{file}} for each file found, set to 1. 1775@end defmac 1776 1777@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found} @r{[}, @var{value-if-not-found} @r{[}, @var{path}, @r{[} @var{reject} @r{]]]}) 1778@maindex CHECK_PROG 1779Check whether program @var{prog-to-check-for} exists in @code{PATH}. If 1780it is found, set @var{variable} to @var{value-if-found}, otherwise to 1781@var{value-if-not-found}, if given. Always pass over @var{reject} (an 1782absolute file name) even if it is the first found in the search path; in 1783that case, set @var{variable} using the absolute file name of the 1784@var{prog-to-check-for} found that is not @var{reject}. If 1785@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for 1786@var{variable}. 1787@end defmac 1788 1789@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) 1790@maindex CHECK_PROGS 1791Check for each program in the whitespace-separated list 1792@var{progs-to-check-for} exists in @code{PATH}. If it is found, set 1793@var{variable} to the name of that program. Otherwise, continue 1794checking the next program in the list. If none of the programs in the 1795list are found, set @var{variable} to @var{value-if-not-found}; if 1796@var{value-if-not-found} is not specified, the value of @var{variable} 1797is not changed. Calls @code{AC_SUBST} for @var{variable}. 1798@end defmac 1799 1800@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) 1801@maindex CHECK_TOOL 1802Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 1803with a prefix of the host type as determined by @code{AC_CANONICAL_HOST}, 1804followed by a dash (@pxref{Canonicalizing}). For example, if the user 1805runs @samp{configure --host=i386-gnu}, then this call: 1806@example 1807AC_CHECK_TOOL(RANLIB, ranlib, :) 1808@end example 1809@noindent 1810sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in 1811@code{PATH}, or to @samp{ranlib} if that program exists in @code{PATH}, 1812or to @samp{:} if neither program exists. 1813@end defmac 1814 1815@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) 1816@maindex PATH_PROG 1817Like @code{AC_CHECK_PROG}, but set @var{variable} to the entire 1818path of @var{prog-to-check-for} if found. 1819@end defmac 1820 1821@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for} @r{[}, @var{value-if-not-found} @r{[}, @var{path}@r{]]}) 1822@maindex PATH_PROGS 1823Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} 1824are found, set @var{variable} to the entire path of the program 1825found. 1826@end defmac 1827 1828@node Libraries, Library Functions, Alternative Programs, Existing Tests 1829@section Library Files 1830 1831The following macros check for the presence of certain C, C++ or Fortran 183277 library archive files. 1833 1834@defmac AC_CHECK_LIB (@var{library}, @var{function} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]}) 1835@maindex CHECK_LIB 1836Depending on the current language(@pxref{Language Choice}), try to 1837ensure that the C, C++ or Fortran 77 function @var{function} is 1838available by checking whether a test program can be linked with the 1839library @var{library} to get the function. @var{library} is the base 1840name of the library; e.g., to check for @samp{-lmp}, use @samp{mp} as 1841the @var{library} argument. 1842 1843@var{action-if-found} is a list of shell commands to run if the link 1844with the library succeeds; @var{action-if-not-found} is a list of 1845shell commands to run if the link fails. If @var{action-if-found} is 1846not specified, the default action will add @samp{-l@var{library}} to 1847@code{LIBS} and define @samp{HAVE_LIB@var{library}} (in all capitals). 1848 1849If linking with @var{library} results in unresolved symbols, which would 1850be resolved by linking with additional libraries, give those libraries 1851as the @var{other-libraries} argument, separated by spaces: @samp{-lXt 1852-lX11}. Otherwise this macro will fail to detect that @var{library} is 1853present, because linking the test program will always fail with 1854unresolved symbols. 1855@end defmac 1856 1857@defmac AC_HAVE_LIBRARY (@var{library}, @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]}) 1858@maindex HAVE_LIBRARY 1859This macro is equivalent to calling @code{AC_CHECK_LIB} with a 1860@var{function} argument of @code{main}. In addition, @var{library} can 1861be written as any of @samp{foo}, @samp{-lfoo}, or @samp{libfoo.a}. In 1862all of those cases, the compiler is passed @samp{-lfoo}. However, 1863@var{library} can not be a shell variable; it must be a literal name. 1864This macro is considered obsolete. 1865@end defmac 1866 1867@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found} @r{[}, @var{other-libraries}@r{]]]}) 1868@maindex SEARCH_LIBS 1869Search for a library defining @var{function}, if it's not already 1870available. This equates to calling @code{AC_TRY_LINK_FUNC} first 1871with no libraries, then for each library listed in @var{search-libs}. 1872 1873If the function is found, run @var{action-if-found}, otherwise run 1874@var{action-if-not-found}. 1875 1876If linking with @var{library} results in unresolved symbols, which would 1877be resolved by linking with additional libraries, give those libraries 1878as the @var{other-libraries} argument, separated by spaces: @samp{-lXt 1879-lX11}. Otherwise this macro will fail to detect that @var{function} is 1880present, because linking the test program will always fail with 1881unresolved symbols. 1882@end defmac 1883 1884@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}@r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 1885@maindex SEARCH_LIBS 1886This macro is equivalent to calling @code{AC_TRY_LINK_FUNC} once for each 1887library listed in @var{search-libs}. Add @samp{-l@var{library}} to 1888@code{LIBS} for the first library found to contain @var{function}, and 1889execute @var{action-if-found}. Otherwise execute 1890@var{action-if-not-found}. 1891@end defmac 1892 1893@node Library Functions, Header Files, Libraries, Existing Tests 1894@section Library Functions 1895 1896The following macros check for particular C library functions. 1897If there is no macro specifically defined to check for a function you need, 1898and you don't need to check for any special properties of 1899it, then you can use one of the general function check macros. 1900 1901@menu 1902* Particular Functions:: Special handling to find certain functions. 1903* Generic Functions:: How to find other functions. 1904@end menu 1905 1906@node Particular Functions, Generic Functions, Library Functions, Library Functions 1907@subsection Particular Function Checks 1908 1909These macros check for particular C functions---whether they exist, and 1910in some cases how they respond when given certain arguments. 1911 1912@defmac AC_FUNC_ALLOCA 1913@maindex FUNC_ALLOCA 1914@cvindex C_ALLOCA 1915@cvindex HAVE_ALLOCA_H 1916@ovindex ALLOCA 1917Check how to get @code{alloca}. Tries to get a builtin version by 1918checking for @file{alloca.h} or the predefined C preprocessor macros 1919@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, 1920it defines @code{HAVE_ALLOCA_H}. 1921 1922If those attempts fail, it looks for the function in the standard C 1923library. If any of those methods succeed, it defines 1924@code{HAVE_ALLOCA}. Otherwise, it sets the output variable 1925@code{ALLOCA} to @samp{alloca.o} and defines @code{C_ALLOCA} (so 1926programs can periodically call @samp{alloca(0)} to garbage collect). 1927This variable is separate from @code{LIBOBJS} so multiple programs can 1928share the value of @code{ALLOCA} without needing to create an actual 1929library, in case only some of them use the code in @code{LIBOBJS}. 1930 1931This macro does not try to get @code{alloca} from the System V R3 1932@file{libPW} or the System V R4 @file{libucb} because those libraries 1933contain some incompatible functions that cause trouble. Some versions 1934do not even contain @code{alloca} or contain a buggy version. If you 1935still want to use their @code{alloca}, use @code{ar} to extract 1936@file{alloca.o} from them instead of compiling @file{alloca.c}. 1937 1938Source files that use @code{alloca} should start with a piece of code 1939like the following, to declare it properly. In some versions 1940of AIX, the declaration of @code{alloca} must precede everything else 1941except for comments and preprocessor directives. The @code{#pragma} 1942directive is indented so that pre-ANSI C compilers will ignore it, 1943rather than choke on it. 1944 1945@example 1946@group 1947/* AIX requires this to be the first thing in the file. */ 1948#ifndef __GNUC__ 1949# if HAVE_ALLOCA_H 1950# include <alloca.h> 1951# else 1952# ifdef _AIX 1953 #pragma alloca 1954# else 1955# ifndef alloca /* predefined by HP cc +Olibcalls */ 1956char *alloca (); 1957# endif 1958# endif 1959# endif 1960#endif 1961@end group 1962@end example 1963@end defmac 1964 1965@defmac AC_FUNC_CLOSEDIR_VOID 1966@maindex FUNC_CLOSEDIR_VOID 1967@cvindex CLOSEDIR_VOID 1968If the @code{closedir} function does not return a meaningful value, 1969define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its 1970return value for an error indicator. 1971@end defmac 1972 1973@defmac AC_FUNC_FNMATCH 1974@maindex FUNC_FNMATCH 1975@ovindex LIBOBJS 1976If the @code{fnmatch} function is available and works (unlike the one on 1977SunOS 5.4), define @code{HAVE_FNMATCH}. 1978@end defmac 1979 1980@defmac AC_FUNC_GETLOADAVG 1981@maindex FUNC_GETLOADAVG 1982@cvindex SVR4 1983@cvindex DGUX 1984@cvindex UMAX 1985@cvindex UMAX4_3 1986@cvindex NLIST_STRUCT 1987@cvindex NLIST_NAME_UNION 1988@cvindex GETLODAVG_PRIVILEGED 1989@cvindex NEED_SETGID 1990@ovindex LIBOBJS 1991@ovindex NEED_SETGID 1992@ovindex KMEM_GROUP 1993Check how to get the system load averages. If the system has the 1994@code{getloadavg} function, this macro defines @code{HAVE_GETLOADAVG}, 1995and adds to @code{LIBS} any libraries needed to get that function. 1996 1997Otherwise, it adds @samp{getloadavg.o} to the output variable 1998@code{LIBOBJS}, and possibly defines several other C preprocessor 1999macros and output variables: 2000 2001@enumerate 2002@item 2003It defines @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if 2004on those systems. 2005 2006@item 2007If it finds @file{nlist.h}, it defines @code{NLIST_STRUCT}. 2008 2009@item 2010If @samp{struct nlist} has an @samp{n_un} member, it defines 2011@code{NLIST_NAME_UNION}. 2012 2013@item 2014If compiling @file{getloadavg.c} defines @code{LDAV_PRIVILEGED}, 2015programs need to be installed specially on this system for 2016@code{getloadavg} to work, and this macro defines 2017@code{GETLOADAVG_PRIVILEGED}. 2018 2019@item 2020This macro sets the output variable @code{NEED_SETGID}. The value is 2021@samp{true} if special installation is required, @samp{false} if not. 2022If @code{NEED_SETGID} is @samp{true}, this macro sets @code{KMEM_GROUP} 2023to the name of the group that should own the installed program. 2024@end enumerate 2025@end defmac 2026 2027@defmac AC_FUNC_GETMNTENT 2028@maindex FUNC_GETMNTENT 2029@cvindex HAVE_GETMNTENT 2030Check for @code{getmntent} in the @file{sun}, @file{seq}, and @file{gen} 2031libraries, for Irix 4, PTX, and Unixware, respectively. Then, if 2032@code{getmntent} is available, define @code{HAVE_GETMNTENT}. 2033@end defmac 2034 2035@defmac AC_FUNC_GETPGRP 2036@maindex FUNC_GETPGRP 2037@cvindex GETPGRP_VOID 2038If @code{getpgrp} takes no argument (the POSIX.1 version), define 2039@code{GETPGRP_VOID}. Otherwise, it is the BSD version, which takes a 2040process ID as an argument. This macro does not check whether 2041@code{getpgrp} exists at all; if you need to work in that situation, 2042first call @code{AC_CHECK_FUNC} for @code{getpgrp}. 2043@end defmac 2044 2045@defmac AC_FUNC_MEMCMP 2046@maindex FUNC_MEMCMP 2047@ovindex LIBOBJS 2048If the @code{memcmp} function is not available, or does not work on 20498-bit data (like the one on SunOS 4.1.3), add @samp{memcmp.o} to output 2050variable @code{LIBOBJS}. 2051@end defmac 2052 2053@defmac AC_FUNC_MMAP 2054@maindex FUNC_MMAP 2055@cvindex HAVE_MMAP 2056If the @code{mmap} function exists and works correctly, define 2057@code{HAVE_MMAP}. Only checks private fixed mapping of already-mapped 2058memory. 2059@end defmac 2060 2061@defmac AC_FUNC_SELECT_ARGTYPES 2062@maindex FUNC_SELECT_ARGTYPES 2063@cvindex SELECT_TYPE_ARG1 2064@cvindex SELECT_TYPE_ARG234 2065@cvindex SELECT_TYPE_ARG5 2066Determines the correct type to be passed to each of the 2067@code{select} function's arguments, and defines those types 2068in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and 2069@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults 2070to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, 2071and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. 2072@end defmac 2073 2074@defmac AC_FUNC_SETPGRP 2075@maindex FUNC_SETPGRP 2076@cvindex SETPGRP_VOID 2077If @code{setpgrp} takes no argument (the POSIX.1 version), define 2078@code{SETPGRP_VOID}. Otherwise, it is the BSD version, which takes two 2079process ID as arguments. This macro does not check whether 2080@code{setpgrp} exists at all; if you need to work in that situation, 2081first call @code{AC_CHECK_FUNC} for @code{setpgrp}. 2082@end defmac 2083 2084@defmac AC_FUNC_SETVBUF_REVERSED 2085@maindex FUNC_SETVBUF_REVERSED 2086@cvindex SETVBUF_REVERSED 2087If @code{setvbuf} takes the buffering type as its second argument and 2088the buffer pointer as the third, instead of the other way around, define 2089@code{SETVBUF_REVERSED}. This is the case on System V before release 3. 2090@end defmac 2091 2092@defmac AC_FUNC_STRCOLL 2093@maindex FUNC_STRCOLL 2094@cvindex HAVE_STRCOLL 2095If the @code{strcoll} function exists and works correctly, define 2096@code{HAVE_STRCOLL}. This does a bit more than 2097@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect 2098definitions of @code{strcoll}, which should not be used. 2099@end defmac 2100 2101@defmac AC_FUNC_STRFTIME 2102@maindex FUNC_STRFTIME 2103@cvindex HAVE_STRFTIME 2104Check for @code{strftime} in the @file{intl} library, for SCO UNIX. 2105Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. 2106@end defmac 2107 2108@defmac AC_FUNC_UTIME_NULL 2109@maindex FUNC_UTIME_NULL 2110@cvindex HAVE_UTIME_NULL 2111If @samp{utime(@var{file}, NULL)} sets @var{file}'s timestamp to 2112the present, define @code{HAVE_UTIME_NULL}. 2113@end defmac 2114 2115@defmac AC_FUNC_VFORK 2116@maindex FUNC_VFORK 2117@cvindex HAVE_VFORK_H 2118@cvindex vfork 2119If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working 2120@code{vfork} is not found, define @code{vfork} to be @code{fork}. This 2121macro checks for several known errors in implementations of @code{vfork} 2122and considers the system to not have a working @code{vfork} if it 2123detects any of them. It is not considered to be an implementation error 2124if a child's invocation of @code{signal} modifies the parent's signal 2125handler, since child processes rarely change their signal handlers. 2126@end defmac 2127 2128@defmac AC_FUNC_VPRINTF 2129@maindex FUNC_VPRINTF 2130@cvindex HAVE_VPRINTF 2131@cvindex HAVE_DOPRNT 2132If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if 2133@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} 2134is available, you may assume that @code{vfprintf} and @code{vsprintf} 2135are also available.) 2136@end defmac 2137 2138@defmac AC_FUNC_WAIT3 2139@maindex FUNC_WAIT3 2140@cvindex HAVE_WAIT3 2141If @code{wait3} is found and fills in the contents of its third argument 2142(a @samp{struct rusage *}), which HP-UX does not do, define 2143@code{HAVE_WAIT3}. 2144@end defmac 2145 2146@node Generic Functions, , Particular Functions, Library Functions 2147@subsection Generic Function Checks 2148 2149These macros are used to find functions not covered by the particular 2150test macros. If the functions might be in libraries other than the 2151default C library, first call @code{AC_CHECK_LIB} for those libraries. 2152If you need to check the behavior of a function as well as find out 2153whether it is present, you have to write your own test for 2154it (@pxref{Writing Tests}). 2155 2156@defmac AC_CHECK_FUNC (@var{function}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 2157@maindex CHECK_FUNC 2158If C function @var{function} is available, run shell commands 2159@var{action-if-found}, otherwise @var{action-if-not-found}. If you just 2160want to define a symbol if the function is available, consider using 2161@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C 2162linkage even when @code{AC_LANG_CPLUSPLUS} has been called, since C++ is 2163more standardized than C is. (@pxref{Language Choice}, for more 2164information about selecting the language for checks.) 2165@end defmac 2166 2167@defmac AC_CHECK_FUNCS (@var{function}@dots{} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 2168@maindex CHECK_FUNCS 2169@cvindex HAVE_@var{function} 2170For each given @var{function} in the whitespace-separated argument list 2171that is available, define @code{HAVE_@var{function}} (in all capitals). If 2172@var{action-if-found} is given, it is additional shell code to execute 2173when one of the functions is found. You can give it a value of 2174@samp{break} to break out of the loop on the first match. If 2175@var{action-if-not-found} is given, it is executed when one of the 2176functions is not found. 2177@end defmac 2178 2179@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) 2180@maindex REPLACE_FUNCS 2181@ovindex LIBOBJS 2182Like calling @code{AC_CHECK_FUNCS} using an @var{action-if-not-found} 2183that adds @samp{@var{function}.o} to the value of the output variable 2184@code{LIBOBJS}. You can declare a function for which your replacement 2185version is used by enclosing the prototype in @samp{#ifndef 2186HAVE_@var{function}}. If the system has the function, it probably 2187declares it in a header file you should be including, so you shouldn't 2188redeclare it, lest your declaration conflict. 2189@end defmac 2190 2191@node Header Files, Structures, Library Functions, Existing Tests 2192@section Header Files 2193 2194The following macros check for the presence of certain C header files. 2195If there is no macro specifically defined to check for a header file you need, 2196and you don't need to check for any special properties of 2197it, then you can use one of the general header file check macros. 2198 2199@menu 2200* Particular Headers:: Special handling to find certain headers. 2201* Generic Headers:: How to find other headers. 2202@end menu 2203 2204@node Particular Headers, Generic Headers, Header Files, Header Files 2205@subsection Particular Header Checks 2206 2207These macros check for particular system header files---whether they 2208exist, and in some cases whether they declare certain symbols. 2209 2210@defmac AC_DECL_SYS_SIGLIST 2211@maindex DECL_SYS_SIGLIST 2212@cvindex SYS_SIGLIST_DECLARED 2213Define @code{SYS_SIGLIST_DECLARED} if the variable @code{sys_siglist} is 2214declared in a system header file, either @file{signal.h} or 2215@file{unistd.h}. 2216@end defmac 2217 2218@defmac AC_DIR_HEADER 2219@maindex DIR_HEADER 2220@cvindex DIRENT 2221@cvindex SYSDIR 2222@cvindex SYSNDIR 2223@cvindex NDIR 2224@cvindex VOID_CLOSEDIR 2225Like calling @code{AC_HEADER_DIRENT} and @code{AC_FUNC_CLOSEDIR_VOID}, 2226but defines a different set of C preprocessor macros to indicate which 2227header file is found. This macro and the names it defines are 2228considered obsolete. The names it defines are: 2229 2230@c The printed table looks too spaced out with blank lines between the entries. 2231@table @file 2232@item dirent.h 2233@code{DIRENT} 2234@item sys/ndir.h 2235@code{SYSNDIR} 2236@item sys/dir.h 2237@code{SYSDIR} 2238@item ndir.h 2239@code{NDIR} 2240@end table 2241 2242In addition, if the @code{closedir} function does not return a 2243meaningful value, define @code{VOID_CLOSEDIR}. 2244@end defmac 2245 2246@defmac AC_HEADER_DIRENT 2247@maindex HEADER_DIRENT 2248@cvindex HAVE_DIRENT_H 2249@cvindex HAVE_NDIR_H 2250@cvindex HAVE_SYS_DIR_H 2251@cvindex HAVE_SYS_NDIR_H 2252Check for the following header files, and for the first one that is 2253found and defines @samp{DIR}, define the listed C preprocessor macro: 2254 2255@c The printed table looks too spaced out with blank lines between the entries. 2256@table @file 2257@item dirent.h 2258@code{HAVE_DIRENT_H} 2259@item sys/ndir.h 2260@code{HAVE_SYS_NDIR_H} 2261@item sys/dir.h 2262@code{HAVE_SYS_DIR_H} 2263@item ndir.h 2264@code{HAVE_NDIR_H} 2265@end table 2266 2267The directory library declarations in the source code should look 2268something like the following: 2269 2270@example 2271@group 2272#if HAVE_DIRENT_H 2273# include <dirent.h> 2274# define NAMLEN(dirent) strlen((dirent)->d_name) 2275#else 2276# define dirent direct 2277# define NAMLEN(dirent) (dirent)->d_namlen 2278# if HAVE_SYS_NDIR_H 2279# include <sys/ndir.h> 2280# endif 2281# if HAVE_SYS_DIR_H 2282# include <sys/dir.h> 2283# endif 2284# if HAVE_NDIR_H 2285# include <ndir.h> 2286# endif 2287#endif 2288@end group 2289@end example 2290 2291Using the above declarations, the program would declare variables to be 2292type @code{struct dirent}, not @code{struct direct}, and would access 2293the length of a directory entry name by passing a pointer to a 2294@code{struct dirent} to the @code{NAMLEN} macro. 2295 2296This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. 2297@end defmac 2298 2299@defmac AC_HEADER_MAJOR 2300@maindex HEADER_MAJOR 2301@cvindex MAJOR_IN_MKDEV 2302@cvindex MAJOR_IN_SYSMACROS 2303If @file{sys/types.h} does not define @code{major}, @code{minor}, and 2304@code{makedev}, but @file{sys/mkdev.h} does, define 2305@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define 2306@code{MAJOR_IN_SYSMACROS}. 2307@end defmac 2308 2309@defmac AC_HEADER_STDC 2310@maindex HEADER_STDC 2311@cvindex STDC_HEADERS 2312Define @code{STDC_HEADERS} if the system has ANSI C header files. 2313Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, 2314@file{string.h}, and @file{float.h}; if the system has those, it 2315probably has the rest of the ANSI C header files. This macro also 2316checks whether @file{string.h} declares @code{memchr} (and thus 2317presumably the other @code{mem} functions), whether @file{stdlib.h} 2318declare @code{free} (and thus presumably @code{malloc} and other related 2319functions), and whether the @file{ctype.h} macros work on characters 2320with the high bit set, as ANSI C requires. 2321 2322Use @code{STDC_HEADERS} instead of @code{__STDC__} to determine whether 2323the system has ANSI-compliant header files (and probably C library 2324functions) because many systems that have GCC do not have ANSI C header 2325files. 2326 2327On systems without ANSI C headers, there is so much variation that it is 2328probably easier to declare the functions you use than to figure out 2329exactly what the system header files declare. Some systems contain a 2330mix of functions ANSI and BSD; some are mostly ANSI but lack 2331@samp{memmove}; some define the BSD functions as macros in 2332@file{string.h} or @file{strings.h}; some have only the BSD functions 2333but @file{string.h}; some declare the memory functions in 2334@file{memory.h}, some in @file{string.h}; etc. It is probably 2335sufficient to check for one string function and one memory function; if 2336the library has the ANSI versions of those then it probably has most of 2337the others. If you put the following in @file{configure.in}: 2338 2339@example 2340AC_HEADER_STDC 2341AC_CHECK_FUNCS(strchr memcpy) 2342@end example 2343 2344@noindent 2345then, in your code, you can put declarations like this: 2346 2347@example 2348@group 2349#if STDC_HEADERS 2350# include <string.h> 2351#else 2352# ifndef HAVE_STRCHR 2353# define strchr index 2354# define strrchr rindex 2355# endif 2356char *strchr (), *strrchr (); 2357# ifndef HAVE_MEMCPY 2358# define memcpy(d, s, n) bcopy ((s), (d), (n)) 2359# define memmove(d, s, n) bcopy ((s), (d), (n)) 2360# endif 2361#endif 2362@end group 2363@end example 2364 2365@noindent 2366If you use a function like @code{memchr}, @code{memset}, @code{strtok}, 2367or @code{strspn}, which have no BSD equivalent, then macros won't 2368suffice; you must provide an implementation of each function. An easy 2369way to incorporate your implementations only when needed (since the ones 2370in system C libraries may be hand optimized) is to, taking @code{memchr} 2371for example, put it in @file{memchr.c} and use 2372@samp{AC_REPLACE_FUNCS(memchr)}. 2373@end defmac 2374 2375@defmac AC_HEADER_SYS_WAIT 2376@maindex HEADER_SYS_WAIT 2377@cvindex HAVE_SYS_WAIT_H 2378If @file{sys/wait.h} exists and is compatible with POSIX.1, define 2379@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} 2380does not exist, or if it uses the old BSD @code{union wait} instead of 2381@code{int} to store a status value. If @file{sys/wait.h} is not POSIX.1 2382compatible, then instead of including it, define the POSIX.1 macros with 2383their usual interpretations. Here is an example: 2384 2385@example 2386@group 2387#include <sys/types.h> 2388#if HAVE_SYS_WAIT_H 2389# include <sys/wait.h> 2390#endif 2391#ifndef WEXITSTATUS 2392# define WEXITSTATUS(stat_val) ((unsigned)(stat_val) >> 8) 2393#endif 2394#ifndef WIFEXITED 2395# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 2396#endif 2397@end group 2398@end example 2399@end defmac 2400 2401@defmac AC_MEMORY_H 2402@maindex MEMORY_H 2403@cvindex NEED_MEMORY_H 2404Define @code{NEED_MEMORY_H} if @code{memcpy}, @code{memcmp}, etc. are 2405not declared in @file{string.h} and @file{memory.h} exists. This macro 2406is obsolete; instead, use @code{AC_CHECK_HEADERS(memory.h)}. See the 2407example for @code{AC_HEADER_STDC}. 2408@end defmac 2409 2410@defmac AC_UNISTD_H 2411@maindex UNISTD_H 2412@cvindex HAVE_UNISTD_H 2413Define @code{HAVE_UNISTD_H} if the system has @file{unistd.h}. This 2414macro is obsolete; instead, use @samp{AC_CHECK_HEADERS(unistd.h)}. 2415 2416The way to check if the system supports POSIX.1 is: 2417 2418@example 2419@group 2420#if HAVE_UNISTD_H 2421# include <sys/types.h> 2422# include <unistd.h> 2423#endif 2424 2425#ifdef _POSIX_VERSION 2426/* Code for POSIX.1 systems. */ 2427#endif 2428@end group 2429@end example 2430 2431@cvindex _POSIX_VERSION 2432@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on 2433POSIX.1 systems. If there is no @file{unistd.h}, it is definitely not a 2434POSIX.1 system. However, some non-POSIX.1 systems do have @file{unistd.h}. 2435@end defmac 2436 2437@defmac AC_USG 2438@maindex USG 2439@cvindex USG 2440Define @code{USG} if the system does not have @file{strings.h}, 2441@code{rindex}, @code{bzero}, etc. This implies that it has 2442@file{string.h}, @code{strrchr}, @code{memset}, etc. 2443 2444The symbol @code{USG} is obsolete. Instead of this macro, see the 2445example for @code{AC_HEADER_STDC}. 2446@end defmac 2447 2448@node Generic Headers, , Particular Headers, Header Files 2449@subsection Generic Header Checks 2450 2451These macros are used to find system header files not covered by the 2452particular test macros. If you need to check the contents of a header 2453as well as find out whether it is present, you have to write your own 2454test for it (@pxref{Writing Tests}). 2455 2456@defmac AC_CHECK_HEADER (@var{header-file}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 2457@maindex CHECK_HEADER 2458If the system header file @var{header-file} exists, execute shell commands 2459@var{action-if-found}, otherwise execute @var{action-if-not-found}. If 2460you just want to define a symbol if the header file is available, 2461consider using @code{AC_CHECK_HEADERS} instead. 2462@end defmac 2463 2464@defmac AC_CHECK_HEADERS (@var{header-file}@dots{} @r{[}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 2465@maindex CHECK_HEADERS 2466@cvindex HAVE_@var{header} 2467For each given system header file @var{header-file} in the 2468whitespace-separated argument list that exists, define 2469@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} 2470is given, it is additional shell code to execute when one of the header 2471files is found. You can give it a value of @samp{break} to break out of 2472the loop on the first match. If @var{action-if-not-found} is given, it 2473is executed when one of the header files is not found. 2474@end defmac 2475 2476@node Structures, Typedefs, Header Files, Existing Tests 2477@section Structures 2478 2479The following macros check for certain structures or structure members. 2480To check structures not listed here, use @code{AC_EGREP_CPP} 2481(@pxref{Examining Declarations}) or @code{AC_TRY_COMPILE} 2482(@pxref{Examining Syntax}). 2483 2484@defmac AC_HEADER_STAT 2485@maindex HEADER_STAT 2486@maindex STAT_MACROS_BROKEN 2487If the macros @code{S_ISDIR}, @code{S_ISREG} et al. defined in 2488@file{sys/stat.h} do not work properly (returning false positives), 2489define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, 2490Amdahl UTS and Motorola System V/88. 2491@end defmac 2492 2493@defmac AC_HEADER_TIME 2494@maindex HEADER_TIME 2495@cvindex TIME_WITH_SYS_TIME 2496If a program may include both @file{time.h} and @file{sys/time.h}, 2497define @code{TIME_WITH_SYS_TIME}. On some older systems, 2498@file{sys/time.h} includes @file{time.h}, but @file{time.h} is not 2499protected against multiple inclusion, so programs should not explicitly 2500include both files. This macro is useful in programs that use, for 2501example, @code{struct timeval} or @code{struct timezone} as well as 2502@code{struct tm}. It is best used in conjunction with 2503@code{HAVE_SYS_TIME_H}, which can be checked for using 2504@code{AC_CHECK_HEADERS(sys/time.h)}. 2505 2506@example 2507@group 2508#if TIME_WITH_SYS_TIME 2509# include <sys/time.h> 2510# include <time.h> 2511#else 2512# if HAVE_SYS_TIME_H 2513# include <sys/time.h> 2514# else 2515# include <time.h> 2516# endif 2517#endif 2518@end group 2519@end example 2520@end defmac 2521 2522@defmac AC_STRUCT_ST_BLKSIZE 2523@maindex STRUCT_ST_BLKSIZE 2524@cvindex HAVE_ST_BLKSIZE 2525If @code{struct stat} contains an @code{st_blksize} member, define 2526@code{HAVE_ST_BLKSIZE}. 2527@end defmac 2528 2529@defmac AC_STRUCT_ST_BLOCKS 2530@maindex STRUCT_ST_BLOCKS 2531@cvindex HAVE_ST_BLOCKS 2532@ovindex LIBOBJS 2533If @code{struct stat} contains an @code{st_blocks} member, define 2534@code{HAVE_ST_BLOCKS}. Otherwise, add @samp{fileblocks.o} to the 2535output variable @code{LIBOBJS}. 2536@end defmac 2537 2538@defmac AC_STRUCT_ST_RDEV 2539@maindex STRUCT_ST_RDEV 2540@cvindex HAVE_ST_RDEV 2541If @code{struct stat} contains an @code{st_rdev} member, define 2542@code{HAVE_ST_RDEV}. 2543@end defmac 2544 2545@defmac AC_STRUCT_TM 2546@maindex STRUCT_TM 2547@cvindex TM_IN_SYS_TIME 2548If @file{time.h} does not define @code{struct tm}, define 2549@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} 2550had better define @code{struct tm}. 2551@end defmac 2552 2553@defmac AC_STRUCT_TIMEZONE 2554@maindex STRUCT_TIMEZONE 2555@cvindex HAVE_TM_ZONE 2556@cvindex HAVE_TZNAME 2557Figure out how to get the current timezone. If @code{struct tm} has a 2558@code{tm_zone} member, define @code{HAVE_TM_ZONE}. Otherwise, if the 2559external array @code{tzname} is found, define @code{HAVE_TZNAME}. 2560@end defmac 2561 2562@node Typedefs, C Compiler Characteristics, Structures, Existing Tests 2563@section Typedefs 2564 2565The following macros check for C typedefs. If there is no macro 2566specifically defined to check for a typedef you need, and you don't need 2567to check for any special properties of it, then you can use a general 2568typedef check macro. 2569 2570@menu 2571* Particular Typedefs:: Special handling to find certain types. 2572* Generic Typedefs:: How to find other types. 2573@end menu 2574 2575@node Particular Typedefs, Generic Typedefs, Typedefs, Typedefs 2576@subsection Particular Typedef Checks 2577 2578These macros check for particular C typedefs in @file{sys/types.h} and 2579@file{stdlib.h} (if it exists). 2580 2581@defmac AC_TYPE_GETGROUPS 2582@maindex TYPE_GETGROUPS 2583@cvindex GETGROUPS_T 2584Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} 2585is the base type of the array argument to @code{getgroups}. 2586@end defmac 2587 2588@defmac AC_TYPE_MODE_T 2589@maindex TYPE_MODE_T 2590@cvindex mode_t 2591If @code{mode_t} is not defined, define @code{mode_t} to be @code{int}. 2592@end defmac 2593 2594@defmac AC_TYPE_OFF_T 2595@maindex TYPE_OFF_T 2596@cvindex off_t 2597If @code{off_t} is not defined, define @code{off_t} to be @code{long}. 2598@end defmac 2599 2600@defmac AC_TYPE_PID_T 2601@maindex TYPE_PID_T 2602@cvindex pid_t 2603If @code{pid_t} is not defined, define @code{pid_t} to be @code{int}. 2604@end defmac 2605 2606@defmac AC_TYPE_SIGNAL 2607@maindex TYPE_SIGNAL 2608@cvindex RETSIGTYPE 2609If @file{signal.h} declares @code{signal} as returning a pointer to a 2610function returning @code{void}, define @code{RETSIGTYPE} to be 2611@code{void}; otherwise, define it to be @code{int}. 2612 2613Define signal handlers as returning type @code{RETSIGTYPE}: 2614 2615@example 2616@group 2617RETSIGTYPE 2618hup_handler () 2619@{ 2620@dots{} 2621@} 2622@end group 2623@end example 2624@end defmac 2625 2626@defmac AC_TYPE_SIZE_T 2627@maindex TYPE_SIZE_T 2628@cvindex size_t 2629If @code{size_t} is not defined, define @code{size_t} to be 2630@code{unsigned}. 2631@end defmac 2632 2633@defmac AC_TYPE_UID_T 2634@maindex TYPE_UID_T 2635@cvindex uid_t 2636@cvindex gid_t 2637If @code{uid_t} is not defined, define @code{uid_t} to be @code{int} and 2638@code{gid_t} to be @code{int}. 2639@end defmac 2640 2641@node Generic Typedefs, , Particular Typedefs, Typedefs 2642@subsection Generic Typedef Checks 2643 2644This macro is used to check for typedefs not covered by the particular 2645test macros. 2646 2647@defmac AC_CHECK_TYPE (@var{type}, @var{default}) 2648@maindex CHECK_TYPE 2649If the type @var{type} is not defined in @file{sys/types.h}, or 2650@file{stdlib.h} or @file{stddef.h} if they exist, define it to be the 2651C (or C++) builtin type @var{default}; e.g., @samp{short} or 2652@samp{unsigned}. 2653@end defmac 2654 2655@node C Compiler Characteristics, Fortran 77 Compiler Characteristics, Typedefs, Existing Tests 2656@section C Compiler Characteristics 2657 2658The following macros check for C compiler or machine architecture 2659features. To check for characteristics not listed here, use 2660@code{AC_TRY_COMPILE} (@pxref{Examining Syntax}) or @code{AC_TRY_RUN} 2661(@pxref{Run Time}) 2662 2663@defmac AC_C_BIGENDIAN 2664@maindex C_BIGENDIAN 2665@cvindex WORDS_BIGENDIAN 2666If words are stored with the most significant byte first (like Motorola 2667and SPARC, but not Intel and VAX, CPUs), define @code{WORDS_BIGENDIAN}. 2668@end defmac 2669 2670@defmac AC_C_CONST 2671@maindex C_CONST 2672@cvindex const 2673If the C compiler does not fully support the keyword @code{const}, 2674define @code{const} to be empty. Some C compilers that do not define 2675@code{__STDC__} do support @code{const}; some compilers that define 2676@code{__STDC__} do not completely support @code{const}. Programs can 2677simply use @code{const} as if every C compiler supported it; for those 2678that don't, the @file{Makefile} or configuration header file will define 2679it as empty. 2680@end defmac 2681 2682@defmac AC_C_INLINE 2683@maindex C_INLINE 2684@cvindex inline 2685If the C compiler supports the keyword @code{inline}, do nothing. 2686Otherwise define @code{inline} to @code{__inline__} or @code{__inline} 2687if it accepts one of those, otherwise define @code{inline} to be empty. 2688@end defmac 2689 2690@defmac AC_C_CHAR_UNSIGNED 2691@maindex C_CHAR_UNSIGNED 2692@cvindex __CHAR_UNSIGNED__ 2693If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, 2694unless the C compiler predefines it. 2695@end defmac 2696 2697@defmac AC_C_LONG_DOUBLE 2698@maindex C_LONG_DOUBLE 2699@cvindex HAVE_LONG_DOUBLE 2700If the C compiler supports the @code{long double} type, define 2701@code{HAVE_LONG_DOUBLE}. Some C compilers that do not define 2702@code{__STDC__} do support the @code{long double} type; some compilers 2703that define @code{__STDC__} do not support @code{long double}. 2704@end defmac 2705 2706@defmac AC_C_STRINGIZE 2707@maindex C_STRINGIZE 2708@cvindex HAVE_STRINGIZE 2709If the C preprocessor supports the stringizing operator, define 2710@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is 2711found in macros such as this: 2712 2713@example 2714#define x(y) #y 2715@end example 2716@end defmac 2717 2718@defmac AC_CHECK_SIZEOF (@var{type} @r{[}, @var{cross-size}@r{]}) 2719@maindex CHECK_SIZEOF 2720Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or 2721C++) builtin type @var{type}, e.g. @samp{int} or @samp{char *}. If 2722@samp{type} is unknown to the compiler, it gets a size of 0. @var{uctype} 2723is @var{type}, with lowercase converted to uppercase, spaces changed to 2724underscores, and asterisks changed to @samp{P}. If cross-compiling, the 2725value @var{cross-size} is used if given, otherwise @code{configure} 2726exits with an error message. 2727 2728For example, the call 2729@example 2730AC_CHECK_SIZEOF(int *) 2731@end example 2732@noindent 2733defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. 2734@end defmac 2735 2736@defmac AC_INT_16_BITS 2737@maindex INT_16_BITS 2738@cvindex INT_16_BITS 2739If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. 2740This macro is obsolete; it is more general to use 2741@samp{AC_CHECK_SIZEOF(int)} instead. 2742@end defmac 2743 2744@defmac AC_LONG_64_BITS 2745@maindex LONG_64_BITS 2746@cvindex LONG_64_BITS 2747If the C type @code{long int} is 64 bits wide, define 2748@code{LONG_64_BITS}. This macro is obsolete; it is more general to use 2749@samp{AC_CHECK_SIZEOF(long)} instead. 2750@end defmac 2751 2752 2753@node Fortran 77 Compiler Characteristics, System Services, C Compiler Characteristics, Existing Tests 2754@section Fortran 77 Compiler Characteristics 2755 2756The following macros check for Fortran 77 compiler characteristics. To 2757check for characteristics not listed here, use @code{AC_TRY_COMPILE} 2758(@pxref{Examining Syntax}) or @code{AC_TRY_RUN} (@pxref{Run Time}), 2759making sure to first set the current lanuage to Fortran 77 2760@code{AC_LANG_FORTRAN77} (@pxref{Language Choice}). 2761 2762@defmac AC_F77_LIBRARY_LDFLAGS 2763@maindex F77_LIBRARY_LDFLAGS 2764@ovindex FLIBS 2765Determine the linker flags (e.g. @samp{-L} and @samp{-l}) for the 2766@dfn{Fortran 77 intrinsic and run-time libraries} that are required to 2767successfully link a Fortran 77 program or shared library. The output 2768variable @code{FLIBS} is set to these flags. 2769 2770This macro is intended to be used in those situations when it is 2771necessary to mix, e.g. C++ and Fortran 77 source code into a single 2772program or shared library (@pxref{Mixing Fortran 77 With C and C++, , , 2773automake, GNU Automake}). 2774 2775For example, if object files from a C++ and Fortran 77 compiler must be 2776linked together, then the C++ compiler/linker must be used for linking 2777(since special C++-ish things need to happen at link time like calling 2778global constructors, instantiating templates, enabling exception 2779support, etc.). 2780 2781However, the Fortran 77 intrinsic and run-time libraries must be linked 2782in as well, but the C++ compiler/linker doesn't know by default how to 2783add these Fortran 77 libraries. Hence, the macro 2784@code{AC_F77_LIBRARY_LDFLAGS} was created to determine these Fortran 77 2785libraries. 2786@end defmac 2787 2788 2789@node System Services, UNIX Variants, Fortran 77 Compiler Characteristics, Existing Tests 2790@section System Services 2791 2792The following macros check for operating system services or capabilities. 2793 2794@defmac AC_CYGWIN 2795@maindex CYGWIN 2796Checks for the Cygwin environment. If present, sets shell variable 2797@code{CYGWIN} to @samp{yes}. If not present, sets @code{CYGWIN} 2798to the empty string. 2799@end defmac 2800 2801@defmac AC_EXEEXT 2802@maindex EXEEXT 2803@ovindex EXEEXT 2804Defines substitute variable @code{EXEEXT} based on the output of the 2805compiler, after .c, .o, and .obj files have been excluded. Typically 2806set to empty string if Unix, @samp{.exe} or @samp{.EXE} if Win32. 2807@end defmac 2808 2809@defmac AC_OBJEXT 2810@maindex OBJEXT 2811@ovindex OBJEXT 2812Defines substitute variable @code{OBJEXT} based on the output of the 2813compiler, after .c files have been excluded. Typically 2814set to @samp{.o} if Unix, @samp{.obj} if Win32. 2815@end defmac 2816 2817@defmac AC_MINGW32 2818@maindex MINGW32 2819Checks for the MingW32 compiler environment. If present, sets shell 2820variable @code{MINGW32} to @samp{yes}. If not present, sets 2821@code{MINGW32} to the empty string. 2822@end defmac 2823 2824@defmac AC_PATH_X 2825@maindex PATH_X 2826Try to locate the X Window System include files and libraries. If the 2827user gave the command line options @samp{--x-includes=@var{dir}} and 2828@samp{--x-libraries=@var{dir}}, use those directories. If either or 2829both were not given, get the missing values by running @code{xmkmf} on a 2830trivial @file{Imakefile} and examining the @file{Makefile} that it 2831produces. If that fails (such as if @code{xmkmf} is not present), look 2832for them in several directories where they often reside. If either 2833method is successful, set the shell variables @code{x_includes} and 2834@code{x_libraries} to their locations, unless they are in directories 2835the compiler searches by default. 2836 2837If both methods fail, or the user gave the command line option 2838@samp{--without-x}, set the shell variable @code{no_x} to @samp{yes}; 2839otherwise set it to the empty string. 2840@end defmac 2841 2842@defmac AC_PATH_XTRA 2843@maindex PATH_XTRA 2844@ovindex X_CFLAGS 2845@ovindex X_LIBS 2846@ovindex X_EXTRA_LIBS 2847@ovindex X_PRE_LIBS 2848An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags that 2849X needs to output variable @code{X_CFLAGS}, and the X linker flags to 2850@code{X_LIBS}. If X is not available, adds @samp{-DX_DISPLAY_MISSING} to 2851@code{X_CFLAGS}. 2852 2853This macro also checks for special libraries that some systems need in 2854order to compile X programs. It adds any that the system needs to 2855output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 2856libraries that need to be linked with before @samp{-lX11}, and adds any 2857found to the output variable @code{X_PRE_LIBS}. 2858 2859@c This is an incomplete kludge. Make a real way to do it. 2860@c If you need to check for other X functions or libraries yourself, then 2861@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to 2862@c @code{LIBS} temporarily, like this: (FIXME - add example) 2863@end defmac 2864 2865@defmac AC_SYS_INTERPRETER 2866@maindex SYS_INTERPRETER 2867Check whether the system supports starting scripts with a line of the 2868form @samp{#! /bin/csh} to select the interpreter to use for the script. 2869After running this macro, shell code in @code{configure.in} can check 2870the shell variable @code{interpval}; it will be set to @samp{yes} 2871if the system supports @samp{#!}, @samp{no} if not. 2872@end defmac 2873 2874@defmac AC_SYS_LONG_FILE_NAMES 2875@maindex SYS_LONG_FILE_NAMES 2876@cvindex HAVE_LONG_FILE_NAMES 2877If the system supports file names longer than 14 characters, define 2878@code{HAVE_LONG_FILE_NAMES}. 2879@end defmac 2880 2881@defmac AC_SYS_RESTARTABLE_SYSCALLS 2882@maindex SYS_RESTARTABLE_SYSCALLS 2883@cvindex HAVE_RESTARTABLE_SYSCALLS 2884If the system automatically restarts a system call that is interrupted 2885by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. 2886@end defmac 2887 2888@node UNIX Variants, , System Services, Existing Tests 2889@section UNIX Variants 2890 2891The following macros check for certain operating systems that need 2892special treatment for some programs, due to exceptional oddities in 2893their header files or libraries. These macros are warts; they will be 2894replaced by a more systematic approach, based on the functions they make 2895available or the environments they provide. 2896 2897@defmac AC_AIX 2898@maindex AIX 2899@cvindex _ALL_SOURCE 2900If on AIX, define @code{_ALL_SOURCE}. Allows the use of some BSD 2901functions. Should be called before any macros that run the C compiler. 2902@end defmac 2903 2904@defmac AC_DYNIX_SEQ 2905@maindex DYNIX_SEQ 2906If on Dynix/PTX (Sequent UNIX), add @samp{-lseq} to output 2907variable @code{LIBS}. This macro is obsolete; instead, use 2908@code{AC_FUNC_GETMNTENT}. 2909@end defmac 2910 2911@defmac AC_IRIX_SUN 2912@maindex IRIX_SUN 2913If on IRIX (Silicon Graphics UNIX), add @samp{-lsun} to output variable 2914@code{LIBS}. This macro is obsolete. If you were using it to get 2915@code{getmntent}, use @code{AC_FUNC_GETMNTENT} instead. If you used it 2916for the NIS versions of the password and group functions, use 2917@samp{AC_CHECK_LIB(sun, getpwnam)}. 2918@end defmac 2919 2920@defmac AC_ISC_POSIX 2921@maindex ISC_POSIX 2922@cvindex _POSIX_SOURCE 2923@ovindex CC 2924If on a POSIXized ISC UNIX, define @code{_POSIX_SOURCE} and add 2925@samp{-posix} (for the GNU C compiler) or @samp{-Xp} (for other C 2926compilers) to output variable @code{CC}. This allows the use of 2927POSIX facilities. Must be called after @code{AC_PROG_CC} and before 2928any other macros that run the C compiler. 2929@end defmac 2930 2931@defmac AC_MINIX 2932@maindex MINIX 2933@cvindex _MINIX 2934@cvindex _POSIX_SOURCE 2935@cvindex _POSIX_1_SOURCE 2936If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define 2937@code{_POSIX_1_SOURCE} to be 2. This allows the use of POSIX 2938facilities. Should be called before any macros that run the C compiler. 2939@end defmac 2940 2941@defmac AC_SCO_INTL 2942@maindex SCO_INTL 2943@ovindex LIBS 2944If on SCO UNIX, add @samp{-lintl} to output variable @code{LIBS}. 2945This macro is obsolete; instead, use @code{AC_FUNC_STRFTIME}. 2946@end defmac 2947 2948@defmac AC_XENIX_DIR 2949@maindex XENIX_DIR 2950@ovindex LIBS 2951If on Xenix, add @samp{-lx} to output variable @code{LIBS}. Also, if 2952@file{dirent.h} is being used, add @samp{-ldir} to @code{LIBS}. This 2953macro is obsolete; use @code{AC_HEADER_DIRENT} instead. 2954@end defmac 2955 2956@node Writing Tests, Results, Existing Tests, Top 2957@chapter Writing Tests 2958 2959If the existing feature tests don't do something you need, you have to 2960write new ones. These macros are the building blocks. They provide 2961ways for other macros to check whether various kinds of features are 2962available and report the results. 2963 2964This chapter contains some suggestions and some of the reasons why the 2965existing tests are written the way they are. You can also learn a lot 2966about how to write Autoconf tests by looking at the existing ones. If 2967something goes wrong in one or more of the Autoconf tests, this 2968information can help you understand the assumptions behind them, which 2969might help you figure out how to best solve the problem. 2970 2971These macros check the output of the C compiler system. They do 2972not cache the results of their tests for future use (@pxref{Caching 2973Results}), because they don't know enough about the information they are 2974checking for to generate a cache variable name. They also do not print 2975any messages, for the same reason. The checks for particular kinds of C 2976features call these macros and do cache their results and print messages 2977about what they're checking for. 2978 2979When you write a feature test that could be applicable to more than one 2980software package, the best thing to do is encapsulate it in a new macro. 2981@xref{Writing Macros}, for how to do that. 2982 2983@menu 2984* Examining Declarations:: Detecting header files and declarations. 2985* Examining Syntax:: Detecting language syntax features. 2986* Examining Libraries:: Detecting functions and global variables. 2987* Run Time:: Testing for run-time features. 2988* Portable Shell:: Shell script portability pitfalls. 2989* Testing Values and Files:: Checking strings and files. 2990* Multiple Cases:: Tests for several possible values. 2991* Language Choice:: Selecting which language to use for testing. 2992@end menu 2993 2994@node Examining Declarations, Examining Syntax, Writing Tests, Writing Tests 2995@section Examining Declarations 2996 2997The macro @code{AC_TRY_CPP} is used to check whether particular header 2998files exist. You can check for one at a time, or more than one if you 2999need several header files to all exist for some purpose. 3000 3001@defmac AC_TRY_CPP (@var{includes}, @r{[}@var{action-if-true} @r{[}, @var{action-if-false}@r{]]}) 3002@maindex TRY_CPP 3003@var{includes} is C or C++ @code{#include} statements and declarations, 3004on which shell variable, backquote, and backslash substitutions are 3005performed. (Actually, it can be any C program, but other statements are 3006probably not useful.) If the preprocessor produces no error messages 3007while processing it, run shell commands @var{action-if-true}. Otherwise 3008run shell commands @var{action-if-false}. 3009 3010This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because 3011@samp{-g}, @samp{-O}, etc. are not valid options to many C 3012preprocessors. 3013@end defmac 3014 3015Here is how to find out whether a header file contains a particular 3016declaration, such as a typedef, a structure, a structure member, or a 3017function. Use @code{AC_EGREP_HEADER} instead of running @code{grep} 3018directly on the header file; on some systems the symbol might be defined 3019in another header file that the file you are checking @samp{#include}s. 3020 3021@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) 3022@maindex EGREP_HEADER 3023If the output of running the preprocessor on the system header file 3024@var{header-file} matches the @code{egrep} regular expression 3025@var{pattern}, execute shell commands @var{action-if-found}, otherwise 3026execute @var{action-if-not-found}. 3027@end defmac 3028 3029To check for C preprocessor symbols, either defined by header files or 3030predefined by the C preprocessor, use @code{AC_EGREP_CPP}. Here is an 3031example of the latter: 3032 3033@example 3034AC_EGREP_CPP(yes, 3035[#ifdef _AIX 3036 yes 3037#endif 3038], is_aix=yes, is_aix=no) 3039@end example 3040 3041@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 3042@maindex EGREP_CPP 3043@var{program} is the text of a C or C++ program, on which shell 3044variable, backquote, and backslash substitutions are performed. If the 3045output of running the preprocessor on @var{program} matches the 3046@code{egrep} regular expression @var{pattern}, execute shell commands 3047@var{action-if-found}, otherwise execute @var{action-if-not-found}. 3048 3049This macro calls @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP} (depending 3050on which language is current, @pxref{Language Choice}), if it hasn't 3051been called already. 3052@end defmac 3053 3054@node Examining Syntax, Examining Libraries, Examining Declarations, Writing Tests 3055@section Examining Syntax 3056 3057To check for a syntax feature of the C, C++ or Fortran 77 compiler, such 3058as whether it recognizes a certain keyword, use @code{AC_TRY_COMPILE} to 3059try to compile a small program that uses that feature. You can also use 3060it to check for structures and structure members that are not present on 3061all systems. 3062 3063@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 3064@maindex TRY_COMPILE 3065Create a C, C++ or Fortran 77 test program (depending on which language 3066is current, @pxref{Language Choice}), to see whether a function whose 3067body consists of @var{function-body} can be compiled. 3068 3069For C and C++, @var{includes} is any @code{#include} statements needed 3070by the code in @var{function-body} (@var{includes} will be ignored if 3071the currently selected language is Fortran 77). This macro also uses 3072@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently 3073selected language, as well as @code{CPPFLAGS}, when compiling. If 3074Fortran 77 is the currently selected language then @code{FFLAGS} will be 3075used when compiling. 3076 3077If the file compiles successfully, run shell commands 3078@var{action-if-found}, otherwise run @var{action-if-not-found}. 3079 3080This macro does not try to link; use @code{AC_TRY_LINK} if you need to 3081do that (@pxref{Examining Libraries}). 3082@end defmac 3083 3084@node Examining Libraries, Run Time, Examining Syntax, Writing Tests 3085@section Examining Libraries 3086 3087To check for a library, a function, or a global variable, Autoconf 3088@code{configure} scripts try to compile and link a small program that 3089uses it. This is unlike Metaconfig, which by default uses @code{nm} 3090or @code{ar} on the C library to try to figure out which functions are 3091available. Trying to link with the function is usually a more reliable 3092approach because it avoids dealing with the variations in the options 3093and output formats of @code{nm} and @code{ar} and in the location of the 3094standard libraries. It also allows configuring for cross-compilation or 3095checking a function's runtime behavior if needed. On the other hand, it 3096can be slower than scanning the libraries once. 3097 3098A few systems have linkers that do not return a failure exit status when 3099there are unresolved functions in the link. This bug makes the 3100configuration scripts produced by Autoconf unusable on those systems. 3101However, some of them can be given options that make the exit status 3102correct. This is a problem that Autoconf does not currently handle 3103automatically. If users encounter this problem, they might be able to 3104solve it by setting @code{LDFLAGS} in the environment to pass whatever 3105options the linker needs (for example, @samp{-Wl,-dn} on MIPS RISC/OS). 3106 3107@code{AC_TRY_LINK} is used to compile test programs to test for 3108functions and global variables. It is also used by @code{AC_CHECK_LIB} 3109to check for libraries (@pxref{Libraries}), by adding the library being 3110checked for to @code{LIBS} temporarily and trying to link a small 3111program. 3112 3113@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 3114@maindex TRY_LINK 3115Depending on the current language (@pxref{Language Choice}), create a 3116test program to see whether a function whose body consists of 3117@var{function-body} can be compiled and linked. 3118 3119For C and C++, @var{includes} is any @code{#include} statements needed 3120by the code in @var{function-body} (@var{includes} will be ignored if 3121the currently selected language is Fortran 77). This macro also uses 3122@code{CFLAGS} or @code{CXXFLAGS} if either C or C++ is the currently 3123selected language, as well as @code{CPPFLAGS}, when compiling. If 3124Fortran 77 is the currently selected language then @code{FFLAGS} will be 3125used when compiling. However, both @code{LDFLAGS} and @code{LIBS} will 3126be used during linking in all cases. 3127 3128If the file compiles and links successfully, run shell commands 3129@var{action-if-found}, otherwise run @var{action-if-not-found}. 3130@end defmac 3131 3132@defmac AC_TRY_LINK_FUNC (@var{function}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 3133@maindex TRY_LINK_FUNC 3134Depending on the current language (@pxref{Language Choice}), create a 3135test program to see whether a program whose body consists of 3136a prototype of and a call to @var{function} can be compiled and linked. 3137 3138If the file compiles and links successfully, run shell commands 3139@var{action-if-found}, otherwise run @var{action-if-not-found}. 3140@end defmac 3141 3142@defmac AC_TRY_LINK_FUNC (@var{function}, @r{[}@var{action-if-found} @r{[}, @var{action-if-not-found}@r{]]}) 3143@maindex TRY_LINK_FUNC 3144Attempt to compile and link a small program that links with 3145@var{function}. If the file compiles and links successfully, 3146run shell commands @var{action-if-found}, otherwise run 3147@var{action-if-not-found}. 3148@end defmac 3149 3150@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-found} @r{[}, @var{action-if-not-found}@r{]}) 3151@maindex COMPILE_CHECK 3152This is an obsolete version of @code{AC_TRY_LINK}, with the addition 3153that it prints @samp{checking for @var{echo-text}} to the standard 3154output first, if @var{echo-text} is non-empty. Use 3155@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print 3156messages (@pxref{Printing Messages}). 3157@end defmac 3158 3159@node Run Time, Portable Shell, Examining Libraries, Writing Tests 3160@section Checking Run Time Behavior 3161 3162Sometimes you need to find out how a system performs at run time, such 3163as whether a given function has a certain capability or bug. If you 3164can, make such checks when your program runs instead of when it is 3165configured. You can check for things like the machine's endianness when 3166your program initializes itself. 3167 3168If you really need to test for a run-time behavior while configuring, 3169you can write a test program to determine the result, and compile and 3170run it using @code{AC_TRY_RUN}. Avoid running test programs if 3171possible, because using them prevents people from configuring your 3172package for cross-compiling. 3173 3174@menu 3175* Test Programs:: Running test programs. 3176* Guidelines:: General rules for writing test programs. 3177* Test Functions:: Avoiding pitfalls in test programs. 3178@end menu 3179 3180@node Test Programs, Guidelines, Run Time, Run Time 3181@subsection Running Test Programs 3182 3183Use the following macro if you need to test run-time behavior of the 3184system while configuring. 3185 3186@defmac AC_TRY_RUN (@var{program}, @r{[}@var{action-if-true} @r{[}, @var{action-if-false} @r{[}, @var{action-if-cross-compiling}@r{]]]}) 3187@maindex TRY_RUN 3188@var{program} is the text of a C program, on which shell variable and 3189backquote substitutions are performed. If it compiles and links 3190successfully and returns an exit status of 0 when executed, run shell 3191commands @var{action-if-true}. Otherwise run shell commands 3192@var{action-if-false}; the exit status of the program is available in 3193the shell variable @samp{$?}. This macro uses @code{CFLAGS} or 3194@code{CXXFLAGS}, @code{CPPFLAGS}, @code{LDFLAGS}, and @code{LIBS} when 3195compiling. 3196 3197If the C compiler being used does not produce executables that run on 3198the system where @code{configure} is being run, then the test program is 3199not run. If the optional shell commands @var{action-if-cross-compiling} 3200are given, they are run instead. Otherwise, @code{configure} prints 3201an error message and exits. 3202@end defmac 3203 3204Try to provide a pessimistic default value to use when cross-compiling 3205makes run-time tests impossible. You do this by passing the optional 3206last argument to @code{AC_TRY_RUN}. @code{autoconf} prints a warning 3207message when creating @code{configure} each time it encounters a call to 3208@code{AC_TRY_RUN} with no @var{action-if-cross-compiling} argument 3209given. You may ignore the warning, though users will not be able to 3210configure your package for cross-compiling. A few of the macros 3211distributed with Autoconf produce this warning message. 3212 3213To configure for cross-compiling you can also choose a value for those 3214parameters based on the canonical system name (@pxref{Manual 3215Configuration}). Alternatively, set up a test results cache file with 3216the correct values for the target system (@pxref{Caching Results}). 3217 3218To provide a default for calls of @code{AC_TRY_RUN} that are embedded in 3219other macros, including a few of the ones that come with Autoconf, you 3220can call @code{AC_PROG_CC} before running them. Then, if the shell 3221variable @code{cross_compiling} is set to @samp{yes}, use an alternate 3222method to get the results instead of calling the macros. 3223 3224@defmac AC_C_CROSS 3225@maindex C_CROSS 3226This macro is obsolete; it does nothing. 3227@end defmac 3228 3229@node Guidelines, Test Functions, Test Programs, Run Time 3230@subsection Guidelines for Test Programs 3231 3232Test programs should not write anything to the standard output. They 3233should return 0 if the test succeeds, nonzero otherwise, so that success 3234can be distinguished easily from a core dump or other failure; 3235segmentation violations and other failures produce a nonzero exit 3236status. Test programs should @code{exit}, not @code{return}, from 3237@code{main}, because on some systems (old Suns, at least) the argument 3238to @code{return} in @code{main} is ignored. 3239 3240Test programs can use @code{#if} or @code{#ifdef} to check the values of 3241preprocessor macros defined by tests that have already run. For 3242example, if you call @code{AC_HEADER_STDC}, then later on in 3243@file{configure.in} you can have a test program that includes an ANSI C 3244header file conditionally: 3245 3246@example 3247@group 3248#if STDC_HEADERS 3249# include <stdlib.h> 3250#endif 3251@end group 3252@end example 3253 3254If a test program needs to use or create a data file, give it a name 3255that starts with @file{conftest}, such as @file{conftestdata}. The 3256@code{configure} script cleans up by running @samp{rm -rf conftest*} 3257after running test programs and if the script is interrupted. 3258 3259@node Test Functions, , Guidelines, Run Time 3260@subsection Test Functions 3261 3262Function declarations in test programs should have a prototype 3263conditionalized for C++. In practice, though, test programs rarely need 3264functions that take arguments. 3265 3266@example 3267#ifdef __cplusplus 3268foo(int i) 3269#else 3270foo(i) int i; 3271#endif 3272@end example 3273 3274Functions that test programs declare should also be conditionalized for 3275C++, which requires @samp{extern "C"} prototypes. Make sure to not 3276include any header files containing clashing prototypes. 3277 3278@example 3279#ifdef __cplusplus 3280extern "C" void *malloc(size_t); 3281#else 3282char *malloc(); 3283#endif 3284@end example 3285 3286If a test program calls a function with invalid parameters (just to see 3287whether it exists), organize the program to ensure that it never invokes 3288that function. You can do this by calling it in another function that is 3289never invoked. You can't do it by putting it after a call to 3290@code{exit}, because GCC version 2 knows that @code{exit} never returns 3291and optimizes out any code that follows it in the same block. 3292 3293If you include any header files, make sure to call the functions 3294relevant to them with the correct number of arguments, even if they are 3295just 0, to avoid compilation errors due to prototypes. GCC version 2 3296has internal prototypes for several functions that it automatically 3297inlines; for example, @code{memcpy}. To avoid errors when checking for 3298them, either pass them the correct number of arguments or redeclare them 3299with a different return type (such as @code{char}). 3300 3301@node Portable Shell, Testing Values and Files, Run Time, Writing Tests 3302@section Portable Shell Programming 3303 3304When writing your own checks, there are some shell script programming 3305techniques you should avoid in order to make your code portable. The 3306Bourne shell and upward-compatible shells like Bash and the Korn shell 3307have evolved over the years, but to prevent trouble, do not take 3308advantage of features that were added after UNIX version 7, circa 1977. 3309You should not use shell functions, aliases, negated character classes, 3310or other features that are not found in all Bourne-compatible shells; 3311restrict yourself to the lowest common denominator. Even @code{unset} 3312is not supported by all shells! Also, include a space after the 3313exclamation point in interpreter specifications, like this: 3314@example 3315#! /usr/bin/perl 3316@end example 3317If you omit the space before the path, then 4.2BSD based systems (such 3318as Sequent DYNIX) will ignore the line, because they interpret @samp{#! /} 3319as a 4-byte magic number. 3320 3321The set of external programs you should run in a @code{configure} script 3322is fairly small. @xref{Utilities in Makefiles, , Utilities in 3323Makefiles, standards, GNU Coding Standards}, for the list. This 3324restriction allows users to start out with a fairly small set of 3325programs and build the rest, avoiding too many interdependencies between 3326packages. 3327 3328Some of these external utilities have a portable subset of features, as 3329well; for example, don't rely on @code{ln} having a @samp{-f} option or 3330@code{cat} having any options. @code{sed} scripts should not contain 3331comments or use branch labels longer than 8 characters. Don't use 3332@samp{grep -s} to suppress output, because @samp{grep -s} on System V 3333does not suppress output, only error messages. Instead, redirect the 3334standard output and standard error (in case the file doesn't exist) of 3335@code{grep} to @file{/dev/null}. Check the exit status of @code{grep} 3336to determine whether it found a match. 3337 3338@node Testing Values and Files, Multiple Cases, Portable Shell, Writing Tests 3339@section Testing Values and Files 3340 3341@code{configure} scripts need to test properties of many files and 3342strings. Here are some portability problems to watch out for when doing 3343those tests. 3344 3345The @code{test} program is the way to perform many file and string 3346tests. It is often invoked by the alternate name @samp{[}, but using 3347that name in Autoconf code is asking for trouble since it is an 3348@code{m4} quote character. 3349 3350If you need to make multiple checks using @code{test}, combine 3351them with the shell operators @samp{&&} and @samp{||} instead of using 3352the @code{test} operators @samp{-a} and @samp{-o}. On System V, the 3353precedence of @samp{-a} and @samp{-o} is wrong relative to the unary 3354operators; consequently, POSIX does not specify them, so using them is 3355nonportable. If you combine @samp{&&} and @samp{||} in the same 3356statement, keep in mind that they have equal precedence. 3357 3358To enable @code{configure} scripts to support cross-compilation, they 3359shouldn't do anything that tests features of the host system instead of 3360the target system. But occasionally you may find it necessary to check 3361whether some arbitrary file exists. To do so, use @samp{test -f} or 3362@samp{test -r}. Do not use @samp{test -x}, because 4.3BSD does not have 3363it. 3364 3365Another nonportable shell programming construction is 3366@example 3367@var{var}=$@{@var{var}:-@var{value}@} 3368@end example 3369@noindent 3370The intent is to set @var{var} to @var{value} only if it is not already 3371set, but if @var{var} has any value, even the empty string, to leave it 3372alone. Old BSD shells, including the Ultrix @code{sh}, don't accept 3373the colon, and complain and die. A portable equivalent is 3374@example 3375: $@{@var{var}=@var{value}@} 3376@end example 3377 3378@node Multiple Cases, Language Choice, Testing Values and Files, Writing Tests 3379@section Multiple Cases 3380 3381Some operations are accomplished in several possible ways, depending on 3382the UNIX variant. Checking for them essentially requires a ``case 3383statement''. Autoconf does not directly provide one; however, it is 3384easy to simulate by using a shell variable to keep track of whether a 3385way to perform the operation has been found yet. 3386 3387Here is an example that uses the shell variable @code{fstype} to keep 3388track of whether the remaining cases need to be checked. 3389 3390@example 3391@group 3392AC_MSG_CHECKING(how to get filesystem type) 3393fstype=no 3394# The order of these tests is important. 3395AC_TRY_CPP([#include <sys/statvfs.h> 3396#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_STATVFS) fstype=SVR4) 3397if test $fstype = no; then 3398AC_TRY_CPP([#include <sys/statfs.h> 3399#include <sys/fstyp.h>], AC_DEFINE(FSTYPE_USG_STATFS) fstype=SVR3) 3400fi 3401if test $fstype = no; then 3402AC_TRY_CPP([#include <sys/statfs.h> 3403#include <sys/vmount.h>], AC_DEFINE(FSTYPE_AIX_STATFS) fstype=AIX) 3404fi 3405# (more cases omitted here) 3406AC_MSG_RESULT($fstype) 3407@end group 3408@end example 3409 3410@node Language Choice, , Multiple Cases, Writing Tests 3411@section Language Choice 3412 3413Packages that use both C and C++ need to test features of both 3414compilers. Autoconf-generated @code{configure} scripts check for C 3415features by default. The following macros determine which language's 3416compiler is used in tests that follow in @file{configure.in}. 3417 3418@defmac AC_LANG_C 3419@maindex LANG_C 3420Do compilation tests using @code{CC} and @code{CPP} and use extension 3421@file{.c} for test programs. Set the shell variable 3422@code{cross_compiling} to the value computed by @code{AC_PROG_CC} if it 3423has been run, empty otherwise. 3424@end defmac 3425 3426@defmac AC_LANG_CPLUSPLUS 3427@maindex LANG_CPLUSPLUS 3428Do compilation tests using @code{CXX} and @code{CXXCPP} and use 3429extension @file{.C} for test programs. Set the shell variable 3430@code{cross_compiling} to the value computed by @code{AC_PROG_CXX} if 3431it has been run, empty otherwise. 3432@end defmac 3433 3434@defmac AC_LANG_FORTRAN77 3435@maindex LANG_FORTRAN77 3436Do compilation tests using @code{F77} and use extension @file{.f} for 3437test programs. Set the shell variable @code{cross_compiling} to the 3438value computed by @code{AC_PROG_F77} if it has been run, empty 3439otherwise. 3440@end defmac 3441 3442@defmac AC_LANG_SAVE 3443@maindex LANG_SAVE 3444Remember the current language (as set by @code{AC_LANG_C}, 3445@code{AC_LANG_CPLUSPLUS} or @code{AC_LANG_FORTRAN77}) on a stack. Does 3446not change which language is current. Use this macro and 3447@code{AC_LANG_RESTORE} in macros that need to temporarily switch to a 3448particular language. 3449@end defmac 3450 3451@defmac AC_LANG_RESTORE 3452@maindex LANG_RESTORE 3453Select the language that is saved on the top of the stack, as set by 3454@code{AC_LANG_SAVE}, and remove it from the stack. This macro is 3455equivalent to either @code{AC_LANG_C}, @code{AC_LANG_CPLUSPLUS} or 3456@code{AC_LANG_FORTRAN77}, whichever had been run most recently when 3457@code{AC_LANG_SAVE} was last called. 3458 3459Do not call this macro more times than @code{AC_LANG_SAVE}. 3460@end defmac 3461 3462@defmac AC_REQUIRE_CPP 3463@maindex REQUIRE_CPP 3464Ensure that whichever preprocessor would currently be used for tests has 3465been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an 3466argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, 3467depending on which language is current. 3468@end defmac 3469 3470@node Results, Writing Macros, Writing Tests, Top 3471@chapter Results of Tests 3472 3473Once @code{configure} has determined whether a feature exists, what can 3474it do to record that information? There are four sorts of things it can 3475do: define a C preprocessor symbol, set a variable in the output files, 3476save the result in a cache file for future @code{configure} runs, and 3477print a message letting the user know the result of the test. 3478 3479@menu 3480* Defining Symbols:: Defining C preprocessor symbols. 3481* Setting Output Variables:: Replacing variables in output files. 3482* Caching Results:: Speeding up subsequent @code{configure} runs. 3483* Printing Messages:: Notifying users of progress or problems. 3484@end menu 3485 3486@node Defining Symbols, Setting Output Variables, Results, Results 3487@section Defining C Preprocessor Symbols 3488 3489A common action to take in response to a feature test is to define a C 3490preprocessor symbol indicating the results of the test. That is done by 3491calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. 3492 3493By default, @code{AC_OUTPUT} places the symbols defined by these macros 3494into the output variable @code{DEFS}, which contains an option 3495@samp{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in 3496Autoconf version 1, there is no variable @code{DEFS} defined while 3497@code{configure} is running. To check whether Autoconf macros have 3498already defined a certain C preprocessor symbol, test the value of the 3499appropriate cache variable, as in this example: 3500 3501@example 3502AC_CHECK_FUNC(vprintf, AC_DEFINE(HAVE_VPRINTF)) 3503if test "$ac_cv_func_vprintf" != yes; then 3504AC_CHECK_FUNC(_doprnt, AC_DEFINE(HAVE_DOPRNT)) 3505fi 3506@end example 3507 3508If @code{AC_CONFIG_HEADER} has been called, then instead of creating 3509@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the 3510correct values into @code{#define} statements in a template file. 3511@xref{Configuration Headers}, for more information about this kind of 3512output. 3513 3514@defmac AC_DEFINE (@var{variable} @r{[}, @var{value} @r{[}, @var{description}@r{]}@r{]}) 3515@maindex DEFINE 3516Define C preprocessor variable @var{variable}. If @var{value} is given, 3517set @var{variable} to that value (verbatim), otherwise set it to 1. 3518@var{value} should not contain literal newlines, and if you are not 3519using @code{AC_CONFIG_HEADER} it should not contain any @samp{#} 3520characters, as @code{make} tends to eat them. To use a shell variable 3521(which you need to do in order to define a value containing the 3522@code{m4} quote characters @samp{[} or @samp{]}), use 3523@code{AC_DEFINE_UNQUOTED} instead. @var{description} is only useful if 3524you are using @code{AC_CONFIG_HEADER}. In this case, @var{description} 3525is put into the generated @file{config.h.in} as the comment before the 3526macro define; the macro need not be mentioned in @file{acconfig.h}. The 3527following example defines the C preprocessor variable @code{EQUATION} to 3528be the string constant @samp{"$a > $b"}: 3529 3530@example 3531AC_DEFINE(EQUATION, "$a > $b") 3532@end example 3533@end defmac 3534 3535@defmac AC_DEFINE_UNQUOTED (@var{variable} @r{[}, @var{value} @r{[}, @var{description}@r{]}@r{]}) 3536@maindex DEFINE_UNQUOTED 3537Like @code{AC_DEFINE}, but three shell expansions are 3538performed---once---on @var{variable} and @var{value}: variable expansion 3539(@samp{$}), command substitution (@samp{`}), and backslash escaping 3540(@samp{\}). Single and double quote characters in the value have no 3541special meaning. Use this macro instead of @code{AC_DEFINE} when 3542@var{variable} or @var{value} is a shell variable. Examples: 3543 3544@example 3545AC_DEFINE_UNQUOTED(config_machfile, "$@{machfile@}") 3546AC_DEFINE_UNQUOTED(GETGROUPS_T, $ac_cv_type_getgroups) 3547AC_DEFINE_UNQUOTED($@{ac_tr_hdr@}) 3548@end example 3549@end defmac 3550 3551Due to the syntactical bizarreness of the Bourne shell, do not use 3552semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} 3553calls from other macro calls or shell code; that can cause syntax errors 3554in the resulting @code{configure} script. Use either spaces or 3555newlines. That is, do this: 3556 3557@example 3558AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4) LIBS="$LIBS -lelf") 3559@end example 3560 3561@noindent 3562or this: 3563 3564@example 3565AC_CHECK_HEADER(elf.h, 3566 AC_DEFINE(SVR4) 3567 LIBS="$LIBS -lelf") 3568@end example 3569 3570@noindent 3571instead of this: 3572 3573@example 3574AC_CHECK_HEADER(elf.h, AC_DEFINE(SVR4); LIBS="$LIBS -lelf") 3575@end example 3576 3577@node Setting Output Variables, Caching Results, Defining Symbols, Results 3578@section Setting Output Variables 3579 3580One way to record the results of tests is to set @dfn{output variables}, 3581which are shell variables whose values are substituted into files that 3582@code{configure} outputs. The two macros below create new output 3583variables. @xref{Preset Output Variables}, for a list of output 3584variables that are always available. 3585 3586@defmac AC_SUBST (@var{variable}) 3587@maindex SUBST 3588Create an output variable from a shell variable. Make @code{AC_OUTPUT} 3589substitute the variable @var{variable} into output files (typically one 3590or more @file{Makefile}s). This means that @code{AC_OUTPUT} will 3591replace instances of @samp{@@@var{variable}@@} in input files with the 3592value that the shell variable @var{variable} has when @code{AC_OUTPUT} 3593is called. The value of @var{variable} should not contain literal 3594newlines. 3595@end defmac 3596 3597@defmac AC_SUBST_FILE (@var{variable}) 3598@maindex SUBST_FILE 3599Another way to create an output variable from a shell variable. Make 3600@code{AC_OUTPUT} insert (without substitutions) the contents of the file 3601named by shell variable @var{variable} into output files. This means 3602that @code{AC_OUTPUT} will replace instances of 3603@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) 3604with the contents of the file that the shell variable @var{variable} 3605names when @code{AC_OUTPUT} is called. Set the variable to 3606@file{/dev/null} for cases that do not have a file to insert. 3607 3608This macro is useful for inserting @file{Makefile} fragments containing 3609special dependencies or other @code{make} directives for particular host 3610or target types into @file{Makefile}s. For example, @file{configure.in} 3611could contain: 3612 3613@example 3614AC_SUBST_FILE(host_frag)dnl 3615host_frag=$srcdir/conf/sun4.mh 3616@end example 3617 3618@noindent 3619and then a @file{Makefile.in} could contain: 3620 3621@example 3622@@host_frag@@ 3623@end example 3624@end defmac 3625 3626@node Caching Results, Printing Messages, Setting Output Variables, Results 3627@section Caching Results 3628 3629To avoid checking for the same features repeatedly in various 3630@code{configure} scripts (or repeated runs of one script), 3631@code{configure} saves the results of many of its checks in a @dfn{cache 3632file}. If, when a @code{configure} script runs, it finds a cache file, 3633it reads from it the results from previous runs and avoids rerunning 3634those checks. As a result, @code{configure} can run much faster than if 3635it had to perform all of the checks every time. 3636 3637@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) 3638@maindex CACHE_VAL 3639Ensure that the results of the check identified by @var{cache-id} are 3640available. If the results of the check were in the cache file that was 3641read, and @code{configure} was not given the @samp{--quiet} or 3642@samp{--silent} option, print a message saying that the result was 3643cached; otherwise, run the shell commands @var{commands-to-set-it}. 3644Those commands should have no side effects except for setting the 3645variable @var{cache-id}. In particular, they should not call 3646@code{AC_DEFINE}; the code that follows the call to @code{AC_CACHE_VAL} 3647should do that, based on the cached value. Also, they should not print 3648any messages, for example with @code{AC_MSG_CHECKING}; do that before 3649calling @code{AC_CACHE_VAL}, so the messages are printed regardless of 3650whether the results of the check are retrieved from the cache or 3651determined by running the shell commands. If the shell commands are run 3652to determine the value, the value will be saved in the cache file just 3653before @code{configure} creates its output files. @xref{Cache 3654Variable Names}, for how to choose the name of the @var{cache-id} variable. 3655@end defmac 3656 3657@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands}) 3658@maindex CACHE_CHECK 3659A wrapper for @code{AC_CACHE_VAL} that takes care of printing the 3660messages. This macro provides a convenient shorthand for the most 3661common way to use these macros. It calls @code{AC_MSG_CHECKING} for 3662@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and 3663@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. 3664@end defmac 3665 3666@defmac AC_CACHE_LOAD 3667@maindex CACHE_LOAD 3668Loads values from existing cache file, or creates a new cache file if 3669a cache file is not found. Called automatically from @code{AC_INIT}. 3670@end defmac 3671 3672@defmac AC_CACHE_SAVE 3673@maindex CACHE_SAVE 3674Flushes all cached values to the cache file. Called automatically 3675from @code{AC_OUTPUT}, but it can be quite useful to call 3676@code{AC_CACHE_SAVE} at key points in configure.in. Doing so 3677checkpoints the cache in case of an early configure script abort. 3678@end defmac 3679 3680@menu 3681* Cache Variable Names:: Shell variables used in caches. 3682* Cache Files:: Files @code{configure} uses for caching. 3683@end menu 3684 3685@node Cache Variable Names, Cache Files, Caching Results, Caching Results 3686@subsection Cache Variable Names 3687 3688The names of cache variables should have the following format: 3689 3690@example 3691@var{package-prefix}_cv_@var{value-type}_@var{specific-value}@r{[}_@var{additional-options}@r{]} 3692@end example 3693 3694@noindent 3695for example, @samp{ac_cv_header_stat_broken} or 3696@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: 3697 3698@table @asis 3699@item @var{package-prefix} 3700An abbreviation for your package or organization; the same prefix you 3701begin local Autoconf macros with, except lowercase by convention. 3702For cache values used by the distributed Autoconf macros, this value is 3703@samp{ac}. 3704 3705@item @code{_cv_} 3706Indicates that this shell variable is a cache value. 3707 3708@item @var{value-type} 3709A convention for classifying cache values, to produce a rational naming 3710system. The values used in Autoconf are listed in @ref{Macro Names}. 3711 3712@item @var{specific-value} 3713Which member of the class of cache values this test applies to. 3714For example, which function (@samp{alloca}), program (@samp{gcc}), or 3715output variable (@samp{INSTALL}). 3716 3717@item @var{additional-options} 3718Any particular behavior of the specific member that this test applies to. 3719For example, @samp{broken} or @samp{set}. This part of the name may 3720be omitted if it does not apply. 3721@end table 3722 3723The values assigned to cache variables may not contain newlines. 3724Usually, their values will be boolean (@samp{yes} or @samp{no}) or the 3725names of files or functions; so this is not an important restriction. 3726 3727@node Cache Files, , Cache Variable Names, Caching Results 3728@subsection Cache Files 3729 3730A cache file is a shell script that caches the results of configure 3731tests run on one system so they can be shared between configure scripts 3732and configure runs. It is not useful on other systems. If its contents 3733are invalid for some reason, the user may delete or edit it. 3734 3735By default, configure uses @file{./config.cache} as the cache file, 3736creating it if it does not exist already. @code{configure} accepts the 3737@samp{--cache-file=@var{file}} option to use a different cache file; 3738that is what @code{configure} does when it calls @code{configure} 3739scripts in subdirectories, so they share the cache. 3740@xref{Subdirectories}, for information on configuring subdirectories 3741with the @code{AC_CONFIG_SUBDIRS} macro. 3742 3743Giving @samp{--cache-file=/dev/null} disables caching, for debugging 3744@code{configure}. @file{config.status} only pays attention to the cache 3745file if it is given the @samp{--recheck} option, which makes it rerun 3746@code{configure}. If you are anticipating a long debugging period, you 3747can also disable cache loading and saving for a @code{configure} script 3748by redefining the cache macros at the start of @file{configure.in}: 3749 3750@example 3751define([AC_CACHE_LOAD], )dnl 3752define([AC_CACHE_SAVE], )dnl 3753AC_INIT(@r{whatever}) 3754@r{ ... rest of configure.in ...} 3755@end example 3756 3757It is wrong to try to distribute cache files for particular system types. 3758There is too much room for error in doing that, and too much 3759administrative overhead in maintaining them. For any features that 3760can't be guessed automatically, use the standard method of the canonical 3761system type and linking files (@pxref{Manual Configuration}). 3762 3763The cache file on a particular system will gradually accumulate whenever 3764someone runs a @code{configure} script; it will be initially 3765nonexistent. Running @code{configure} merges the new cache results with 3766the existing cache file. The site initialization script can specify a 3767site-wide cache file to use instead of the default, to make it work 3768transparently, as long as the same C compiler is used every time 3769(@pxref{Site Defaults}). 3770 3771If your configure script, or a macro called from configure.in, happens to 3772abort the configure process, it may be useful to checkpoint the cache a 3773few times at key points. Doing so will reduce the amount of time it 3774takes to re-run the configure script with (hopefully) the error that 3775caused the previous abort corrected. 3776 3777@example 3778@r{ ... AC_INIT, etc. ...} 3779dnl checks for programs 3780AC_PROG_CC 3781AC_PROG_GCC_TRADITIONAL 3782@r{ ... more program checks ...} 3783AC_CACHE_SAVE 3784 3785dnl checks for libraries 3786AC_CHECK_LIB(nsl, gethostbyname) 3787AC_CHECK_LIB(socket, connect) 3788@r{ ... more lib checks ...} 3789AC_CACHE_SAVE 3790 3791dnl Might abort... 3792AM_PATH_GTK(1.0.2, , exit 1) 3793AM_PATH_GTKMM(0.9.5, , exit 1) 3794@end example 3795 3796@node Printing Messages, , Caching Results, Results 3797@section Printing Messages 3798 3799@code{configure} scripts need to give users running them several kinds 3800of information. The following macros print messages in ways appropriate 3801for each kind. The arguments to all of them get enclosed in shell 3802double quotes, so the shell performs variable and backquote substitution 3803on them. You can print a message containing a comma by quoting the 3804message with the @code{m4} quote characters: 3805 3806@example 3807AC_MSG_RESULT([never mind, I found the BASIC compiler]) 3808@end example 3809 3810These macros are all wrappers around the @code{echo} shell command. 3811@code{configure} scripts should rarely need to run @code{echo} directly 3812to print messages for the user. Using these macros makes it easy to 3813change how and when each kind of message is printed; such changes need 3814only be made to the macro definitions, and all of the callers change 3815automatically. 3816 3817@defmac AC_MSG_CHECKING (@var{feature-description}) 3818@maindex MSG_CHECKING 3819Notify the user that @code{configure} is checking for a particular 3820feature. This macro prints a message that starts with @samp{checking } 3821and ends with @samp{...} and no newline. It must be followed by a call 3822to @code{AC_MSG_RESULT} to print the result of the check and the 3823newline. The @var{feature-description} should be something like 3824@samp{whether the Fortran compiler accepts C++ comments} or @samp{for 3825c89}. 3826 3827This macro prints nothing if @code{configure} is run with the 3828@samp{--quiet} or @samp{--silent} option. 3829@end defmac 3830 3831@defmac AC_MSG_RESULT (@var{result-description}) 3832@maindex MSG_RESULT 3833Notify the user of the results of a check. @var{result-description} is 3834almost always the value of the cache variable for the check, typically 3835@samp{yes}, @samp{no}, or a file name. This macro should follow a call 3836to @code{AC_MSG_CHECKING}, and the @var{result-description} should be 3837the completion of the message printed by the call to 3838@code{AC_MSG_CHECKING}. 3839 3840This macro prints nothing if @code{configure} is run with the 3841@samp{--quiet} or @samp{--silent} option. 3842@end defmac 3843 3844@defmac AC_MSG_ERROR (@var{error-description}) 3845@maindex MSG_ERROR 3846Notify the user of an error that prevents @code{configure} from 3847completing. This macro prints an error message on the standard error 3848output and exits @code{configure} with a nonzero status. 3849@var{error-description} should be something like @samp{invalid value 3850$HOME for \$HOME}. 3851@end defmac 3852 3853@defmac AC_MSG_WARN (@var{problem-description}) 3854@maindex MSG_WARN 3855Notify the @code{configure} user of a possible problem. This macro 3856prints the message on the standard error output; @code{configure} 3857continues running afterward, so macros that call @code{AC_MSG_WARN} should 3858provide a default (back-up) behavior for the situations they warn about. 3859@var{problem-description} should be something like @samp{ln -s seems to 3860make hard links}. 3861@end defmac 3862 3863The following two macros are an obsolete alternative to 3864@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT}. 3865 3866@defmac AC_CHECKING (@var{feature-description}) 3867@maindex CHECKING 3868This macro is similar to @code{AC_MSG_CHECKING}, except that it prints a 3869newline after the @var{feature-description}. It is useful mainly to 3870print a general description of the overall purpose of a group of feature 3871checks, e.g., 3872 3873@example 3874AC_CHECKING(if stack overflow is detectable) 3875@end example 3876@end defmac 3877 3878@defmac AC_VERBOSE (@var{result-description}) 3879@maindex VERBOSE 3880This macro is similar to @code{AC_MSG_RESULT}, except that it is meant 3881to follow a call to @code{AC_CHECKING} instead of 3882@code{AC_MSG_CHECKING}; it starts the message it prints with a tab. It 3883is considered obsolete. 3884@end defmac 3885 3886@node Writing Macros, Manual Configuration, Results, Top 3887@chapter Writing Macros 3888 3889When you write a feature test that could be applicable to more than one 3890software package, the best thing to do is encapsulate it in a new macro. 3891Here are some instructions and guidelines for writing Autoconf macros. 3892 3893@menu 3894* Macro Definitions:: Basic format of an Autoconf macro. 3895* Macro Names:: What to call your new macros. 3896* Quoting:: Protecting macros from unwanted expansion. 3897* Dependencies Between Macros:: What to do when macros depend on other macros. 3898@end menu 3899 3900@node Macro Definitions, Macro Names, Writing Macros, Writing Macros 3901@section Macro Definitions 3902 3903@maindex DEFUN 3904Autoconf macros are defined using the @code{AC_DEFUN} macro, which is 3905similar to the @code{m4} builtin @code{define} macro. In addition to 3906defining a macro, @code{AC_DEFUN} adds to it some code which is used to 3907constrain the order in which macros are called (@pxref{Prerequisite 3908Macros}). 3909 3910An Autoconf macro definition looks like this: 3911 3912@example 3913AC_DEFUN(@var{macro-name}, [@var{macro-body}]) 3914@end example 3915 3916@noindent 3917The square brackets here do not indicate optional text: they should 3918literally be present in the macro definition to avoid macro expansion 3919problems (@pxref{Quoting}). You can refer to any arguments passed to 3920the macro as @samp{$1}, @samp{$2}, etc. 3921 3922To introduce comments in @code{m4}, use the @code{m4} builtin 3923@code{dnl}; it causes @code{m4} to discard the text through the next 3924newline. It is not needed between macro definitions in @file{acsite.m4} 3925and @file{aclocal.m4}, because all output is discarded until 3926@code{AC_INIT} is called. 3927 3928@xref{Definitions, , How to define new macros, m4.info, GNU m4}, for 3929more complete information on writing @code{m4} macros. 3930 3931@node Macro Names, Quoting, Macro Definitions, Writing Macros 3932@section Macro Names 3933 3934All of the Autoconf macros have all-uppercase names starting with 3935@samp{AC_} to prevent them from accidentally conflicting with other 3936text. All shell variables that they use for internal purposes have 3937mostly-lowercase names starting with @samp{ac_}. To ensure that your 3938macros don't conflict with present or future Autoconf macros, you should 3939prefix your own macro names and any shell variables they use with some 3940other sequence. Possibilities include your initials, or an abbreviation 3941for the name of your organization or software package. 3942 3943Most of the Autoconf macros' names follow a structured naming convention 3944that indicates the kind of feature check by the name. The macro names 3945consist of several words, separated by underscores, going from most 3946general to most specific. The names of their cache variables use the 3947same convention (@pxref{Cache Variable Names}, for more information on them). 3948 3949The first word of the name after @samp{AC_} usually tells the category 3950of feature being tested. Here are the categories used in Autoconf for 3951specific test macros, the kind of macro that you are more likely to 3952write. They are also used for cache variables, in all-lowercase. Use 3953them where applicable; where they're not, invent your own categories. 3954 3955@table @code 3956@item C 3957C language builtin features. 3958@item DECL 3959Declarations of C variables in header files. 3960@item FUNC 3961Functions in libraries. 3962@item GROUP 3963UNIX group owners of files. 3964@item HEADER 3965Header files. 3966@item LIB 3967C libraries. 3968@item PATH 3969The full path names to files, including programs. 3970@item PROG 3971The base names of programs. 3972@item STRUCT 3973Definitions of C structures in header files. 3974@item SYS 3975Operating system features. 3976@item TYPE 3977C builtin or declared types. 3978@item VAR 3979C variables in libraries. 3980@end table 3981 3982After the category comes the name of the particular feature being 3983tested. Any further words in the macro name indicate particular aspects 3984of the feature. For example, @code{AC_FUNC_UTIME_NULL} checks the 3985behavior of the @code{utime} function when called with a @code{NULL} 3986pointer. 3987 3988A macro that is an internal subroutine of another macro should have a 3989name that starts with the name of that other macro, followed by one or 3990more words saying what the internal macro does. For example, 3991@code{AC_PATH_X} has internal macros @code{AC_PATH_X_XMKMF} and 3992@code{AC_PATH_X_DIRECT}. 3993 3994@node Quoting, Dependencies Between Macros, Macro Names, Writing Macros 3995@section Quoting 3996 3997Macros that are called by other macros are evaluated by @code{m4} 3998several times; each evaluation might require another layer of quotes to 3999prevent unwanted expansions of macros or @code{m4} builtins, such as 4000@samp{define} and @samp{$1}. Quotes are also required around macro 4001arguments that contain commas, since commas separate the arguments from 4002each other. It's a good idea to quote any macro arguments that contain 4003newlines or calls to other macros, as well. 4004 4005Autoconf changes the @code{m4} quote characters 4006from the default @samp{`} and @samp{'} to @samp{[} and @samp{]}, because 4007many of the macros use @samp{`} and @samp{'}, mismatched. However, in a 4008few places the macros need to use brackets (usually in C program text or 4009regular expressions). In those places, they use the @code{m4} builtin 4010command @code{changequote} to temporarily change the quote characters to 4011@samp{<<} and @samp{>>}. (Sometimes, if they don't need to quote 4012anything, they disable quoting entirely instead by setting the quote 4013characters to empty strings.) Here is an example: 4014 4015@example 4016AC_TRY_LINK( 4017changequote(<<, >>)dnl 4018<<#include <time.h> 4019#ifndef tzname /* For SGI. */ 4020extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 4021#endif>>, 4022changequote([, ])dnl 4023[atoi(*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 4024@end example 4025 4026When you create a @code{configure} script using newly written macros, 4027examine it carefully to check whether you need to add more quotes in 4028your macros. If one or more words have disappeared in the @code{m4} 4029output, you need more quotes. When in doubt, quote. 4030 4031However, it's also possible to put on too many layers of quotes. If 4032this happens, the resulting @code{configure} script will contain 4033unexpanded macros. The @code{autoconf} program checks for this problem 4034by doing @samp{grep AC_ configure}. 4035 4036@node Dependencies Between Macros, , Quoting, Writing Macros 4037@section Dependencies Between Macros 4038 4039Some Autoconf macros depend on other macros having been called first in 4040order to work correctly. Autoconf provides a way to ensure that certain 4041macros are called if needed and a way to warn the user if macros are 4042called in an order that might cause incorrect operation. 4043 4044@menu 4045* Prerequisite Macros:: Ensuring required information. 4046* Suggested Ordering:: Warning about possible ordering problems. 4047* Obsolete Macros:: Warning about old ways of doing things. 4048@end menu 4049 4050@node Prerequisite Macros, Suggested Ordering, Dependencies Between Macros, Dependencies Between Macros 4051@subsection Prerequisite Macros 4052 4053A macro that you write might need to use values that have previously 4054been computed by other macros. For example, @code{AC_DECL_YYTEXT} 4055examines the output of @code{flex} or @code{lex}, so it depends on 4056@code{AC_PROG_LEX} having been called first to set the shell variable 4057@code{LEX}. 4058 4059Rather than forcing the user of the macros to keep track of the 4060dependencies between them, you can use the @code{AC_REQUIRE} macro to do 4061it automatically. @code{AC_REQUIRE} can ensure that a macro is only 4062called if it is needed, and only called once. 4063 4064@defmac AC_REQUIRE (@var{macro-name}) 4065@maindex REQUIRE 4066If the @code{m4} macro @var{macro-name} has not already been called, 4067call it (without any arguments). Make sure to quote @var{macro-name} 4068with square brackets. @var{macro-name} must have been defined using 4069@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 4070that it has been called. 4071@end defmac 4072 4073An alternative to using @code{AC_DEFUN} is to use @code{define} and call 4074@code{AC_PROVIDE}. Because this technique does not prevent nested 4075messages, it is considered obsolete. 4076 4077@defmac AC_PROVIDE (@var{this-macro-name}) 4078@maindex PROVIDE 4079Record the fact that @var{this-macro-name} has been called. 4080@var{this-macro-name} should be the name of the macro that is calling 4081@code{AC_PROVIDE}. An easy way to get it is from the @code{m4} builtin 4082variable @code{$0}, like this: 4083 4084@example 4085AC_PROVIDE([$0]) 4086@end example 4087@end defmac 4088 4089@node Suggested Ordering, Obsolete Macros, Prerequisite Macros, Dependencies Between Macros 4090@subsection Suggested Ordering 4091 4092Some macros should be run before another macro if both are called, but 4093neither @emph{requires} that the other be called. For example, a macro 4094that changes the behavior of the C compiler should be called before any 4095macros that run the C compiler. Many of these dependencies are noted in 4096the documentation. 4097 4098Autoconf provides the @code{AC_BEFORE} macro to warn users when macros 4099with this kind of dependency appear out of order in a 4100@file{configure.in} file. The warning occurs when creating 4101@code{configure} from @file{configure.in}, not when running 4102@code{configure}. 4103For example, @code{AC_PROG_CPP} checks whether the C compiler 4104can run the C preprocessor when given the @samp{-E} option. It should 4105therefore be called after any macros that change which C compiler is 4106being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: 4107 4108@example 4109AC_BEFORE([$0], [AC_PROG_CPP])dnl 4110@end example 4111 4112@noindent 4113This warns the user if a call to @code{AC_PROG_CPP} has already occurred 4114when @code{AC_PROG_CC} is called. 4115 4116@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) 4117@maindex BEFORE 4118Make @code{m4} print a warning message on the standard error output if 4119@var{called-macro-name} has already been called. @var{this-macro-name} 4120should be the name of the macro that is calling @code{AC_BEFORE}. The 4121macro @var{called-macro-name} must have been defined using 4122@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 4123that it has been called. 4124@end defmac 4125 4126@node Obsolete Macros, , Suggested Ordering, Dependencies Between Macros 4127@subsection Obsolete Macros 4128 4129Configuration and portability technology has evolved over the years. 4130Often better ways of solving a particular problem are developed, or 4131ad-hoc approaches are systematized. This process has occurred in many 4132parts of Autoconf. One result is that some of the macros are now 4133considered @dfn{obsolete}; they still work, but are no longer considered 4134the best thing to do. Autoconf provides the @code{AC_OBSOLETE} macro to 4135warn users producing @code{configure} scripts when they use obsolete 4136macros, to encourage them to modernize. A sample call is: 4137 4138@example 4139AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 4140@end example 4141 4142@defmac AC_OBSOLETE (@var{this-macro-name} @r{[}, @var{suggestion}@r{]}) 4143@maindex OBSOLETE 4144Make @code{m4} print a message on the standard error output warning that 4145@var{this-macro-name} is obsolete, and giving the file and line number 4146where it was called. @var{this-macro-name} should be the name of the 4147macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, 4148it is printed at the end of the warning message; for example, it can be 4149a suggestion for what to use instead of @var{this-macro-name}. 4150@end defmac 4151 4152@node Manual Configuration, Site Configuration, Writing Macros, Top 4153@chapter Manual Configuration 4154 4155A few kinds of features can't be guessed automatically by running test 4156programs. For example, the details of the object file format, or 4157special options that need to be passed to the compiler or linker. You 4158can check for such features using ad-hoc means, such as having 4159@code{configure} check the output of the @code{uname} program, or 4160looking for libraries that are unique to particular systems. However, 4161Autoconf provides a uniform method for handling unguessable features. 4162 4163@menu 4164* Specifying Names:: Specifying the system type. 4165* Canonicalizing:: Getting the canonical system type. 4166* System Type Variables:: Variables containing the system type. 4167* Using System Type:: What to do with the system type. 4168@end menu 4169 4170@node Specifying Names, Canonicalizing, Manual Configuration, Manual Configuration 4171@section Specifying the System Type 4172 4173Like other GNU @code{configure} scripts, Autoconf-generated 4174@code{configure} scripts can make decisions based on a canonical name 4175for the system type, which has the form: 4176 4177@example 4178@var{cpu}-@var{company}-@var{system} 4179@end example 4180 4181@code{configure} can usually guess the canonical name for the type of 4182system it's running on. To do so it runs a script called 4183@code{config.guess}, which derives the name using the @code{uname} 4184command or symbols predefined by the C preprocessor. 4185 4186Alternately, the user can specify the system type with command line 4187arguments to @code{configure}. Doing so is necessary when 4188cross-compiling. In the most complex case of cross-compiling, three 4189system types are involved. The options to specify them are: 4190 4191@table @code 4192@item --build=@var{build-type} 4193the type of system on which the package is being configured and 4194compiled (rarely needed); 4195 4196@item --host=@var{host-type} 4197the type of system on which the package will run; 4198 4199@item --target=@var{target-type} 4200the type of system for which any compiler tools in the package will 4201produce code. 4202@end table 4203 4204@noindent 4205If the user gives @code{configure} a non-option argument, it is used as 4206the default for the host, target, and build system types if the user 4207does not specify them explicitly with options. The target and build 4208types default to the host type if it is given and they are not. If you 4209are cross-compiling, you still have to specify the names of the 4210cross-tools you use, in particular the C compiler, on the 4211@code{configure} command line, e.g., 4212 4213@example 4214CC=m68k-coff-gcc configure --target=m68k-coff 4215@end example 4216 4217@code{configure} recognizes short aliases for many system types; for 4218example, @samp{decstation} can be given on the command line instead of 4219@samp{mips-dec-ultrix4.2}. @code{configure} runs a script called 4220@code{config.sub} to canonicalize system type aliases. 4221 4222@node Canonicalizing, System Type Variables, Specifying Names, Manual Configuration 4223@section Getting the Canonical System Type 4224 4225The following macros make the system type available to @code{configure} 4226scripts. They run the shell script @code{config.guess} to determine any 4227values for the host, target, and build types that they need and the user 4228did not specify on the command line. They run @code{config.sub} to 4229canonicalize any aliases the user gave. If you use these macros, you 4230must distribute those two shell scripts along with your source code. 4231@xref{Output}, for information about the @code{AC_CONFIG_AUX_DIR} macro 4232which you can use to control which directory @code{configure} looks for 4233those scripts in. If you do not use either of these macros, 4234@code{configure} ignores any @samp{--host}, @samp{--target}, and 4235@samp{--build} options given to it. 4236 4237@defmac AC_CANONICAL_SYSTEM 4238@maindex CANONICAL_SYSTEM 4239Determine the system type and set output variables to the names of the 4240canonical system types. @xref{System Type Variables}, for details about 4241the variables this macro sets. 4242@end defmac 4243 4244@defmac AC_CANONICAL_HOST 4245@maindex CANONICAL_HOST 4246Perform only the subset of @code{AC_CANONICAL_SYSTEM} relevant to the 4247host type. This is all that is needed for programs that are not part of 4248a compiler toolchain. 4249@end defmac 4250 4251@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@var{cmd}) 4252@maindex VALIDATE_CACHED_SYSTEM_TUPLE 4253If the cache file is inconsistent with the current host, 4254target and build system types, execute @var{cmd} or print a default 4255error message. 4256@end defmac 4257 4258@node System Type Variables, Using System Type, Canonicalizing, Manual Configuration 4259@section System Type Variables 4260 4261After calling @code{AC_CANONICAL_SYSTEM}, the following output variables 4262contain the system type information. After @code{AC_CANONICAL_HOST}, 4263only the @code{host} variables below are set. 4264 4265@table @code 4266@ovindex build 4267@ovindex host 4268@ovindex target 4269@item @code{build}, @code{host}, @code{target} 4270the canonical system names; 4271 4272@item @code{build_alias}, @code{host_alias}, @code{target_alias} 4273@ovindex build_alias 4274@ovindex host_alias 4275@ovindex target_alias 4276the names the user specified, or the canonical names if 4277@code{config.guess} was used; 4278 4279@item @code{build_cpu}, @code{build_vendor}, @code{build_os} 4280@itemx @code{host_cpu}, @code{host_vendor}, @code{host_os} 4281@itemx @code{target_cpu}, @code{target_vendor}, @code{target_os} 4282@ovindex build_cpu 4283@ovindex host_cpu 4284@ovindex target_cpu 4285@ovindex build_vendor 4286@ovindex host_vendor 4287@ovindex target_vendor 4288@ovindex build_os 4289@ovindex host_os 4290@ovindex target_os 4291the individual parts of the canonical names (for convenience). 4292@end table 4293 4294@node Using System Type, , System Type Variables, Manual Configuration 4295@section Using the System Type 4296 4297How do you use a canonical system type? Usually, you use it in one or 4298more @code{case} statements in @file{configure.in} to select 4299system-specific C files. Then link those files, which have names based 4300on the system name, to generic names, such as @file{host.h} or 4301@file{target.c}. The @code{case} statement patterns can use shell 4302wildcards to group several cases together, like in this fragment: 4303 4304@example 4305case "$target" in 4306i386-*-mach* | i386-*-gnu*) obj_format=aout emulation=mach bfd_gas=yes ;; 4307i960-*-bout) obj_format=bout ;; 4308esac 4309@end example 4310 4311@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) 4312@maindex LINK_FILES 4313Make @code{AC_OUTPUT} link each of the existing files @var{source} to 4314the corresponding link name @var{dest}. Makes a symbolic link if 4315possible, otherwise a hard link. The @var{dest} and @var{source} names 4316should be relative to the top level source or build directory. 4317This macro may be called multiple times. 4318 4319For example, this call: 4320 4321@example 4322AC_LINK_FILES(config/$@{machine@}.h config/$@{obj_format@}.h, host.h object.h) 4323@end example 4324 4325@noindent 4326creates in the current directory @file{host.h}, which is a link to 4327@file{@var{srcdir}/config/$@{machine@}.h}, and @file{object.h}, which is a link 4328to @file{@var{srcdir}/config/$@{obj_format@}.h}. 4329@end defmac 4330 4331You can also use the host system type to find cross-compilation tools. 4332@xref{Generic Programs}, for information about the @code{AC_CHECK_TOOL} 4333macro which does that. 4334 4335@node Site Configuration, Invoking configure, Manual Configuration, Top 4336@chapter Site Configuration 4337 4338@code{configure} scripts support several kinds of local configuration 4339decisions. There are ways for users to specify where external software 4340packages are, include or exclude optional features, install programs 4341under modified names, and set default values for @code{configure} 4342options. 4343 4344@menu 4345* External Software:: Working with other optional software. 4346* Package Options:: Selecting optional features. 4347* Site Details:: Configuring site details. 4348* Transforming Names:: Changing program names when installing. 4349* Site Defaults:: Giving @code{configure} local defaults. 4350@end menu 4351 4352@node External Software, Package Options, Site Configuration, Site Configuration 4353@section Working With External Software 4354 4355Some packages require, or can optionally use, other software packages 4356which are already installed. The user can give @code{configure} 4357command line options to specify which such external software to use. 4358The options have one of these forms: 4359 4360@example 4361--with-@var{package}@r{[}=@var{arg}@r{]} 4362--without-@var{package} 4363@end example 4364 4365For example, @samp{--with-gnu-ld} means work with the GNU linker instead 4366of some other linker. @samp{--with-x} means work with The X Window System. 4367 4368The user can give an argument by following the package name with 4369@samp{=} and the argument. Giving an argument of @samp{no} is for 4370packages that are used by default; it says to @emph{not} use the 4371package. An argument that is neither @samp{yes} nor @samp{no} could 4372include a name or number of a version of the other package, to specify 4373more precisely which other package this program is supposed to work 4374with. If no argument is given, it defaults to @samp{yes}. 4375@samp{--without-@var{package}} is equivalent to 4376@samp{--with-@var{package}=no}. 4377 4378@code{configure} scripts do not complain about 4379@samp{--with-@var{package}} options that they do not support. 4380This behavior permits configuring a source tree containing multiple 4381packages with a top-level @code{configure} script when the packages 4382support different options, without spurious error messages about options 4383that some of the packages support. 4384An unfortunate side effect is that option spelling errors are not diagnosed. 4385No better approach to this problem has been suggested so far. 4386 4387For each external software package that may be used, @file{configure.in} 4388should call @code{AC_ARG_WITH} to detect whether the @code{configure} 4389user asked to use it. Whether each package is used or not by 4390default, and which arguments are valid, is up to you. 4391 4392@defmac AC_ARG_WITH (@var{package}, @var{help-string} @r{[}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]]}) 4393@maindex ARG_WITH 4394If the user gave @code{configure} the option @samp{--with-@var{package}} 4395or @samp{--without-@var{package}}, run shell commands 4396@var{action-if-given}. If neither option was given, run shell commands 4397@var{action-if-not-given}. The name @var{package} indicates another 4398software package that this program should work with. It should consist 4399only of alphanumeric characters and dashes. 4400 4401The option's argument is available to the shell commands 4402@var{action-if-given} in the shell variable @code{withval}, which is 4403actually just the value of the shell variable @code{with_@var{package}}, 4404with any @samp{-} characters changed into @samp{_}. 4405You may use that variable instead, if you wish. 4406 4407The argument @var{help-string} is a description of the option which 4408looks like this: 4409@example 4410 --with-readline support fancy command line editing 4411@end example 4412@noindent 4413@var{help-string} may be more than one line long, if more detail is 4414needed. Just make sure the columns line up in @samp{configure --help}. 4415Avoid tabs in the help string. You'll need to enclose it in @samp{[} 4416and @samp{]} in order to produce the leading spaces. 4417@end defmac 4418 4419@defmac AC_WITH (@var{package}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]}) 4420@maindex WITH 4421This is an obsolete version of @code{AC_ARG_WITH} that does not 4422support providing a help string. 4423@end defmac 4424 4425@node Package Options, Site Details, External Software, Site Configuration 4426@section Choosing Package Options 4427 4428If a software package has optional compile-time features, the user can 4429give @code{configure} command line options to specify whether to 4430compile them. The options have one of these forms: 4431 4432@example 4433--enable-@var{feature}@r{[}=@var{arg}@r{]} 4434--disable-@var{feature} 4435@end example 4436 4437These options allow users to choose which optional features to build and 4438install. @samp{--enable-@var{feature}} options should never make a 4439feature behave differently or cause one feature to replace another. 4440They should only cause parts of the program to be built rather than left 4441out. 4442 4443The user can give an argument by following the feature name with 4444@samp{=} and the argument. Giving an argument of @samp{no} requests 4445that the feature @emph{not} be made available. A feature with an 4446argument looks like @samp{--enable-debug=stabs}. If no argument is 4447given, it defaults to @samp{yes}. @samp{--disable-@var{feature}} is 4448equivalent to @samp{--enable-@var{feature}=no}. 4449 4450@code{configure} scripts do not complain about 4451@samp{--enable-@var{feature}} options that they do not support. 4452This behavior permits configuring a source tree containing multiple 4453packages with a top-level @code{configure} script when the packages 4454support different options, without spurious error messages about options 4455that some of the packages support. 4456An unfortunate side effect is that option spelling errors are not diagnosed. 4457No better approach to this problem has been suggested so far. 4458 4459For each optional feature, @file{configure.in} should call 4460@code{AC_ARG_ENABLE} to detect whether the @code{configure} user asked 4461to include it. Whether each feature is included or not by default, and 4462which arguments are valid, is up to you. 4463 4464@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string} @r{[}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]]}) 4465@maindex ARG_ENABLE 4466If the user gave @code{configure} the option 4467@samp{--enable-@var{feature}} or @samp{--disable-@var{feature}}, run 4468shell commands @var{action-if-given}. If neither option was given, run 4469shell commands @var{action-if-not-given}. The name @var{feature} 4470indicates an optional user-level facility. It should consist only of 4471alphanumeric characters and dashes. 4472 4473The option's argument is available to the shell commands 4474@var{action-if-given} in the shell variable @code{enableval}, which is 4475actually just the value of the shell variable 4476@code{enable_@var{feature}}, with any @samp{-} characters changed into 4477@samp{_}. You may use that variable instead, if you wish. The 4478@var{help-string} argument is like that of @code{AC_ARG_WITH} 4479(@pxref{External Software}). 4480@end defmac 4481 4482@defmac AC_ENABLE (@var{feature}, @var{action-if-given} @r{[}, @var{action-if-not-given}@r{]}) 4483@maindex ENABLE 4484This is an obsolete version of @code{AC_ARG_ENABLE} that does not 4485support providing a help string. 4486@end defmac 4487 4488@node Site Details, Transforming Names, Package Options, Site Configuration 4489@section Configuring Site Details 4490 4491Some software packages require complex site-specific information. Some 4492examples are host names to use for certain services, company names, and 4493email addresses to contact. Since some configuration scripts generated 4494by Metaconfig ask for such information interactively, people sometimes 4495wonder how to get that information in Autoconf-generated configuration 4496scripts, which aren't interactive. 4497 4498Such site configuration information should be put in a file that is 4499edited @emph{only by users}, not by programs. The location of the file 4500can either be based on the @code{prefix} variable, or be a standard 4501location such as the user's home directory. It could even be specified 4502by an environment variable. The programs should examine that file at 4503run time, rather than at compile time. Run time configuration is more 4504convenient for users and makes the configuration process simpler than 4505getting the information while configuring. @xref{Directory Variables, , 4506Variables for Installation Directories, standards, GNU Coding 4507Standards}, for more information on where to put data files. 4508 4509@node Transforming Names, Site Defaults, Site Details, Site Configuration 4510@section Transforming Program Names When Installing 4511 4512Autoconf supports changing the names of programs when installing them. 4513In order to use these transformations, @file{configure.in} must call the 4514macro @code{AC_ARG_PROGRAM}. 4515 4516@defmac AC_ARG_PROGRAM 4517@maindex ARG_PROGRAM 4518@ovindex program_transform_name 4519Place in output variable @code{program_transform_name} a sequence of 4520@code{sed} commands for changing the names of installed programs. 4521 4522If any of the options described below are given to @code{configure}, 4523program names are transformed accordingly. Otherwise, if 4524@code{AC_CANONICAL_SYSTEM} has been called and a @samp{--target} value 4525is given that differs from the host type (specified with @samp{--host} 4526or defaulted by @code{config.sub}), the target type followed by a dash 4527is used as a prefix. Otherwise, no program name transformation is done. 4528@end defmac 4529 4530@menu 4531* Transformation Options:: @code{configure} options to transform names. 4532* Transformation Examples:: Sample uses of transforming names. 4533* Transformation Rules:: @file{Makefile} uses of transforming names. 4534@end menu 4535 4536@node Transformation Options, Transformation Examples, Transforming Names, Transforming Names 4537@subsection Transformation Options 4538 4539You can specify name transformations by giving @code{configure} these 4540command line options: 4541 4542@table @code 4543@item --program-prefix=@var{prefix} 4544prepend @var{prefix} to the names; 4545 4546@item --program-suffix=@var{suffix} 4547append @var{suffix} to the names; 4548 4549@item --program-transform-name=@var{expression} 4550perform @code{sed} substitution @var{expression} on the names. 4551@end table 4552 4553@node Transformation Examples, Transformation Rules, Transformation Options, Transforming Names 4554@subsection Transformation Examples 4555 4556These transformations are useful with programs that can be part of a 4557cross-compilation development environment. For example, a 4558cross-assembler running on a Sun 4 configured with 4559@samp{--target=i960-vxworks} is normally installed as 4560@file{i960-vxworks-as}, rather than @file{as}, which could be confused 4561with a native Sun 4 assembler. 4562 4563You can force a program name to begin with @file{g}, if you don't want 4564GNU programs installed on your system to shadow other programs with the 4565same name. For example, if you configure GNU @code{diff} with 4566@samp{--program-prefix=g}, then when you run @samp{make install} it is 4567installed as @file{/usr/local/bin/gdiff}. 4568 4569As a more sophisticated example, you could use 4570@example 4571--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 4572@end example 4573@noindent 4574to prepend @samp{g} to most of the program names in a source tree, 4575excepting those like @code{gdb} that already have one and those like 4576@code{less} and @code{lesskey} that aren't GNU programs. (That is 4577assuming that you have a source tree containing those programs that is 4578set up to use this feature.) 4579 4580One way to install multiple versions of some programs simultaneously is 4581to append a version number to the name of one or both. For example, if 4582you want to keep Autoconf version 1 around for awhile, you can configure 4583Autoconf version 2 using @samp{--program-suffix=2} to install the 4584programs as @file{/usr/local/bin/autoconf2}, 4585@file{/usr/local/bin/autoheader2}, etc. 4586 4587@node Transformation Rules, , Transformation Examples, Transforming Names 4588@subsection Transformation Rules 4589 4590Here is how to use the variable @code{program_transform_name} in a 4591@file{Makefile.in}: 4592 4593@example 4594transform=@@program_transform_name@@ 4595install: all 4596 $(INSTALL_PROGRAM) myprog $(bindir)/`echo myprog|sed '$(transform)'` 4597 4598uninstall: 4599 rm -f $(bindir)/`echo myprog|sed '$(transform)'` 4600@end example 4601 4602@noindent 4603If you have more than one program to install, you can do it in a loop: 4604 4605@example 4606PROGRAMS=cp ls rm 4607install: 4608 for p in $(PROGRAMS); do \ 4609 $(INSTALL_PROGRAM) $$p $(bindir)/`echo $$p|sed '$(transform)'`; \ 4610 done 4611 4612uninstall: 4613 for p in $(PROGRAMS); do \ 4614 rm -f $(bindir)/`echo $$p|sed '$(transform)'`; \ 4615 done 4616@end example 4617 4618Whether to do the transformations on documentation files (Texinfo or 4619@code{man}) is a tricky question; there seems to be no perfect answer, 4620due to the several reasons for name transforming. Documentation is not 4621usually particular to a specific architecture, and Texinfo files do not 4622conflict with system documentation. But they might conflict with 4623earlier versions of the same files, and @code{man} pages sometimes do 4624conflict with system documentation. As a compromise, it is probably 4625best to do name transformations on @code{man} pages but not on Texinfo 4626manuals. 4627 4628@node Site Defaults, , Transforming Names, Site Configuration 4629@section Setting Site Defaults 4630 4631Autoconf-generated @code{configure} scripts allow your site to provide 4632default values for some configuration values. You do this by creating 4633site- and system-wide initialization files. 4634 4635@evindex CONFIG_SITE 4636If the environment variable @code{CONFIG_SITE} is set, @code{configure} 4637uses its value as the name of a shell script to read. Otherwise, it 4638reads the shell script @file{@var{prefix}/share/config.site} if it exists, 4639then @file{@var{prefix}/etc/config.site} if it exists. Thus, 4640settings in machine-specific files override those in machine-independent 4641ones in case of conflict. 4642 4643Site files can be arbitrary shell scripts, but only certain kinds of 4644code are really appropriate to be in them. Because @code{configure} 4645reads any cache file after it has read any site files, a site file can 4646define a default cache file to be shared between all Autoconf-generated 4647@code{configure} scripts run on that system. If you set a default cache 4648file in a site file, it is a good idea to also set the output variable 4649@code{CC} in that site file, because the cache file is only valid for a 4650particular compiler, but many systems have several available. 4651 4652You can examine or override the value set by a command line option to 4653@code{configure} in a site file; options set shell variables that have 4654the same names as the options, with any dashes turned into underscores. 4655The exceptions are that @samp{--without-} and @samp{--disable-} options 4656are like giving the corresponding @samp{--with-} or @samp{--enable-} 4657option and the value @samp{no}. Thus, @samp{--cache-file=localcache} 4658sets the variable @code{cache_file} to the value @samp{localcache}; 4659@samp{--enable-warnings=no} or @samp{--disable-warnings} sets the variable 4660@code{enable_warnings} to the value @samp{no}; @samp{--prefix=/usr} sets the 4661variable @code{prefix} to the value @samp{/usr}; etc. 4662 4663Site files are also good places to set default values for other output 4664variables, such as @code{CFLAGS}, if you need to give them non-default 4665values: anything you would normally do, repetitively, on the command 4666line. If you use non-default values for @var{prefix} or 4667@var{exec_prefix} (wherever you locate the site file), you can set them 4668in the site file if you specify it with the @code{CONFIG_SITE} 4669environment variable. 4670 4671You can set some cache values in the site file itself. Doing this is 4672useful if you are cross-compiling, so it is impossible to check features 4673that require running a test program. You could ``prime the cache'' by 4674setting those values correctly for that system in 4675@file{@var{prefix}/etc/config.site}. To find out the names of the cache 4676variables you need to set, look for shell variables with @samp{_cv_} in 4677their names in the affected @code{configure} scripts, or in the Autoconf 4678@code{m4} source code for those macros. 4679 4680The cache file is careful to not override any variables set in the site 4681files. Similarly, you should not override command-line options in the 4682site files. Your code should check that variables such as @code{prefix} 4683and @code{cache_file} have their default values (as set near the top of 4684@code{configure}) before changing them. 4685 4686Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The 4687command @samp{configure --prefix=/usr/share/local/gnu} would read this 4688file (if @code{CONFIG_SITE} is not set to a different file). 4689 4690@example 4691# config.site for configure 4692# 4693# Change some defaults. 4694test "$prefix" = NONE && prefix=/usr/share/local/gnu 4695test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 4696test "$sharedstatedir" = '$@{prefix@}/com' && sharedstatedir=/var 4697test "$localstatedir" = '$@{prefix@}/var' && localstatedir=/var 4698# 4699# Give Autoconf 2.x generated configure scripts a shared default 4700# cache file for feature test results, architecture-specific. 4701if test "$cache_file" = ./config.cache; then 4702 cache_file="$prefix/var/config.cache" 4703 # A cache file is only valid for one C compiler. 4704 CC=gcc 4705fi 4706@end example 4707 4708@node Invoking configure, Invoking config.status, Site Configuration, Top 4709@chapter Running @code{configure} Scripts 4710 4711Below are instructions on how to configure a package that uses a 4712@code{configure} script, suitable for inclusion as an @file{INSTALL} 4713file in the package. A plain-text version of @file{INSTALL} which you 4714may use comes with Autoconf. 4715 4716@menu 4717* Basic Installation:: Instructions for typical cases. 4718* Compilers and Options:: Selecting compilers and optimization. 4719* Multiple Architectures:: Compiling for multiple architectures at once. 4720* Installation Names:: Installing in different directories. 4721* Optional Features:: Selecting optional features. 4722* System Type:: Specifying the system type. 4723* Sharing Defaults:: Setting site-wide defaults for @code{configure}. 4724* Operation Controls:: Changing how @code{configure} runs. 4725@end menu 4726 4727@include install.texi 4728 4729@node Invoking config.status, Questions, Invoking configure, Top 4730@chapter Recreating a Configuration 4731 4732The @code{configure} script creates a file named @file{config.status} 4733which describes which configuration options were specified when the 4734package was last configured. This file is a shell script which, 4735if run, will recreate the same configuration. 4736 4737You can give @file{config.status} the @samp{--recheck} option to update 4738itself. This option is useful if you change @code{configure}, so that 4739the results of some tests might be different from the previous run. The 4740@samp{--recheck} option re-runs @code{configure} with the same arguments 4741you used before, plus the @samp{--no-create} option, which prevent 4742@code{configure} from running @file{config.status} and creating 4743@file{Makefile} and other files, and the @samp{--no-recursion} option, 4744which prevents @code{configure} from running other @code{configure} 4745scripts in subdirectories. (This is so other @file{Makefile} rules can 4746run @file{config.status} when it changes; @pxref{Automatic Remaking}, 4747for an example). 4748 4749@file{config.status} also accepts the options @samp{--help}, which 4750prints a summary of the options to @file{config.status}, and 4751@samp{--version}, which prints the version of Autoconf used to create 4752the @code{configure} script that generated @file{config.status}. 4753 4754@file{config.status} checks several optional environment variables that 4755can alter its behavior: 4756 4757@defvar CONFIG_SHELL 4758@evindex CONFIG_SHELL 4759The shell with which to run @code{configure} for the @samp{--recheck} 4760option. It must be Bourne-compatible. The default is @file{/bin/sh}. 4761@end defvar 4762 4763@defvar CONFIG_STATUS 4764@evindex CONFIG_STATUS 4765The file name to use for the shell script that records the 4766configuration. The default is @file{./config.status}. This variable is 4767useful when one package uses parts of another and the @code{configure} 4768scripts shouldn't be merged because they are maintained separately. 4769@end defvar 4770 4771The following variables provide one way for separately distributed 4772packages to share the values computed by @code{configure}. Doing so can 4773be useful if some of the packages need a superset of the features that 4774one of them, perhaps a common library, does. These variables allow a 4775@file{config.status} file to create files other than the ones that its 4776@file{configure.in} specifies, so it can be used for a different package. 4777 4778@defvar CONFIG_FILES 4779@evindex CONFIG_FILES 4780The files in which to perform @samp{@@@var{variable}@@} substitutions. 4781The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}. 4782@end defvar 4783 4784@defvar CONFIG_HEADERS 4785@evindex CONFIG_HEADERS 4786The files in which to substitute C @code{#define} statements. 4787The default is the arguments given to @code{AC_CONFIG_HEADER}; if that 4788macro was not called, @file{config.status} ignores this variable. 4789@end defvar 4790 4791These variables also allow you to write @file{Makefile} rules that 4792regenerate only some of the files. For example, in the dependencies 4793given above (@pxref{Automatic Remaking}), @file{config.status} is run 4794twice when @file{configure.in} has changed. If that bothers you, you 4795can make each run only regenerate the files for that rule: 4796 4797@example 4798@group 4799config.h: stamp-h 4800stamp-h: config.h.in config.status 4801 CONFIG_FILES= CONFIG_HEADERS=config.h ./config.status 4802 echo > stamp-h 4803 4804Makefile: Makefile.in config.status 4805 CONFIG_FILES=Makefile CONFIG_HEADERS= ./config.status 4806@end group 4807@end example 4808 4809@noindent 4810(If @file{configure.in} does not call @code{AC_CONFIG_HEADER}, there is 4811no need to set @code{CONFIG_HEADERS} in the @code{make} rules.) 4812 4813@node Questions, Upgrading, Invoking config.status, Top 4814@chapter Questions About Autoconf 4815 4816Several questions about Autoconf come up occasionally. Here some of them 4817are addressed. 4818 4819@menu 4820* Distributing:: Distributing @code{configure} scripts. 4821* Why GNU m4:: Why not use the standard @code{m4}? 4822* Bootstrapping:: Autoconf and GNU @code{m4} require each other? 4823* Why Not Imake:: Why GNU uses @code{configure} instead of Imake. 4824@end menu 4825 4826@node Distributing, Why GNU m4, Questions, Questions 4827@section Distributing @code{configure} Scripts 4828 4829@display 4830What are the restrictions on distributing @code{configure} 4831scripts that Autoconf generates? How does that affect my 4832programs that use them? 4833@end display 4834 4835There are no restrictions on how the configuration scripts that Autoconf 4836produces may be distributed or used. In Autoconf version 1, they were 4837covered by the GNU General Public License. We still encourage software 4838authors to distribute their work under terms like those of the GPL, but 4839doing so is not required to use Autoconf. 4840 4841Of the other files that might be used with @code{configure}, 4842@file{config.h.in} is under whatever copyright you use for your 4843@file{configure.in}, since it is derived from that file and from the 4844public domain file @file{acconfig.h}. @file{config.sub} and 4845@file{config.guess} have an exception to the GPL when they are used with 4846an Autoconf-generated @code{configure} script, which permits you to 4847distribute them under the same terms as the rest of your package. 4848@file{install-sh} is from the X Consortium and is not copyrighted. 4849 4850@node Why GNU m4, Bootstrapping, Distributing, Questions 4851@section Why Require GNU @code{m4}? 4852 4853@display 4854Why does Autoconf require GNU @code{m4}? 4855@end display 4856 4857Many @code{m4} implementations have hard-coded limitations on the size 4858and number of macros, which Autoconf exceeds. They also lack several 4859builtin macros that it would be difficult to get along without in a 4860sophisticated application like Autoconf, including: 4861 4862@example 4863builtin 4864indir 4865patsubst 4866__file__ 4867__line__ 4868@end example 4869 4870Since only software maintainers need to use Autoconf, and since GNU 4871@code{m4} is simple to configure and install, it seems reasonable to 4872require GNU @code{m4} to be installed also. Many maintainers of GNU and 4873other free software already have most of the GNU utilities installed, 4874since they prefer them. 4875 4876@node Bootstrapping, Why Not Imake, Why GNU m4, Questions 4877@section How Can I Bootstrap? 4878 4879@display 4880If Autoconf requires GNU @code{m4} and GNU @code{m4} has an 4881Autoconf @code{configure} script, how do I bootstrap? It seems 4882like a chicken and egg problem! 4883@end display 4884 4885This is a misunderstanding. Although GNU @code{m4} does come with a 4886@code{configure} script produced by Autoconf, Autoconf is not required 4887in order to run the script and install GNU @code{m4}. Autoconf is only 4888required if you want to change the @code{m4} @code{configure} script, 4889which few people have to do (mainly its maintainer). 4890 4891@node Why Not Imake, , Bootstrapping, Questions 4892@section Why Not Imake? 4893 4894@display 4895Why not use Imake instead of @code{configure} scripts? 4896@end display 4897 4898Several people have written addressing this question, so I include 4899adaptations of their explanations here. 4900 4901The following answer is based on one written by Richard Pixley: 4902 4903Autoconf generated scripts frequently work on machines which it has 4904never been set up to handle before. That is, it does a good job of 4905inferring a configuration for a new system. Imake cannot do this. 4906 4907Imake uses a common database of host specific data. For X11, this makes 4908sense because the distribution is made as a collection of tools, by one 4909central authority who has control over the database. 4910 4911GNU tools are not released this way. Each GNU tool has a maintainer; 4912these maintainers are scattered across the world. Using a common 4913database would be a maintenance nightmare. Autoconf may appear to be 4914this kind of database, but in fact it is not. Instead of listing host 4915dependencies, it lists program requirements. 4916 4917If you view the GNU suite as a collection of native tools, then the 4918problems are similar. But the GNU development tools can be configured 4919as cross tools in almost any host+target permutation. All of these 4920configurations can be installed concurrently. They can even be 4921configured to share host independent files across hosts. Imake doesn't 4922address these issues. 4923 4924Imake templates are a form of standardization. The GNU coding standards 4925address the same issues without necessarily imposing the same 4926restrictions. 4927 4928Here is some further explanation, written by Per Bothner: 4929 4930One of the advantages of Imake is that it easy to generate large 4931Makefiles using @code{cpp}'s @samp{#include} and macro mechanisms. 4932However, @code{cpp} is not programmable: it has limited conditional 4933facilities, and no looping. And @code{cpp} cannot inspect its 4934environment. 4935 4936All of these problems are solved by using @code{sh} instead of 4937@code{cpp}. The shell is fully programmable, has macro substitution, 4938can execute (or source) other shell scripts, and can inspect its 4939environment. 4940 4941Paul Eggert elaborates more: 4942 4943With Autoconf, installers need not assume that Imake itself is already 4944installed and working well. This may not seem like much of an advantage 4945to people who are accustomed to Imake. But on many hosts Imake is not 4946installed or the default installation is not working well, and requiring 4947Imake to install a package hinders the acceptance of that package on 4948those hosts. For example, the Imake template and configuration files 4949might not be installed properly on a host, or the Imake build procedure 4950might wrongly assume that all source files are in one big directory 4951tree, or the Imake configuration might assume one compiler whereas the 4952package or the installer needs to use another, or there might be a 4953version mismatch between the Imake expected by the package and the Imake 4954supported by the host. These problems are much rarer with Autoconf, 4955where each package comes with its own independent configuration 4956processor. 4957 4958Also, Imake often suffers from unexpected interactions between 4959@code{make} and the installer's C preprocessor. The fundamental problem 4960here is that the C preprocessor was designed to preprocess C programs, 4961not @file{Makefile}s. This is much less of a problem with Autoconf, 4962which uses the general-purpose preprocessor @code{m4}, and where the 4963package's author (rather than the installer) does the preprocessing in a 4964standard way. 4965 4966Finally, Mark Eichin notes: 4967 4968Imake isn't all that extensible, either. In order to add new features to 4969Imake, you need to provide your own project template, and duplicate most 4970of the features of the existing one. This means that for a sophisticated 4971project, using the vendor-provided Imake templates fails to provide any 4972leverage---since they don't cover anything that your own project needs 4973(unless it is an X11 program). 4974 4975On the other side, though: 4976 4977The one advantage that Imake has over @code{configure}: 4978@file{Imakefile}s tend to be much shorter (likewise, less redundant) 4979than @file{Makefile.in}s. There is a fix to this, however---at least 4980for the Kerberos V5 tree, we've modified things to call in common 4981@file{post.in} and @file{pre.in} @file{Makefile} fragments for the 4982entire tree. This means that a lot of common things don't have to be 4983duplicated, even though they normally are in @code{configure} setups. 4984 4985@node Upgrading, History, Questions, Top 4986@chapter Upgrading From Version 1 4987 4988Autoconf version 2 is mostly backward compatible with version 1. 4989However, it introduces better ways to do some things, and doesn't 4990support some of the ugly things in version 1. So, depending on how 4991sophisticated your @file{configure.in} files are, you might have to do 4992some manual work in order to upgrade to version 2. This chapter points 4993out some problems to watch for when upgrading. Also, perhaps your 4994@code{configure} scripts could benefit from some of the new features in 4995version 2; the changes are summarized in the file @file{NEWS} in the 4996Autoconf distribution. 4997 4998First, make sure you have GNU @code{m4} version 1.1 or higher installed, 4999preferably 1.3 or higher. Versions before 1.1 have bugs that prevent 5000them from working with Autoconf version 2. Versions 1.3 and later are 5001much faster than earlier versions, because as of version 1.3, GNU 5002@code{m4} has a more efficient implementation of diversions and can 5003freeze its internal state in a file that it can read back quickly. 5004 5005@menu 5006* Changed File Names:: Files you might rename. 5007* Changed Makefiles:: New things to put in @file{Makefile.in}. 5008* Changed Macros:: Macro calls you might replace. 5009* Invoking autoupdate:: Replacing old macro names in @code{configure.in}. 5010* Changed Results:: Changes in how to check test results. 5011* Changed Macro Writing:: Better ways to write your own macros. 5012@end menu 5013 5014@node Changed File Names, Changed Makefiles, Upgrading, Upgrading 5015@section Changed File Names 5016 5017If you have an @file{aclocal.m4} installed with Autoconf (as opposed to 5018in a particular package's source directory), you must rename it to 5019@file{acsite.m4}. @xref{Invoking autoconf}. 5020 5021If you distribute @file{install.sh} with your package, rename it to 5022@file{install-sh} so @code{make} builtin rules won't inadvertently 5023create a file called @file{install} from it. @code{AC_PROG_INSTALL} 5024looks for the script under both names, but it is best to use the new name. 5025 5026If you were using @file{config.h.top} or @file{config.h.bot}, you still 5027can, but you will have less clutter if you merge them into 5028@file{acconfig.h}. @xref{Invoking autoheader}. 5029 5030@node Changed Makefiles, Changed Macros, Changed File Names, Upgrading 5031@section Changed Makefiles 5032 5033Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in 5034your @file{Makefile.in} files, so they can take advantage of the values 5035of those variables in the environment when @code{configure} is run. 5036Doing this isn't necessary, but it's a convenience for users. 5037 5038Also add @samp{@@configure_input@@} in a comment to each non-@file{Makefile} 5039input file for 5040@code{AC_OUTPUT}, so that the output files will contain a comment saying 5041they were produced by @code{configure}. Automatically selecting the 5042right comment syntax for all the kinds of files that people call 5043@code{AC_OUTPUT} on became too much work. 5044 5045Add @file{config.log} and @file{config.cache} to the list of files you 5046remove in @code{distclean} targets. 5047 5048If you have the following in @file{Makefile.in}: 5049 5050@example 5051prefix = /usr/local 5052exec_prefix = $@{prefix@} 5053@end example 5054 5055@noindent 5056you must change it to: 5057 5058@example 5059prefix = @@prefix@@ 5060exec_prefix = @@exec_prefix@@ 5061@end example 5062 5063@noindent 5064The old behavior of replacing those variables without @samp{@@} 5065characters around them has been removed. 5066 5067@node Changed Macros, Invoking autoupdate, Changed Makefiles, Upgrading 5068@section Changed Macros 5069 5070Many of the macros were renamed in Autoconf version 2. You can still 5071use the old names, but the new ones are clearer, and it's easier to find 5072the documentation for them. @xref{Old Macro Names}, for a table showing 5073the new names for the old macros. Use the @code{autoupdate} program to 5074convert your @file{configure.in} to using the new macro names. 5075@xref{Invoking autoupdate}. 5076 5077Some macros have been superseded by similar ones that do the job better, 5078but are not call-compatible. If you get warnings about calling obsolete 5079macros while running @code{autoconf}, you may safely ignore them, but 5080your @code{configure} script will generally work better if you follow 5081the advice it prints about what to replace the obsolete macros with. In 5082particular, the mechanism for reporting the results of tests has 5083changed. If you were using @code{echo} or @code{AC_VERBOSE} (perhaps 5084via @code{AC_COMPILE_CHECK}), your @code{configure} script's output will 5085look better if you switch to @code{AC_MSG_CHECKING} and 5086@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best 5087in conjunction with cache variables. @xref{Caching Results}. 5088 5089@node Invoking autoupdate, Changed Results, Changed Macros, Upgrading 5090@section Using @code{autoupdate} to Modernize @code{configure} 5091 5092The @code{autoupdate} program updates a @file{configure.in} file that 5093calls Autoconf macros by their old names to use the current macro names. 5094In version 2 of Autoconf, most of the macros were renamed to use a more 5095uniform and descriptive naming scheme. @xref{Macro Names}, for a 5096description of the new scheme. Although the old names still work 5097(@pxref{Old Macro Names}, for a list of the old macro names and the 5098corresponding new names), you can make your @file{configure.in} files 5099more readable and make it easier to use the current Autoconf 5100documentation if you update them to use the new macro names. 5101 5102@evindex SIMPLE_BACKUP_SUFFIX 5103If given no arguments, @code{autoupdate} updates @file{configure.in}, 5104backing up the original version with the suffix @file{~} (or the value 5105of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is 5106set). If you give @code{autoupdate} an argument, it reads that file 5107instead of @file{configure.in} and writes the updated file to the 5108standard output. 5109 5110@noindent 5111@code{autoupdate} accepts the following options: 5112 5113@table @code 5114@item --help 5115@itemx -h 5116Print a summary of the command line options and exit. 5117 5118@item --macrodir=@var{dir} 5119@itemx -m @var{dir} 5120@evindex AC_MACRODIR 5121Look for the Autoconf macro files in directory @var{dir} instead of the 5122default installation directory. 5123You can also set the @code{AC_MACRODIR} 5124environment variable to a directory; this option overrides the 5125environment variable. 5126 5127@item --version 5128Print the version number of @code{autoupdate} and exit. 5129@end table 5130 5131@node Changed Results, Changed Macro Writing, Invoking autoupdate, Upgrading 5132@section Changed Results 5133 5134If you were checking the results of previous tests by examining the 5135shell variable @code{DEFS}, you need to switch to checking the values of 5136the cache variables for those tests. @code{DEFS} no longer exists while 5137@code{configure} is running; it is only created when generating output 5138files. This difference from version 1 is because properly quoting the 5139contents of that variable turned out to be too cumbersome and 5140inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache 5141Variable Names}. 5142 5143For example, here is a @file{configure.in} fragment written for Autoconf 5144version 1: 5145 5146@example 5147AC_HAVE_FUNCS(syslog) 5148case "$DEFS" in 5149*-DHAVE_SYSLOG*) ;; 5150*) # syslog is not in the default libraries. See if it's in some other. 5151 saved_LIBS="$LIBS" 5152 for lib in bsd socket inet; do 5153 AC_CHECKING(for syslog in -l$lib) 5154 LIBS="$saved_LIBS -l$lib" 5155 AC_HAVE_FUNCS(syslog) 5156 case "$DEFS" in 5157 *-DHAVE_SYSLOG*) break ;; 5158 *) ;; 5159 esac 5160 LIBS="$saved_LIBS" 5161 done ;; 5162esac 5163@end example 5164 5165Here is a way to write it for version 2: 5166 5167@example 5168AC_CHECK_FUNCS(syslog) 5169if test $ac_cv_func_syslog = no; then 5170 # syslog is not in the default libraries. See if it's in some other. 5171 for lib in bsd socket inet; do 5172 AC_CHECK_LIB($lib, syslog, [AC_DEFINE(HAVE_SYSLOG) 5173 LIBS="$LIBS $lib"; break]) 5174 done 5175fi 5176@end example 5177 5178If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding 5179backslashes before quotes, you need to remove them. It now works 5180predictably, and does not treat quotes (except backquotes) specially. 5181@xref{Setting Output Variables}. 5182 5183All of the boolean shell variables set by Autoconf macros now use 5184@samp{yes} for the true value. Most of them use @samp{no} for false, 5185though for backward compatibility some use the empty string instead. If 5186you were relying on a shell variable being set to something like 1 or 5187@samp{t} for true, you need to change your tests. 5188 5189@node Changed Macro Writing, , Changed Results, Upgrading 5190@section Changed Macro Writing 5191 5192When defining your own macros, you should now use @code{AC_DEFUN} 5193instead of @code{define}. @code{AC_DEFUN} automatically calls 5194@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} 5195do not interrupt other macros, to prevent nested @samp{checking@dots{}} 5196messages on the screen. There's no actual harm in continuing to use the 5197older way, but it's less convenient and attractive. @xref{Macro 5198Definitions}. 5199 5200You probably looked at the macros that came with Autoconf as a guide for 5201how to do things. It would be a good idea to take a look at the new 5202versions of them, as the style is somewhat improved and they take 5203advantage of some new features. 5204 5205If you were doing tricky things with undocumented Autoconf internals 5206(macros, variables, diversions), check whether you need to change 5207anything to account for changes that have been made. Perhaps you can 5208even use an officially supported technique in version 2 instead of 5209kludging. Or perhaps not. 5210 5211To speed up your locally written feature tests, add caching to them. 5212See whether any of your tests are of general enough usefulness to 5213encapsulate into macros that you can share. 5214 5215@node History, Old Macro Names, Upgrading, Top 5216@chapter History of Autoconf 5217 5218You may be wondering, Why was Autoconf originally written? How did it 5219get into its present form? (Why does it look like gorilla spit?) If 5220you're not wondering, then this chapter contains no information useful 5221to you, and you might as well skip it. If you @emph{are} wondering, 5222then let there be light@dots{} 5223 5224@menu 5225* Genesis:: Prehistory and naming of @code{configure}. 5226* Exodus:: The plagues of @code{m4} and Perl. 5227* Leviticus:: The priestly code of portability arrives. 5228* Numbers:: Growth and contributors. 5229* Deuteronomy:: Approaching the promises of easy configuration. 5230@end menu 5231 5232@node Genesis, Exodus, History, History 5233@section Genesis 5234 5235In June 1991 I was maintaining many of the GNU utilities for the Free 5236Software Foundation. As they were ported to more platforms and more 5237programs were added, the number of @samp{-D} options that users had to 5238select in the @file{Makefile} (around 20) became burdensome. Especially 5239for me---I had to test each new release on a bunch of different systems. 5240So I wrote a little shell script to guess some of the correct settings 5241for the fileutils package, and released it as part of fileutils 2.0. 5242That @code{configure} script worked well enough that the next month I 5243adapted it (by hand) to create similar @code{configure} scripts for 5244several other GNU utilities packages. Brian Berliner also adapted one 5245of my scripts for his CVS revision control system. 5246 5247Later that summer, I learned that Richard Stallman and Richard Pixley 5248were developing similar scripts to use in the GNU compiler tools; so I 5249adapted my @code{configure} scripts to support their evolving interface: 5250using the file name @file{Makefile.in} as the templates; adding 5251@samp{+srcdir}, the first option (of many); and creating 5252@file{config.status} files. 5253 5254@node Exodus, Leviticus, Genesis, History 5255@section Exodus 5256 5257As I got feedback from users, I incorporated many improvements, using 5258Emacs to search and replace, cut and paste, similar changes in each of 5259the scripts. As I adapted more GNU utilities packages to use 5260@code{configure} scripts, updating them all by hand became impractical. 5261Rich Murphey, the maintainer of the GNU graphics utilities, sent me mail 5262saying that the @code{configure} scripts were great, and asking if I had 5263a tool for generating them that I could send him. No, I thought, but 5264I should! So I started to work out how to generate them. And the 5265journey from the slavery of hand-written @code{configure} scripts to the 5266abundance and ease of Autoconf began. 5267 5268Cygnus @code{configure}, which was being developed at around that time, 5269is table driven; it is meant to deal mainly with a discrete number of 5270system types with a small number of mainly unguessable features (such as 5271details of the object file format). The automatic configuration system 5272that Brian Fox had developed for Bash takes a similar approach. For 5273general use, it seems to me a hopeless cause to try to maintain an 5274up-to-date database of which features each variant of each operating 5275system has. It's easier and more reliable to check for most features on 5276the fly---especially on hybrid systems that people have hacked on 5277locally or that have patches from vendors installed. 5278 5279I considered using an architecture similar to that of Cygnus 5280@code{configure}, where there is a single @code{configure} script that 5281reads pieces of @file{configure.in} when run. But I didn't want to have 5282to distribute all of the feature tests with every package, so I settled 5283on having a different @code{configure} made from each 5284@file{configure.in} by a preprocessor. That approach also offered more 5285control and flexibility. 5286 5287I looked briefly into using the Metaconfig package, by Larry Wall, 5288Harlan Stenn, and Raphael Manfredi, but I decided not to for several 5289reasons. The @code{Configure} scripts it produces are interactive, 5290which I find quite inconvenient; I didn't like the ways it checked for 5291some features (such as library functions); I didn't know that it was 5292still being maintained, and the @code{Configure} scripts I had 5293seen didn't work on many modern systems (such as System V R4 and NeXT); 5294it wasn't very flexible in what it could do in response to a feature's 5295presence or absence; I found it confusing to learn; and it was too big 5296and complex for my needs (I didn't realize then how much Autoconf would 5297eventually have to grow). 5298 5299I considered using Perl to generate my style of @code{configure} scripts, 5300but decided that @code{m4} was better suited to the job of simple 5301textual substitutions: it gets in the way less, because output is 5302implicit. Plus, everyone already has it. (Initially I didn't rely on 5303the GNU extensions to @code{m4}.) Also, some of my friends at the 5304University of Maryland had recently been putting @code{m4} front ends on 5305several programs, including @code{tvtwm}, and I was interested in trying 5306out a new language. 5307 5308@node Leviticus, Numbers, Exodus, History 5309@section Leviticus 5310 5311Since my @code{configure} scripts determine the system's capabilities 5312automatically, with no interactive user intervention, I decided to call 5313the program that generates them Autoconfig. But with a version number 5314tacked on, that name would be too long for old UNIX file systems, so 5315I shortened it to Autoconf. 5316 5317In the fall of 1991 I called together a group of fellow questers after 5318the Holy Grail of portability (er, that is, alpha testers) to give me 5319feedback as I encapsulated pieces of my handwritten scripts in @code{m4} 5320macros and continued to add features and improve the techniques used in 5321the checks. Prominent among the testers were 5322@ifinfo 5323Franc,ois 5324@end ifinfo 5325@tex 5326Fran\c cois 5327@end tex 5328Pinard, who came up with the idea of making an @file{autoconf} shell 5329script to run @code{m4} and check for unresolved macro calls; Richard 5330Pixley, who suggested running the compiler instead of searching the file 5331system to find include files and symbols, for more accurate results; 5332Karl Berry, who got Autoconf to configure @TeX{} and added the 5333macro index to the documentation; and Ian Taylor, who added support for 5334creating a C header file as an alternative to putting @samp{-D} options 5335in a @file{Makefile}, so he could use Autoconf for his UUCP package. The 5336alpha testers cheerfully adjusted their files again and again as the 5337names and calling conventions of the Autoconf macros changed from 5338release to release. They all contributed many specific checks, great 5339ideas, and bug fixes. 5340 5341@node Numbers, Deuteronomy, Leviticus, History 5342@section Numbers 5343 5344In July 1992, after months of alpha testing, I released Autoconf 1.0, 5345and converted many GNU packages to use it. I was surprised by how 5346positive the reaction to it was. More people started using it than I 5347could keep track of, including people working on software that wasn't 5348part of the GNU Project (such as TCL, FSP, and Kerberos V5). 5349Autoconf continued to improve rapidly, as many people using the 5350@code{configure} scripts reported problems they encountered. 5351 5352Autoconf turned out to be a good torture test for @code{m4} 5353implementations. UNIX @code{m4} started to dump core because of the 5354length of the macros that Autoconf defined, and several bugs showed up 5355in GNU @code{m4} as well. Eventually, we realized that we needed to use 5356some features that only GNU @code{m4} has. 4.3BSD @code{m4}, in 5357particular, has an impoverished set of builtin macros; the System V 5358version is better, but still doesn't provide everything we need. 5359 5360More development occurred as people put Autoconf under more stresses 5361(and to uses I hadn't anticipated). Karl Berry added checks for X11. 5362david zuhn contributed C++ support. 5363@ifinfo 5364Franc,ois 5365@end ifinfo 5366@tex 5367Fran\c cois 5368@end tex 5369Pinard made it diagnose invalid arguments. Jim Blandy bravely coerced 5370it into configuring GNU Emacs, laying the groundwork for several later 5371improvements. Roland McGrath got it to configure the GNU C Library, 5372wrote the @code{autoheader} script to automate the creation of C header 5373file templates, and added a @samp{--verbose} option to @code{configure}. 5374Noah Friedman added the @samp{--macrodir} option and @code{AC_MACRODIR} 5375environment variable. (He also coined the term @dfn{autoconfiscate} to 5376mean ``adapt a software package to use Autoconf''.) Roland and Noah 5377improved the quoting protection in @code{AC_DEFINE} and fixed many bugs, 5378especially when I got sick of dealing with portability problems from 5379February through June, 1993. 5380 5381@node Deuteronomy, , Numbers, History 5382@section Deuteronomy 5383 5384A long wish list for major features had accumulated, and the effect of 5385several years of patching by various people had left some residual 5386cruft. In April 1994, while working for Cygnus Support, I began a major 5387revision of Autoconf. I added most of the features of the Cygnus 5388@code{configure} that Autoconf had lacked, largely by adapting the 5389relevant parts of Cygnus @code{configure} with the help of david zuhn 5390and Ken Raeburn. These features include support for using 5391@file{config.sub}, @file{config.guess}, @samp{--host}, and 5392@samp{--target}; making links to files; and running @code{configure} 5393scripts in subdirectories. Adding these features enabled Ken to convert 5394GNU @code{as}, and Rob Savoye to convert DejaGNU, to using Autoconf. 5395 5396I added more features in response to other peoples' requests. Many 5397people had asked for @code{configure} scripts to share the results of 5398the checks between runs, because (particularly when configuring a large 5399source tree, like Cygnus does) they were frustratingly slow. Mike 5400Haertel suggested adding site-specific initialization scripts. People 5401distributing software that had to unpack on MS-DOS asked for a way to 5402override the @file{.in} extension on the file names, which produced file 5403names like @file{config.h.in} containing two dots. Jim Avera did an 5404extensive examination of the problems with quoting in @code{AC_DEFINE} 5405and @code{AC_SUBST}; his insights led to significant improvements. 5406Richard Stallman asked that compiler output be sent to @file{config.log} 5407instead of @file{/dev/null}, to help people debug the Emacs 5408@code{configure} script. 5409 5410I made some other changes because of my dissatisfaction with the quality 5411of the program. I made the messages showing results of the checks less 5412ambiguous, always printing a result. I regularized the names of the 5413macros and cleaned up coding style inconsistencies. I added some 5414auxiliary utilities that I had developed to help convert source code 5415packages to use Autoconf. With the help of 5416@ifinfo 5417Franc,ois 5418@end ifinfo 5419@tex 5420Fran\c cois 5421@end tex 5422Pinard, I made the macros not interrupt each others' messages. 5423(That feature revealed some performance bottlenecks in GNU @code{m4}, 5424which he hastily corrected!) 5425I reorganized the documentation around problems people want to solve. 5426And I began a testsuite, because experience 5427had shown that Autoconf has a pronounced tendency to regress when we 5428change it. 5429 5430Again, several alpha testers gave invaluable feedback, especially 5431@ifinfo 5432Franc,ois 5433@end ifinfo 5434@tex 5435Fran\c cois 5436@end tex 5437Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, and Mark Eichin. 5438 5439Finally, version 2.0 was ready. And there was much rejoicing. 5440(And I have free time again. I think. Yeah, right.) 5441 5442@node Old Macro Names, Environment Variable Index, History, Top 5443@chapter Old Macro Names 5444 5445In version 2 of Autoconf, most of the macros were renamed to use a more 5446uniform and descriptive naming scheme. Here are the old names of the 5447macros that were renamed, followed by the current names of those macros. 5448Although the old names are still accepted by the @code{autoconf} program 5449for backward compatibility, the old names are considered obsolete. 5450@xref{Macro Names}, for a description of the new naming scheme. 5451 5452@table @code 5453@item AC_ALLOCA 5454@maindex ALLOCA 5455@code{AC_FUNC_ALLOCA} 5456@item AC_ARG_ARRAY 5457@maindex ARG_ARRAY 5458removed because of limited usefulness 5459@item AC_CHAR_UNSIGNED 5460@maindex CHAR_UNSIGNED 5461@code{AC_C_CHAR_UNSIGNED} 5462@item AC_CONST 5463@maindex CONST 5464@code{AC_C_CONST} 5465@item AC_CROSS_CHECK 5466@maindex CROSS_CHECK 5467@code{AC_C_CROSS} 5468@item AC_ERROR 5469@maindex ERROR 5470@code{AC_MSG_ERROR} 5471@item AC_FIND_X 5472@maindex FIND_X 5473@code{AC_PATH_X} 5474@item AC_FIND_XTRA 5475@maindex FIND_XTRA 5476@code{AC_PATH_XTRA} 5477@item AC_FUNC_CHECK 5478@maindex FUNC_CHECK 5479@code{AC_CHECK_FUNC} 5480@item AC_GCC_TRADITIONAL 5481@maindex GCC_TRADITIONAL 5482@code{AC_PROG_GCC_TRADITIONAL} 5483@item AC_GETGROUPS_T 5484@maindex GETGROUPS_T 5485@code{AC_TYPE_GETGROUPS} 5486@item AC_GETLOADAVG 5487@maindex GETLOADAVG 5488@code{AC_FUNC_GETLOADAVG} 5489@item AC_HAVE_FUNCS 5490@maindex HAVE_FUNCS 5491@code{AC_CHECK_FUNCS} 5492@item AC_HAVE_HEADERS 5493@maindex HAVE_HEADERS 5494@code{AC_CHECK_HEADERS} 5495@item AC_HAVE_POUNDBANG 5496@maindex HAVE_POUNDBANG 5497@code{AC_SYS_INTERPRETER} (different calling convention) 5498@item AC_HEADER_CHECK 5499@maindex HEADER_CHECK 5500@code{AC_CHECK_HEADER} 5501@item AC_HEADER_EGREP 5502@maindex HEADER_EGREP 5503@code{AC_EGREP_HEADER} 5504@item AC_INLINE 5505@maindex INLINE 5506@code{AC_C_INLINE} 5507@item AC_LN_S 5508@maindex LN_S 5509@code{AC_PROG_LN_S} 5510@item AC_LONG_DOUBLE 5511@maindex LONG_DOUBLE 5512@code{AC_C_LONG_DOUBLE} 5513@item AC_LONG_FILE_NAMES 5514@maindex LONG_FILE_NAMES 5515@code{AC_SYS_LONG_FILE_NAMES} 5516@item AC_MAJOR_HEADER 5517@maindex MAJOR_HEADER 5518@code{AC_HEADER_MAJOR} 5519@item AC_MINUS_C_MINUS_O 5520@maindex MINUS_C_MINUS_O 5521@code{AC_PROG_CC_C_O} 5522@item AC_MMAP 5523@maindex MMAP 5524@code{AC_FUNC_MMAP} 5525@item AC_MODE_T 5526@maindex MODE_T 5527@code{AC_TYPE_MODE_T} 5528@item AC_OFF_T 5529@maindex OFF_T 5530@code{AC_TYPE_OFF_T} 5531@item AC_PID_T 5532@maindex PID_T 5533@code{AC_TYPE_PID_T} 5534@item AC_PREFIX 5535@maindex PREFIX 5536@code{AC_PREFIX_PROGRAM} 5537@item AC_PROGRAMS_CHECK 5538@maindex PROGRAMS_CHECK 5539@code{AC_CHECK_PROGS} 5540@item AC_PROGRAMS_PATH 5541@maindex PROGRAMS_PATH 5542@code{AC_PATH_PROGS} 5543@item AC_PROGRAM_CHECK 5544@maindex PROGRAM_CHECK 5545@code{AC_CHECK_PROG} 5546@item AC_PROGRAM_EGREP 5547@maindex PROGRAM_EGREP 5548@code{AC_EGREP_CPP} 5549@item AC_PROGRAM_PATH 5550@maindex PROGRAM_PATH 5551@code{AC_PATH_PROG} 5552@item AC_REMOTE_TAPE 5553@maindex REMOTE_TAPE 5554removed because of limited usefulness 5555@item AC_RESTARTABLE_SYSCALLS 5556@maindex RESTARTABLE_SYSCALLS 5557@code{AC_SYS_RESTARTABLE_SYSCALLS} 5558@item AC_RETSIGTYPE 5559@maindex RETSIGTYPE 5560@code{AC_TYPE_SIGNAL} 5561@item AC_RSH 5562@maindex RSH 5563removed because of limited usefulness 5564@item AC_SETVBUF_REVERSED 5565@maindex SETVBUF_REVERSED 5566@code{AC_FUNC_SETVBUF_REVERSED} 5567@item AC_SET_MAKE 5568@maindex SET_MAKE 5569@code{AC_PROG_MAKE_SET} 5570@item AC_SIZEOF_TYPE 5571@maindex SIZEOF_TYPE 5572@code{AC_CHECK_SIZEOF} 5573@item AC_SIZE_T 5574@maindex SIZE_T 5575@code{AC_TYPE_SIZE_T} 5576@item AC_STAT_MACROS_BROKEN 5577@maindex STAT_MACROS_BROKEN 5578@code{AC_HEADER_STAT} 5579@item AC_STDC_HEADERS 5580@maindex STDC_HEADERS 5581@code{AC_HEADER_STDC} 5582@item AC_STRCOLL 5583@maindex STRCOLL 5584@code{AC_FUNC_STRCOLL} 5585@item AC_ST_BLKSIZE 5586@maindex ST_BLKSIZE 5587@code{AC_STRUCT_ST_BLKSIZE} 5588@item AC_ST_BLOCKS 5589@maindex ST_BLOCKS 5590@code{AC_STRUCT_ST_BLOCKS} 5591@item AC_ST_RDEV 5592@maindex ST_RDEV 5593@code{AC_STRUCT_ST_RDEV} 5594@item AC_SYS_SIGLIST_DECLARED 5595@maindex SYS_SIGLIST_DECLARED 5596@code{AC_DECL_SYS_SIGLIST} 5597@item AC_TEST_CPP 5598@maindex TEST_CPP 5599@code{AC_TRY_CPP} 5600@item AC_TEST_PROGRAM 5601@maindex TEST_PROGRAM 5602@code{AC_TRY_RUN} 5603@item AC_TIMEZONE 5604@maindex TIMEZONE 5605@code{AC_STRUCT_TIMEZONE} 5606@item AC_TIME_WITH_SYS_TIME 5607@maindex TIME_WITH_SYS_TIME 5608@code{AC_HEADER_TIME} 5609@item AC_UID_T 5610@maindex UID_T 5611@code{AC_TYPE_UID_T} 5612@item AC_UTIME_NULL 5613@maindex UTIME_NULL 5614@code{AC_FUNC_UTIME_NULL} 5615@item AC_VFORK 5616@maindex VFORK 5617@code{AC_FUNC_VFORK} 5618@item AC_VPRINTF 5619@maindex VPRINTF 5620@code{AC_FUNC_VPRINTF} 5621@item AC_WAIT3 5622@maindex WAIT3 5623@code{AC_FUNC_WAIT3} 5624@item AC_WARN 5625@maindex WARN 5626@code{AC_MSG_WARN} 5627@item AC_WORDS_BIGENDIAN 5628@maindex WORDS_BIGENDIAN 5629@code{AC_C_BIGENDIAN} 5630@item AC_YYTEXT_POINTER 5631@maindex YYTEXT_POINTER 5632@code{AC_DECL_YYTEXT} 5633@end table 5634 5635@node Environment Variable Index, Output Variable Index, Old Macro Names, Top 5636@unnumbered Environment Variable Index 5637 5638This is an alphabetical list of the environment variables that Autoconf 5639checks. 5640 5641@printindex ev 5642 5643@node Output Variable Index, Preprocessor Symbol Index, Environment Variable Index, Top 5644@unnumbered Output Variable Index 5645 5646This is an alphabetical list of the variables that Autoconf can 5647substitute into files that it creates, typically one or more 5648@file{Makefile}s. @xref{Setting Output Variables}, for more information on how 5649this is done. 5650 5651@printindex ov 5652 5653@node Preprocessor Symbol Index, Macro Index, Output Variable Index, Top 5654@unnumbered Preprocessor Symbol Index 5655 5656This is an alphabetical list of the C preprocessor symbols that the 5657Autoconf macros define. To work with Autoconf, C source code needs to 5658use these names in @code{#if} directives. 5659 5660@printindex cv 5661 5662@node Macro Index, , Preprocessor Symbol Index, Top 5663@unnumbered Macro Index 5664 5665This is an alphabetical list of the Autoconf macros. To make the list 5666easier to use, the macros are listed without their preceding @samp{AC_}. 5667 5668@printindex ma 5669 5670@contents 5671@bye 5672