1\input texinfo @c -*-texinfo-*- 2@comment ======================================================== 3@comment %**start of header 4@setfilename autoconf.info 5@include version.texi 6@settitle Autoconf 7@setchapternewpage odd 8@ifnothtml 9@setcontentsaftertitlepage 10@end ifnothtml 11@finalout 12 13@c @ovar(ARG, DEFAULT) 14@c ------------------- 15@c The ARG is an optional argument. To be used for macro arguments in 16@c their documentation (@defmac). 17@macro ovar{varname} 18@r{[}@var{\varname\}@r{]} 19@end macro 20 21@c @dvar(ARG, DEFAULT) 22@c ------------------- 23@c The ARG is an optional argument, defaulting to DEFAULT. To be used 24@c for macro arguments in their documentation (@defmac). 25@macro dvar{varname, default} 26@r{[}@var{\varname\} = @samp{\default\}@r{]} 27@end macro 28 29@c Handling the indexes with Texinfo yields several different problems. 30@c 31@c Because we want to drop out the AC_ part of the macro names in the 32@c printed manual, but not in the other outputs, we need a layer above 33@c the usual @acindex{} etc. That's why we first define indexes such as 34@c acx meant to become the macro @acindex. First of all, using ``ac_'' 35@c does not work with makeinfo, and using ``ac1'' doesn't work with TeX. 36@c So use something more regular ``acx''. Then you finish with a printed 37@c index saying ``index is not existent''. Of course: you ought to use 38@c two letters :( So you use capitals. 39@c 40@c Second, when defining a macro in the TeX world, following spaces are 41@c eaten. But then, since we embed @acxindex commands that use the end 42@c of line as an end marker, the whole things wrecks itself. So make 43@c sure you do *force* an additional end of line, add a ``@c''. 44@c 45@c Finally, you might want to get rid of TeX expansion, using --expand 46@c with texi2dvi. But then you wake up an old problem: we use macros 47@c in @defmac etc. where TeX does perform the expansion, but not makeinfo. 48 49@c Define an environment variable index. 50@defcodeindex ev 51@c Define an output variable index. 52@defcodeindex ov 53@c Define a CPP variable index. 54@defcodeindex cv 55@c Define an Autoconf macro index that @defmac doesn't write to. 56@defcodeindex AC 57@c Define an Autotest macro index that @defmac doesn't write to. 58@defcodeindex AT 59@c Define an M4sugar macro index that @defmac doesn't write to. 60@defcodeindex MS 61@c Define an index for *foreign* programs: `mv' etc. Used for the 62@c portability sections and so on. 63@defindex pr 64 65@c shortindexflag 66@c -------------- 67@c Shall we factor AC_ out of the Autoconf macro index etc.? 68@iftex 69@set shortindexflag 70@end iftex 71 72@c @acindex{MACRO} 73@c --------------- 74@c Registering an AC_\MACRO\. 75@ifset shortindexflag 76@macro acindex{macro} 77@ACindex \macro\ 78@c 79@end macro 80@end ifset 81@ifclear shortindexflag 82@macro acindex{macro} 83@ACindex AC_\macro\ 84@end macro 85@end ifclear 86 87@c @ahindex{MACRO} 88@c --------------- 89@c Registering an AH_\MACRO\. 90@macro ahindex{macro} 91@ACindex AH_\macro\ 92@c 93@end macro 94 95@c @asindex{MACRO} 96@c --------------- 97@c Registering an AS_\MACRO\. 98@ifset shortindexflag 99@macro asindex{macro} 100@MSindex \macro\ 101@c 102@end macro 103@end ifset 104@ifclear shortindexflag 105@macro asindex{macro} 106@MSindex AS_\macro\ 107@end macro 108@end ifclear 109 110@c @atindex{MACRO} 111@c --------------- 112@c Registering an AT_\MACRO\. 113@ifset shortindexflag 114@macro atindex{macro} 115@ATindex \macro\ 116@c 117@end macro 118@end ifset 119@ifclear shortindexflag 120@macro atindex{macro} 121@ATindex AT_\macro\ 122@end macro 123@end ifclear 124 125@c @auindex{MACRO} 126@c --------------- 127@c Registering an AU_\MACRO\. 128@macro auindex{macro} 129@ACindex AU_\macro\ 130@c 131@end macro 132 133@c @hdrindex{MACRO} 134@c ---------------- 135@c Indexing a header. 136@macro hdrindex{macro} 137@prindex @file{\macro\} 138@c 139@end macro 140 141@c @msindex{MACRO} 142@c --------------- 143@c Registering an m4_\MACRO\. 144@ifset shortindexflag 145@macro msindex{macro} 146@MSindex \macro\ 147@c 148@end macro 149@end ifset 150@ifclear shortindexflag 151@macro msindex{macro} 152@MSindex m4_\macro\ 153@end macro 154@end ifclear 155 156 157@c Define an index for functions: `alloca' etc. Used for the 158@c portability sections and so on. We can't use `fn' (aka `fnindex), 159@c since `@defmac' goes into it => we'd get all the macros too. 160 161@c FIXME: Aaarg! It seems there are too many indices for TeX :( 162@c 163@c ! No room for a new @write . 164@c l.112 @defcodeindex fu 165@c 166@c so don't define yet another one :( Just put some tags before each 167@c @prindex which is actually a @funindex. 168@c 169@c @defcodeindex fu 170@c 171@c 172@c @c Put the programs and functions into their own index. 173@c @syncodeindex fu pr 174 175@comment %**end of header 176@comment ======================================================== 177 178@copying 179 180This manual is for @acronym{GNU} Autoconf 181(version @value{VERSION}, @value{UPDATED}), 182a package for creating scripts to configure source code packages using 183templates and an M4 macro package. 184 185Copyright @copyright{} 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 1862001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. 187 188@quotation 189Permission is granted to copy, distribute and/or modify this document 190under the terms of the @acronym{GNU} Free Documentation License, 191Version 1.2 or any later version published by the Free Software 192Foundation; with no Invariant Sections, with the Front-Cover texts 193being ``A @acronym{GNU} Manual,'' and with the Back-Cover Texts as in 194(a) below. A copy of the license is included in the section entitled 195``@acronym{GNU} Free Documentation License.'' 196 197(a) The FSF's Back-Cover Text is: ``You have freedom to copy and 198modify this @acronym{GNU} Manual, like @acronym{GNU} software. Copies 199published by the Free Software Foundation raise funds for 200@acronym{GNU} development.'' 201@end quotation 202@end copying 203 204 205 206@dircategory Software development 207@direntry 208* Autoconf: (autoconf). Create source code configuration scripts. 209@end direntry 210 211@dircategory Individual utilities 212@direntry 213* autoscan: (autoconf)autoscan Invocation. 214 Semi-automatic @file{configure.ac} writing 215* ifnames: (autoconf)ifnames Invocation. Listing conditionals in source. 216* autoconf: (autoconf)autoconf Invocation. 217 How to create configuration scripts 218* autoreconf: (autoconf)autoreconf Invocation. 219 Remaking multiple @command{configure} scripts 220* autoheader: (autoconf)autoheader Invocation. 221 How to create configuration templates 222* autom4te: (autoconf)autom4te Invocation. 223 The Autoconf executables backbone 224* configure: (autoconf)configure Invocation. Configuring a package. 225* autoupdate: (autoconf)autoupdate Invocation. 226 Automatic update of @file{configure.ac} 227* config.status: (autoconf)config.status Invocation. Recreating configurations. 228* testsuite: (autoconf)testsuite Invocation. Running an Autotest test suite. 229@end direntry 230 231@titlepage 232@title Autoconf 233@subtitle Creating Automatic Configuration Scripts 234@subtitle for version @value{VERSION}, @value{UPDATED} 235@author David MacKenzie 236@author Ben Elliston 237@author Akim Demaille 238@page 239@vskip 0pt plus 1filll 240@insertcopying 241@end titlepage 242 243@contents 244 245 246@ifnottex 247@node Top 248@top Autoconf 249@insertcopying 250@end ifnottex 251 252@c The master menu, created with texinfo-master-menu, goes here. 253 254@menu 255* Introduction:: Autoconf's purpose, strengths, and weaknesses 256* The GNU Build System:: A set of tools for portable software packages 257* Making configure Scripts:: How to organize and produce Autoconf scripts 258* Setup:: Initialization and output 259* Existing Tests:: Macros that check for particular features 260* Writing Tests:: How to write new feature checks 261* Results:: What to do with results from feature checks 262* Programming in M4:: Layers on top of which Autoconf is written 263* Writing Autoconf Macros:: Adding new macros to Autoconf 264* Portable Shell:: Shell script portability pitfalls 265* Portable Make:: Makefile portability pitfalls 266* Portable C and C++:: C and C++ portability pitfalls 267* Manual Configuration:: Selecting features that can't be guessed 268* Site Configuration:: Local defaults for @command{configure} 269* Running configure Scripts:: How to use the Autoconf output 270* config.status Invocation:: Recreating a configuration 271* Obsolete Constructs:: Kept for backward compatibility 272* Using Autotest:: Creating portable test suites 273* FAQ:: Frequent Autoconf Questions, with answers 274* History:: History of Autoconf 275* Copying This Manual:: How to make copies of this manual 276* Indices:: Indices of symbols, concepts, etc. 277 278@detailmenu 279 --- The Detailed Node Listing --- 280 281The @acronym{GNU} Build System 282 283* Automake:: Escaping makefile hell 284* Gnulib:: The @acronym{GNU} portability library 285* Libtool:: Building libraries portably 286* Pointers:: More info on the @acronym{GNU} build system 287 288Making @command{configure} Scripts 289 290* Writing configure.ac:: What to put in an Autoconf input file 291* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 292* ifnames Invocation:: Listing the conditionals in source code 293* autoconf Invocation:: How to create configuration scripts 294* autoreconf Invocation:: Remaking multiple @command{configure} scripts 295 296Writing @file{configure.ac} 297 298* Shell Script Compiler:: Autoconf as solution of a problem 299* Autoconf Language:: Programming in Autoconf 300* configure.ac Layout:: Standard organization of @file{configure.ac} 301 302Initialization and Output Files 303 304* Initializing configure:: Option processing etc. 305* Notices:: Copyright, version numbers in @command{configure} 306* Input:: Where Autoconf should find files 307* Output:: Outputting results from the configuration 308* Configuration Actions:: Preparing the output based on results 309* Configuration Files:: Creating output files 310* Makefile Substitutions:: Using output variables in makefiles 311* Configuration Headers:: Creating a configuration header file 312* Configuration Commands:: Running arbitrary instantiation commands 313* Configuration Links:: Links depending on the configuration 314* Subdirectories:: Configuring independent packages together 315* Default Prefix:: Changing the default installation prefix 316 317Substitutions in Makefiles 318 319* Preset Output Variables:: Output variables that are always set 320* Installation Directory Variables:: Other preset output variables 321* Changed Directory Variables:: Warnings about @file{datarootdir} 322* Build Directories:: Supporting multiple concurrent compiles 323* Automatic Remaking:: Makefile rules for configuring 324 325Configuration Header Files 326 327* Header Templates:: Input for the configuration headers 328* autoheader Invocation:: How to create configuration templates 329* Autoheader Macros:: How to specify CPP templates 330 331Existing Tests 332 333* Common Behavior:: Macros' standard schemes 334* Alternative Programs:: Selecting between alternative programs 335* Files:: Checking for the existence of files 336* Libraries:: Library archives that might be missing 337* Library Functions:: C library functions that might be missing 338* Header Files:: Header files that might be missing 339* Declarations:: Declarations that may be missing 340* Structures:: Structures or members that might be missing 341* Types:: Types that might be missing 342* Compilers and Preprocessors:: Checking for compiling programs 343* System Services:: Operating system services 344* Posix Variants:: Special kludges for specific Posix variants 345* Erlang Libraries:: Checking for the existence of Erlang libraries 346 347Common Behavior 348 349* Standard Symbols:: Symbols defined by the macros 350* Default Includes:: Includes used by the generic macros 351 352Alternative Programs 353 354* Particular Programs:: Special handling to find certain programs 355* Generic Programs:: How to find other programs 356 357Library Functions 358 359* Function Portability:: Pitfalls with usual functions 360* Particular Functions:: Special handling to find certain functions 361* Generic Functions:: How to find other functions 362 363Header Files 364 365* Header Portability:: Collected knowledge on common headers 366* Particular Headers:: Special handling to find certain headers 367* Generic Headers:: How to find other headers 368 369Declarations 370 371* Particular Declarations:: Macros to check for certain declarations 372* Generic Declarations:: How to find other declarations 373 374Structures 375 376* Particular Structures:: Macros to check for certain structure members 377* Generic Structures:: How to find other structure members 378 379Types 380 381* Particular Types:: Special handling to find certain types 382* Generic Types:: How to find other types 383 384Compilers and Preprocessors 385 386* Specific Compiler Characteristics:: Some portability issues 387* Generic Compiler Characteristics:: Language independent tests and features 388* C Compiler:: Checking its characteristics 389* C++ Compiler:: Likewise 390* Objective C Compiler:: Likewise 391* Erlang Compiler and Interpreter:: Likewise 392* Fortran Compiler:: Likewise 393 394Writing Tests 395 396* Language Choice:: Selecting which language to use for testing 397* Writing Test Programs:: Forging source files for compilers 398* Running the Preprocessor:: Detecting preprocessor symbols 399* Running the Compiler:: Detecting language or header features 400* Running the Linker:: Detecting library features 401* Runtime:: Testing for runtime features 402* Systemology:: A zoology of operating systems 403* Multiple Cases:: Tests for several possible values 404 405Writing Test Programs 406 407* Guidelines:: General rules for writing test programs 408* Test Functions:: Avoiding pitfalls in test programs 409* Generating Sources:: Source program boilerplate 410 411Results of Tests 412 413* Defining Symbols:: Defining C preprocessor symbols 414* Setting Output Variables:: Replacing variables in output files 415* Special Chars in Variables:: Characters to beware of in variables 416* Caching Results:: Speeding up subsequent @command{configure} runs 417* Printing Messages:: Notifying @command{configure} users 418 419Caching Results 420 421* Cache Variable Names:: Shell variables used in caches 422* Cache Files:: Files @command{configure} uses for caching 423* Cache Checkpointing:: Loading and saving the cache file 424 425Programming in M4 426 427* M4 Quotation:: Protecting macros from unwanted expansion 428* Using autom4te:: The Autoconf executables backbone 429* Programming in M4sugar:: Convenient pure M4 macros 430* Programming in M4sh:: Common shell Constructs 431* File Descriptor Macros:: File descriptor macros for input and output 432 433M4 Quotation 434 435* Active Characters:: Characters that change the behavior of M4 436* One Macro Call:: Quotation and one macro call 437* Quotation and Nested Macros:: Macros calling macros 438* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 439* Quadrigraphs:: Another way to escape special characters 440* Quotation Rule Of Thumb:: One parenthesis, one quote 441 442Using @command{autom4te} 443 444* autom4te Invocation:: A @acronym{GNU} M4 wrapper 445* Customizing autom4te:: Customizing the Autoconf package 446 447Programming in M4sugar 448 449* Redefined M4 Macros:: M4 builtins changed in M4sugar 450* Looping constructs:: Iteration in M4 451* Evaluation Macros:: More quotation and evaluation control 452* Text processing Macros:: String manipulation in M4 453* Forbidden Patterns:: Catching unexpanded macros 454 455Writing Autoconf Macros 456 457* Macro Definitions:: Basic format of an Autoconf macro 458* Macro Names:: What to call your new macros 459* Reporting Messages:: Notifying @command{autoconf} users 460* Dependencies Between Macros:: What to do when macros depend on other macros 461* Obsoleting Macros:: Warning about old ways of doing things 462* Coding Style:: Writing Autoconf macros @`a la Autoconf 463 464Dependencies Between Macros 465 466* Prerequisite Macros:: Ensuring required information 467* Suggested Ordering:: Warning about possible ordering problems 468* One-Shot Macros:: Ensuring a macro is called only once 469 470Portable Shell Programming 471 472* Shellology:: A zoology of shells 473* Here-Documents:: Quirks and tricks 474* File Descriptors:: FDs and redirections 475* File System Conventions:: File names 476* Shell Substitutions:: Variable and command expansions 477* Assignments:: Varying side effects of assignments 478* Parentheses:: Parentheses in shell scripts 479* Slashes:: Slashes in shell scripts 480* Special Shell Variables:: Variables you should not change 481* Limitations of Builtins:: Portable use of not so portable /bin/sh 482* Limitations of Usual Tools:: Portable use of portable tools 483 484Portable Make Programming 485 486* $< in Ordinary Make Rules:: $< in ordinary rules 487* Failure in Make Rules:: Failing portably in rules 488* Special Chars in Names:: Special Characters in Macro Names 489* Backslash-Newline-Newline:: Empty last lines in macro definitions 490* Backslash-Newline Comments:: Spanning comments across line boundaries 491* Long Lines in Makefiles:: Line length limitations 492* Macros and Submakes:: @code{make macro=value} and submakes 493* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 494* The Make Macro SHELL:: @code{$(SHELL)} portability issues 495* Comments in Make Rules:: Other problems with Make comments 496* obj/ and Make:: Don't name a subdirectory @file{obj} 497* make -k Status:: Exit status of @samp{make -k} 498* VPATH and Make:: @code{VPATH} woes 499* Single Suffix Rules:: Single suffix rules and separated dependencies 500* Timestamps and Make:: Subsecond timestamp resolution 501 502@code{VPATH} and Make 503 504* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 505* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 506* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 507* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 508* Make Target Lookup:: More details about @code{VPATH} lookup 509 510Portable C and C++ Programming 511 512* Varieties of Unportability:: How to make your programs unportable 513* Integer Overflow:: When integers get too large 514* Null Pointers:: Properties of null pointers 515* Buffer Overruns:: Subscript errors and the like 516* Volatile Objects:: @code{volatile} and signals 517* Floating Point Portability:: Portable floating-point arithmetic 518* Exiting Portably:: Exiting and the exit status 519 520Manual Configuration 521 522* Specifying Names:: Specifying the system type 523* Canonicalizing:: Getting the canonical system type 524* Using System Type:: What to do with the system type 525 526Site Configuration 527 528* Help Formatting:: Customizing @samp{configure --help} 529* External Software:: Working with other optional software 530* Package Options:: Selecting optional features 531* Pretty Help Strings:: Formatting help string 532* Site Details:: Configuring site details 533* Transforming Names:: Changing program names when installing 534* Site Defaults:: Giving @command{configure} local defaults 535 536Transforming Program Names When Installing 537 538* Transformation Options:: @command{configure} options to transform names 539* Transformation Examples:: Sample uses of transforming names 540* Transformation Rules:: Makefile uses of transforming names 541 542Running @command{configure} Scripts 543 544* Basic Installation:: Instructions for typical cases 545* Compilers and Options:: Selecting compilers and optimization 546* Multiple Architectures:: Compiling for multiple architectures at once 547* Installation Names:: Installing in different directories 548* Optional Features:: Selecting optional features 549* System Type:: Specifying the system type 550* Sharing Defaults:: Setting site-wide defaults for @command{configure} 551* Defining Variables:: Specifying the compiler etc. 552* configure Invocation:: Changing how @command{configure} runs 553 554Obsolete Constructs 555 556* Obsolete config.status Use:: Different calling convention 557* acconfig.h:: Additional entries in @file{config.h.in} 558* autoupdate Invocation:: Automatic update of @file{configure.ac} 559* Obsolete Macros:: Backward compatibility macros 560* Autoconf 1:: Tips for upgrading your files 561* Autoconf 2.13:: Some fresher tips 562 563Upgrading From Version 1 564 565* Changed File Names:: Files you might rename 566* Changed Makefiles:: New things to put in @file{Makefile.in} 567* Changed Macros:: Macro calls you might replace 568* Changed Results:: Changes in how to check test results 569* Changed Macro Writing:: Better ways to write your own macros 570 571Upgrading From Version 2.13 572 573* Changed Quotation:: Broken code which used to work 574* New Macros:: Interaction with foreign macros 575* Hosts and Cross-Compilation:: Bugward compatibility kludges 576* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 577* AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources 578 579Generating Test Suites with Autotest 580 581* Using an Autotest Test Suite:: Autotest and the user 582* Writing testsuite.at:: Autotest macros 583* testsuite Invocation:: Running @command{testsuite} scripts 584* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 585 586Using an Autotest Test Suite 587 588* testsuite Scripts:: The concepts of Autotest 589* Autotest Logs:: Their contents 590 591Frequent Autoconf Questions, with answers 592 593* Distributing:: Distributing @command{configure} scripts 594* Why GNU M4:: Why not use the standard M4? 595* Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other? 596* Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake 597* Defining Directories:: Passing @code{datadir} to program 598* autom4te.cache:: What is it? Can I remove it? 599* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 600 601History of Autoconf 602 603* Genesis:: Prehistory and naming of @command{configure} 604* Exodus:: The plagues of M4 and Perl 605* Leviticus:: The priestly code of portability arrives 606* Numbers:: Growth and contributors 607* Deuteronomy:: Approaching the promises of easy configuration 608 609Copying This Manual 610 611* GNU Free Documentation License:: License for copying this manual 612 613Indices 614 615* Environment Variable Index:: Index of environment variables used 616* Output Variable Index:: Index of variables set in output files 617* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 618* Autoconf Macro Index:: Index of Autoconf macros 619* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 620* Autotest Macro Index:: Index of Autotest macros 621* Program & Function Index:: Index of those with portability problems 622* Concept Index:: General index 623 624@end detailmenu 625@end menu 626 627@c ============================================================= Introduction. 628 629@node Introduction 630@chapter Introduction 631@cindex Introduction 632 633@flushright 634A physicist, an engineer, and a computer scientist were discussing the 635nature of God. ``Surely a Physicist,'' said the physicist, ``because 636early in the Creation, God made Light; and you know, Maxwell's 637equations, the dual nature of electromagnetic waves, the relativistic 638consequences@dots{}'' ``An Engineer!,'' said the engineer, ``because 639before making Light, God split the Chaos into Land and Water; it takes a 640hell of an engineer to handle that big amount of mud, and orderly 641separation of solids from liquids@dots{}'' The computer scientist 642shouted: ``And the Chaos, where do you think it was coming from, hmm?'' 643 644---Anonymous 645@end flushright 646@c (via Franc,ois Pinard) 647 648Autoconf is a tool for producing shell scripts that automatically 649configure software source code packages to adapt to many kinds of 650Posix-like systems. The configuration scripts produced by Autoconf 651are independent of Autoconf when they are run, so their users do not 652need to have Autoconf. 653 654The configuration scripts produced by Autoconf require no manual user 655intervention when run; they do not normally even need an argument 656specifying the system type. Instead, they individually test for the 657presence of each feature that the software package they are for might need. 658(Before each check, they print a one-line message stating what they are 659checking for, so the user doesn't get too bored while waiting for the 660script to finish.) As a result, they deal well with systems that are 661hybrids or customized from the more common Posix variants. There is 662no need to maintain files that list the features supported by each 663release of each variant of Posix. 664 665For each software package that Autoconf is used with, it creates a 666configuration script from a template file that lists the system features 667that the package needs or can use. After the shell code to recognize 668and respond to a system feature has been written, Autoconf allows it to 669be shared by many software packages that can use (or need) that feature. 670If it later turns out that the shell code needs adjustment for some 671reason, it needs to be changed in only one place; all of the 672configuration scripts can be regenerated automatically to take advantage 673of the updated code. 674 675The Metaconfig package is similar in purpose to Autoconf, but the 676scripts it produces require manual user intervention, which is quite 677inconvenient when configuring large source trees. Unlike Metaconfig 678scripts, Autoconf scripts can support cross-compiling, if some care is 679taken in writing them. 680 681Autoconf does not solve all problems related to making portable 682software packages---for a more complete solution, it should be used in 683concert with other @acronym{GNU} build tools like Automake and 684Libtool. These other tools take on jobs like the creation of a 685portable, recursive makefile with all of the standard targets, 686linking of shared libraries, and so on. @xref{The GNU Build System}, 687for more information. 688 689Autoconf imposes some restrictions on the names of macros used with 690@code{#if} in C programs (@pxref{Preprocessor Symbol Index}). 691 692Autoconf requires @acronym{GNU} M4 in order to generate the scripts. It uses 693features that some versions of M4, including @acronym{GNU} M4 1.3, 694do not have. You should use version 1.4.7 or later of @acronym{GNU} M4. 695 696@xref{Autoconf 1}, for information about upgrading from version 1. 697@xref{History}, for the story of Autoconf's development. @xref{FAQ}, 698for answers to some common questions about Autoconf. 699 700See the @uref{http://www.gnu.org/software/autoconf/, 701Autoconf web page} for up-to-date information, details on the mailing 702lists, pointers to a list of known bugs, etc. 703 704Mail suggestions to @email{autoconf@@gnu.org, the Autoconf mailing 705list}. Past suggestions are 706@uref{http://lists.gnu.org/archive/html/autoconf/, archived}. 707 708Mail bug reports to @email{bug-autoconf@@gnu.org, the 709Autoconf Bugs mailing list}. Past bug reports are 710@uref{http://lists.gnu.org/archive/html/bug-autoconf/, archived}. 711 712If possible, first check that your bug is 713not already solved in current development versions, and that it has not 714been reported yet. Be sure to include all the needed information and a 715short @file{configure.ac} that demonstrates the problem. 716 717Autoconf's development tree is accessible via anonymous @acronym{CVS}; see the 718@uref{http://savannah.gnu.org/projects/autoconf/, Autoconf 719Summary} for details. Patches relative to the 720current @acronym{CVS} version can be sent for review to the 721@email{autoconf-patches@@gnu.org, Autoconf Patches mailing list}. 722Past patches are 723@uref{http://lists.gnu.org/@/archive/@/html/@/autoconf-patches/, archived}. 724 725Because of its mission, the Autoconf package itself 726includes only a set of often-used 727macros that have already demonstrated their usefulness. Nevertheless, 728if you wish to share your macros, or find existing ones, see the 729@uref{http://autoconf-archive.cryp.to/, Autoconf Macro 730Archive}, which is kindly run by @email{simons@@cryp.to, 731Peter Simons}. 732 733 734@c ================================================= The GNU Build System 735 736@node The GNU Build System 737@chapter The @acronym{GNU} Build System 738@cindex @acronym{GNU} build system 739 740Autoconf solves an important problem---reliable discovery of 741system-specific build and runtime information---but this is only one 742piece of the puzzle for the development of portable software. To this 743end, the @acronym{GNU} project has developed a suite of integrated 744utilities to finish the job Autoconf started: the @acronym{GNU} build 745system, whose most important components are Autoconf, Automake, and 746Libtool. In this chapter, we introduce you to those tools, point you 747to sources of more information, and try to convince you to use the 748entire @acronym{GNU} build system for your software. 749 750@menu 751* Automake:: Escaping makefile hell 752* Gnulib:: The @acronym{GNU} portability library 753* Libtool:: Building libraries portably 754* Pointers:: More info on the @acronym{GNU} build system 755@end menu 756 757@node Automake 758@section Automake 759 760The ubiquity of @command{make} means that a makefile is almost the 761only viable way to distribute automatic build rules for software, but 762one quickly runs into its numerous limitations. Its lack of 763support for automatic dependency tracking, recursive builds in 764subdirectories, reliable timestamps (e.g., for network file systems), and 765so on, mean that developers must painfully (and often incorrectly) 766reinvent the wheel for each project. Portability is non-trivial, thanks 767to the quirks of @command{make} on many systems. On top of all this is the 768manual labor required to implement the many standard targets that users 769have come to expect (@code{make install}, @code{make distclean}, 770@code{make uninstall}, etc.). Since you are, of course, using Autoconf, 771you also have to insert repetitive code in your @code{Makefile.in} to 772recognize @code{@@CC@@}, @code{@@CFLAGS@@}, and other substitutions 773provided by @command{configure}. Into this mess steps @dfn{Automake}. 774@cindex Automake 775 776Automake allows you to specify your build needs in a @code{Makefile.am} 777file with a vastly simpler and more powerful syntax than that of a plain 778makefile, and then generates a portable @code{Makefile.in} for 779use with Autoconf. For example, the @code{Makefile.am} to build and 780install a simple ``Hello world'' program might look like: 781 782@example 783bin_PROGRAMS = hello 784hello_SOURCES = hello.c 785@end example 786 787@noindent 788The resulting @code{Makefile.in} (~400 lines) automatically supports all 789the standard targets, the substitutions provided by Autoconf, automatic 790dependency tracking, @code{VPATH} building, and so on. @command{make} 791builds the @code{hello} program, and @code{make install} installs it 792in @file{/usr/local/bin} (or whatever prefix was given to 793@command{configure}, if not @file{/usr/local}). 794 795The benefits of Automake increase for larger packages (especially ones 796with subdirectories), but even for small programs the added convenience 797and portability can be substantial. And that's not all@enddots{} 798 799@node Gnulib 800@section Gnulib 801 802@acronym{GNU} software has a well-deserved reputation for running on 803many different types of systems. While our primary goal is to write 804software for the @acronym{GNU} system, many users and developers have 805been introduced to us through the systems that they were already using. 806 807@cindex Gnulib 808Gnulib is a central location for common @acronym{GNU} code, intended to 809be shared among free software packages. Its components are typically 810shared at the source level, rather than being a library that gets built, 811installed, and linked against. The idea is to copy files from Gnulib 812into your own source tree. There is no distribution tarball; developers 813should just grab source modules from the repository. The source files 814are available online, under various licenses, mostly @acronym{GNU} 815@acronym{GPL} or @acronym{GNU} @acronym{LGPL}. 816 817Gnulib modules typically contain C source code along with Autoconf 818macros used to configure the source code. For example, the Gnulib 819@code{stdbool} module implements a @file{stdbool.h} header that nearly 820conforms to C99, even on old-fashioned hosts that lack @file{stdbool.h}. 821This module contains a source file for the replacement header, along 822with an Autoconf macro that arranges to use the replacement header on 823old-fashioned systems. 824 825@node Libtool 826@section Libtool 827 828Often, one wants to build not only programs, but libraries, so that 829other programs can benefit from the fruits of your labor. Ideally, one 830would like to produce @emph{shared} (dynamically linked) libraries, 831which can be used by multiple programs without duplication on disk or in 832memory and can be updated independently of the linked programs. 833Producing shared libraries portably, however, is the stuff of 834nightmares---each system has its own incompatible tools, compiler flags, 835and magic incantations. Fortunately, @acronym{GNU} provides a solution: 836@dfn{Libtool}. 837@cindex Libtool 838 839Libtool handles all the requirements of building shared libraries for 840you, and at this time seems to be the @emph{only} way to do so with any 841portability. It also handles many other headaches, such as: the 842interaction of Make rules with the variable suffixes of 843shared libraries, linking reliably with shared libraries before they are 844installed by the superuser, and supplying a consistent versioning system 845(so that different versions of a library can be installed or upgraded 846without breaking binary compatibility). Although Libtool, like 847Autoconf, can be used without Automake, it is most simply utilized in 848conjunction with Automake---there, Libtool is used automatically 849whenever shared libraries are needed, and you need not know its syntax. 850 851@node Pointers 852@section Pointers 853 854Developers who are used to the simplicity of @command{make} for small 855projects on a single system might be daunted at the prospect of 856learning to use Automake and Autoconf. As your software is 857distributed to more and more users, however, you otherwise 858quickly find yourself putting lots of effort into reinventing the 859services that the @acronym{GNU} build tools provide, and making the 860same mistakes that they once made and overcame. (Besides, since 861you're already learning Autoconf, Automake is a piece of cake.) 862 863There are a number of places that you can go to for more information on 864the @acronym{GNU} build tools. 865 866@itemize @minus 867 868@item Web 869 870The home pages for 871@uref{http://www.gnu.org/@/software/@/autoconf/, Autoconf}, 872@uref{http://www.gnu.org/@/software/@/automake/, Automake}, 873@uref{http://www.gnu.org/@/software/@/gnulib/, Gnulib}, and 874@uref{http://www.gnu.org/@/software/@/libtool/, Libtool}. 875 876@item Automake Manual 877 878@xref{Top, , Automake, automake, @acronym{GNU} Automake}, for more 879information on Automake. 880 881@item Books 882 883The book @cite{@acronym{GNU} Autoconf, Automake and 884Libtool}@footnote{@cite{@acronym{GNU} Autoconf, Automake and Libtool}, 885by G. V. Vaughan, B. Elliston, T. Tromey, and I. L. Taylor. SAMS (originally 886New Riders), 2000, ISBN 1578701902.} describes the complete @acronym{GNU} 887build environment. You can also find 888@uref{http://sources.redhat.com/@/autobook/, the entire book on-line}. 889 890@end itemize 891 892@c ================================================= Making configure Scripts. 893 894@node Making configure Scripts 895@chapter Making @command{configure} Scripts 896@cindex @file{aclocal.m4} 897@cindex @command{configure} 898 899The configuration scripts that Autoconf produces are by convention 900called @command{configure}. When run, @command{configure} creates several 901files, replacing configuration parameters in them with appropriate 902values. The files that @command{configure} creates are: 903 904@itemize @minus 905@item 906one or more @file{Makefile} files, usually one in each subdirectory of the 907package (@pxref{Makefile Substitutions}); 908 909@item 910optionally, a C header file, the name of which is configurable, 911containing @code{#define} directives (@pxref{Configuration Headers}); 912 913@item 914a shell script called @file{config.status} that, when run, recreates 915the files listed above (@pxref{config.status Invocation}); 916 917@item 918an optional shell script normally called @file{config.cache} 919(created when using @samp{configure --config-cache}) that 920saves the results of running many of the tests (@pxref{Cache Files}); 921 922@item 923a file called @file{config.log} containing any messages produced by 924compilers, to help debugging if @command{configure} makes a mistake. 925@end itemize 926 927@cindex @file{configure.in} 928@cindex @file{configure.ac} 929To create a @command{configure} script with Autoconf, you need to write an 930Autoconf input file @file{configure.ac} (or @file{configure.in}) and run 931@command{autoconf} on it. If you write your own feature tests to 932supplement those that come with Autoconf, you might also write files 933called @file{aclocal.m4} and @file{acsite.m4}. If you use a C header 934file to contain @code{#define} directives, you might also run 935@command{autoheader}, and you can distribute the generated file 936@file{config.h.in} with the package. 937 938Here is a diagram showing how the files that can be used in 939configuration are produced. Programs that are executed are suffixed by 940@samp{*}. Optional files are enclosed in square brackets (@samp{[]}). 941@command{autoconf} and @command{autoheader} also read the installed Autoconf 942macro files (by reading @file{autoconf.m4}). 943 944@noindent 945Files used in preparing a software package for distribution: 946@example 947your source files --> [autoscan*] --> [configure.scan] --> configure.ac 948 949@group 950configure.ac --. 951 | .------> autoconf* -----> configure 952[aclocal.m4] --+---+ 953 | `-----> [autoheader*] --> [config.h.in] 954[acsite.m4] ---' 955@end group 956 957Makefile.in -------------------------------> Makefile.in 958@end example 959 960@noindent 961Files used in configuring a software package: 962@example 963@group 964 .-------------> [config.cache] 965configure* ------------+-------------> config.log 966 | 967[config.h.in] -. v .-> [config.h] -. 968 +--> config.status* -+ +--> make* 969Makefile.in ---' `-> Makefile ---' 970@end group 971@end example 972 973@menu 974* Writing configure.ac:: What to put in an Autoconf input file 975* autoscan Invocation:: Semi-automatic @file{configure.ac} writing 976* ifnames Invocation:: Listing the conditionals in source code 977* autoconf Invocation:: How to create configuration scripts 978* autoreconf Invocation:: Remaking multiple @command{configure} scripts 979@end menu 980 981@node Writing configure.ac 982@section Writing @file{configure.ac} 983 984To produce a @command{configure} script for a software package, create a 985file called @file{configure.ac} that contains invocations of the 986Autoconf macros that test the system features your package needs or can 987use. Autoconf macros already exist to check for many features; see 988@ref{Existing Tests}, for their descriptions. For most other features, 989you can use Autoconf template macros to produce custom checks; see 990@ref{Writing Tests}, for information about them. For especially tricky 991or specialized features, @file{configure.ac} might need to contain some 992hand-crafted shell commands; see @ref{Portable Shell}. The 993@command{autoscan} program can give you a good start in writing 994@file{configure.ac} (@pxref{autoscan Invocation}, for more information). 995 996Previous versions of Autoconf promoted the name @file{configure.in}, 997which is somewhat ambiguous (the tool needed to process this file is not 998described by its extension), and introduces a slight confusion with 999@file{config.h.in} and so on (for which @samp{.in} means ``to be 1000processed by @command{configure}''). Using @file{configure.ac} is now 1001preferred. 1002 1003@menu 1004* Shell Script Compiler:: Autoconf as solution of a problem 1005* Autoconf Language:: Programming in Autoconf 1006* configure.ac Layout:: Standard organization of @file{configure.ac} 1007@end menu 1008 1009@node Shell Script Compiler 1010@subsection A Shell Script Compiler 1011 1012Just as for any other computer language, in order to properly program 1013@file{configure.ac} in Autoconf you must understand @emph{what} problem 1014the language tries to address and @emph{how} it does so. 1015 1016The problem Autoconf addresses is that the world is a mess. After all, 1017you are using Autoconf in order to have your package compile easily on 1018all sorts of different systems, some of them being extremely hostile. 1019Autoconf itself bears the price for these differences: @command{configure} 1020must run on all those systems, and thus @command{configure} must limit itself 1021to their lowest common denominator of features. 1022 1023Naturally, you might then think of shell scripts; who needs 1024@command{autoconf}? A set of properly written shell functions is enough to 1025make it easy to write @command{configure} scripts by hand. Sigh! 1026Unfortunately, shell functions do not belong to the least common 1027denominator; therefore, where you would like to define a function and 1028use it ten times, you would instead need to copy its body ten times. 1029 1030So, what is really needed is some kind of compiler, @command{autoconf}, 1031that takes an Autoconf program, @file{configure.ac}, and transforms it 1032into a portable shell script, @command{configure}. 1033 1034How does @command{autoconf} perform this task? 1035 1036There are two obvious possibilities: creating a brand new language or 1037extending an existing one. The former option is attractive: all 1038sorts of optimizations could easily be implemented in the compiler and 1039many rigorous checks could be performed on the Autoconf program 1040(e.g., rejecting any non-portable construct). Alternatively, you can 1041extend an existing language, such as the @code{sh} (Bourne shell) 1042language. 1043 1044Autoconf does the latter: it is a layer on top of @code{sh}. It was 1045therefore most convenient to implement @command{autoconf} as a macro 1046expander: a program that repeatedly performs @dfn{macro expansions} on 1047text input, replacing macro calls with macro bodies and producing a pure 1048@code{sh} script in the end. Instead of implementing a dedicated 1049Autoconf macro expander, it is natural to use an existing 1050general-purpose macro language, such as M4, and implement the extensions 1051as a set of M4 macros. 1052 1053 1054@node Autoconf Language 1055@subsection The Autoconf Language 1056@cindex quotation 1057 1058The Autoconf language differs from many other computer 1059languages because it treats actual code the same as plain text. Whereas 1060in C, for instance, data and instructions have different syntactic 1061status, in Autoconf their status is rigorously the same. Therefore, we 1062need a means to distinguish literal strings from text to be expanded: 1063quotation. 1064 1065When calling macros that take arguments, there must not be any white 1066space between the macro name and the open parenthesis. Arguments should 1067be enclosed within the M4 quote characters @samp{[} and @samp{]}, and be 1068separated by commas. Any leading blanks or newlines in arguments are ignored, 1069unless they are quoted. You should always quote an argument that 1070might contain a macro name, comma, parenthesis, or a leading blank or 1071newline. This rule applies recursively for every macro 1072call, including macros called from other macros. 1073 1074For instance: 1075 1076@example 1077AC_CHECK_HEADER([stdio.h], 1078 [AC_DEFINE([HAVE_STDIO_H], [1], 1079 [Define to 1 if you have <stdio.h>.])], 1080 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 1081@end example 1082 1083@noindent 1084is quoted properly. You may safely simplify its quotation to: 1085 1086@example 1087AC_CHECK_HEADER([stdio.h], 1088 [AC_DEFINE([HAVE_STDIO_H], 1, 1089 [Define to 1 if you have <stdio.h>.])], 1090 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 1091@end example 1092 1093@noindent 1094because @samp{1} cannot contain a macro call. Here, the argument of 1095@code{AC_MSG_ERROR} must be quoted; otherwise, its comma would be 1096interpreted as an argument separator. Also, the second and third arguments 1097of @samp{AC_CHECK_HEADER} must be quoted, since they contain 1098macro calls. The three arguments @samp{HAVE_STDIO_H}, @samp{stdio.h}, 1099and @samp{Define to 1 if you have <stdio.h>.} do not need quoting, but 1100if you unwisely defined a macro with a name like @samp{Define} or 1101@samp{stdio} then they would need quoting. Cautious Autoconf users 1102would keep the quotes, but many Autoconf users find such precautions 1103annoying, and would rewrite the example as follows: 1104 1105@example 1106AC_CHECK_HEADER(stdio.h, 1107 [AC_DEFINE(HAVE_STDIO_H, 1, 1108 [Define to 1 if you have <stdio.h>.])], 1109 [AC_MSG_ERROR([Sorry, can't do anything for you])]) 1110@end example 1111 1112@noindent 1113This is safe, so long as you adopt good naming conventions and do not 1114define macros with names like @samp{HAVE_STDIO_H}, @samp{stdio}, or 1115@samp{h}. Though it is also safe here to omit the quotes around 1116@samp{Define to 1 if you have <stdio.h>.} this is not recommended, as 1117message strings are more likely to inadvertently contain commas. 1118 1119The following example is wrong and dangerous, as it is underquoted: 1120 1121@example 1122AC_CHECK_HEADER(stdio.h, 1123 AC_DEFINE(HAVE_STDIO_H, 1, 1124 Define to 1 if you have <stdio.h>.), 1125 AC_MSG_ERROR([Sorry, can't do anything for you])) 1126@end example 1127 1128In other cases, you may have to use text that also resembles a macro 1129call. You must quote that text even when it is not passed as a macro 1130argument: 1131 1132@example 1133echo "Hard rock was here! --[AC_DC]" 1134@end example 1135 1136@noindent 1137which results in: 1138 1139@example 1140echo "Hard rock was here! --AC_DC" 1141@end example 1142 1143@noindent 1144When you use the same text in a macro argument, you must therefore have 1145an extra quotation level (since one is stripped away by the macro 1146substitution). In general, then, it is a good idea to @emph{use double 1147quoting for all literal string arguments}: 1148 1149@example 1150AC_MSG_WARN([[AC_DC stinks --Iron Maiden]]) 1151@end example 1152 1153You are now able to understand one of the constructs of Autoconf that 1154has been continually misunderstood@dots{} The rule of thumb is that 1155@emph{whenever you expect macro expansion, expect quote expansion}; 1156i.e., expect one level of quotes to be lost. For instance: 1157 1158@example 1159AC_COMPILE_IFELSE([char b[10];], [], [AC_MSG_ERROR([you lose])]) 1160@end example 1161 1162@noindent 1163is incorrect: here, the first argument of @code{AC_COMPILE_IFELSE} is 1164@samp{char b[10];} and is expanded once, which results in 1165@samp{char b10;}. (There was an idiom common in Autoconf's past to 1166address this issue via the M4 @code{changequote} primitive, but do not 1167use it!) Let's take a closer look: the author meant the first argument 1168to be understood as a literal, and therefore it must be quoted twice: 1169 1170@example 1171AC_COMPILE_IFELSE([[char b[10];]], [], [AC_MSG_ERROR([you lose])]) 1172@end example 1173 1174@noindent 1175Voil@`a, you actually produce @samp{char b[10];} this time! 1176 1177On the other hand, descriptions (e.g., the last parameter of 1178@code{AC_DEFINE} or @code{AS_HELP_STRING}) are not literals---they 1179are subject to line breaking, for example---and should not be double quoted. 1180Even if these descriptions are short and are not actually broken, double 1181quoting them yields weird results. 1182 1183Some macros take optional arguments, which this documentation represents 1184as @ovar{arg} (not to be confused with the quote characters). You may 1185just leave them empty, or use @samp{[]} to make the emptiness of the 1186argument explicit, or you may simply omit the trailing commas. The 1187three lines below are equivalent: 1188 1189@example 1190AC_CHECK_HEADERS([stdio.h], [], [], []) 1191AC_CHECK_HEADERS([stdio.h],,,) 1192AC_CHECK_HEADERS([stdio.h]) 1193@end example 1194 1195It is best to put each macro call on its own line in 1196@file{configure.ac}. Most of the macros don't add extra newlines; they 1197rely on the newline after the macro call to terminate the commands. 1198This approach makes the generated @command{configure} script a little 1199easier to read by not inserting lots of blank lines. It is generally 1200safe to set shell variables on the same line as a macro call, because 1201the shell allows assignments without intervening newlines. 1202 1203You can include comments in @file{configure.ac} files by starting them 1204with the @samp{#}. For example, it is helpful to begin 1205@file{configure.ac} files with a line like this: 1206 1207@example 1208# Process this file with autoconf to produce a configure script. 1209@end example 1210 1211@node configure.ac Layout 1212@subsection Standard @file{configure.ac} Layout 1213 1214The order in which @file{configure.ac} calls the Autoconf macros is not 1215important, with a few exceptions. Every @file{configure.ac} must 1216contain a call to @code{AC_INIT} before the checks, and a call to 1217@code{AC_OUTPUT} at the end (@pxref{Output}). Additionally, some macros 1218rely on other macros having been called first, because they check 1219previously set values of some variables to decide what to do. These 1220macros are noted in the individual descriptions (@pxref{Existing 1221Tests}), and they also warn you when @command{configure} is created if they 1222are called out of order. 1223 1224To encourage consistency, here is a suggested order for calling the 1225Autoconf macros. Generally speaking, the things near the end of this 1226list are those that could depend on things earlier in it. For example, 1227library functions could be affected by types and libraries. 1228 1229@display 1230@group 1231Autoconf requirements 1232@code{AC_INIT(@var{package}, @var{version}, @var{bug-report-address})} 1233information on the package 1234checks for programs 1235checks for libraries 1236checks for header files 1237checks for types 1238checks for structures 1239checks for compiler characteristics 1240checks for library functions 1241checks for system services 1242@code{AC_CONFIG_FILES(@r{[}@var{file@dots{}}@r{]})} 1243@code{AC_OUTPUT} 1244@end group 1245@end display 1246 1247 1248@node autoscan Invocation 1249@section Using @command{autoscan} to Create @file{configure.ac} 1250@cindex @command{autoscan} 1251 1252The @command{autoscan} program can help you create and/or maintain a 1253@file{configure.ac} file for a software package. @command{autoscan} 1254examines source files in the directory tree rooted at a directory given 1255as a command line argument, or the current directory if none is given. 1256It searches the source files for common portability problems and creates 1257a file @file{configure.scan} which is a preliminary @file{configure.ac} 1258for that package, and checks a possibly existing @file{configure.ac} for 1259completeness. 1260 1261When using @command{autoscan} to create a @file{configure.ac}, you 1262should manually examine @file{configure.scan} before renaming it to 1263@file{configure.ac}; it probably needs some adjustments. 1264Occasionally, @command{autoscan} outputs a macro in the wrong order 1265relative to another macro, so that @command{autoconf} produces a warning; 1266you need to move such macros manually. Also, if you want the package to 1267use a configuration header file, you must add a call to 1268@code{AC_CONFIG_HEADERS} (@pxref{Configuration Headers}). You might 1269also have to change or add some @code{#if} directives to your program in 1270order to make it work with Autoconf (@pxref{ifnames Invocation}, for 1271information about a program that can help with that job). 1272 1273When using @command{autoscan} to maintain a @file{configure.ac}, simply 1274consider adding its suggestions. The file @file{autoscan.log} 1275contains detailed information on why a macro is requested. 1276 1277@command{autoscan} uses several data files (installed along with Autoconf) 1278to determine which macros to output when it finds particular symbols in 1279a package's source files. These data files all have the same format: 1280each line consists of a symbol, one or more blanks, and the Autoconf macro to 1281output if that symbol is encountered. Lines starting with @samp{#} are 1282comments. 1283 1284@command{autoscan} accepts the following options: 1285 1286@table @option 1287@item --help 1288@itemx -h 1289Print a summary of the command line options and exit. 1290 1291@item --version 1292@itemx -V 1293Print the version number of Autoconf and exit. 1294 1295@item --verbose 1296@itemx -v 1297Print the names of the files it examines and the potentially interesting 1298symbols it finds in them. This output can be voluminous. 1299 1300@item --include=@var{dir} 1301@itemx -I @var{dir} 1302Append @var{dir} to the include path. Multiple invocations accumulate. 1303 1304@item --prepend-include=@var{dir} 1305@item -B @var{dir} 1306Prepend @var{dir} to the include path. Multiple invocations accumulate. 1307@end table 1308 1309@node ifnames Invocation 1310@section Using @command{ifnames} to List Conditionals 1311@cindex @command{ifnames} 1312 1313@command{ifnames} can help you write @file{configure.ac} for a software 1314package. It prints the identifiers that the package already uses in C 1315preprocessor conditionals. If a package has already been set up to have 1316some portability, @command{ifnames} can thus help you figure out what its 1317@command{configure} needs to check for. It may help fill in some gaps in a 1318@file{configure.ac} generated by @command{autoscan} (@pxref{autoscan 1319Invocation}). 1320 1321@command{ifnames} scans all of the C source files named on the command line 1322(or the standard input, if none are given) and writes to the standard 1323output a sorted list of all the identifiers that appear in those files 1324in @code{#if}, @code{#elif}, @code{#ifdef}, or @code{#ifndef} 1325directives. It prints each identifier on a line, followed by a 1326space-separated list of the files in which that identifier occurs. 1327 1328@noindent 1329@command{ifnames} accepts the following options: 1330 1331@table @option 1332@item --help 1333@itemx -h 1334Print a summary of the command line options and exit. 1335 1336@item --version 1337@itemx -V 1338Print the version number of Autoconf and exit. 1339@end table 1340 1341@node autoconf Invocation 1342@section Using @command{autoconf} to Create @command{configure} 1343@cindex @command{autoconf} 1344 1345To create @command{configure} from @file{configure.ac}, run the 1346@command{autoconf} program with no arguments. @command{autoconf} processes 1347@file{configure.ac} with the M4 macro processor, using the 1348Autoconf macros. If you give @command{autoconf} an argument, it reads that 1349file instead of @file{configure.ac} and writes the configuration script 1350to the standard output instead of to @command{configure}. If you give 1351@command{autoconf} the argument @option{-}, it reads from the standard 1352input instead of @file{configure.ac} and writes the configuration script 1353to the standard output. 1354 1355The Autoconf macros are defined in several files. Some of the files are 1356distributed with Autoconf; @command{autoconf} reads them first. Then it 1357looks for the optional file @file{acsite.m4} in the directory that 1358contains the distributed Autoconf macro files, and for the optional file 1359@file{aclocal.m4} in the current directory. Those files can contain 1360your site's or the package's own Autoconf macro definitions 1361(@pxref{Writing Autoconf Macros}, for more information). If a macro is 1362defined in more than one of the files that @command{autoconf} reads, the 1363last definition it reads overrides the earlier ones. 1364 1365@command{autoconf} accepts the following options: 1366 1367@table @option 1368@item --help 1369@itemx -h 1370Print a summary of the command line options and exit. 1371 1372@item --version 1373@itemx -V 1374Print the version number of Autoconf and exit. 1375 1376@item --verbose 1377@itemx -v 1378Report processing steps. 1379 1380@item --debug 1381@itemx -d 1382Don't remove the temporary files. 1383 1384@item --force 1385@itemx -f 1386Remake @file{configure} even if newer than its input files. 1387 1388@item --include=@var{dir} 1389@itemx -I @var{dir} 1390Append @var{dir} to the include path. Multiple invocations accumulate. 1391 1392@item --prepend-include=@var{dir} 1393@item -B @var{dir} 1394Prepend @var{dir} to the include path. Multiple invocations accumulate. 1395 1396@item --output=@var{file} 1397@itemx -o @var{file} 1398Save output (script or trace) to @var{file}. The file @option{-} stands 1399for the standard output. 1400 1401@item --warnings=@var{category} 1402@itemx -W @var{category} 1403@evindex WARNINGS 1404Report the warnings related to @var{category} (which can actually be a 1405comma separated list). @xref{Reporting Messages}, macro 1406@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 1407values include: 1408 1409@table @samp 1410@item all 1411report all the warnings 1412 1413@item none 1414report none 1415 1416@item error 1417treats warnings as errors 1418 1419@item no-@var{category} 1420disable warnings falling into @var{category} 1421@end table 1422 1423Warnings about @samp{syntax} are enabled by default, and the environment 1424variable @env{WARNINGS}, a comma separated list of categories, is 1425honored as well. Passing @option{-W @var{category}} actually behaves as if 1426you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If 1427you want to disable the defaults and @env{WARNINGS}, but (for example) 1428enable the warnings about obsolete constructs, you would use @option{-W 1429none,obsolete}. 1430 1431@cindex Back trace 1432@cindex Macro invocation stack 1433Because @command{autoconf} uses @command{autom4te} behind the scenes, it 1434displays a back trace for errors, but not for warnings; if you want 1435them, just pass @option{-W error}. @xref{autom4te Invocation}, for some 1436examples. 1437 1438@item --trace=@var{macro}[:@var{format}] 1439@itemx -t @var{macro}[:@var{format}] 1440Do not create the @command{configure} script, but list the calls to 1441@var{macro} according to the @var{format}. Multiple @option{--trace} 1442arguments can be used to list several macros. Multiple @option{--trace} 1443arguments for a single macro are not cumulative; instead, you should 1444just make @var{format} as long as needed. 1445 1446The @var{format} is a regular string, with newlines if desired, and 1447several special escape codes. It defaults to @samp{$f:$l:$n:$%}; see 1448@ref{autom4te Invocation}, for details on the @var{format}. 1449 1450@item --initialization 1451@itemx -i 1452By default, @option{--trace} does not trace the initialization of the 1453Autoconf macros (typically the @code{AC_DEFUN} definitions). This 1454results in a noticeable speedup, but can be disabled by this option. 1455@end table 1456 1457 1458It is often necessary to check the content of a @file{configure.ac} 1459file, but parsing it yourself is extremely fragile and error-prone. It 1460is suggested that you rely upon @option{--trace} to scan 1461@file{configure.ac}. For instance, to find the list of variables that 1462are substituted, use: 1463 1464@example 1465@group 1466$ @kbd{autoconf -t AC_SUBST} 1467configure.ac:2:AC_SUBST:ECHO_C 1468configure.ac:2:AC_SUBST:ECHO_N 1469configure.ac:2:AC_SUBST:ECHO_T 1470@i{More traces deleted} 1471@end group 1472@end example 1473 1474@noindent 1475The example below highlights the difference between @samp{$@@}, 1476@samp{$*}, and @samp{$%}. 1477 1478@example 1479@group 1480$ @kbd{cat configure.ac} 1481AC_DEFINE(This, is, [an 1482[example]]) 1483$ @kbd{autoconf -t 'AC_DEFINE:@@: $@@} 1484*: $* 1485%: $%' 1486@@: [This],[is],[an 1487[example]] 1488*: This,is,an 1489[example] 1490%: This:is:an [example] 1491@end group 1492@end example 1493 1494@noindent 1495The @var{format} gives you a lot of freedom: 1496 1497@example 1498@group 1499$ @kbd{autoconf -t 'AC_SUBST:$$ac_subst@{"$1"@} = "$f:$l";'} 1500$ac_subst@{"ECHO_C"@} = "configure.ac:2"; 1501$ac_subst@{"ECHO_N"@} = "configure.ac:2"; 1502$ac_subst@{"ECHO_T"@} = "configure.ac:2"; 1503@i{More traces deleted} 1504@end group 1505@end example 1506 1507@noindent 1508A long @var{separator} can be used to improve the readability of complex 1509structures, and to ease their parsing (for instance when no single 1510character is suitable as a separator): 1511 1512@example 1513@group 1514$ @kbd{autoconf -t 'AM_MISSING_PROG:$@{|:::::|@}*'} 1515ACLOCAL|:::::|aclocal|:::::|$missing_dir 1516AUTOCONF|:::::|autoconf|:::::|$missing_dir 1517AUTOMAKE|:::::|automake|:::::|$missing_dir 1518@i{More traces deleted} 1519@end group 1520@end example 1521 1522@node autoreconf Invocation 1523@section Using @command{autoreconf} to Update @command{configure} Scripts 1524@cindex @command{autoreconf} 1525 1526Installing the various components of the @acronym{GNU} Build System can be 1527tedious: running @command{autopoint} for Gettext, @command{automake} for 1528@file{Makefile.in} etc.@: in each directory. It may be needed either 1529because some tools such as @command{automake} have been updated on your 1530system, or because some of the sources such as @file{configure.ac} have 1531been updated, or finally, simply in order to install the @acronym{GNU} Build 1532System in a fresh tree. 1533 1534@command{autoreconf} runs @command{autoconf}, @command{autoheader}, 1535@command{aclocal}, @command{automake}, @command{libtoolize}, and 1536@command{autopoint} (when appropriate) repeatedly to update the 1537@acronym{GNU} Build System in the specified directories and their 1538subdirectories (@pxref{Subdirectories}). By default, it only remakes 1539those files that are older than their sources. 1540 1541If you install a new version of some tool, you can make 1542@command{autoreconf} remake @emph{all} of the files by giving it the 1543@option{--force} option. 1544 1545@xref{Automatic Remaking}, for Make rules to automatically 1546remake @command{configure} scripts when their source files change. That 1547method handles the timestamps of configuration header templates 1548properly, but does not pass @option{--autoconf-dir=@var{dir}} or 1549@option{--localdir=@var{dir}}. 1550 1551@cindex Gettext 1552@cindex @command{autopoint} 1553Gettext supplies the @command{autopoint} command to add translation 1554infrastructure to a source package. If you use @command{autopoint}, 1555your @file{configure.ac} should invoke both @code{AM_GNU_GETTEXT} and 1556@code{AM_GNU_GETTEXT_VERSION(@var{gettext-version})}. @xref{autopoint 1557Invocation, , Invoking the @code{autopoint} Program, gettext, 1558@acronym{GNU} @code{gettext} utilities}, for further details. 1559 1560@noindent 1561@command{autoreconf} accepts the following options: 1562 1563@table @option 1564@item --help 1565@itemx -h 1566Print a summary of the command line options and exit. 1567 1568@item --version 1569@itemx -V 1570Print the version number of Autoconf and exit. 1571 1572@item --verbose 1573Print the name of each directory @command{autoreconf} examines and the 1574commands it runs. If given two or more times, pass @option{--verbose} 1575to subordinate tools that support it. 1576 1577@item --debug 1578@itemx -d 1579Don't remove the temporary files. 1580 1581@item --force 1582@itemx -f 1583Remake even @file{configure} scripts and configuration headers that are 1584newer than their input files (@file{configure.ac} and, if present, 1585@file{aclocal.m4}). 1586 1587@item --install 1588@itemx -i 1589Install the missing auxiliary files in the package. By default, files 1590are copied; this can be changed with @option{--symlink}. 1591 1592If deemed appropriate, this option triggers calls to 1593@samp{automake --add-missing}, 1594@samp{libtoolize}, @samp{autopoint}, etc. 1595 1596@item --no-recursive 1597Do not rebuild files in subdirectories to configure (see @ref{Subdirectories}, 1598macro @code{AC_CONFIG_SUBDIRS}). 1599 1600@item --symlink 1601@itemx -s 1602When used with @option{--install}, install symbolic links to the missing 1603auxiliary files instead of copying them. 1604 1605@item --make 1606@itemx -m 1607When the directories were configured, update the configuration by 1608running @samp{./config.status --recheck && ./config.status}, and then 1609run @samp{make}. 1610 1611@item --include=@var{dir} 1612@itemx -I @var{dir} 1613Append @var{dir} to the include path. Multiple invocations accumulate. 1614Passed on to @command{autoconf} and @command{autoheader} internally. 1615 1616@item --prepend-include=@var{dir} 1617@item -B @var{dir} 1618Prepend @var{dir} to the include path. Multiple invocations accumulate. 1619Passed on to @command{autoconf} and @command{autoheader} internally. 1620 1621@item --warnings=@var{category} 1622@itemx -W @var{category} 1623@evindex WARNINGS 1624Report the warnings related to @var{category} (which can actually be a 1625comma separated list). 1626 1627@table @samp 1628@item cross 1629related to cross compilation issues. 1630 1631@item obsolete 1632report the uses of obsolete constructs. 1633 1634@item portability 1635portability issues 1636 1637@item syntax 1638dubious syntactic constructs. 1639 1640@item all 1641report all the warnings 1642 1643@item none 1644report none 1645 1646@item error 1647treats warnings as errors 1648 1649@item no-@var{category} 1650disable warnings falling into @var{category} 1651@end table 1652 1653Warnings about @samp{syntax} are enabled by default, and the environment 1654variable @env{WARNINGS}, a comma separated list of categories, is 1655honored as well. Passing @option{-W @var{category}} actually behaves as if 1656you had passed @option{--warnings=syntax,$WARNINGS,@var{category}}. If 1657you want to disable the defaults and @env{WARNINGS}, but (for example) 1658enable the warnings about obsolete constructs, you would use @option{-W 1659none,obsolete}. 1660@end table 1661 1662If you want @command{autoreconf} to pass flags that are not listed here 1663on to @command{aclocal}, set @code{ACLOCAL_AMFLAGS} in your @file{Makefile.am}. 1664 1665@c ========================================= Initialization and Output Files. 1666 1667@node Setup 1668@chapter Initialization and Output Files 1669 1670Autoconf-generated @command{configure} scripts need some information about 1671how to initialize, such as how to find the package's source files and 1672about the output files to produce. The following sections describe the 1673initialization and the creation of output files. 1674 1675@menu 1676* Initializing configure:: Option processing etc. 1677* Notices:: Copyright, version numbers in @command{configure} 1678* Input:: Where Autoconf should find files 1679* Output:: Outputting results from the configuration 1680* Configuration Actions:: Preparing the output based on results 1681* Configuration Files:: Creating output files 1682* Makefile Substitutions:: Using output variables in makefiles 1683* Configuration Headers:: Creating a configuration header file 1684* Configuration Commands:: Running arbitrary instantiation commands 1685* Configuration Links:: Links depending on the configuration 1686* Subdirectories:: Configuring independent packages together 1687* Default Prefix:: Changing the default installation prefix 1688@end menu 1689 1690@node Initializing configure 1691@section Initializing @command{configure} 1692 1693Every @command{configure} script must call @code{AC_INIT} before doing 1694anything else. The only other required macro is @code{AC_OUTPUT} 1695(@pxref{Output}). 1696 1697@defmac AC_INIT (@var{package}, @var{version}, @ovar{bug-report}, @ovar{tarname}) 1698@acindex{INIT} 1699Process any command-line arguments and perform various initializations 1700and verifications. 1701 1702Set the name of the @var{package} and its @var{version}. These are 1703typically used in @option{--version} support, including that of 1704@command{configure}. The optional argument @var{bug-report} should be 1705the email to which users should send bug reports. The package 1706@var{tarname} differs from @var{package}: the latter designates the full 1707package name (e.g., @samp{GNU Autoconf}), while the former is meant for 1708distribution tar ball names (e.g., @samp{autoconf}). It defaults to 1709@var{package} with @samp{GNU } stripped, lower-cased, and all characters 1710other than alphanumerics and underscores are changed to @samp{-}. 1711 1712It is preferable that the arguments of @code{AC_INIT} be static, i.e., 1713there should not be any shell computation, but they can be computed by 1714M4. 1715 1716The following M4 macros (e.g., @code{AC_PACKAGE_NAME}), output variables 1717(e.g., @code{PACKAGE_NAME}), and preprocessor symbols (e.g., 1718@code{PACKAGE_NAME}) are defined by @code{AC_INIT}: 1719 1720@table @asis 1721@item @code{AC_PACKAGE_NAME}, @code{PACKAGE_NAME} 1722@acindex{PACKAGE_NAME} 1723@ovindex PACKAGE_NAME 1724@cvindex PACKAGE_NAME 1725Exactly @var{package}. 1726 1727@item @code{AC_PACKAGE_TARNAME}, @code{PACKAGE_TARNAME} 1728@acindex{PACKAGE_TARNAME} 1729@ovindex PACKAGE_TARNAME 1730@cvindex PACKAGE_TARNAME 1731Exactly @var{tarname}. 1732 1733@item @code{AC_PACKAGE_VERSION}, @code{PACKAGE_VERSION} 1734@acindex{PACKAGE_VERSION} 1735@ovindex PACKAGE_VERSION 1736@cvindex PACKAGE_VERSION 1737Exactly @var{version}. 1738 1739@item @code{AC_PACKAGE_STRING}, @code{PACKAGE_STRING} 1740@acindex{PACKAGE_STRING} 1741@ovindex PACKAGE_STRING 1742@cvindex PACKAGE_STRING 1743Exactly @samp{@var{package} @var{version}}. 1744 1745@item @code{AC_PACKAGE_BUGREPORT}, @code{PACKAGE_BUGREPORT} 1746@acindex{PACKAGE_BUGREPORT} 1747@ovindex PACKAGE_BUGREPORT 1748@cvindex PACKAGE_BUGREPORT 1749Exactly @var{bug-report}. 1750@end table 1751@end defmac 1752 1753If your @command{configure} script does its own option processing, it 1754should inspect @samp{$@@} or @samp{$*} immediately after calling 1755@code{AC_INIT}, because other Autoconf macros liberally use the 1756@command{set} command to process strings, and this has the side effect 1757of updating @samp{$@@} and @samp{$*}. However, we suggest that you use 1758standard macros like @code{AC_ARG_ENABLE} instead of attempting to 1759implement your own option processing. @xref{Site Configuration}. 1760 1761 1762@node Notices 1763@section Notices in @command{configure} 1764@cindex Notices in @command{configure} 1765 1766The following macros manage version numbers for @command{configure} 1767scripts. Using them is optional. 1768 1769@c FIXME: AC_PREREQ should not be here 1770@defmac AC_PREREQ (@var{version}) 1771@acindex{PREREQ} 1772@cindex Version 1773Ensure that a recent enough version of Autoconf is being used. If the 1774version of Autoconf being used to create @command{configure} is 1775earlier than @var{version}, print an error message to the standard 1776error output and exit with failure (exit status is 63). For example: 1777 1778@example 1779AC_PREREQ([@value{VERSION}]) 1780@end example 1781 1782This macro is the only macro that may be used before @code{AC_INIT}, but 1783for consistency, you are invited not to do so. 1784@end defmac 1785 1786@defmac AC_COPYRIGHT (@var{copyright-notice}) 1787@acindex{COPYRIGHT} 1788@cindex Copyright Notice 1789State that, in addition to the Free Software Foundation's copyright on 1790the Autoconf macros, parts of your @command{configure} are covered by the 1791@var{copyright-notice}. 1792 1793The @var{copyright-notice} shows up in both the head of 1794@command{configure} and in @samp{configure --version}. 1795@end defmac 1796 1797 1798@defmac AC_REVISION (@var{revision-info}) 1799@acindex{REVISION} 1800@cindex Revision 1801Copy revision stamp @var{revision-info} into the @command{configure} 1802script, with any dollar signs or double-quotes removed. This macro lets 1803you put a revision stamp from @file{configure.ac} into @command{configure} 1804without @acronym{RCS} or @acronym{CVS} changing it when you check in 1805@command{configure}. That way, you can determine easily which revision of 1806@file{configure.ac} a particular @command{configure} corresponds to. 1807 1808For example, this line in @file{configure.ac}: 1809 1810@c The asis prevents RCS from changing the example in the manual. 1811@example 1812AC_REVISION([$@asis{Revision: 1.30 }$]) 1813@end example 1814 1815@noindent 1816produces this in @command{configure}: 1817 1818@example 1819#!/bin/sh 1820# From configure.ac Revision: 1.30 1821@end example 1822@end defmac 1823 1824 1825@node Input 1826@section Finding @command{configure} Input 1827 1828 1829@defmac AC_CONFIG_SRCDIR (@var{unique-file-in-source-dir}) 1830@acindex{CONFIG_SRCDIR} 1831@var{unique-file-in-source-dir} is some file that is in the package's 1832source directory; @command{configure} checks for this file's existence to 1833make sure that the directory that it is told contains the source code in 1834fact does. Occasionally people accidentally specify the wrong directory 1835with @option{--srcdir}; this is a safety check. @xref{configure 1836Invocation}, for more information. 1837@end defmac 1838 1839 1840@c FIXME: Remove definitively once --install explained. 1841@c 1842@c Small packages may store all their macros in @code{aclocal.m4}. As the 1843@c set of macros grows, or for maintenance reasons, a maintainer may prefer 1844@c to split the macros in several files. In this case, Autoconf must be 1845@c told which files to load, and in which order. 1846@c 1847@c @defmac AC_INCLUDE (@var{file}@dots{}) 1848@c @acindex{INCLUDE} 1849@c @c FIXME: There is no longer shell globbing. 1850@c Read the macro definitions that appear in the listed files. A list of 1851@c space-separated file names or shell globbing patterns is expected. The 1852@c files are read in the order they're listed. 1853@c 1854@c Because the order of definition of macros is important (only the last 1855@c definition of a macro is used), beware that it is @code{AC_INIT} that 1856@c loads @file{acsite.m4} and @file{aclocal.m4}. Note that 1857@c @code{AC_INCLUDE}ing a file before @code{AC_INIT} or within 1858@c @file{aclocal.m4} is different from doing so after @code{AC_INIT}: in 1859@c the latter case, non-macro lines from included files may end up in the 1860@c @file{configure} script, whereas in the former case, they'd be discarded 1861@c just like any text that appear before @code{AC_INIT}. 1862@c @end defmac 1863 1864Packages that do manual configuration or use the @command{install} program 1865might need to tell @command{configure} where to find some other shell 1866scripts by calling @code{AC_CONFIG_AUX_DIR}, though the default places 1867it looks are correct for most cases. 1868 1869@defmac AC_CONFIG_AUX_DIR (@var{dir}) 1870@acindex{CONFIG_AUX_DIR} 1871Use the auxiliary build tools (e.g., @file{install-sh}, 1872@file{config.sub}, @file{config.guess}, Cygnus @command{configure}, 1873Automake and Libtool scripts, etc.)@: that are in directory @var{dir}. 1874These are auxiliary files used in configuration. @var{dir} can be 1875either absolute or relative to @file{@var{srcdir}}. The default is 1876@file{@var{srcdir}} or @file{@var{srcdir}/..} or 1877@file{@var{srcdir}/../..}, whichever is the first that contains 1878@file{install-sh}. The other files are not checked for, so that using 1879@code{AC_PROG_INSTALL} does not automatically require distributing the 1880other auxiliary files. It checks for @file{install.sh} also, but that 1881name is obsolete because some @code{make} have a rule that creates 1882@file{install} from it if there is no makefile. 1883 1884The auxiliary directory is commonly named @file{build-aux}. 1885If you need portability to @acronym{DOS} variants, do not name the 1886auxiliary directory @file{aux}. @xref{File System Conventions}. 1887@end defmac 1888 1889@defmac AC_REQUIRE_AUX_FILE (@var{file}) 1890@acindex{REQUIRE_AUX_FILE} 1891Declares that @var{file} is expected in the directory defined above. In 1892Autoconf proper, this macro does nothing: its sole purpose is to be 1893traced by third-party tools to produce a list of expected auxiliary 1894files. For instance it is called by macros like @code{AC_PROG_INSTALL} 1895(@pxref{Particular Programs}) or @code{AC_CANONICAL_BUILD} 1896(@pxref{Canonicalizing}) to register the auxiliary files they need. 1897@end defmac 1898 1899Similarly, packages that use @command{aclocal} should declare where 1900local macros can be found using @code{AC_CONFIG_MACRO_DIR}. 1901 1902@defmac AC_CONFIG_MACRO_DIR (@var{dir}) 1903@acindex{CONFIG_MACRO_DIR} 1904Specify @var{dir} as the location of additional local Autoconf macros. 1905This macro is intended for use by future versions of commands like 1906@command{autoreconf} that trace macro calls. It should be called 1907directly from @file{configure.ac} so that tools that install macros for 1908@command{aclocal} can find the macros' declarations. 1909@end defmac 1910 1911 1912@node Output 1913@section Outputting Files 1914@cindex Outputting files 1915 1916Every Autoconf script, e.g., @file{configure.ac}, should finish by 1917calling @code{AC_OUTPUT}. That is the macro that generates and runs 1918@file{config.status}, which in turn creates the makefiles and any 1919other files resulting from configuration. This is the only required 1920macro besides @code{AC_INIT} (@pxref{Input}). 1921 1922@defmac AC_OUTPUT 1923@acindex{OUTPUT} 1924@cindex Instantiation 1925Generate @file{config.status} and launch it. Call this macro once, at 1926the end of @file{configure.ac}. 1927 1928@file{config.status} performs all the configuration actions: all the 1929output files (see @ref{Configuration Files}, macro 1930@code{AC_CONFIG_FILES}), header files (see @ref{Configuration Headers}, 1931macro @code{AC_CONFIG_HEADERS}), commands (see @ref{Configuration 1932Commands}, macro @code{AC_CONFIG_COMMANDS}), links (see 1933@ref{Configuration Links}, macro @code{AC_CONFIG_LINKS}), subdirectories 1934to configure (see @ref{Subdirectories}, macro @code{AC_CONFIG_SUBDIRS}) 1935are honored. 1936 1937The location of your @code{AC_OUTPUT} invocation is the exact point 1938where configuration actions are taken: any code afterwards is 1939executed by @code{configure} once @command{config.status} was run. If 1940you want to bind actions to @command{config.status} itself 1941(independently of whether @command{configure} is being run), see 1942@ref{Configuration Commands, , Running Arbitrary Configuration 1943Commands}. 1944@end defmac 1945 1946Historically, the usage of @code{AC_OUTPUT} was somewhat different. 1947@xref{Obsolete Macros}, for a description of the arguments that 1948@code{AC_OUTPUT} used to support. 1949 1950 1951If you run @command{make} in subdirectories, you should run it using the 1952@code{make} variable @code{MAKE}. Most versions of @command{make} set 1953@code{MAKE} to the name of the @command{make} program plus any options it 1954was given. (But many do not include in it the values of any variables 1955set on the command line, so those are not passed on automatically.) 1956Some old versions of @command{make} do not set this variable. The 1957following macro allows you to use it even with those versions. 1958 1959@defmac AC_PROG_MAKE_SET 1960@acindex{PROG_MAKE_SET} 1961@ovindex SET_MAKE 1962If the Make command, @code{$MAKE} if set or else @samp{make}, predefines 1963@code{$(MAKE)}, define output variable @code{SET_MAKE} to be empty. 1964Otherwise, define @code{SET_MAKE} to a macro definition that sets 1965@code{$(MAKE)}, such as @samp{MAKE=make}. Calls @code{AC_SUBST} for 1966@code{SET_MAKE}. 1967@end defmac 1968 1969If you use this macro, place a line like this in each @file{Makefile.in} 1970that runs @code{MAKE} on other directories: 1971 1972@example 1973@@SET_MAKE@@ 1974@end example 1975 1976 1977 1978@node Configuration Actions 1979@section Performing Configuration Actions 1980@cindex Configuration actions 1981 1982@file{configure} is designed so that it appears to do everything itself, 1983but there is actually a hidden slave: @file{config.status}. 1984@file{configure} is in charge of examining your system, but it is 1985@file{config.status} that actually takes the proper actions based on the 1986results of @file{configure}. The most typical task of 1987@file{config.status} is to @emph{instantiate} files. 1988 1989This section describes the common behavior of the four standard 1990instantiating macros: @code{AC_CONFIG_FILES}, @code{AC_CONFIG_HEADERS}, 1991@code{AC_CONFIG_COMMANDS} and @code{AC_CONFIG_LINKS}. They all 1992have this prototype: 1993 1994@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 1995@c awful. 1996@example 1997AC_CONFIG_FOOS(@var{tag}@dots{}, [@var{commands}], [@var{init-cmds}]) 1998@end example 1999 2000@noindent 2001where the arguments are: 2002 2003@table @var 2004@item tag@dots{} 2005A blank-or-newline-separated list of tags, which are typically the names of 2006the files to instantiate. 2007 2008You are encouraged to use literals as @var{tags}. In particular, you 2009should avoid 2010 2011@example 2012@dots{} && my_foos="$my_foos fooo" 2013@dots{} && my_foos="$my_foos foooo" 2014AC_CONFIG_FOOS([$my_foos]) 2015@end example 2016 2017@noindent 2018and use this instead: 2019 2020@example 2021@dots{} && AC_CONFIG_FOOS([fooo]) 2022@dots{} && AC_CONFIG_FOOS([foooo]) 2023@end example 2024 2025The macros @code{AC_CONFIG_FILES} and @code{AC_CONFIG_HEADERS} use 2026special @var{tag} values: they may have the form @samp{@var{output}} or 2027@samp{@var{output}:@var{inputs}}. The file @var{output} is instantiated 2028from its templates, @var{inputs} (defaulting to @samp{@var{output}.in}). 2029 2030@samp{AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk)]}, 2031for example, asks for 2032the creation of the file @file{Makefile} that contains the expansion of the 2033output variables in the concatenation of @file{boiler/top.mk} and 2034@file{boiler/bot.mk}. 2035 2036The special value @samp{-} might be used to denote the standard output 2037when used in @var{output}, or the standard input when used in the 2038@var{inputs}. You most probably don't need to use this in 2039@file{configure.ac}, but it is convenient when using the command line 2040interface of @file{./config.status}, see @ref{config.status Invocation}, 2041for more details. 2042 2043The @var{inputs} may be absolute or relative file names. In the latter 2044case they are first looked for in the build tree, and then in the source 2045tree. 2046 2047@item commands 2048Shell commands output literally into @file{config.status}, and 2049associated with a tag that the user can use to tell @file{config.status} 2050which the commands to run. The commands are run each time a @var{tag} 2051request is given to @file{config.status}, typically each time the file 2052@file{@var{tag}} is created. 2053 2054The variables set during the execution of @command{configure} are 2055@emph{not} available here: you first need to set them via the 2056@var{init-cmds}. Nonetheless the following variables are precomputed: 2057 2058@table @code 2059@item srcdir 2060The name of the top source directory, assuming that the working 2061directory is the top build directory. This 2062is what the @command{configure} option @option{--srcdir} sets. 2063 2064@item ac_top_srcdir 2065The name of the top source directory, assuming that the working 2066directory is the current build directory. 2067 2068 2069@item ac_top_build_prefix 2070The name of the top build directory, assuming that the working 2071directory is the current build directory. 2072It can be empty, or else ends with a slash, so that you may concatenate 2073it. 2074 2075@item ac_srcdir 2076The name of the corresponding source directory, assuming that the 2077working directory is the current build directory. 2078@end table 2079 2080@noindent 2081The @dfn{current} directory refers to the directory (or 2082pseudo-directory) containing the input part of @var{tags}. For 2083instance, running 2084 2085@example 2086AC_CONFIG_COMMANDS([deep/dir/out:in/in.in], [@dots{}], [@dots{}]) 2087@end example 2088 2089@noindent 2090 with @option{--srcdir=../package} produces the following values: 2091 2092@example 2093# Argument of --srcdir 2094srcdir='../package' 2095# Reversing deep/dir 2096ac_top_build_prefix='../../' 2097# Concatenation of $ac_top_build_prefix and srcdir 2098ac_top_srcdir='../../../package' 2099# Concatenation of $ac_top_srcdir and deep/dir 2100ac_srcdir='../../../package/deep/dir' 2101@end example 2102 2103@noindent 2104independently of @samp{in/in.in}. 2105 2106@item init-cmds 2107Shell commands output @emph{unquoted} near the beginning of 2108@file{config.status}, and executed each time @file{config.status} runs 2109(regardless of the tag). Because they are unquoted, for example, 2110@samp{$var} is output as the value of @code{var}. @var{init-cmds} 2111is typically used by @file{configure} to give @file{config.status} some 2112variables it needs to run the @var{commands}. 2113 2114You should be extremely cautious in your variable names: all the 2115@var{init-cmds} share the same name space and may overwrite each other 2116in unpredictable ways. Sorry@enddots{} 2117@end table 2118 2119All these macros can be called multiple times, with different 2120@var{tag} values, of course! 2121 2122 2123@node Configuration Files 2124@section Creating Configuration Files 2125@cindex Creating configuration files 2126@cindex Configuration file creation 2127 2128Be sure to read the previous section, @ref{Configuration Actions}. 2129 2130@defmac AC_CONFIG_FILES (@var{file}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 2131@acindex{CONFIG_FILES} 2132Make @code{AC_OUTPUT} create each @file{@var{file}} by copying an input 2133file (by default @file{@var{file}.in}), substituting the output variable 2134values. 2135@c Before we used to have this feature, which was later rejected 2136@c because it complicates the writing of makefiles: 2137@c If the file would be unchanged, it is left untouched, to preserve 2138@c timestamp. 2139This macro is one of the instantiating macros; see @ref{Configuration 2140Actions}. @xref{Makefile Substitutions}, for more information on using 2141output variables. @xref{Setting Output Variables}, for more information 2142on creating them. This macro creates the directory that the file is in 2143if it doesn't exist. Usually, makefiles are created this way, 2144but other files, such as @file{.gdbinit}, can be specified as well. 2145 2146Typical calls to @code{AC_CONFIG_FILES} look like this: 2147 2148@example 2149AC_CONFIG_FILES([Makefile src/Makefile man/Makefile X/Imakefile]) 2150AC_CONFIG_FILES([autoconf], [chmod +x autoconf]) 2151@end example 2152 2153You can override an input file name by appending to @var{file} a 2154colon-separated list of input files. Examples: 2155 2156@example 2157AC_CONFIG_FILES([Makefile:boiler/top.mk:boiler/bot.mk] 2158 [lib/Makefile:boiler/lib.mk]) 2159@end example 2160 2161@noindent 2162Doing this allows you to keep your file names acceptable to 2163@acronym{DOS} variants, or 2164to prepend and/or append boilerplate to the file. 2165@end defmac 2166 2167 2168 2169@node Makefile Substitutions 2170@section Substitutions in Makefiles 2171@cindex Substitutions in makefiles 2172@cindex Makefile substitutions 2173 2174Each subdirectory in a distribution that contains something to be 2175compiled or installed should come with a file @file{Makefile.in}, from 2176which @command{configure} creates a file @file{Makefile} in that directory. 2177To create @file{Makefile}, @command{configure} performs a simple variable 2178substitution, replacing occurrences of @samp{@@@var{variable}@@} in 2179@file{Makefile.in} with the value that @command{configure} has determined 2180for that variable. Variables that are substituted into output files in 2181this way are called @dfn{output variables}. They are ordinary shell 2182variables that are set in @command{configure}. To make @command{configure} 2183substitute a particular variable into the output files, the macro 2184@code{AC_SUBST} must be called with that variable name as an argument. 2185Any occurrences of @samp{@@@var{variable}@@} for other variables are 2186left unchanged. @xref{Setting Output Variables}, for more information 2187on creating output variables with @code{AC_SUBST}. 2188 2189A software package that uses a @command{configure} script should be 2190distributed with a file @file{Makefile.in}, but no makefile; that 2191way, the user has to properly configure the package for the local system 2192before compiling it. 2193 2194@xref{Makefile Conventions, , Makefile Conventions, standards, The 2195@acronym{GNU} Coding Standards}, for more information on what to put in 2196makefiles. 2197 2198@menu 2199* Preset Output Variables:: Output variables that are always set 2200* Installation Directory Variables:: Other preset output variables 2201* Changed Directory Variables:: Warnings about @file{datarootdir} 2202* Build Directories:: Supporting multiple concurrent compiles 2203* Automatic Remaking:: Makefile rules for configuring 2204@end menu 2205 2206@node Preset Output Variables 2207@subsection Preset Output Variables 2208@cindex Output variables 2209 2210Some output variables are preset by the Autoconf macros. Some of the 2211Autoconf macros set additional output variables, which are mentioned in 2212the descriptions for those macros. @xref{Output Variable Index}, for a 2213complete list of output variables. @xref{Installation Directory 2214Variables}, for the list of the preset ones related to installation 2215directories. Below are listed the other preset ones. They all are 2216precious variables (@pxref{Setting Output Variables}, 2217@code{AC_ARG_VAR}). 2218 2219@c Just say no to ASCII sorting! We're humans, not computers. 2220@c These variables are listed as they would be in a dictionary: 2221@c actor 2222@c Actress 2223@c actress 2224 2225@defvar CFLAGS 2226@ovindex CFLAGS 2227Debugging and optimization options for the C compiler. If it is not set 2228in the environment when @command{configure} runs, the default value is set 2229when you call @code{AC_PROG_CC} (or empty if you don't). @command{configure} 2230uses this variable when compiling or linking programs to test for C features. 2231 2232If a compiler option affects only the behavior of the preprocessor 2233(e.g., @option{-D @var{name}}), it should be put into @code{CPPFLAGS} 2234instead. If it affects only the linker (e.g., @option{-L 2235@var{directory}}), it should be put into @code{LDFLAGS} instead. If it 2236affects only the compiler proper, @code{CFLAGS} is the natural home for 2237it. If an option affects multiple phases of the compiler, though, 2238matters get tricky. One approach to put such options directly into 2239@code{CC}, e.g., @code{CC='gcc -m64'}. Another is to put them into both 2240@code{CPPFLAGS} and @code{LDFLAGS}, but not into @code{CFLAGS}. 2241 2242@end defvar 2243 2244@defvar configure_input 2245@ovindex configure_input 2246A comment saying that the file was generated automatically by 2247@command{configure} and giving the name of the input file. 2248@code{AC_OUTPUT} adds a comment line containing this variable to the top 2249of every makefile it creates. For other files, you should 2250reference this variable in a comment at the top of each input file. For 2251example, an input shell script should begin like this: 2252 2253@example 2254#!/bin/sh 2255# @@configure_input@@ 2256@end example 2257 2258@noindent 2259The presence of that line also reminds people editing the file that it 2260needs to be processed by @command{configure} in order to be used. 2261@end defvar 2262 2263@defvar CPPFLAGS 2264@ovindex CPPFLAGS 2265Preprocessor options for the C, C++, and Objective C preprocessors and 2266compilers. If 2267it is not set in the environment when @command{configure} runs, the default 2268value is empty. @command{configure} uses this variable when preprocessing 2269or compiling programs to test for C, C++, and Objective C features. 2270 2271This variable's contents should contain options like @option{-I}, 2272@option{-D}, and @option{-U} that affect only the behavior of the 2273preprocessor. Please see the explanation of @code{CFLAGS} for what you 2274can do if an option affects other phases of the compiler as well. 2275 2276Currently, @command{configure} always links as part of a single 2277invocation of the compiler that also preprocesses and compiles, so it 2278uses this variable also when linking programs. However, it is unwise to 2279depend on this behavior because the @acronym{GNU} coding standards do 2280not require it and many packages do not use @code{CPPFLAGS} when linking 2281programs. 2282 2283@xref{Special Chars in Variables}, for limitations that @code{CPPFLAGS} 2284might run into. 2285@end defvar 2286 2287@defvar CXXFLAGS 2288@ovindex CXXFLAGS 2289Debugging and optimization options for the C++ compiler. It acts like 2290@code{CFLAGS}, but for C++ instead of C. 2291@end defvar 2292 2293@defvar DEFS 2294@ovindex DEFS 2295@option{-D} options to pass to the C compiler. If @code{AC_CONFIG_HEADERS} 2296is called, @command{configure} replaces @samp{@@DEFS@@} with 2297@option{-DHAVE_CONFIG_H} instead (@pxref{Configuration Headers}). This 2298variable is not defined while @command{configure} is performing its tests, 2299only when creating the output files. @xref{Setting Output Variables}, for 2300how to check the results of previous tests. 2301@end defvar 2302 2303@defvar ECHO_C 2304@defvarx ECHO_N 2305@defvarx ECHO_T 2306@ovindex ECHO_C 2307@ovindex ECHO_N 2308@ovindex ECHO_T 2309How does one suppress the trailing newline from @command{echo} for 2310question-answer message pairs? These variables provide a way: 2311 2312@example 2313echo $ECHO_N "And the winner is... $ECHO_C" 2314sleep 100000000000 2315echo "$@{ECHO_T@}dead." 2316@end example 2317 2318@noindent 2319Some old and uncommon @command{echo} implementations offer no means to 2320achieve this, in which case @code{ECHO_T} is set to tab. You might not 2321want to use it. 2322@end defvar 2323 2324@defvar ERLCFLAGS 2325@ovindex ERLCFLAGS 2326Debugging and optimization options for the Erlang compiler. If it is not set 2327in the environment when @command{configure} runs, the default value is empty. 2328@command{configure} uses this variable when compiling 2329programs to test for Erlang features. 2330@end defvar 2331 2332@defvar FCFLAGS 2333@ovindex FCFLAGS 2334Debugging and optimization options for the Fortran compiler. If it 2335is not set in the environment when @command{configure} runs, the default 2336value is set when you call @code{AC_PROG_FC} (or empty if you don't). 2337@command{configure} uses this variable when compiling or linking 2338programs to test for Fortran features. 2339@end defvar 2340 2341@defvar FFLAGS 2342@ovindex FFLAGS 2343Debugging and optimization options for the Fortran 77 compiler. If it 2344is not set in the environment when @command{configure} runs, the default 2345value is set when you call @code{AC_PROG_F77} (or empty if you don't). 2346@command{configure} uses this variable when compiling or linking 2347programs to test for Fortran 77 features. 2348@end defvar 2349 2350@defvar LDFLAGS 2351@ovindex LDFLAGS 2352Options for the linker. If it is not set 2353in the environment when @command{configure} runs, the default value is empty. 2354@command{configure} uses this variable when linking programs to test for 2355C, C++, Objective C, and Fortran features. 2356 2357This variable's contents should contain options like @option{-s} and 2358@option{-L} that affect only the behavior of the linker. Please see the 2359explanation of @code{CFLAGS} for what you can do if an option also 2360affects other phases of the compiler. 2361 2362Don't use this variable to pass library names 2363(@option{-l}) to the linker; use @code{LIBS} instead. 2364@end defvar 2365 2366@defvar LIBS 2367@ovindex LIBS 2368@option{-l} options to pass to the linker. The default value is empty, 2369but some Autoconf macros may prepend extra libraries to this variable if 2370those libraries are found and provide necessary functions, see 2371@ref{Libraries}. @command{configure} uses this variable when linking 2372programs to test for C, C++, and Fortran features. 2373@end defvar 2374 2375@defvar OBJCFLAGS 2376@ovindex OBJCFLAGS 2377Debugging and optimization options for the Objective C compiler. It 2378acts like @code{CFLAGS}, but for Objective C instead of C. 2379@end defvar 2380 2381@defvar builddir 2382@ovindex builddir 2383Rigorously equal to @samp{.}. Added for symmetry only. 2384@end defvar 2385 2386@defvar abs_builddir 2387@ovindex abs_builddir 2388Absolute name of @code{builddir}. 2389@end defvar 2390 2391@defvar top_builddir 2392@ovindex top_builddir 2393The relative name of the top level of the current build tree. In the 2394top-level directory, this is the same as @code{builddir}. 2395@end defvar 2396 2397@defvar abs_top_builddir 2398@ovindex abs_top_builddir 2399Absolute name of @code{top_builddir}. 2400@end defvar 2401 2402@defvar srcdir 2403@ovindex srcdir 2404The name of the directory that contains the source code for 2405that makefile. 2406@end defvar 2407 2408@defvar abs_srcdir 2409@ovindex abs_srcdir 2410Absolute name of @code{srcdir}. 2411@end defvar 2412 2413@defvar top_srcdir 2414@ovindex top_srcdir 2415The name of the top-level source code directory for the 2416package. In the top-level directory, this is the same as @code{srcdir}. 2417@end defvar 2418 2419@defvar abs_top_srcdir 2420@ovindex abs_top_srcdir 2421Absolute name of @code{top_srcdir}. 2422@end defvar 2423 2424@node Installation Directory Variables 2425@subsection Installation Directory Variables 2426@cindex Installation directories 2427@cindex Directories, installation 2428 2429The following variables specify the directories for 2430package installation, see @ref{Directory Variables, , Variables for 2431Installation Directories, standards, The @acronym{GNU} Coding 2432Standards}, for more information. See the end of this section for 2433details on when and how to use these variables. 2434 2435@defvar bindir 2436@ovindex bindir 2437The directory for installing executables that users run. 2438@end defvar 2439 2440@defvar datadir 2441@ovindex datadir 2442The directory for installing idiosyncratic read-only 2443architecture-independent data. 2444@end defvar 2445 2446@defvar datarootdir 2447@ovindex datarootdir 2448The root of the directory tree for read-only architecture-independent 2449data files. 2450@end defvar 2451 2452@defvar docdir 2453@ovindex docdir 2454The directory for installing documentation files (other than Info and 2455man). 2456@end defvar 2457 2458@defvar dvidir 2459@ovindex dvidir 2460The directory for installing documentation files in DVI format. 2461@end defvar 2462 2463@defvar exec_prefix 2464@ovindex exec_prefix 2465The installation prefix for architecture-dependent files. By default 2466it's the same as @var{prefix}. You should avoid installing anything 2467directly to @var{exec_prefix}. However, the default value for 2468directories containing architecture-dependent files should be relative 2469to @var{exec_prefix}. 2470@end defvar 2471 2472@defvar htmldir 2473@ovindex htmldir 2474The directory for installing HTML documentation. 2475@end defvar 2476 2477@defvar includedir 2478@ovindex includedir 2479The directory for installing C header files. 2480@end defvar 2481 2482@defvar infodir 2483@ovindex infodir 2484The directory for installing documentation in Info format. 2485@end defvar 2486 2487@defvar libdir 2488@ovindex libdir 2489The directory for installing object code libraries. 2490@end defvar 2491 2492@defvar libexecdir 2493@ovindex libexecdir 2494The directory for installing executables that other programs run. 2495@end defvar 2496 2497@defvar localedir 2498@ovindex localedir 2499The directory for installing locale-dependent but 2500architecture-independent data, such as message catalogs. This directory 2501usually has a subdirectory per locale. 2502@end defvar 2503 2504@defvar localstatedir 2505@ovindex localstatedir 2506The directory for installing modifiable single-machine data. 2507@end defvar 2508 2509@defvar mandir 2510@ovindex mandir 2511The top-level directory for installing documentation in man format. 2512@end defvar 2513 2514@defvar oldincludedir 2515@ovindex oldincludedir 2516The directory for installing C header files for non-@acronym{GCC} compilers. 2517@end defvar 2518 2519@defvar pdfdir 2520@ovindex pdfdir 2521The directory for installing PDF documentation. 2522@end defvar 2523 2524@defvar prefix 2525@ovindex prefix 2526The common installation prefix for all files. If @var{exec_prefix} 2527is defined to a different value, @var{prefix} is used only for 2528architecture-independent files. 2529@end defvar 2530 2531@defvar psdir 2532@ovindex psdir 2533The directory for installing PostScript documentation. 2534@end defvar 2535 2536@defvar sbindir 2537@ovindex sbindir 2538The directory for installing executables that system 2539administrators run. 2540@end defvar 2541 2542@defvar sharedstatedir 2543@ovindex sharedstatedir 2544The directory for installing modifiable architecture-independent data. 2545@end defvar 2546 2547@defvar sysconfdir 2548@ovindex sysconfdir 2549The directory for installing read-only single-machine data. 2550@end defvar 2551 2552 2553Most of these variables have values that rely on @code{prefix} or 2554@code{exec_prefix}. It is deliberate that the directory output 2555variables keep them unexpanded: typically @samp{@@datarootdir@@} is 2556replaced by @samp{$@{prefix@}/share}, not @samp{/usr/local/share}, and 2557@samp{@@datadir@@} is replaced by @samp{$@{datarootdir@}}. 2558 2559This behavior is mandated by the @acronym{GNU} coding standards, so that when 2560the user runs: 2561 2562@table @samp 2563@item make 2564she can still specify a different prefix from the one specified to 2565@command{configure}, in which case, if needed, the package should hard 2566code dependencies corresponding to the make-specified prefix. 2567 2568@item make install 2569she can specify a different installation location, in which case the 2570package @emph{must} still depend on the location which was compiled in 2571(i.e., never recompile when @samp{make install} is run). This is an 2572extremely important feature, as many people may decide to install all 2573the files of a package grouped together, and then install links from 2574the final locations to there. 2575@end table 2576 2577In order to support these features, it is essential that 2578@code{datarootdir} remains being defined as @samp{$@{prefix@}/share} to 2579depend upon the current value of @code{prefix}. 2580 2581A corollary is that you should not use these variables except in 2582makefiles. For instance, instead of trying to evaluate @code{datadir} 2583in @file{configure} and hard-coding it in makefiles using 2584e.g., @samp{AC_DEFINE_UNQUOTED([DATADIR], ["$datadir"], [Data directory.])}, 2585you should add 2586@option{-DDATADIR='$(datadir)'} to your makefile's definition of 2587@code{CPPFLAGS} (@code{AM_CPPFLAGS} if you are also using Automake). 2588 2589Similarly, you should not rely on @code{AC_CONFIG_FILES} to replace 2590@code{datadir} and friends in your shell scripts and other files; instead, 2591let @command{make} manage their replacement. For instance Autoconf 2592ships templates of its shell scripts ending with @samp{.in}, and uses a 2593makefile snippet similar to the following to build scripts like 2594@command{autoheader} and @command{autom4te}: 2595 2596@example 2597@group 2598edit = sed \ 2599 -e 's|@@datadir[@@]|$(pkgdatadir)|g' \ 2600 -e 's|@@prefix[@@]|$(prefix)|g' 2601@end group 2602 2603@group 2604autoheader autom4te: Makefile 2605 rm -f $@@ $@@.tmp 2606 $(edit) '$(srcdir)/$@@.in' >$@@.tmp 2607 chmod +x $@@.tmp 2608 chmod a-w $@@.tmp 2609 mv $@@.tmp $@@ 2610@end group 2611 2612@group 2613autoheader: $(srcdir)/autoheader.in 2614autom4te: $(srcdir)/autom4te.in 2615@end group 2616@end example 2617 2618Some details are noteworthy: 2619 2620@table @asis 2621@item @samp{@@datadir[@@]} 2622The brackets prevent @command{configure} from replacing 2623@samp{@@datadir@@} in the Sed expression itself. 2624Brackets are preferable to a backslash here, since 2625Posix says @samp{\@@} is not portable. 2626 2627@item @samp{$(pkgdatadir)} 2628Don't use @samp{@@pkgdatadir@@}! Use the matching makefile variable 2629instead. 2630 2631@item @samp{/} 2632Don't use @samp{/} in the Sed expressions that replace file names since 2633most likely the 2634variables you use, such as @samp{$(pkgdatadir)}, contain @samp{/}. 2635Use a shell metacharacter instead, such as @samp{|}. 2636 2637@item special characters 2638File names, file name components, and the value of @code{VPATH} should 2639not contain shell metacharacters or white 2640space. @xref{Special Chars in Variables}. 2641 2642@item dependency on @file{Makefile} 2643Since @code{edit} uses values that depend on the configuration specific 2644values (@code{prefix}, etc.)@: and not only on @code{VERSION} and so forth, 2645the output depends on @file{Makefile}, not @file{configure.ac}. 2646 2647@item @samp{$@@} 2648The main rule is generic, and uses @samp{$@@} extensively to 2649avoid the need for multiple copies of the rule. 2650 2651@item Separated dependencies and single suffix rules 2652You can't use them! The above snippet cannot be (portably) rewritten 2653as: 2654 2655@example 2656autoconf autoheader: Makefile 2657@group 2658.in: 2659 rm -f $@@ $@@.tmp 2660 $(edit) $< >$@@.tmp 2661 chmod +x $@@.tmp 2662 mv $@@.tmp $@@ 2663@end group 2664@end example 2665 2666@xref{Single Suffix Rules}, for details. 2667 2668@item @samp{$(srcdir)} 2669Be sure to specify the name of the source directory, 2670otherwise the package won't support separated builds. 2671@end table 2672 2673For the more specific installation of Erlang libraries, the following variables 2674are defined: 2675 2676@defvar ERLANG_INSTALL_LIB_DIR 2677@ovindex ERLANG_INSTALL_LIB_DIR 2678@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 2679The common parent directory of Erlang library installation directories. 2680This variable is set by calling the @code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} 2681macro in @file{configure.ac}. 2682@end defvar 2683 2684@defvar ERLANG_INSTALL_LIB_DIR_@var{library} 2685@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 2686@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 2687The installation directory for Erlang library @var{library}. 2688This variable is set by calling the 2689@samp{AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR(@var{library}, @var{version}} 2690macro in @file{configure.ac}. 2691@end defvar 2692 2693@xref{Erlang Libraries}, for details. 2694 2695 2696@node Changed Directory Variables 2697@subsection Changed Directory Variables 2698@cindex @file{datarootdir} 2699 2700In Autoconf 2.60, the set of directory variables has changed, and the 2701defaults of some variables have been adjusted 2702(@pxref{Installation Directory Variables}) to changes in the 2703@acronym{GNU} Coding Standards. Notably, @file{datadir}, @file{infodir}, and 2704@file{mandir} are now expressed in terms of @file{datarootdir}. If you are 2705upgrading from an earlier Autoconf version, you may need to adjust your files 2706to ensure that the directory variables are substituted correctly 2707(@pxref{Defining Directories}), and that a definition of @file{datarootdir} is 2708in place. For example, in a @file{Makefile.in}, adding 2709 2710@example 2711datarootdir = @@datarootdir@@ 2712@end example 2713 2714@noindent 2715is usually sufficient. If you use Automake to create @file{Makefile.in}, 2716it will add this for you. 2717 2718To help with the transition, Autoconf warns about files that seem to use 2719@code{datarootdir} without defining it. In some cases, it then expands 2720the value of @code{$datarootdir} in substitutions of the directory 2721variables. The following example shows such a warning: 2722 2723@example 2724$ @kbd{cat configure.ac} 2725AC_INIT 2726AC_CONFIG_FILES([Makefile]) 2727AC_OUTPUT 2728$ @kbd{cat Makefile.in} 2729prefix = @@prefix@@ 2730datadir = @@datadir@@ 2731$ @kbd{autoconf} 2732$ @kbd{configure} 2733configure: creating ./config.status 2734config.status: creating Makefile 2735config.status: WARNING: 2736 Makefile.in seems to ignore the --datarootdir setting 2737$ @kbd{cat Makefile} 2738prefix = /usr/local 2739datadir = $@{prefix@}/share 2740@end example 2741 2742Usually one can easily change the file to accommodate both older and newer 2743Autoconf releases: 2744 2745@example 2746$ @kbd{cat Makefile.in} 2747prefix = @@prefix@@ 2748datarootdir = @@datarootdir@@ 2749datadir = @@datadir@@ 2750$ @kbd{configure} 2751configure: creating ./config.status 2752config.status: creating Makefile 2753$ @kbd{cat Makefile} 2754prefix = /usr/local 2755datarootdir = $@{prefix@}/share 2756datadir = $@{datarootdir@} 2757@end example 2758 2759@acindex{DATAROOTDIR_CHECKED} 2760In some cases, however, the checks may not be able to detect that a suitable 2761initialization of @code{datarootdir} is in place, or they may fail to detect 2762that such an initialization is necessary in the output file. If, after 2763auditing your package, there are still spurious @file{configure} warnings about 2764@code{datarootdir}, you may add the line 2765 2766@example 2767AC_DEFUN([AC_DATAROOTDIR_CHECKED]) 2768@end example 2769 2770@noindent 2771to your @file{configure.ac} to disable the warnings. This is an exception 2772to the usual rule that you should not define a macro whose name begins with 2773@code{AC_} (@pxref{Macro Names}). 2774 2775 2776 2777@node Build Directories 2778@subsection Build Directories 2779@cindex Build directories 2780@cindex Directories, build 2781 2782You can support compiling a software package for several architectures 2783simultaneously from the same copy of the source code. The object files 2784for each architecture are kept in their own directory. 2785 2786To support doing this, @command{make} uses the @code{VPATH} variable to 2787find the files that are in the source directory. @acronym{GNU} Make 2788and most other recent @command{make} programs can do this. Older 2789@command{make} programs do not support @code{VPATH}; when using them, the 2790source code must be in the same directory as the object files. 2791 2792To support @code{VPATH}, each @file{Makefile.in} should contain two 2793lines that look like: 2794 2795@example 2796srcdir = @@srcdir@@ 2797VPATH = @@srcdir@@ 2798@end example 2799 2800Do not set @code{VPATH} to the value of another variable, for example 2801@samp{VPATH = $(srcdir)}, because some versions of @command{make} do not do 2802variable substitutions on the value of @code{VPATH}. 2803 2804@command{configure} substitutes the correct value for @code{srcdir} when 2805it produces @file{Makefile}. 2806 2807Do not use the @code{make} variable @code{$<}, which expands to the 2808file name of the file in the source directory (found with @code{VPATH}), 2809except in implicit rules. (An implicit rule is one such as @samp{.c.o}, 2810which tells how to create a @file{.o} file from a @file{.c} file.) Some 2811versions of @command{make} do not set @code{$<} in explicit rules; they 2812expand it to an empty value. 2813 2814Instead, Make command lines should always refer to source 2815files by prefixing them with @samp{$(srcdir)/}. For example: 2816 2817@example 2818time.info: time.texinfo 2819 $(MAKEINFO) '$(srcdir)/time.texinfo' 2820@end example 2821 2822@node Automatic Remaking 2823@subsection Automatic Remaking 2824@cindex Automatic remaking 2825@cindex Remaking automatically 2826 2827You can put rules like the following in the top-level @file{Makefile.in} 2828for a package to automatically update the configuration information when 2829you change the configuration files. This example includes all of the 2830optional files, such as @file{aclocal.m4} and those related to 2831configuration header files. Omit from the @file{Makefile.in} rules for 2832any of these files that your package does not use. 2833 2834The @samp{$(srcdir)/} prefix is included because of limitations in the 2835@code{VPATH} mechanism. 2836 2837The @file{stamp-} files are necessary because the timestamps of 2838@file{config.h.in} and @file{config.h} are not changed if remaking 2839them does not change their contents. This feature avoids unnecessary 2840recompilation. You should include the file @file{stamp-h.in} your 2841package's distribution, so that @command{make} considers 2842@file{config.h.in} up to date. Don't use @command{touch} 2843(@pxref{Limitations of Usual Tools}); instead, use @command{echo} (using 2844@command{date} would cause needless differences, hence @acronym{CVS} 2845conflicts, etc.). 2846 2847@example 2848@group 2849$(srcdir)/configure: configure.ac aclocal.m4 2850 cd '$(srcdir)' && autoconf 2851 2852# autoheader might not change config.h.in, so touch a stamp file. 2853$(srcdir)/config.h.in: stamp-h.in 2854$(srcdir)/stamp-h.in: configure.ac aclocal.m4 2855 cd '$(srcdir)' && autoheader 2856 echo timestamp > '$(srcdir)/stamp-h.in' 2857 2858config.h: stamp-h 2859stamp-h: config.h.in config.status 2860 ./config.status 2861 2862Makefile: Makefile.in config.status 2863 ./config.status 2864 2865config.status: configure 2866 ./config.status --recheck 2867@end group 2868@end example 2869 2870@noindent 2871(Be careful if you copy these lines directly into your makefile, as you 2872need to convert the indented lines to start with the tab character.) 2873 2874In addition, you should use 2875 2876@example 2877AC_CONFIG_FILES([stamp-h], [echo timestamp > stamp-h]) 2878@end example 2879 2880@noindent 2881so @file{config.status} ensures that @file{config.h} is considered up to 2882date. @xref{Output}, for more information about @code{AC_OUTPUT}. 2883 2884@xref{config.status Invocation}, for more examples of handling 2885configuration-related dependencies. 2886 2887@node Configuration Headers 2888@section Configuration Header Files 2889@cindex Configuration Header 2890@cindex @file{config.h} 2891 2892When a package contains more than a few tests that define C preprocessor 2893symbols, the command lines to pass @option{-D} options to the compiler 2894can get quite long. This causes two problems. One is that the 2895@command{make} output is hard to visually scan for errors. More 2896seriously, the command lines can exceed the length limits of some 2897operating systems. As an alternative to passing @option{-D} options to 2898the compiler, @command{configure} scripts can create a C header file 2899containing @samp{#define} directives. The @code{AC_CONFIG_HEADERS} 2900macro selects this kind of output. Though it can be called anywhere 2901between @code{AC_INIT} and @code{AC_OUTPUT}, it is customary to call 2902it right after @code{AC_INIT}. 2903 2904The package should @samp{#include} the configuration header file before 2905any other header files, to prevent inconsistencies in declarations (for 2906example, if it redefines @code{const}). 2907 2908To provide for VPATH builds, remember to pass the C compiler a @option{-I.} 2909option (or @option{-I..}; whichever directory contains @file{config.h}). 2910Even if you use @samp{#include "config.h"}, the preprocessor searches only 2911the directory of the currently read file, i.e., the source directory, not 2912the build directory. 2913 2914With the appropriate @option{-I} option, you can use 2915@samp{#include <config.h>}. Actually, it's a good habit to use it, 2916because in the rare case when the source directory contains another 2917@file{config.h}, the build directory should be searched first. 2918 2919 2920@defmac AC_CONFIG_HEADERS (@var{header} @dots{}, @ovar{cmds}, @ovar{init-cmds}) 2921@acindex{CONFIG_HEADERS} 2922@cvindex HAVE_CONFIG_H 2923This macro is one of the instantiating macros; see @ref{Configuration 2924Actions}. Make @code{AC_OUTPUT} create the file(s) in the 2925blank-or-newline-separated list @var{header} containing C preprocessor 2926@code{#define} statements, and replace @samp{@@DEFS@@} in generated 2927files with @option{-DHAVE_CONFIG_H} instead of the value of @code{DEFS}. 2928The usual name for @var{header} is @file{config.h}. 2929 2930If @var{header} already exists and its contents are identical to what 2931@code{AC_OUTPUT} would put in it, it is left alone. Doing this allows 2932making some changes in the configuration without needlessly causing 2933object files that depend on the header file to be recompiled. 2934 2935Usually the input file is named @file{@var{header}.in}; however, you can 2936override the input file name by appending to @var{header} a 2937colon-separated list of input files. Examples: 2938 2939@example 2940AC_CONFIG_HEADERS([config.h:config.hin]) 2941AC_CONFIG_HEADERS([defines.h:defs.pre:defines.h.in:defs.post]) 2942@end example 2943 2944@noindent 2945Doing this allows you to keep your file names acceptable to 2946@acronym{DOS} variants, or 2947to prepend and/or append boilerplate to the file. 2948@end defmac 2949 2950@defmac AH_HEADER 2951@ahindex{HEADER} 2952This macro is defined as the name of the first declared config header 2953and undefined if no config headers have been declared up to this point. 2954A third-party macro may, for example, require use of a config header 2955without invoking AC_CONFIG_HEADERS twice, like this: 2956 2957@example 2958AC_CONFIG_COMMANDS_PRE( 2959 [m4_ifndef([AH_HEADER], [AC_CONFIG_HEADERS([config.h])])]) 2960@end example 2961 2962@end defmac 2963 2964@xref{Configuration Actions}, for more details on @var{header}. 2965 2966@menu 2967* Header Templates:: Input for the configuration headers 2968* autoheader Invocation:: How to create configuration templates 2969* Autoheader Macros:: How to specify CPP templates 2970@end menu 2971 2972@node Header Templates 2973@subsection Configuration Header Templates 2974@cindex Configuration Header Template 2975@cindex Header templates 2976@cindex @file{config.h.in} 2977 2978Your distribution should contain a template file that looks as you want 2979the final header file to look, including comments, with @code{#undef} 2980statements which are used as hooks. For example, suppose your 2981@file{configure.ac} makes these calls: 2982 2983@example 2984AC_CONFIG_HEADERS([conf.h]) 2985AC_CHECK_HEADERS([unistd.h]) 2986@end example 2987 2988@noindent 2989Then you could have code like the following in @file{conf.h.in}. On 2990systems that have @file{unistd.h}, @command{configure} defines 2991@samp{HAVE_UNISTD_H} to 1. On other systems, the whole line is 2992commented out (in case the system predefines that symbol). 2993 2994@example 2995@group 2996/* Define as 1 if you have unistd.h. */ 2997#undef HAVE_UNISTD_H 2998@end group 2999@end example 3000 3001Pay attention that @samp{#undef} is in the first column, and there is 3002nothing after @samp{HAVE_UNISTD_H}, not even white space. You can 3003then decode the configuration header using the preprocessor directives: 3004 3005@example 3006@group 3007#include <conf.h> 3008 3009#ifdef HAVE_UNISTD_H 3010# include <unistd.h> 3011#else 3012/* We are in trouble. */ 3013#endif 3014@end group 3015@end example 3016 3017The use of old form templates, with @samp{#define} instead of 3018@samp{#undef} is strongly discouraged. Similarly with old templates 3019with comments on the same line as the @samp{#undef}. Anyway, putting 3020comments in preprocessor macros has never been a good idea. 3021 3022Since it is a tedious task to keep a template header up to date, you may 3023use @command{autoheader} to generate it, see @ref{autoheader Invocation}. 3024 3025 3026@node autoheader Invocation 3027@subsection Using @command{autoheader} to Create @file{config.h.in} 3028@cindex @command{autoheader} 3029 3030The @command{autoheader} program can create a template file of C 3031@samp{#define} statements for @command{configure} to use. If 3032@file{configure.ac} invokes @code{AC_CONFIG_HEADERS(@var{file})}, 3033@command{autoheader} creates @file{@var{file}.in}; if multiple file 3034arguments are given, the first one is used. Otherwise, 3035@command{autoheader} creates @file{config.h.in}. 3036 3037In order to do its job, @command{autoheader} needs you to document all 3038of the symbols that you might use. Typically this is done via an 3039@code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} call whose first argument 3040is a literal symbol and whose third argument describes the symbol 3041(@pxref{Defining Symbols}). Alternatively, you can use 3042@code{AH_TEMPLATE} (@pxref{Autoheader Macros}), or you can supply a 3043suitable input file for a subsequent configuration header file. 3044Symbols defined by Autoconf's builtin tests are already documented properly; 3045you need to document only those that you 3046define yourself. 3047 3048You might wonder why @command{autoheader} is needed: after all, why 3049would @command{configure} need to ``patch'' a @file{config.h.in} to 3050produce a @file{config.h} instead of just creating @file{config.h} from 3051scratch? Well, when everything rocks, the answer is just that we are 3052wasting our time maintaining @command{autoheader}: generating 3053@file{config.h} directly is all that is needed. When things go wrong, 3054however, you'll be thankful for the existence of @command{autoheader}. 3055 3056The fact that the symbols are documented is important in order to 3057@emph{check} that @file{config.h} makes sense. The fact that there is a 3058well-defined list of symbols that should be defined (or not) is 3059also important for people who are porting packages to environments where 3060@command{configure} cannot be run: they just have to @emph{fill in the 3061blanks}. 3062 3063But let's come back to the point: the invocation of @command{autoheader}@dots{} 3064 3065If you give @command{autoheader} an argument, it uses that file instead 3066of @file{configure.ac} and writes the header file to the standard output 3067instead of to @file{config.h.in}. If you give @command{autoheader} an 3068argument of @option{-}, it reads the standard input instead of 3069@file{configure.ac} and writes the header file to the standard output. 3070 3071@command{autoheader} accepts the following options: 3072 3073@table @option 3074@item --help 3075@itemx -h 3076Print a summary of the command line options and exit. 3077 3078@item --version 3079@itemx -V 3080Print the version number of Autoconf and exit. 3081 3082@item --verbose 3083@itemx -v 3084Report processing steps. 3085 3086@item --debug 3087@itemx -d 3088Don't remove the temporary files. 3089 3090@item --force 3091@itemx -f 3092Remake the template file even if newer than its input files. 3093 3094@item --include=@var{dir} 3095@itemx -I @var{dir} 3096Append @var{dir} to the include path. Multiple invocations accumulate. 3097 3098@item --prepend-include=@var{dir} 3099@item -B @var{dir} 3100Prepend @var{dir} to the include path. Multiple invocations accumulate. 3101 3102@item --warnings=@var{category} 3103@itemx -W @var{category} 3104@evindex WARNINGS 3105Report the warnings related to @var{category} (which can actually be a 3106comma separated list). Current categories include: 3107 3108@table @samp 3109@item obsolete 3110report the uses of obsolete constructs 3111 3112@item all 3113report all the warnings 3114 3115@item none 3116report none 3117 3118@item error 3119treats warnings as errors 3120 3121@item no-@var{category} 3122disable warnings falling into @var{category} 3123@end table 3124 3125@end table 3126 3127 3128 3129@node Autoheader Macros 3130@subsection Autoheader Macros 3131@cindex Autoheader macros 3132 3133@command{autoheader} scans @file{configure.ac} and figures out which C 3134preprocessor symbols it might define. It knows how to generate 3135templates for symbols defined by @code{AC_CHECK_HEADERS}, 3136@code{AC_CHECK_FUNCS} etc., but if you @code{AC_DEFINE} any additional 3137symbol, you must define a template for it. If there are missing 3138templates, @command{autoheader} fails with an error message. 3139 3140The template for a @var{symbol} is created 3141by @command{autoheader} from 3142the @var{description} argument to an @code{AC_DEFINE}; 3143see @ref{Defining Symbols}. 3144 3145For special needs, you can use the following macros. 3146 3147 3148@defmac AH_TEMPLATE (@var{key}, @var{description}) 3149@ahindex{TEMPLATE} 3150Tell @command{autoheader} to generate a template for @var{key}. This macro 3151generates standard templates just like @code{AC_DEFINE} when a 3152@var{description} is given. 3153 3154For example: 3155 3156@example 3157AH_TEMPLATE([CRAY_STACKSEG_END], 3158 [Define to one of _getb67, GETB67, getb67 3159 for Cray-2 and Cray-YMP systems. This 3160 function is required for alloca.c support 3161 on those systems.]) 3162@end example 3163 3164@noindent 3165generates the following template, with the description properly 3166justified. 3167 3168@example 3169/* Define to one of _getb67, GETB67, getb67 for Cray-2 and 3170 Cray-YMP systems. This function is required for alloca.c 3171 support on those systems. */ 3172#undef CRAY_STACKSEG_END 3173@end example 3174@end defmac 3175 3176 3177@defmac AH_VERBATIM (@var{key}, @var{template}) 3178@ahindex{VERBATIM} 3179Tell @command{autoheader} to include the @var{template} as-is in the header 3180template file. This @var{template} is associated with the @var{key}, 3181which is used to sort all the different templates and guarantee their 3182uniqueness. It should be a symbol that can be defined via @code{AC_DEFINE}. 3183@end defmac 3184 3185 3186@defmac AH_TOP (@var{text}) 3187@ahindex{TOP} 3188Include @var{text} at the top of the header template file. 3189@end defmac 3190 3191 3192@defmac AH_BOTTOM (@var{text}) 3193@ahindex{BOTTOM} 3194Include @var{text} at the bottom of the header template file. 3195@end defmac 3196 3197 3198Please note that @var{text} gets included ``verbatim'' to the template file, 3199not to the resulting config header, so it can easily get mangled when the 3200template is processed. There is rarely a need for something other than 3201 3202@example 3203AH_BOTTOM([#include <custom.h>]) 3204@end example 3205 3206 3207 3208@node Configuration Commands 3209@section Running Arbitrary Configuration Commands 3210@cindex Configuration commands 3211@cindex Commands for configuration 3212 3213You can execute arbitrary commands before, during, and after 3214@file{config.status} is run. The three following macros accumulate the 3215commands to run when they are called multiple times. 3216@code{AC_CONFIG_COMMANDS} replaces the obsolete macro 3217@code{AC_OUTPUT_COMMANDS}; see @ref{Obsolete Macros}, for details. 3218 3219@defmac AC_CONFIG_COMMANDS (@var{tag}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 3220@acindex{CONFIG_COMMANDS} 3221Specify additional shell commands to run at the end of 3222@file{config.status}, and shell commands to initialize any variables 3223from @command{configure}. Associate the commands with @var{tag}. 3224Since typically the @var{cmds} create a file, @var{tag} should 3225naturally be the name of that file. If needed, the directory hosting 3226@var{tag} is created. This macro is one of the instantiating macros; 3227see @ref{Configuration Actions}. 3228 3229Here is an unrealistic example: 3230@example 3231fubar=42 3232AC_CONFIG_COMMANDS([fubar], 3233 [echo this is extra $fubar, and so on.], 3234 [fubar=$fubar]) 3235@end example 3236 3237Here is a better one: 3238@example 3239AC_CONFIG_COMMANDS([timestamp], [date >timestamp]) 3240@end example 3241@end defmac 3242 3243The following two macros look similar, but in fact they are not of the same 3244breed: they are executed directly by @file{configure}, so you cannot use 3245@file{config.status} to rerun them. 3246 3247@c Yet it is good to leave them here. The user sees them together and 3248@c decides which best fits their needs. 3249 3250@defmac AC_CONFIG_COMMANDS_PRE (@var{cmds}) 3251@acindex{CONFIG_COMMANDS_PRE} 3252Execute the @var{cmds} right before creating @file{config.status}. 3253 3254This macro presents the last opportunity to call @code{AC_SUBST}, 3255@code{AC_DEFINE}, or @code{AC_CONFIG_FOOS} macros. 3256@end defmac 3257 3258@defmac AC_CONFIG_COMMANDS_POST (@var{cmds}) 3259@acindex{CONFIG_COMMANDS_POST} 3260Execute the @var{cmds} right after creating @file{config.status}. 3261@end defmac 3262 3263 3264 3265 3266@node Configuration Links 3267@section Creating Configuration Links 3268@cindex Configuration links 3269@cindex Links for configuration 3270 3271You may find it convenient to create links whose destinations depend upon 3272results of tests. One can use @code{AC_CONFIG_COMMANDS} but the 3273creation of relative symbolic links can be delicate when the package is 3274built in a directory different from the source directory. 3275 3276@defmac AC_CONFIG_LINKS (@var{dest}:@var{source}@dots{}, @ovar{cmds}, @ovar{init-cmds}) 3277@acindex{CONFIG_LINKS} 3278@cindex Links 3279Make @code{AC_OUTPUT} link each of the existing files @var{source} to 3280the corresponding link name @var{dest}. Makes a symbolic link if 3281possible, otherwise a hard link if possible, otherwise a copy. The 3282@var{dest} and @var{source} names should be relative to the top level 3283source or build directory. This macro is one of the instantiating 3284macros; see @ref{Configuration Actions}. 3285 3286For example, this call: 3287 3288@example 3289AC_CONFIG_LINKS([host.h:config/$machine.h 3290 object.h:config/$obj_format.h]) 3291@end example 3292 3293@noindent 3294creates in the current directory @file{host.h} as a link to 3295@file{@var{srcdir}/config/$machine.h}, and @file{object.h} as a 3296link to @file{@var{srcdir}/config/$obj_format.h}. 3297 3298The tempting value @samp{.} for @var{dest} is invalid: it makes it 3299impossible for @samp{config.status} to guess the links to establish. 3300 3301One can then run: 3302@example 3303./config.status host.h object.h 3304@end example 3305@noindent 3306to create the links. 3307@end defmac 3308 3309 3310 3311@node Subdirectories 3312@section Configuring Other Packages in Subdirectories 3313@cindex Configure subdirectories 3314@cindex Subdirectory configure 3315 3316In most situations, calling @code{AC_OUTPUT} is sufficient to produce 3317makefiles in subdirectories. However, @command{configure} scripts 3318that control more than one independent package can use 3319@code{AC_CONFIG_SUBDIRS} to run @command{configure} scripts for other 3320packages in subdirectories. 3321 3322@defmac AC_CONFIG_SUBDIRS (@var{dir} @dots{}) 3323@acindex{CONFIG_SUBDIRS} 3324@ovindex subdirs 3325Make @code{AC_OUTPUT} run @command{configure} in each subdirectory 3326@var{dir} in the given blank-or-newline-separated list. Each @var{dir} should 3327be a literal, i.e., please do not use: 3328 3329@example 3330if test "$package_foo_enabled" = yes; then 3331 $my_subdirs="$my_subdirs foo" 3332fi 3333AC_CONFIG_SUBDIRS([$my_subdirs]) 3334@end example 3335 3336@noindent 3337because this prevents @samp{./configure --help=recursive} from 3338displaying the options of the package @code{foo}. Instead, you should 3339write: 3340 3341@example 3342if test "$package_foo_enabled" = yes; then 3343 AC_CONFIG_SUBDIRS([foo]) 3344fi 3345@end example 3346 3347If a given @var{dir} is not found, an error is reported: if the 3348subdirectory is optional, write: 3349 3350@example 3351if test -d "$srcdir/foo"; then 3352 AC_CONFIG_SUBDIRS([foo]) 3353fi 3354@end example 3355 3356@c NB: Yes, below we mean configure.in, not configure.ac. 3357If a given @var{dir} contains @command{configure.gnu}, it is run instead 3358of @command{configure}. This is for packages that might use a 3359non-Autoconf script @command{Configure}, which can't be called through a 3360wrapper @command{configure} since it would be the same file on 3361case-insensitive file systems. Likewise, if a @var{dir} contains 3362@file{configure.in} but no @command{configure}, the Cygnus 3363@command{configure} script found by @code{AC_CONFIG_AUX_DIR} is used. 3364 3365The subdirectory @command{configure} scripts are given the same command 3366line options that were given to this @command{configure} script, with minor 3367changes if needed, which include: 3368 3369@itemize @minus 3370@item 3371adjusting a relative name for the cache file; 3372 3373@item 3374adjusting a relative name for the source directory; 3375 3376@item 3377propagating the current value of @code{$prefix}, including if it was 3378defaulted, and if the default values of the top level and of the subdirectory 3379@file{configure} differ. 3380@end itemize 3381 3382This macro also sets the output variable @code{subdirs} to the list of 3383directories @samp{@var{dir} @dots{}}. Make rules can use 3384this variable to determine which subdirectories to recurse into. 3385 3386This macro may be called multiple times. 3387@end defmac 3388 3389@node Default Prefix 3390@section Default Prefix 3391@cindex Install prefix 3392@cindex Prefix for install 3393 3394By default, @command{configure} sets the prefix for files it installs to 3395@file{/usr/local}. The user of @command{configure} can select a different 3396prefix using the @option{--prefix} and @option{--exec-prefix} options. 3397There are two ways to change the default: when creating 3398@command{configure}, and when running it. 3399 3400Some software packages might want to install in a directory other than 3401@file{/usr/local} by default. To accomplish that, use the 3402@code{AC_PREFIX_DEFAULT} macro. 3403 3404@defmac AC_PREFIX_DEFAULT (@var{prefix}) 3405@acindex{PREFIX_DEFAULT} 3406Set the default installation prefix to @var{prefix} instead of 3407@file{/usr/local}. 3408@end defmac 3409 3410It may be convenient for users to have @command{configure} guess the 3411installation prefix from the location of a related program that they 3412have already installed. If you wish to do that, you can call 3413@code{AC_PREFIX_PROGRAM}. 3414 3415@defmac AC_PREFIX_PROGRAM (@var{program}) 3416@acindex{PREFIX_PROGRAM} 3417If the user did not specify an installation prefix (using the 3418@option{--prefix} option), guess a value for it by looking for 3419@var{program} in @env{PATH}, the way the shell does. If @var{program} 3420is found, set the prefix to the parent of the directory containing 3421@var{program}, else default the prefix as described above 3422(@file{/usr/local} or @code{AC_PREFIX_DEFAULT}). For example, if 3423@var{program} is @code{gcc} and the @env{PATH} contains 3424@file{/usr/local/gnu/bin/gcc}, set the prefix to @file{/usr/local/gnu}. 3425@end defmac 3426 3427 3428 3429@c ======================================================== Existing tests 3430 3431@node Existing Tests 3432@chapter Existing Tests 3433 3434These macros test for particular system features that packages might 3435need or want to use. If you need to test for a kind of feature that 3436none of these macros check for, you can probably do it by calling 3437primitive test macros with appropriate arguments (@pxref{Writing 3438Tests}). 3439 3440These tests print messages telling the user which feature they're 3441checking for, and what they find. They cache their results for future 3442@command{configure} runs (@pxref{Caching Results}). 3443 3444Some of these macros set output variables. @xref{Makefile 3445Substitutions}, for how to get their values. The phrase ``define 3446@var{name}'' is used below as a shorthand to mean ``define the C 3447preprocessor symbol @var{name} to the value 1''. @xref{Defining 3448Symbols}, for how to get those symbol definitions into your program. 3449 3450@menu 3451* Common Behavior:: Macros' standard schemes 3452* Alternative Programs:: Selecting between alternative programs 3453* Files:: Checking for the existence of files 3454* Libraries:: Library archives that might be missing 3455* Library Functions:: C library functions that might be missing 3456* Header Files:: Header files that might be missing 3457* Declarations:: Declarations that may be missing 3458* Structures:: Structures or members that might be missing 3459* Types:: Types that might be missing 3460* Compilers and Preprocessors:: Checking for compiling programs 3461* System Services:: Operating system services 3462* Posix Variants:: Special kludges for specific Posix variants 3463* Erlang Libraries:: Checking for the existence of Erlang libraries 3464@end menu 3465 3466@node Common Behavior 3467@section Common Behavior 3468@cindex Common autoconf behavior 3469 3470Much effort has been expended to make Autoconf easy to learn. The most 3471obvious way to reach this goal is simply to enforce standard interfaces 3472and behaviors, avoiding exceptions as much as possible. Because of 3473history and inertia, unfortunately, there are still too many exceptions 3474in Autoconf; nevertheless, this section describes some of the common 3475rules. 3476 3477@menu 3478* Standard Symbols:: Symbols defined by the macros 3479* Default Includes:: Includes used by the generic macros 3480@end menu 3481 3482@node Standard Symbols 3483@subsection Standard Symbols 3484@cindex Standard symbols 3485 3486All the generic macros that @code{AC_DEFINE} a symbol as a result of 3487their test transform their @var{argument} values to a standard alphabet. 3488First, @var{argument} is converted to upper case and any asterisks 3489(@samp{*}) are each converted to @samp{P}. Any remaining characters 3490that are not alphanumeric are converted to underscores. 3491 3492For instance, 3493 3494@example 3495AC_CHECK_TYPES([struct $Expensive*]) 3496@end example 3497 3498@noindent 3499defines the symbol @samp{HAVE_STRUCT__EXPENSIVEP} if the check 3500succeeds. 3501 3502 3503@node Default Includes 3504@subsection Default Includes 3505@cindex Default includes 3506@cindex Includes, default 3507 3508Several tests depend upon a set of header files. Since these headers 3509are not universally available, tests actually have to provide a set of 3510protected includes, such as: 3511 3512@example 3513@group 3514#ifdef TIME_WITH_SYS_TIME 3515# include <sys/time.h> 3516# include <time.h> 3517#else 3518# ifdef HAVE_SYS_TIME_H 3519# include <sys/time.h> 3520# else 3521# include <time.h> 3522# endif 3523#endif 3524@end group 3525@end example 3526 3527@noindent 3528Unless you know exactly what you are doing, you should avoid using 3529unconditional includes, and check the existence of the headers you 3530include beforehand (@pxref{Header Files}). 3531 3532Most generic macros use the following macro to provide the default set 3533of includes: 3534 3535@defmac AC_INCLUDES_DEFAULT (@ovar{include-directives}) 3536@acindex{INCLUDES_DEFAULT} 3537Expand to @var{include-directives} if defined, otherwise to: 3538 3539@example 3540@group 3541#include <stdio.h> 3542#ifdef HAVE_SYS_TYPES_H 3543# include <sys/types.h> 3544#endif 3545#ifdef HAVE_SYS_STAT_H 3546# include <sys/stat.h> 3547#endif 3548#ifdef STDC_HEADERS 3549# include <stdlib.h> 3550# include <stddef.h> 3551#else 3552# ifdef HAVE_STDLIB_H 3553# include <stdlib.h> 3554# endif 3555#endif 3556#ifdef HAVE_STRING_H 3557# if !defined STDC_HEADERS && defined HAVE_MEMORY_H 3558# include <memory.h> 3559# endif 3560# include <string.h> 3561#endif 3562#ifdef HAVE_STRINGS_H 3563# include <strings.h> 3564#endif 3565#ifdef HAVE_INTTYPES_H 3566# include <inttypes.h> 3567#endif 3568#ifdef HAVE_STDINT_H 3569# include <stdint.h> 3570#endif 3571#ifdef HAVE_UNISTD_H 3572# include <unistd.h> 3573#endif 3574@end group 3575@end example 3576 3577If the default includes are used, then check for the presence of these 3578headers and their compatibility, i.e., you don't need to run 3579@code{AC_HEADER_STDC}, nor check for @file{stdlib.h} etc. 3580 3581These headers are checked for in the same order as they are included. 3582For instance, on some systems @file{string.h} and @file{strings.h} both 3583exist, but conflict. Then @code{HAVE_STRING_H} is defined, not 3584@code{HAVE_STRINGS_H}. 3585@end defmac 3586 3587@node Alternative Programs 3588@section Alternative Programs 3589@cindex Programs, checking 3590 3591These macros check for the presence or behavior of particular programs. 3592They are used to choose between several alternative programs and to 3593decide what to do once one has been chosen. If there is no macro 3594specifically defined to check for a program you need, and you don't need 3595to check for any special properties of it, then you can use one of the 3596general program-check macros. 3597 3598@menu 3599* Particular Programs:: Special handling to find certain programs 3600* Generic Programs:: How to find other programs 3601@end menu 3602 3603@node Particular Programs 3604@subsection Particular Program Checks 3605 3606These macros check for particular programs---whether they exist, and 3607in some cases whether they support certain features. 3608 3609@defmac AC_PROG_AWK 3610@acindex{PROG_AWK} 3611@ovindex AWK 3612Check for @code{gawk}, @code{mawk}, @code{nawk}, and @code{awk}, in that 3613order, and set output variable @code{AWK} to the first one that is found. 3614It tries @code{gawk} first because that is reported to be the 3615best implementation. 3616@end defmac 3617 3618@defmac AC_PROG_GREP 3619@acindex{PROG_GREP} 3620@ovindex GREP 3621Look for the best available @code{grep} or @code{ggrep} that accepts the 3622longest input lines possible, and that supports multiple @option{-e} options. 3623Set the output variable @code{GREP} to whatever is chosen. 3624@xref{Limitations of Usual Tools}, for more information about 3625portability problems with the @command{grep} command family. 3626@end defmac 3627 3628@defmac AC_PROG_EGREP 3629@acindex{PROG_EGREP} 3630@ovindex EGREP 3631Check whether @code{$GREP -E} works, or else look for the best available 3632@code{egrep} or @code{gegrep} that accepts the longest input lines possible. 3633Set the output variable @code{EGREP} to whatever is chosen. 3634@end defmac 3635 3636@defmac AC_PROG_FGREP 3637@acindex{PROG_FGREP} 3638@ovindex FGREP 3639Check whether @code{$GREP -F} works, or else look for the best available 3640@code{fgrep} or @code{gfgrep} that accepts the longest input lines possible. 3641Set the output variable @code{FGREP} to whatever is chosen. 3642@end defmac 3643 3644@defmac AC_PROG_INSTALL 3645@acindex{PROG_INSTALL} 3646@ovindex INSTALL 3647@ovindex INSTALL_PROGRAM 3648@ovindex INSTALL_DATA 3649@ovindex INSTALL_SCRIPT 3650Set output variable @code{INSTALL} to the name of a @acronym{BSD}-compatible 3651@command{install} program, if one is found in the current @env{PATH}. 3652Otherwise, set @code{INSTALL} to @samp{@var{dir}/install-sh -c}, 3653checking the directories specified to @code{AC_CONFIG_AUX_DIR} (or its 3654default directories) to determine @var{dir} (@pxref{Output}). Also set 3655the variables @code{INSTALL_PROGRAM} and @code{INSTALL_SCRIPT} to 3656@samp{$@{INSTALL@}} and @code{INSTALL_DATA} to @samp{$@{INSTALL@} -m 644}. 3657 3658@samp{@@INSTALL@@} is special, as its value may vary for different 3659configuration files. 3660 3661This macro screens out various instances of @command{install} known not to 3662work. It prefers to find a C program rather than a shell script, for 3663speed. Instead of @file{install-sh}, it can also use @file{install.sh}, 3664but that name is obsolete because some @command{make} programs have a rule 3665that creates @file{install} from it if there is no makefile. 3666 3667Autoconf comes with a copy of @file{install-sh} that you can use. If 3668you use @code{AC_PROG_INSTALL}, you must include either 3669@file{install-sh} or @file{install.sh} in your distribution; otherwise 3670@command{configure} produces an error message saying it can't find 3671them---even if the system you're on has a good @command{install} program. 3672This check is a safety measure to prevent you from accidentally leaving 3673that file out, which would prevent your package from installing on 3674systems that don't have a @acronym{BSD}-compatible @command{install} program. 3675 3676If you need to use your own installation program because it has features 3677not found in standard @command{install} programs, there is no reason to use 3678@code{AC_PROG_INSTALL}; just put the file name of your program into your 3679@file{Makefile.in} files. 3680@end defmac 3681 3682@defmac AC_PROG_MKDIR_P 3683@acindex{AC_PROG_MKDIR_P} 3684@ovindex MKDIR_P 3685Set output variable @code{MKDIR_P} to a program that ensures that for 3686each argument, a directory named by this argument exists, creating it 3687and its parent directories if needed, and without race conditions when 3688two instances of the program attempt to make the same directory at 3689nearly the same time. 3690 3691This macro uses the @samp{mkdir -p} command if possible. Otherwise, it 3692falls back on invoking @command{install-sh} with the @option{-d} option, 3693so your package should 3694contain @file{install-sh} as described under @code{AC_PROG_INSTALL}. 3695An @file{install-sh} file that predates Autoconf 2.60 or Automake 1.10 3696is vulnerable to race conditions, so if you want to support parallel 3697installs from 3698different packages into the same directory you need to make sure you 3699have an up-to-date @file{install-sh}. In particular, be careful about 3700using @samp{autoreconf -if} if your Automake predates Automake 1.10. 3701 3702This macro is related to the @code{AS_MKDIR_P} macro (@pxref{Programming 3703in M4sh}), but it sets an output variable intended for use in other 3704files, whereas @code{AS_MKDIR_P} is intended for use in scripts like 3705@command{configure}. Also, @code{AS_MKDIR_P} does not accept options, 3706but @code{MKDIR_P} supports the @option{-m} option, e.g., a makefile 3707might invoke @code{$(MKDIR_P) -m 0 dir} to create an inaccessible 3708directory, and conversely a makefile should use @code{$(MKDIR_P) -- 3709$(FOO)} if @var{FOO} might yield a value that begins with @samp{-}. 3710Finally, @code{AS_MKDIR_P} does not check for race condition 3711vulnerability, whereas @code{AC_PROG_MKDIR_P} does. 3712 3713@samp{@@MKDIR_P@@} is special, as its value may vary for different 3714configuration files. 3715@end defmac 3716 3717@defmac AC_PROG_LEX 3718@acindex{PROG_LEX} 3719@ovindex LEX 3720@ovindex LEXLIB 3721@cvindex YYTEXT_POINTER 3722@ovindex LEX_OUTPUT_ROOT 3723If @code{flex} is found, set output variable @code{LEX} to @samp{flex} 3724and @code{LEXLIB} to @option{-lfl}, if that library is in a standard 3725place. Otherwise set @code{LEX} to @samp{lex} and @code{LEXLIB} to 3726@option{-ll}. 3727 3728Define @code{YYTEXT_POINTER} if @code{yytext} defaults to @samp{char *} instead 3729of to @samp{char []}. Also set output variable @code{LEX_OUTPUT_ROOT} to 3730the base of the file name that the lexer generates; usually 3731@file{lex.yy}, but sometimes something else. These results vary 3732according to whether @code{lex} or @code{flex} is being used. 3733 3734You are encouraged to use Flex in your sources, since it is both more 3735pleasant to use than plain Lex and the C source it produces is portable. 3736In order to ensure portability, however, you must either provide a 3737function @code{yywrap} or, if you don't use it (e.g., your scanner has 3738no @samp{#include}-like feature), simply include a @samp{%noyywrap} 3739statement in the scanner's source. Once this done, the scanner is 3740portable (unless @emph{you} felt free to use nonportable constructs) and 3741does not depend on any library. In this case, and in this case only, it 3742is suggested that you use this Autoconf snippet: 3743 3744@example 3745AC_PROG_LEX 3746if test "$LEX" != flex; then 3747 LEX="$SHELL $missing_dir/missing flex" 3748 AC_SUBST([LEX_OUTPUT_ROOT], [lex.yy]) 3749 AC_SUBST([LEXLIB], ['']) 3750fi 3751@end example 3752 3753The shell script @command{missing} can be found in the Automake 3754distribution. 3755 3756To ensure backward compatibility, Automake's @code{AM_PROG_LEX} invokes 3757(indirectly) this macro twice, which causes an annoying but benign 3758``@code{AC_PROG_LEX} invoked multiple times'' warning. Future versions 3759of Automake will fix this issue; meanwhile, just ignore this message. 3760 3761As part of running the test, this macro may delete any file in the 3762configuration directory named @file{lex.yy.c} or @file{lexyy.c}. 3763@end defmac 3764 3765@defmac AC_PROG_LN_S 3766@acindex{PROG_LN_S} 3767@ovindex LN_S 3768If @samp{ln -s} works on the current file system (the operating system 3769and file system support symbolic links), set the output variable 3770@code{LN_S} to @samp{ln -s}; otherwise, if @samp{ln} works, set 3771@code{LN_S} to @samp{ln}, and otherwise set it to @samp{cp -p}. 3772 3773If you make a link in a directory other than the current directory, its 3774meaning depends on whether @samp{ln} or @samp{ln -s} is used. To safely 3775create links using @samp{$(LN_S)}, either find out which form is used 3776and adjust the arguments, or always invoke @code{ln} in the directory 3777where the link is to be created. 3778 3779In other words, it does not work to do: 3780@example 3781$(LN_S) foo /x/bar 3782@end example 3783 3784Instead, do: 3785 3786@example 3787(cd /x && $(LN_S) foo bar) 3788@end example 3789@end defmac 3790 3791@defmac AC_PROG_RANLIB 3792@acindex{PROG_RANLIB} 3793@ovindex RANLIB 3794Set output variable @code{RANLIB} to @samp{ranlib} if @code{ranlib} 3795is found, and otherwise to @samp{:} (do nothing). 3796@end defmac 3797 3798@defmac AC_PROG_SED 3799@acindex{PROG_SED} 3800@ovindex SED 3801Set output variable @code{SED} to a Sed implementation that conforms to 3802Posix and does not have arbitrary length limits. Report an error if no 3803acceptable Sed is found. @xref{Limitations of Usual Tools}, for more 3804information about portability problems with Sed. 3805@end defmac 3806 3807@defmac AC_PROG_YACC 3808@acindex{PROG_YACC} 3809@ovindex YACC 3810If @code{bison} is found, set output variable @code{YACC} to @samp{bison 3811-y}. Otherwise, if @code{byacc} is found, set @code{YACC} to 3812@samp{byacc}. Otherwise set @code{YACC} to @samp{yacc}. 3813@end defmac 3814 3815@node Generic Programs 3816@subsection Generic Program and File Checks 3817 3818These macros are used to find programs not covered by the ``particular'' 3819test macros. If you need to check the behavior of a program as well as 3820find out whether it is present, you have to write your own test for it 3821(@pxref{Writing Tests}). By default, these macros use the environment 3822variable @env{PATH}. If you need to check for a program that might not 3823be in the user's @env{PATH}, you can pass a modified path to use 3824instead, like this: 3825 3826@example 3827AC_PATH_PROG([INETD], [inetd], [/usr/libexec/inetd], 3828 [$PATH:/usr/libexec:/usr/sbin:/usr/etc:/etc]) 3829@end example 3830 3831You are strongly encouraged to declare the @var{variable} passed to 3832@code{AC_CHECK_PROG} etc.@: as precious, @xref{Setting Output Variables}, 3833@code{AC_ARG_VAR}, for more details. 3834 3835@defmac AC_CHECK_PROG (@var{variable}, @var{prog-to-check-for}, @var{value-if-found}, @ovar{value-if-not-found}, @ovar{path}, @ovar{reject}) 3836@acindex{CHECK_PROG} 3837Check whether program @var{prog-to-check-for} exists in @env{PATH}. If 3838it is found, set @var{variable} to @var{value-if-found}, otherwise to 3839@var{value-if-not-found}, if given. Always pass over @var{reject} (an 3840absolute file name) even if it is the first found in the search path; in 3841that case, set @var{variable} using the absolute file name of the 3842@var{prog-to-check-for} found that is not @var{reject}. If 3843@var{variable} was already set, do nothing. Calls @code{AC_SUBST} for 3844@var{variable}. 3845@end defmac 3846 3847@defmac AC_CHECK_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3848@acindex{CHECK_PROGS} 3849Check for each program in the blank-separated list 3850@var{progs-to-check-for} existing in the @env{PATH}. If one is found, set 3851@var{variable} to the name of that program. Otherwise, continue 3852checking the next program in the list. If none of the programs in the 3853list are found, set @var{variable} to @var{value-if-not-found}; if 3854@var{value-if-not-found} is not specified, the value of @var{variable} 3855is not changed. Calls @code{AC_SUBST} for @var{variable}. 3856@end defmac 3857 3858@defmac AC_CHECK_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3859@acindex{CHECK_TARGET_TOOL} 3860Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 3861with a prefix of the target type as determined by 3862@code{AC_CANONICAL_TARGET}, followed by a dash (@pxref{Canonicalizing}). 3863If the tool cannot be found with a prefix, and if the build and target 3864types are equal, then it is also searched for without a prefix. 3865 3866As noted in @ref{Specifying Names, , Specifying the system type}, the 3867target is rarely specified, because most of the time it is the same 3868as the host: it is the type of system for which any compiler tool in 3869the package produces code. What this macro looks for is, 3870for example, @emph{a tool @r{(assembler, linker, etc.)}@: that the 3871compiler driver @r{(@command{gcc} for the @acronym{GNU} C Compiler)} 3872uses to produce objects, archives or executables}. 3873@end defmac 3874 3875@defmac AC_CHECK_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3876@acindex{CHECK_TOOL} 3877Like @code{AC_CHECK_PROG}, but first looks for @var{prog-to-check-for} 3878with a prefix of the host type as determined by 3879@code{AC_CANONICAL_HOST}, followed by a dash (@pxref{Canonicalizing}). 3880For example, if the user runs @samp{configure --host=i386-gnu}, then 3881this call: 3882@example 3883AC_CHECK_TOOL([RANLIB], [ranlib], [:]) 3884@end example 3885@noindent 3886sets @code{RANLIB} to @file{i386-gnu-ranlib} if that program exists in 3887@env{PATH}, or otherwise to @samp{ranlib} if that program exists in 3888@env{PATH}, or to @samp{:} if neither program exists. 3889 3890In the future, when cross-compiling this macro will @emph{only} 3891accept program names that are prefixed with the host type. 3892For more information, see @ref{Specifying Names, , Specifying the 3893system type}. 3894@end defmac 3895 3896@defmac AC_CHECK_TARGET_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3897@acindex{CHECK_TARGET_TOOLS} 3898Like @code{AC_CHECK_TARGET_TOOL}, each of the tools in the list 3899@var{progs-to-check-for} are checked with a prefix of the target type as 3900determined by @code{AC_CANONICAL_TARGET}, followed by a dash 3901(@pxref{Canonicalizing}). If none of the tools can be found with a 3902prefix, and if the build and target types are equal, then the first one 3903without a prefix is used. If a tool is found, set @var{variable} to 3904the name of that program. If none of the tools in the list are found, 3905set @var{variable} to @var{value-if-not-found}; if @var{value-if-not-found} 3906is not specified, the value of @var{variable} is not changed. Calls 3907@code{AC_SUBST} for @var{variable}. 3908@end defmac 3909 3910@defmac AC_CHECK_TOOLS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3911@acindex{CHECK_TOOLS} 3912Like @code{AC_CHECK_TOOL}, each of the tools in the list 3913@var{progs-to-check-for} are checked with a prefix of the host type as 3914determined by @code{AC_CANONICAL_HOST}, followed by a dash 3915(@pxref{Canonicalizing}). If none of the tools can be found with a 3916prefix, then the first one without a prefix is used. If a tool is found, 3917set @var{variable} to the name of that program. If none of the tools in 3918the list are found, set @var{variable} to @var{value-if-not-found}; if 3919@var{value-if-not-found} is not specified, the value of @var{variable} 3920is not changed. Calls @code{AC_SUBST} for @var{variable}. 3921 3922In the future, when cross-compiling this macro will @emph{not} 3923accept program names that are not prefixed with the host type. 3924@end defmac 3925 3926@defmac AC_PATH_PROG (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3927@acindex{PATH_PROG} 3928Like @code{AC_CHECK_PROG}, but set @var{variable} to the absolute 3929name of @var{prog-to-check-for} if found. 3930@end defmac 3931 3932@defmac AC_PATH_PROGS (@var{variable}, @var{progs-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3933@acindex{PATH_PROGS} 3934Like @code{AC_CHECK_PROGS}, but if any of @var{progs-to-check-for} 3935are found, set @var{variable} to the absolute name of the program 3936found. 3937@end defmac 3938 3939@defmac AC_PATH_TARGET_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3940@acindex{PATH_TARGET_TOOL} 3941Like @code{AC_CHECK_TARGET_TOOL}, but set @var{variable} to the absolute 3942name of the program if it is found. 3943@end defmac 3944 3945@defmac AC_PATH_TOOL (@var{variable}, @var{prog-to-check-for}, @ovar{value-if-not-found}, @ovar{path}) 3946@acindex{PATH_TOOL} 3947Like @code{AC_CHECK_TOOL}, but set @var{variable} to the absolute 3948name of the program if it is found. 3949 3950In the future, when cross-compiling this macro will @emph{not} 3951accept program names that are not prefixed with the host type. 3952@end defmac 3953 3954 3955@node Files 3956@section Files 3957@cindex File, checking 3958 3959You might also need to check for the existence of files. Before using 3960these macros, ask yourself whether a runtime test might not be a better 3961solution. Be aware that, like most Autoconf macros, they test a feature 3962of the host machine, and therefore, they die when cross-compiling. 3963 3964@defmac AC_CHECK_FILE (@var{file}, @ovar{action-if-found}, @ovar{action-if-not-found}) 3965@acindex{CHECK_FILE} 3966Check whether file @var{file} exists on the native system. If it is 3967found, execute @var{action-if-found}, otherwise do 3968@var{action-if-not-found}, if given. 3969@end defmac 3970 3971@defmac AC_CHECK_FILES (@var{files}, @ovar{action-if-found}, @ovar{action-if-not-found}) 3972@acindex{CHECK_FILES} 3973Executes @code{AC_CHECK_FILE} once for each file listed in @var{files}. 3974Additionally, defines @samp{HAVE_@var{file}} (@pxref{Standard Symbols}) 3975for each file found. 3976@end defmac 3977 3978 3979@node Libraries 3980@section Library Files 3981@cindex Library, checking 3982 3983The following macros check for the presence of certain C, C++, or Fortran 3984library archive files. 3985 3986@defmac AC_CHECK_LIB (@var{library}, @var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 3987@acindex{CHECK_LIB} 3988Test whether the library @var{library} is available by trying to link 3989a test program that calls function @var{function} with the library. 3990@var{function} should be a function provided by the library. 3991Use the base 3992name of the library; e.g., to check for @option{-lmp}, use @samp{mp} as 3993the @var{library} argument. 3994 3995@var{action-if-found} is a list of shell commands to run if the link 3996with the library succeeds; @var{action-if-not-found} is a list of shell 3997commands to run if the link fails. If @var{action-if-found} is not 3998specified, the default action prepends @option{-l@var{library}} to 3999@code{LIBS} and defines @samp{HAVE_LIB@var{library}} (in all 4000capitals). This macro is intended to support building @code{LIBS} in 4001a right-to-left (least-dependent to most-dependent) fashion such that 4002library dependencies are satisfied as a natural side effect of 4003consecutive tests. Linkers are sensitive to library ordering 4004so the order in which @code{LIBS} is generated is important to reliable 4005detection of libraries. 4006 4007If linking with @var{library} results in unresolved symbols that would 4008be resolved by linking with additional libraries, give those libraries 4009as the @var{other-libraries} argument, separated by spaces: 4010e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect 4011that @var{library} is present, because linking the test program 4012always fails with unresolved symbols. The @var{other-libraries} argument 4013should be limited to cases where it is desirable to test for one library 4014in the presence of another that is not already in @code{LIBS}. 4015 4016@code{AC_CHECK_LIB} requires some care in usage, and should be avoided 4017in some common cases. Many standard functions like @code{gethostbyname} 4018appear the standard C library on some hosts, and in special libraries 4019like @code{nsl} on other hosts. On some hosts the special libraries 4020contain variant implementations that you may not want to use. These 4021days it is normally better to use @code{AC_SEARCH_LIBS([gethostbyname], 4022[nsl])} instead of @code{AC_CHECK_LIB([nsl], [gethostbyname])}. 4023@end defmac 4024 4025 4026@defmac AC_SEARCH_LIBS (@var{function}, @var{search-libs}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 4027@acindex{SEARCH_LIBS} 4028Search for a library defining @var{function} if it's not already 4029available. This equates to calling 4030@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])])} first with 4031no libraries, then for each library listed in @var{search-libs}. 4032 4033Add @option{-l@var{library}} to @code{LIBS} for the first library found 4034to contain @var{function}, and run @var{action-if-found}. If the 4035function is not found, run @var{action-if-not-found}. 4036 4037If linking with @var{library} results in unresolved symbols that would 4038be resolved by linking with additional libraries, give those libraries 4039as the @var{other-libraries} argument, separated by spaces: 4040e.g., @option{-lXt -lX11}. Otherwise, this macro fails to detect 4041that @var{function} is present, because linking the test program 4042always fails with unresolved symbols. 4043@end defmac 4044 4045 4046 4047@node Library Functions 4048@section Library Functions 4049 4050The following macros check for particular C library functions. 4051If there is no macro specifically defined to check for a function you need, 4052and you don't need to check for any special properties of 4053it, then you can use one of the general function-check macros. 4054 4055@menu 4056* Function Portability:: Pitfalls with usual functions 4057* Particular Functions:: Special handling to find certain functions 4058* Generic Functions:: How to find other functions 4059@end menu 4060 4061@node Function Portability 4062@subsection Portability of C Functions 4063@cindex Portability of C functions 4064@cindex C function portability 4065 4066Most usual functions can either be missing, or be buggy, or be limited 4067on some architectures. This section tries to make an inventory of these 4068portability issues. By definition, this list always requires 4069additions. Please help us keeping it as complete as possible. 4070 4071@table @asis 4072@item @code{exit} 4073@c @fuindex exit 4074@prindex @code{exit} 4075On ancient hosts, @code{exit} returned @code{int}. 4076This is because @code{exit} predates @code{void}, and there was a long 4077tradition of it returning @code{int}. 4078 4079On current hosts, the problem more likely is that @code{exit} is not 4080declared, due to C++ problems of some sort or another. For this reason 4081we suggest that test programs not invoke @code{exit}, but return from 4082@code{main} instead. 4083 4084@item @code{free} 4085@c @fuindex free 4086@prindex @code{free} 4087The C standard says a call @code{free (NULL)} does nothing, but 4088some old systems don't support this (e.g., NextStep). 4089 4090@item @code{isinf} 4091@itemx @code{isnan} 4092@c @fuindex isinf 4093@c @fuindex isnan 4094@prindex @code{isinf} 4095@prindex @code{isnan} 4096The C99 standard says that @code{isinf} and @code{isnan} are 4097macros. On some systems just macros are available 4098(e.g., @acronym{HP-UX} and Solaris 10), on 4099some systems both macros and functions (e.g., glibc 2.3.2), and on some 4100systems only functions (e.g., IRIX 6 and Solaris 9). In some cases 4101these functions are declared in nonstandard headers like 4102@code{<sunmath.h>} and defined in non-default libraries like 4103@option{-lm} or @option{-lsunmath}. 4104 4105The C99 @code{isinf} and @code{isnan} macros work correctly with 4106@code{long double} arguments, but pre-C99 systems that use functions 4107typically assume @code{double} arguments. On such a system, 4108@code{isinf} incorrectly returns true for a finite @code{long double} 4109argument that is outside the range of @code{double}. 4110 4111To work around this porting mess, you can use code like the following. 4112 4113@smallexample 4114#include <math.h> 4115 4116#ifndef isnan 4117# define isnan(x) \ 4118 (sizeof (x) == sizeof (long double) ? isnan_ld (x) \ 4119 : sizeof (x) == sizeof (double) ? isnan_d (x) \ 4120 : isnan_f (x)) 4121static inline int isnan_f (float x) @{ return x != x; @} 4122static inline int isnan_d (double x) @{ return x != x; @} 4123static inline int isnan_ld (long double x) @{ return x != x; @} 4124#endif 4125 4126#ifndef isinf 4127# define isinf(x) \ 4128 (sizeof (x) == sizeof (long double) ? isinf_ld (x) \ 4129 : sizeof (x) == sizeof (double) ? isinf_d (x) \ 4130 : isinf_f (x)) 4131static inline int isinf_f (float x) @{ return isnan (x - x); @} 4132static inline int isinf_d (double x) @{ return isnan (x - x); @} 4133static inline int isinf_ld (long double x) @{ return isnan (x - x); @} 4134#endif 4135@end smallexample 4136 4137Use @code{AC_C_INLINE} (@pxref{C Compiler}) so that this code works on 4138compilers that lack the @code{inline} keyword. Some optimizing 4139compilers mishandle these definitions, but systems with that bug 4140typically have missing or broken @code{isnan} functions anyway, so it's 4141probably not worth worrying about. 4142 4143@item @code{malloc} 4144@c @fuindex malloc 4145@prindex @code{malloc} 4146The C standard says a call @code{malloc (0)} is implementation 4147dependent. It can return either @code{NULL} or a new non-null pointer. 4148The latter is more common (e.g., the @acronym{GNU} C Library) but is by 4149no means universal. @code{AC_FUNC_MALLOC} 4150can be used to insist on non-@code{NULL} (@pxref{Particular Functions}). 4151 4152@item @code{putenv} 4153@c @fuindex putenv 4154@prindex @code{putenv} 4155Posix prefers @code{setenv} to @code{putenv}; among other things, 4156@code{putenv} is not required of all Posix implementations, but 4157@code{setenv} is. 4158 4159Posix specifies that @code{putenv} puts the given string directly in 4160@code{environ}, but some systems make a copy of it instead (e.g., 4161glibc 2.0, or @acronym{BSD}). And when a copy is made, @code{unsetenv} might 4162not free it, causing a memory leak (e.g., Free@acronym{BSD} 4). 4163 4164On some systems @code{putenv ("FOO")} removes @samp{FOO} from the 4165environment, but this is not standard usage and it dumps core 4166on some systems (e.g., AIX). 4167 4168On MinGW, a call @code{putenv ("FOO=")} removes @samp{FOO} from the 4169environment, rather than inserting it with an empty value. 4170 4171@item @code{realloc} 4172@c @fuindex realloc 4173@prindex @code{realloc} 4174The C standard says a call @code{realloc (NULL, size)} is equivalent 4175to @code{malloc (size)}, but some old systems don't support this (e.g., 4176NextStep). 4177 4178@item @code{signal} handler 4179@c @fuindex signal 4180@prindex @code{signal} 4181Normally @code{signal} takes a handler function with a return type of 4182@code{void}, but some old systems required @code{int} instead. Any 4183actual @code{int} value returned is not used; this is only a 4184difference in the function prototype demanded. 4185 4186All systems we know of in current use return @code{void}. The 4187@code{int} was to support K&R C, where of course @code{void} is not 4188available. @code{AC_TYPE_SIGNAL} (@pxref{Particular Types}) can be 4189used to establish the correct type in all cases. 4190 4191@item @code{snprintf} 4192@c @fuindex snprintf 4193@prindex @code{snprintf} 4194@c @fuindex vsnprintf 4195@prindex @code{vsnprintf} 4196The C99 standard says that if the output array isn't big enough 4197and if no other errors occur, @code{snprintf} and @code{vsnprintf} 4198truncate the output and return the number of bytes that ought to have 4199been produced. Some older systems return the truncated length (e.g., 4200@acronym{GNU} C Library 2.0.x or @sc{irix} 6.5), some a negative value 4201(e.g., earlier @acronym{GNU} C Library versions), and some the buffer 4202length without truncation (e.g., 32-bit Solaris 7). Also, some buggy 4203older systems ignore the length and overrun the buffer (e.g., 64-bit 4204Solaris 7). 4205 4206@item @code{sprintf} 4207@c @fuindex sprintf 4208@prindex @code{sprintf} 4209@c @fuindex vsprintf 4210@prindex @code{vsprintf} 4211The C standard says @code{sprintf} and @code{vsprintf} return the 4212number of bytes written. On some ancient systems (SunOS 4 for 4213instance) they return the buffer pointer instead, but these no 4214longer need to be worried about. 4215 4216@item @code{sscanf} 4217@c @fuindex sscanf 4218@prindex @code{sscanf} 4219On various old systems, e.g., @acronym{HP-UX} 9, @code{sscanf} requires that its 4220input string be writable (though it doesn't actually change it). This 4221can be a problem when using @command{gcc} since it normally puts 4222constant strings in read-only memory (@pxref{Incompatibilities, 4223Incompatibilities of @acronym{GCC}, , gcc, Using and 4224Porting the @acronym{GNU} Compiler Collection}). Apparently in some cases even 4225having format strings read-only can be a problem. 4226 4227@item @code{strerror_r} 4228@c @fuindex strerror_r 4229@prindex @code{strerror_r} 4230Posix specifies that @code{strerror_r} returns an @code{int}, but many 4231systems (e.g., @acronym{GNU} C Library version 2.2.4) provide a 4232different version returning a @code{char *}. @code{AC_FUNC_STRERROR_R} 4233can detect which is in use (@pxref{Particular Functions}). 4234 4235@item @code{strnlen} 4236@c @fuindex strnlen 4237@prindex @code{strnlen} 4238@acronym{AIX} 4.3 provides a broken version which produces the 4239following results: 4240 4241@example 4242strnlen ("foobar", 0) = 0 4243strnlen ("foobar", 1) = 3 4244strnlen ("foobar", 2) = 2 4245strnlen ("foobar", 3) = 1 4246strnlen ("foobar", 4) = 0 4247strnlen ("foobar", 5) = 6 4248strnlen ("foobar", 6) = 6 4249strnlen ("foobar", 7) = 6 4250strnlen ("foobar", 8) = 6 4251strnlen ("foobar", 9) = 6 4252@end example 4253 4254@item @code{sysconf} 4255@c @fuindex sysconf 4256@prindex @code{sysconf} 4257@code{_SC_PAGESIZE} is standard, but some older systems (e.g., @acronym{HP-UX} 42589) have @code{_SC_PAGE_SIZE} instead. This can be tested with 4259@code{#ifdef}. 4260 4261@item @code{unlink} 4262@c @fuindex unlink 4263@prindex @code{unlink} 4264The Posix spec says that @code{unlink} causes the given file to be 4265removed only after there are no more open file handles for it. Some 4266non-Posix hosts have trouble with this requirement, though, 4267and some @acronym{DOS} variants even corrupt the file system. 4268 4269@item @code{unsetenv} 4270@c @fuindex unsetenv 4271@prindex @code{unsetenv} 4272On MinGW, @code{unsetenv} is not available, but a variable @samp{FOO} 4273can be removed with a call @code{putenv ("FOO=")}, as described under 4274@code{putenv} above. 4275 4276@item @code{va_copy} 4277@c @fuindex va_copy 4278@prindex @code{va_copy} 4279The C99 standard provides @code{va_copy} for copying 4280@code{va_list} variables. It may be available in older environments 4281too, though possibly as @code{__va_copy} (e.g., @command{gcc} in strict 4282pre-C99 mode). These can be tested with @code{#ifdef}. A fallback to 4283@code{memcpy (&dst, &src, sizeof (va_list))} gives maximum 4284portability. 4285 4286@item @code{va_list} 4287@c @fuindex va_list 4288@prindex @code{va_list} 4289@code{va_list} is not necessarily just a pointer. It can be a 4290@code{struct} (e.g., @command{gcc} on Alpha), which means @code{NULL} is 4291not portable. Or it can be an array (e.g., @command{gcc} in some 4292PowerPC configurations), which means as a function parameter it can be 4293effectively call-by-reference and library routines might modify the 4294value back in the caller (e.g., @code{vsnprintf} in the @acronym{GNU} C Library 42952.1). 4296 4297@item Signed @code{>>} 4298Normally the C @code{>>} right shift of a signed type replicates the 4299high bit, giving a so-called ``arithmetic'' shift. But care should be 4300taken since Standard C doesn't require that behavior. On those 4301few processors without a native arithmetic shift (for instance Cray 4302vector systems) zero bits may be shifted in, the same as a shift of an 4303unsigned type. 4304 4305@item Integer @code{/} 4306C divides signed integers by truncating their quotient toward zero, 4307yielding the same result as Fortran. However, before C99 the standard 4308allowed C implementations to take the floor or ceiling of the quotient 4309in some cases. Hardly any implementations took advantage of this 4310freedom, though, and it's probably not worth worrying about this issue 4311nowadays. 4312@end table 4313 4314 4315@node Particular Functions 4316@subsection Particular Function Checks 4317@cindex Function, checking 4318 4319These macros check for particular C functions---whether they exist, and 4320in some cases how they respond when given certain arguments. 4321 4322@defmac AC_FUNC_ALLOCA 4323@acindex{FUNC_ALLOCA} 4324@cvindex C_ALLOCA 4325@cvindex HAVE_ALLOCA_H 4326@ovindex ALLOCA 4327@c @fuindex alloca 4328@prindex @code{alloca} 4329@hdrindex{alloca.h} 4330Check how to get @code{alloca}. Tries to get a builtin version by 4331checking for @file{alloca.h} or the predefined C preprocessor macros 4332@code{__GNUC__} and @code{_AIX}. If this macro finds @file{alloca.h}, 4333it defines @code{HAVE_ALLOCA_H}. 4334 4335If those attempts fail, it looks for the function in the standard C 4336library. If any of those methods succeed, it defines 4337@code{HAVE_ALLOCA}. Otherwise, it sets the output variable 4338@code{ALLOCA} to @samp{$@{LIBOBJDIR@}alloca.o} and defines 4339@code{C_ALLOCA} (so programs can periodically call @samp{alloca (0)} to 4340garbage collect). This variable is separate from @code{LIBOBJS} so 4341multiple programs can share the value of @code{ALLOCA} without needing 4342to create an actual library, in case only some of them use the code in 4343@code{LIBOBJS}. The @samp{$@{LIBOBJDIR@}} prefix serves the same 4344purpose as in @code{LIBOBJS} (@pxref{AC_LIBOBJ vs LIBOBJS}). 4345 4346This macro does not try to get @code{alloca} from the System V R3 4347@file{libPW} or the System V R4 @file{libucb} because those libraries 4348contain some incompatible functions that cause trouble. Some versions 4349do not even contain @code{alloca} or contain a buggy version. If you 4350still want to use their @code{alloca}, use @code{ar} to extract 4351@file{alloca.o} from them instead of compiling @file{alloca.c}. 4352 4353Source files that use @code{alloca} should start with a piece of code 4354like the following, to declare it properly. 4355 4356@example 4357@group 4358#ifdef HAVE_ALLOCA_H 4359# include <alloca.h> 4360#elif defined __GNUC__ 4361# define alloca __builtin_alloca 4362#elif defined _AIX 4363# define alloca __alloca 4364#elif defined _MSC_VER 4365# include <malloc.h> 4366# define alloca _alloca 4367#else 4368# include <stddef.h> 4369# ifdef __cplusplus 4370extern "C" 4371# endif 4372void *alloca (size_t); 4373#endif 4374@end group 4375@end example 4376@end defmac 4377 4378@defmac AC_FUNC_CHOWN 4379@acindex{FUNC_CHOWN} 4380@c @fuindex chown 4381@prindex @code{chown} 4382If the @code{chown} function is available and works (in particular, it 4383should accept @option{-1} for @code{uid} and @code{gid}), define 4384@code{HAVE_CHOWN}. 4385@end defmac 4386 4387 4388@defmac AC_FUNC_CLOSEDIR_VOID 4389@acindex{FUNC_CLOSEDIR_VOID} 4390@cvindex CLOSEDIR_VOID 4391@c @fuindex closedir 4392@prindex @code{closedir} 4393If the @code{closedir} function does not return a meaningful value, 4394define @code{CLOSEDIR_VOID}. Otherwise, callers ought to check its 4395return value for an error indicator. 4396 4397Currently this test is implemented by running a test program. When 4398cross compiling the pessimistic assumption that @code{closedir} does not 4399return a meaningful value is made. 4400 4401This macro is obsolescent, as @code{closedir} returns a meaningful value 4402on current systems. New programs need not use this macro. 4403@end defmac 4404 4405@defmac AC_FUNC_ERROR_AT_LINE 4406@acindex{FUNC_ERROR_AT_LINE} 4407@c @fuindex error_at_line 4408@prindex @code{error_at_line} 4409If the @code{error_at_line} function is not found, require an 4410@code{AC_LIBOBJ} replacement of @samp{error}. 4411@end defmac 4412 4413@defmac AC_FUNC_FNMATCH 4414@acindex{FUNC_FNMATCH} 4415@c @fuindex fnmatch 4416@prindex @code{fnmatch} 4417If the @code{fnmatch} function conforms to Posix, define 4418@code{HAVE_FNMATCH}. Detect common implementation bugs, for example, 4419the bugs in Solaris 2.4. 4420 4421Unlike the other specific 4422@code{AC_FUNC} macros, @code{AC_FUNC_FNMATCH} does not replace a 4423broken/missing @code{fnmatch}. This is for historical reasons. 4424See @code{AC_REPLACE_FNMATCH} below. 4425 4426This macro is obsolescent. New programs should use Gnulib's 4427@code{fnmatch-posix} module. @xref{Gnulib}. 4428@end defmac 4429 4430@defmac AC_FUNC_FNMATCH_GNU 4431@acindex{FUNC_FNMATCH_GNU} 4432@c @fuindex fnmatch 4433@prindex @code{fnmatch} 4434Behave like @code{AC_REPLACE_FNMATCH} (@emph{replace}) but also test 4435whether @code{fnmatch} supports @acronym{GNU} extensions. Detect common 4436implementation bugs, for example, the bugs in the @acronym{GNU} C 4437Library 2.1. 4438 4439This macro is obsolescent. New programs should use Gnulib's 4440@code{fnmatch-gnu} module. @xref{Gnulib}. 4441@end defmac 4442 4443@defmac AC_FUNC_FORK 4444@acindex{FUNC_FORK} 4445@cvindex HAVE_VFORK_H 4446@cvindex HAVE_WORKING_FORK 4447@cvindex HAVE_WORKING_VFORK 4448@cvindex vfork 4449@c @fuindex fork 4450@prindex @code{fork} 4451@c @fuindex vfork 4452@prindex @code{vfork} 4453@hdrindex{vfork.h} 4454This macro checks for the @code{fork} and @code{vfork} functions. If a 4455working @code{fork} is found, define @code{HAVE_WORKING_FORK}. This macro 4456checks whether @code{fork} is just a stub by trying to run it. 4457 4458If @file{vfork.h} is found, define @code{HAVE_VFORK_H}. If a working 4459@code{vfork} is found, define @code{HAVE_WORKING_VFORK}. Otherwise, 4460define @code{vfork} to be @code{fork} for backward compatibility with 4461previous versions of @command{autoconf}. This macro checks for several known 4462errors in implementations of @code{vfork} and considers the system to not 4463have a working @code{vfork} if it detects any of them. It is not considered 4464to be an implementation error if a child's invocation of @code{signal} 4465modifies the parent's signal handler, since child processes rarely change 4466their signal handlers. 4467 4468Since this macro defines @code{vfork} only for backward compatibility with 4469previous versions of @command{autoconf} you're encouraged to define it 4470yourself in new code: 4471@example 4472@group 4473#ifndef HAVE_WORKING_VFORK 4474# define vfork fork 4475#endif 4476@end group 4477@end example 4478@end defmac 4479 4480@defmac AC_FUNC_FSEEKO 4481@acindex{FUNC_FSEEKO} 4482@cvindex _LARGEFILE_SOURCE 4483@c @fuindex fseeko 4484@prindex @code{fseeko} 4485If the @code{fseeko} function is available, define @code{HAVE_FSEEKO}. 4486Define @code{_LARGEFILE_SOURCE} if necessary to make the prototype 4487visible on some systems (e.g., glibc 2.2). Otherwise linkage problems 4488may occur when compiling with @code{AC_SYS_LARGEFILE} on 4489largefile-sensitive systems where @code{off_t} does not default to a 449064bit entity. 4491@end defmac 4492 4493@defmac AC_FUNC_GETGROUPS 4494@acindex{FUNC_GETGROUPS} 4495@ovindex GETGROUPS_LIBS 4496@c @fuindex getgroups 4497@prindex @code{getgroups} 4498If the @code{getgroups} function is available and works (unlike on 4499Ultrix 4.3, where @samp{getgroups (0, 0)} always fails), define 4500@code{HAVE_GETGROUPS}. Set @code{GETGROUPS_LIBS} to any libraries 4501needed to get that function. This macro runs @code{AC_TYPE_GETGROUPS}. 4502@end defmac 4503 4504@defmac AC_FUNC_GETLOADAVG 4505@acindex{FUNC_GETLOADAVG} 4506@cvindex SVR4 4507@cvindex DGUX 4508@cvindex UMAX 4509@cvindex UMAX4_3 4510@cvindex HAVE_NLIST_H 4511@cvindex NLIST_NAME_UNION 4512@cvindex GETLODAVG_PRIVILEGED 4513@cvindex NEED_SETGID 4514@cvindex C_GETLOADAVG 4515@ovindex LIBOBJS 4516@ovindex NEED_SETGID 4517@ovindex KMEM_GROUP 4518@ovindex GETLOADAVG_LIBS 4519@c @fuindex getloadavg 4520@prindex @code{getloadavg} 4521Check how to get the system load averages. To perform its tests 4522properly, this macro needs the file @file{getloadavg.c}; therefore, be 4523sure to set the @code{AC_LIBOBJ} replacement directory properly (see 4524@ref{Generic Functions}, @code{AC_CONFIG_LIBOBJ_DIR}). 4525 4526If the system has the @code{getloadavg} function, define 4527@code{HAVE_GETLOADAVG}, and set @code{GETLOADAVG_LIBS} to any libraries 4528necessary to get that function. Also add @code{GETLOADAVG_LIBS} to 4529@code{LIBS}. Otherwise, require an @code{AC_LIBOBJ} replacement for 4530@samp{getloadavg} with source code in @file{@var{dir}/getloadavg.c}, and 4531possibly define several other C preprocessor macros and output 4532variables: 4533 4534@enumerate 4535@item 4536Define @code{C_GETLOADAVG}. 4537 4538@item 4539Define @code{SVR4}, @code{DGUX}, @code{UMAX}, or @code{UMAX4_3} if on 4540those systems. 4541 4542@item 4543@hdrindex{nlist.h} 4544If @file{nlist.h} is found, define @code{HAVE_NLIST_H}. 4545 4546@item 4547If @samp{struct nlist} has an @samp{n_un.n_name} member, define 4548@code{HAVE_STRUCT_NLIST_N_UN_N_NAME}. The obsolete symbol 4549@code{NLIST_NAME_UNION} is still defined, but do not depend upon it. 4550 4551@item 4552Programs may need to be installed set-group-ID (or set-user-ID) for 4553@code{getloadavg} to work. In this case, define 4554@code{GETLOADAVG_PRIVILEGED}, set the output variable @code{NEED_SETGID} 4555to @samp{true} (and otherwise to @samp{false}), and set 4556@code{KMEM_GROUP} to the name of the group that should own the installed 4557program. 4558@end enumerate 4559 4560The @code{AC_FUNC_GETLOADVG} macro is obsolescent. New programs should 4561use Gnulib's @code{getloadavg} module. @xref{Gnulib}. 4562@end defmac 4563 4564@defmac AC_FUNC_GETMNTENT 4565@acindex{FUNC_GETMNTENT} 4566@cvindex HAVE_GETMNTENT 4567@c @fuindex getmntent 4568@prindex @code{getmntent} 4569Check for @code{getmntent} in the standard C library, and then in the 4570@file{sun}, @file{seq}, and @file{gen} libraries, for @sc{unicos}, 4571@sc{irix} 4, @sc{ptx}, and UnixWare, respectively. Then, if 4572@code{getmntent} is available, define @code{HAVE_GETMNTENT}. 4573@end defmac 4574 4575@defmac AC_FUNC_GETPGRP 4576@acindex{FUNC_GETPGRP} 4577@cvindex GETPGRP_VOID 4578@c @fuindex getpgid 4579@c @fuindex getpgrp 4580@prindex @code{getpgid} 4581@prindex @code{getpgrp} 4582Define @code{GETPGRP_VOID} if it is an error to pass 0 to 4583@code{getpgrp}; this is the Posix behavior. On older @acronym{BSD} 4584systems, you must pass 0 to @code{getpgrp}, as it takes an argument and 4585behaves like Posix's @code{getpgid}. 4586 4587@example 4588#ifdef GETPGRP_VOID 4589 pid = getpgrp (); 4590#else 4591 pid = getpgrp (0); 4592#endif 4593@end example 4594 4595This macro does not check whether 4596@code{getpgrp} exists at all; if you need to work in that situation, 4597first call @code{AC_CHECK_FUNC} for @code{getpgrp}. 4598 4599This macro is obsolescent, as current systems have a @code{getpgrp} 4600whose signature conforms to Posix. New programs need not use this macro. 4601@end defmac 4602 4603@defmac AC_FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK 4604@acindex{FUNC_LSTAT_FOLLOWS_SLASHED_SYMLINK} 4605@cvindex LSTAT_FOLLOWS_SLASHED_SYMLINK 4606@c @fuindex lstat 4607@prindex @code{lstat} 4608If @file{link} is a symbolic link, then @code{lstat} should treat 4609@file{link/} the same as @file{link/.}. However, many older 4610@code{lstat} implementations incorrectly ignore trailing slashes. 4611 4612It is safe to assume that if @code{lstat} incorrectly ignores 4613trailing slashes, then other symbolic-link-aware functions like 4614@code{unlink} also incorrectly ignore trailing slashes. 4615 4616If @code{lstat} behaves properly, define 4617@code{LSTAT_FOLLOWS_SLASHED_SYMLINK}, otherwise require an 4618@code{AC_LIBOBJ} replacement of @code{lstat}. 4619@end defmac 4620 4621@defmac AC_FUNC_MALLOC 4622@acindex{FUNC_MALLOC} 4623@cvindex HAVE_MALLOC 4624@cvindex malloc 4625@c @fuindex malloc 4626@prindex @code{malloc} 4627If the @code{malloc} function is compatible with the @acronym{GNU} C 4628library @code{malloc} (i.e., @samp{malloc (0)} returns a valid 4629pointer), define @code{HAVE_MALLOC} to 1. Otherwise define 4630@code{HAVE_MALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 4631@samp{malloc}, and define @code{malloc} to @code{rpl_malloc} so that the 4632native @code{malloc} is not used in the main project. 4633 4634Typically, the replacement file @file{malloc.c} should look like (note 4635the @samp{#undef malloc}): 4636 4637@verbatim 4638#ifdef HAVE_CONFIG_H 4639# include <config.h> 4640#endif 4641#undef malloc 4642 4643#include <sys/types.h> 4644 4645void *malloc (); 4646 4647/* Allocate an N-byte block of memory from the heap. 4648 If N is zero, allocate a 1-byte block. */ 4649 4650void * 4651rpl_malloc (size_t n) 4652{ 4653 if (n == 0) 4654 n = 1; 4655 return malloc (n); 4656} 4657@end verbatim 4658@end defmac 4659 4660@defmac AC_FUNC_MEMCMP 4661@acindex{FUNC_MEMCMP} 4662@ovindex LIBOBJS 4663@c @fuindex memcmp 4664@prindex @code{memcmp} 4665If the @code{memcmp} function is not available, or does not work on 46668-bit data (like the one on SunOS 4.1.3), or fails when comparing 16 4667bytes or more and with at least one buffer not starting on a 4-byte 4668boundary (such as the one on NeXT x86 OpenStep), require an 4669@code{AC_LIBOBJ} replacement for @samp{memcmp}. 4670 4671This macro is obsolescent, as current systems have a working 4672@code{memcmp}. New programs need not use this macro. 4673@end defmac 4674 4675@defmac AC_FUNC_MBRTOWC 4676@acindex{FUNC_MBRTOWC} 4677@cvindex HAVE_MBRTOWC 4678@c @fuindex mbrtowc 4679@prindex @code{mbrtowc} 4680Define @code{HAVE_MBRTOWC} to 1 if the function @code{mbrtowc} and the 4681type @code{mbstate_t} are properly declared. 4682@end defmac 4683 4684@defmac AC_FUNC_MKTIME 4685@acindex{FUNC_MKTIME} 4686@ovindex LIBOBJS 4687@c @fuindex mktime 4688@prindex @code{mktime} 4689If the @code{mktime} function is not available, or does not work 4690correctly, require an @code{AC_LIBOBJ} replacement for @samp{mktime}. 4691For the purposes of this test, @code{mktime} should conform to the 4692Posix standard and should be the inverse of 4693@code{localtime}. 4694@end defmac 4695 4696@defmac AC_FUNC_MMAP 4697@acindex{FUNC_MMAP} 4698@cvindex HAVE_MMAP 4699@c @fuindex mmap 4700@prindex @code{mmap} 4701If the @code{mmap} function exists and works correctly, define 4702@code{HAVE_MMAP}. This checks only private fixed mapping of already-mapped 4703memory. 4704@end defmac 4705 4706@defmac AC_FUNC_OBSTACK 4707@acindex{FUNC_OBSTACK} 4708@cvindex HAVE_OBSTACK 4709@cindex obstack 4710If the obstacks are found, define @code{HAVE_OBSTACK}, else require an 4711@code{AC_LIBOBJ} replacement for @samp{obstack}. 4712@end defmac 4713 4714@defmac AC_FUNC_REALLOC 4715@acindex{FUNC_REALLOC} 4716@cvindex HAVE_REALLOC 4717@cvindex realloc 4718@c @fuindex realloc 4719@prindex @code{realloc} 4720If the @code{realloc} function is compatible with the @acronym{GNU} C 4721library @code{realloc} (i.e., @samp{realloc (NULL, 0)} returns a 4722valid pointer), define @code{HAVE_REALLOC} to 1. Otherwise define 4723@code{HAVE_REALLOC} to 0, ask for an @code{AC_LIBOBJ} replacement for 4724@samp{realloc}, and define @code{realloc} to @code{rpl_realloc} so that 4725the native @code{realloc} is not used in the main project. See 4726@code{AC_FUNC_MALLOC} for details. 4727@end defmac 4728 4729@defmac AC_FUNC_SELECT_ARGTYPES 4730@acindex{FUNC_SELECT_ARGTYPES} 4731@cvindex SELECT_TYPE_ARG1 4732@cvindex SELECT_TYPE_ARG234 4733@cvindex SELECT_TYPE_ARG5 4734@c @fuindex select 4735@prindex @code{select} 4736Determines the correct type to be passed for each of the 4737@code{select} function's arguments, and defines those types 4738in @code{SELECT_TYPE_ARG1}, @code{SELECT_TYPE_ARG234}, and 4739@code{SELECT_TYPE_ARG5} respectively. @code{SELECT_TYPE_ARG1} defaults 4740to @samp{int}, @code{SELECT_TYPE_ARG234} defaults to @samp{int *}, 4741and @code{SELECT_TYPE_ARG5} defaults to @samp{struct timeval *}. 4742 4743This macro is obsolescent, as current systems have a @code{select} whose 4744signature conforms to Posix. New programs need not use this macro. 4745@end defmac 4746 4747@defmac AC_FUNC_SETPGRP 4748@acindex{FUNC_SETPGRP} 4749@cvindex SETPGRP_VOID 4750@c @fuindex setpgrp 4751@prindex @code{setpgrp} 4752If @code{setpgrp} takes no argument (the Posix version), define 4753@code{SETPGRP_VOID}. Otherwise, it is the @acronym{BSD} version, which takes 4754two process IDs as arguments. This macro does not check whether 4755@code{setpgrp} exists at all; if you need to work in that situation, 4756first call @code{AC_CHECK_FUNC} for @code{setpgrp}. 4757 4758This macro is obsolescent, as current systems have a @code{setpgrp} 4759whose signature conforms to Posix. New programs need not use this macro. 4760@end defmac 4761 4762@defmac AC_FUNC_STAT 4763@defmacx AC_FUNC_LSTAT 4764@acindex{FUNC_STAT} 4765@acindex{FUNC_LSTAT} 4766@cvindex HAVE_STAT_EMPTY_STRING_BUG 4767@cvindex HAVE_LSTAT_EMPTY_STRING_BUG 4768@c @fuindex stat 4769@prindex @code{stat} 4770@c @fuindex lstat 4771@prindex @code{lstat} 4772Determine whether @code{stat} or @code{lstat} have the bug that it 4773succeeds when given the zero-length file name as argument. The @code{stat} 4774and @code{lstat} from SunOS 4.1.4 and the Hurd (as of 1998-11-01) do 4775this. 4776 4777If it does, then define @code{HAVE_STAT_EMPTY_STRING_BUG} (or 4778@code{HAVE_LSTAT_EMPTY_STRING_BUG}) and ask for an @code{AC_LIBOBJ} 4779replacement of it. 4780 4781These macros are obsolescent, as no current systems have the bug. 4782New programs need not use these macros. 4783@end defmac 4784 4785@defmac AC_FUNC_SETVBUF_REVERSED 4786@acindex{FUNC_SETVBUF_REVERSED} 4787@cvindex SETVBUF_REVERSED 4788@c @fuindex setvbuf 4789@prindex @code{setvbuf} 4790If @code{setvbuf} takes the buffering type as its second argument and 4791the buffer pointer as the third, instead of the other way around, define 4792@code{SETVBUF_REVERSED}. 4793 4794This macro is obsolescent, as no current systems have the bug. 4795New programs need not use this macro. 4796@end defmac 4797 4798@defmac AC_FUNC_STRCOLL 4799@acindex{FUNC_STRCOLL} 4800@cvindex HAVE_STRCOLL 4801@c @fuindex strcoll 4802@prindex @code{strcoll} 4803If the @code{strcoll} function exists and works correctly, define 4804@code{HAVE_STRCOLL}. This does a bit more than 4805@samp{AC_CHECK_FUNCS(strcoll)}, because some systems have incorrect 4806definitions of @code{strcoll} that should not be used. 4807@end defmac 4808 4809@defmac AC_FUNC_STRERROR_R 4810@acindex{FUNC_STRERROR_R} 4811@cvindex HAVE_STRERROR_R 4812@cvindex HAVE_DECL_STRERROR_R 4813@cvindex STRERROR_R_CHAR_P 4814@c @fuindex strerror_r 4815@prindex @code{strerror_r} 4816If @code{strerror_r} is available, define @code{HAVE_STRERROR_R}, and if 4817it is declared, define @code{HAVE_DECL_STRERROR_R}. If it returns a 4818@code{char *} message, define @code{STRERROR_R_CHAR_P}; otherwise it 4819returns an @code{int} error number. The Thread-Safe Functions option of 4820Posix requires @code{strerror_r} to return @code{int}, but 4821many systems (including, for example, version 2.2.4 of the @acronym{GNU} C 4822Library) return a @code{char *} value that is not necessarily equal to 4823the buffer argument. 4824@end defmac 4825 4826@defmac AC_FUNC_STRFTIME 4827@acindex{FUNC_STRFTIME} 4828@cvindex HAVE_STRFTIME 4829@c @fuindex strftime 4830@prindex @code{strftime} 4831Check for @code{strftime} in the @file{intl} library, for SCO Unix. 4832Then, if @code{strftime} is available, define @code{HAVE_STRFTIME}. 4833 4834This macro is obsolescent, as no current systems require the @file{intl} 4835library for @code{strftime}. New programs need not use this macro. 4836@end defmac 4837 4838@defmac AC_FUNC_STRTOD 4839@acindex{FUNC_STRTOD} 4840@ovindex POW_LIB 4841@c @fuindex strtod 4842@prindex @code{strtod} 4843If the @code{strtod} function does not exist or doesn't work correctly, 4844ask for an @code{AC_LIBOBJ} replacement of @samp{strtod}. In this case, 4845because @file{strtod.c} is likely to need @samp{pow}, set the output 4846variable @code{POW_LIB} to the extra library needed. 4847@end defmac 4848 4849@defmac AC_FUNC_STRTOLD 4850@acindex{FUNC_STRTOLD} 4851@prindex @code{strtold} 4852If the @code{strtold} function exists and conforms to C99, define 4853@code{HAVE_STRTOLD}. 4854@end defmac 4855 4856@defmac AC_FUNC_STRNLEN 4857@acindex{FUNC_STRNLEN} 4858@cvindex HAVE_STRNLEN 4859@c @fuindex strnlen 4860@prindex @code{strnlen} 4861If the @code{strnlen} function is not available, or is buggy (like the one 4862from @acronym{AIX} 4.3), require an @code{AC_LIBOBJ} replacement for it. 4863@end defmac 4864 4865@defmac AC_FUNC_UTIME_NULL 4866@acindex{FUNC_UTIME_NULL} 4867@cvindex HAVE_UTIME_NULL 4868@c @fuindex utime 4869@prindex @code{utime} 4870If @samp{utime (@var{file}, NULL)} sets @var{file}'s timestamp to 4871the present, define @code{HAVE_UTIME_NULL}. 4872 4873This macro is obsolescent, as all current systems have a @code{utime} 4874that behaves this way. New programs need not use this macro. 4875@end defmac 4876 4877@defmac AC_FUNC_VPRINTF 4878@acindex{FUNC_VPRINTF} 4879@cvindex HAVE_VPRINTF 4880@cvindex HAVE_DOPRNT 4881@c @fuindex vprintf 4882@prindex @code{vprintf} 4883If @code{vprintf} is found, define @code{HAVE_VPRINTF}. Otherwise, if 4884@code{_doprnt} is found, define @code{HAVE_DOPRNT}. (If @code{vprintf} 4885is available, you may assume that @code{vfprintf} and @code{vsprintf} 4886are also available.) 4887 4888This macro is obsolescent, as all current systems have @code{vprintf}. 4889New programs need not use this macro. 4890@end defmac 4891 4892@defmac AC_REPLACE_FNMATCH 4893@acindex{REPLACE_FNMATCH} 4894@c @fuindex fnmatch 4895@prindex @code{fnmatch} 4896@hdrindex{fnmatch.h} 4897If the @code{fnmatch} function does not conform to Posix (see 4898@code{AC_FUNC_FNMATCH}), ask for its @code{AC_LIBOBJ} replacement. 4899 4900The files @file{fnmatch.c}, @file{fnmatch_loop.c}, and @file{fnmatch_.h} 4901in the @code{AC_LIBOBJ} replacement directory are assumed to contain a 4902copy of the source code of @acronym{GNU} @code{fnmatch}. If necessary, 4903this source code is compiled as an @code{AC_LIBOBJ} replacement, and the 4904@file{fnmatch_.h} file is linked to @file{fnmatch.h} so that it can be 4905included in place of the system @code{<fnmatch.h>}. 4906 4907This macro is obsolescent, as it assumes the use of particular source 4908files. New programs should use Gnulib's @code{fnmatch-posix} module, 4909which provides this macro along with the source files. @xref{Gnulib}. 4910@end defmac 4911 4912 4913 4914@node Generic Functions 4915@subsection Generic Function Checks 4916 4917These macros are used to find functions not covered by the ``particular'' 4918test macros. If the functions might be in libraries other than the 4919default C library, first call @code{AC_CHECK_LIB} for those libraries. 4920If you need to check the behavior of a function as well as find out 4921whether it is present, you have to write your own test for 4922it (@pxref{Writing Tests}). 4923 4924@defmac AC_CHECK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}) 4925@acindex{CHECK_FUNC} 4926If C function @var{function} is available, run shell commands 4927@var{action-if-found}, otherwise @var{action-if-not-found}. If you just 4928want to define a symbol if the function is available, consider using 4929@code{AC_CHECK_FUNCS} instead. This macro checks for functions with C 4930linkage even when @code{AC_LANG(C++)} has been called, since C is more 4931standardized than C++. (@pxref{Language Choice}, for more information 4932about selecting the language for checks.) 4933@end defmac 4934 4935@defmac AC_CHECK_FUNCS (@var{function}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}) 4936@acindex{CHECK_FUNCS} 4937@cvindex HAVE_@var{function} 4938For each @var{function} enumerated in the blank-or-newline-separated argument 4939list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 4940If @var{action-if-found} is given, it is additional shell code to 4941execute when one of the functions is found. You can give it a value of 4942@samp{break} to break out of the loop on the first match. If 4943@var{action-if-not-found} is given, it is executed when one of the 4944functions is not found. 4945@end defmac 4946 4947@defmac AC_CHECK_FUNCS_ONCE (@var{function}@dots{}) 4948@acindex{CHECK_FUNCS_ONCE} 4949@cvindex HAVE_@var{function} 4950For each @var{function} enumerated in the blank-or-newline-separated argument 4951list, define @code{HAVE_@var{function}} (in all capitals) if it is available. 4952This is a once-only variant of @code{AC_CHECK_FUNCS}. It generates the 4953checking code at most once, so that @command{configure} is smaller and 4954faster; but the checks cannot be conditionalized and are always done once, 4955early during the @command{configure} run. 4956@end defmac 4957 4958@sp 1 4959 4960Autoconf follows a philosophy that was formed over the years by those 4961who have struggled for portability: isolate the portability issues in 4962specific files, and then program as if you were in a Posix 4963environment. Some functions may be missing or unfixable, and your 4964package must be ready to replace them. 4965 4966Suitable replacements for many such problem functions are available from 4967Gnulib (@pxref{Gnulib}). 4968 4969@defmac AC_LIBOBJ (@var{function}) 4970@acindex{LIBOBJ} 4971@ovindex LIBOBJS 4972Specify that @samp{@var{function}.c} must be included in the executables 4973to replace a missing or broken implementation of @var{function}. 4974 4975Technically, it adds @samp{@var{function}.$ac_objext} to the output 4976variable @code{LIBOBJS} if it is not already in, and calls 4977@code{AC_LIBSOURCE} for @samp{@var{function}.c}. You should not 4978directly change @code{LIBOBJS}, since this is not traceable. 4979@end defmac 4980 4981@defmac AC_LIBSOURCE (@var{file}) 4982@acindex{LIBSOURCE} 4983Specify that @var{file} might be needed to compile the project. If you 4984need to know what files might be needed by a @file{configure.ac}, you 4985should trace @code{AC_LIBSOURCE}. @var{file} must be a literal. 4986 4987This macro is called automatically from @code{AC_LIBOBJ}, but you must 4988call it explicitly if you pass a shell variable to @code{AC_LIBOBJ}. In 4989that case, since shell variables cannot be traced statically, you must 4990pass to @code{AC_LIBSOURCE} any possible files that the shell variable 4991might cause @code{AC_LIBOBJ} to need. For example, if you want to pass 4992a variable @code{$foo_or_bar} to @code{AC_LIBOBJ} that holds either 4993@code{"foo"} or @code{"bar"}, you should do: 4994 4995@example 4996AC_LIBSOURCE([foo.c]) 4997AC_LIBSOURCE([bar.c]) 4998AC_LIBOBJ([$foo_or_bar]) 4999@end example 5000 5001@noindent 5002There is usually a way to avoid this, however, and you are encouraged to 5003simply call @code{AC_LIBOBJ} with literal arguments. 5004 5005Note that this macro replaces the obsolete @code{AC_LIBOBJ_DECL}, with 5006slightly different semantics: the old macro took the function name, 5007e.g., @code{foo}, as its argument rather than the file name. 5008@end defmac 5009 5010@defmac AC_LIBSOURCES (@var{files}) 5011@acindex{LIBSOURCES} 5012Like @code{AC_LIBSOURCE}, but accepts one or more @var{files} in a 5013comma-separated M4 list. Thus, the above example might be rewritten: 5014 5015@example 5016AC_LIBSOURCES([foo.c, bar.c]) 5017AC_LIBOBJ([$foo_or_bar]) 5018@end example 5019@end defmac 5020 5021@defmac AC_CONFIG_LIBOBJ_DIR (@var{directory}) 5022@acindex{CONFIG_LIBOBJ_DIR} 5023Specify that @code{AC_LIBOBJ} replacement files are to be found in 5024@var{directory}, a name relative to the top level of the 5025source tree. The replacement directory defaults to @file{.}, the top 5026level directory, and the most typical value is @file{lib}, corresponding 5027to @samp{AC_CONFIG_LIBOBJ_DIR([lib])}. 5028 5029@command{configure} might need to know the replacement directory for the 5030following reasons: (i) some checks use the replacement files, (ii) some 5031macros bypass broken system headers by installing links to the 5032replacement headers (iii) when used in conjunction with Automake, 5033within each makefile, @var{directory} is used as a relative path 5034from @code{$(top_srcdir)} to each object named in @code{LIBOBJS} and 5035@code{LTLIBOBJS}, etc. 5036@end defmac 5037 5038@sp 1 5039 5040It is common to merely check for the existence of a function, and ask 5041for its @code{AC_LIBOBJ} replacement if missing. The following macro is 5042a convenient shorthand. 5043 5044@defmac AC_REPLACE_FUNCS (@var{function}@dots{}) 5045@acindex{REPLACE_FUNCS} 5046@ovindex LIBOBJS 5047Like @code{AC_CHECK_FUNCS}, but uses @samp{AC_LIBOBJ(@var{function})} as 5048@var{action-if-not-found}. You can declare your replacement function by 5049enclosing the prototype in @samp{#ifndef HAVE_@var{function}}. If the 5050system has the function, it probably declares it in a header file you 5051should be including, so you shouldn't redeclare it lest your declaration 5052conflict. 5053@end defmac 5054 5055@node Header Files 5056@section Header Files 5057@cindex Header, checking 5058 5059The following macros check for the presence of certain C header files. 5060If there is no macro specifically defined to check for a header file you need, 5061and you don't need to check for any special properties of 5062it, then you can use one of the general header-file check macros. 5063 5064@menu 5065* Header Portability:: Collected knowledge on common headers 5066* Particular Headers:: Special handling to find certain headers 5067* Generic Headers:: How to find other headers 5068@end menu 5069 5070@node Header Portability 5071@subsection Portability of Headers 5072@cindex Portability of headers 5073@cindex Header portability 5074 5075This section tries to collect knowledge about common headers, and the 5076problems they cause. By definition, this list always requires 5077additions. Please help us keeping it as complete as possible. 5078 5079@table @asis 5080 5081@item @file{limits.h} 5082C99 says that @file{limits.h} defines @code{LLONG_MIN}, 5083@code{LLONG_MAX}, and @code{ULLONG_MAX}, but many almost-C99 5084environments (e.g., default @acronym{GCC} 4.0.2 + glibc 2.4) do not 5085define them. 5086 5087@item @file{inttypes.h} vs.@: @file{stdint.h} 5088@hdrindex{inttypes.h} 5089@hdrindex{stdint.h} 5090The C99 standard says that @file{inttypes.h} includes 5091@file{stdint.h}, so there's no need to include @file{stdint.h} 5092separately in a standard environment. Some implementations have 5093@file{inttypes.h} but not @file{stdint.h} (e.g., Solaris 7), but we don't 5094know of any implementation that has @file{stdint.h} but not 5095@file{inttypes.h}. 5096 5097@item @file{linux/irda.h} 5098@hdrindex{linux/irda.h} 5099It requires @file{linux/types.h} and @file{sys/socket.h}. 5100 5101@item @file{linux/random.h} 5102@hdrindex{linux/random.h} 5103It requires @file{linux/types.h}. 5104 5105@item @file{net/if.h} 5106@hdrindex{net/if.h} 5107On Darwin, this file requires that @file{sys/socket.h} be included 5108beforehand. One should run: 5109 5110@example 5111AC_CHECK_HEADERS([sys/socket.h]) 5112AC_CHECK_HEADERS([net/if.h], [], [], 5113[#include <stdio.h> 5114#ifdef STDC_HEADERS 5115# include <stdlib.h> 5116# include <stddef.h> 5117#else 5118# ifdef HAVE_STDLIB_H 5119# include <stdlib.h> 5120# endif 5121#endif 5122#ifdef HAVE_SYS_SOCKET_H 5123# include <sys/socket.h> 5124#endif 5125]) 5126@end example 5127 5128@item @file{netinet/if_ether.h} 5129@hdrindex{netinet/if_ether.h} 5130On Darwin, this file requires that @file{stdio.h} and 5131@file{sys/socket.h} be included beforehand. One should run: 5132 5133@example 5134AC_CHECK_HEADERS([sys/socket.h]) 5135AC_CHECK_HEADERS([netinet/if_ether.h], [], [], 5136[#include <stdio.h> 5137#ifdef STDC_HEADERS 5138# include <stdlib.h> 5139# include <stddef.h> 5140#else 5141# ifdef HAVE_STDLIB_H 5142# include <stdlib.h> 5143# endif 5144#endif 5145#ifdef HAVE_SYS_SOCKET_H 5146# include <sys/socket.h> 5147#endif 5148]) 5149@end example 5150 5151@item @file{stdint.h} 5152See above, item @file{inttypes.h} vs.@: @file{stdint.h}. 5153 5154@item @file{stdlib.h} 5155@hdrindex{stdlib.h} 5156On many systems (e.g., Darwin), @file{stdio.h} is a prerequisite. 5157 5158@item @file{sys/mount.h} 5159@hdrindex{sys/mount.h} 5160On Free@acronym{BSD} 4.8 on ia32 and using gcc version 2.95.4, 5161@file{sys/params.h} is a prerequisite. 5162 5163@item @file{sys/ptem.h} 5164@hdrindex{sys/ptem.h} 5165On Solaris 8, @file{sys/stream.h} is a prerequisite. 5166 5167@item @file{sys/socket.h} 5168@hdrindex{sys/socket.h} 5169On Darwin, @file{stdlib.h} is a prerequisite. 5170 5171@item @file{sys/ucred.h} 5172@hdrindex{sys/ucred.h} 5173On Tru64 5.1, @file{sys/types.h} is a prerequisite. 5174 5175@item @file{X11/extensions/scrnsaver.h} 5176@hdrindex{X11/extensions/scrnsaver.h} 5177Using XFree86, this header requires @file{X11/Xlib.h}, which is probably 5178so required that you might not even consider looking for it. 5179 5180@example 5181AC_CHECK_HEADERS([X11/extensions/scrnsaver.h], [], [], 5182[[#include <X11/Xlib.h> 5183]]) 5184@end example 5185@end table 5186 5187 5188@node Particular Headers 5189@subsection Particular Header Checks 5190 5191These macros check for particular system header files---whether they 5192exist, and in some cases whether they declare certain symbols. 5193 5194@defmac AC_HEADER_ASSERT 5195@acindex{HEADER_ASSERT} 5196@cvindex NDEBUG 5197@hdrindex{assert.h} 5198Check whether to enable assertions in the style of @file{assert.h}. 5199Assertions are enabled by default, but the user can override this by 5200invoking @command{configure} with the @option{--disable-assert} option. 5201@end defmac 5202 5203@defmac AC_HEADER_DIRENT 5204@acindex{HEADER_DIRENT} 5205@cvindex HAVE_DIRENT_H 5206@cvindex HAVE_NDIR_H 5207@cvindex HAVE_SYS_DIR_H 5208@cvindex HAVE_SYS_NDIR_H 5209@hdrindex{dirent.h} 5210@hdrindex{sys/ndir.h} 5211@hdrindex{sys/dir.h} 5212@hdrindex{ndir.h} 5213Check for the following header files. For the first one that is 5214found and defines @samp{DIR}, define the listed C preprocessor macro: 5215 5216@multitable {@file{sys/ndir.h}} {@code{HAVE_SYS_NDIR_H}} 5217@item @file{dirent.h} @tab @code{HAVE_DIRENT_H} 5218@item @file{sys/ndir.h} @tab @code{HAVE_SYS_NDIR_H} 5219@item @file{sys/dir.h} @tab @code{HAVE_SYS_DIR_H} 5220@item @file{ndir.h} @tab @code{HAVE_NDIR_H} 5221@end multitable 5222 5223The directory-library declarations in your source code should look 5224something like the following: 5225 5226@example 5227@group 5228#include <sys/types.h> 5229#ifdef HAVE_DIRENT_H 5230# include <dirent.h> 5231# define NAMLEN(dirent) strlen ((dirent)->d_name) 5232#else 5233# define dirent direct 5234# define NAMLEN(dirent) ((dirent)->d_namlen) 5235# ifdef HAVE_SYS_NDIR_H 5236# include <sys/ndir.h> 5237# endif 5238# ifdef HAVE_SYS_DIR_H 5239# include <sys/dir.h> 5240# endif 5241# ifdef HAVE_NDIR_H 5242# include <ndir.h> 5243# endif 5244#endif 5245@end group 5246@end example 5247 5248Using the above declarations, the program would declare variables to be 5249of type @code{struct dirent}, not @code{struct direct}, and would access 5250the length of a directory entry name by passing a pointer to a 5251@code{struct dirent} to the @code{NAMLEN} macro. 5252 5253This macro also checks for the SCO Xenix @file{dir} and @file{x} libraries. 5254 5255This macro is obsolescent, as all current systems with directory 5256libraries have @code{<dirent.h>}. New programs need not use this macro. 5257 5258Also see @code{AC_STRUCT_DIRENT_D_INO} and 5259@code{AC_STRUCT_DIRENT_D_TYPE} (@pxref{Particular Structures}). 5260@end defmac 5261 5262@defmac AC_HEADER_MAJOR 5263@acindex{HEADER_MAJOR} 5264@cvindex MAJOR_IN_MKDEV 5265@cvindex MAJOR_IN_SYSMACROS 5266@hdrindex{sys/mkdev.h} 5267@hdrindex{sys/sysmacros.h} 5268If @file{sys/types.h} does not define @code{major}, @code{minor}, and 5269@code{makedev}, but @file{sys/mkdev.h} does, define 5270@code{MAJOR_IN_MKDEV}; otherwise, if @file{sys/sysmacros.h} does, define 5271@code{MAJOR_IN_SYSMACROS}. 5272@end defmac 5273 5274@defmac AC_HEADER_RESOLV 5275@acindex{HEADER_RESOLV} 5276@cvindex HAVE_RESOLV_H 5277@hdrindex{resolv.h} 5278Checks for header @file{resolv.h}, checking for prerequisites first. 5279To properly use @file{resolv.h}, your code should contain something like 5280the following: 5281 5282@verbatim 5283#ifdef HAVE_SYS_TYPES_H 5284# include <sys/types.h> 5285#endif 5286#ifdef HAVE_NETINET_IN_H 5287# include <netinet/in.h> /* inet_ functions / structs */ 5288#endif 5289#ifdef HAVE_ARPA_NAMESER_H 5290# include <arpa/nameser.h> /* DNS HEADER struct */ 5291#endif 5292#ifdef HAVE_NETDB_H 5293# include <netdb.h> 5294#endif 5295#include <resolv.h> 5296@end verbatim 5297@end defmac 5298 5299@defmac AC_HEADER_STAT 5300@acindex{HEADER_STAT} 5301@cvindex STAT_MACROS_BROKEN 5302@hdrindex{sys/stat.h} 5303If the macros @code{S_ISDIR}, @code{S_ISREG}, etc.@: defined in 5304@file{sys/stat.h} do not work properly (returning false positives), 5305define @code{STAT_MACROS_BROKEN}. This is the case on Tektronix UTekV, 5306Amdahl UTS and Motorola System V/88. 5307 5308This macro is obsolescent, as no current systems have the bug. 5309New programs need not use this macro. 5310@end defmac 5311 5312@defmac AC_HEADER_STDBOOL 5313@acindex{HEADER_STDBOOL} 5314@cvindex HAVE_STDBOOL_H 5315@cvindex HAVE__BOOL 5316@hdrindex{stdbool.h} 5317@hdrindex{system.h} 5318If @file{stdbool.h} exists and conforms to C99, define 5319@code{HAVE_STDBOOL_H} to 1; if the type @code{_Bool} is defined, define 5320@code{HAVE__BOOL} to 1. To fulfill the C99 requirements, your 5321@file{system.h} could contain the following code: 5322 5323@verbatim 5324#ifdef HAVE_STDBOOL_H 5325# include <stdbool.h> 5326#else 5327# ifndef HAVE__BOOL 5328# ifdef __cplusplus 5329typedef bool _Bool; 5330# else 5331# define _Bool signed char 5332# endif 5333# endif 5334# define bool _Bool 5335# define false 0 5336# define true 1 5337# define __bool_true_false_are_defined 1 5338#endif 5339@end verbatim 5340 5341Alternatively you can use the @samp{stdbool} package of Gnulib 5342(@pxref{Gnulib}); it packages the above code into a replacement header 5343and contains a few other bells and whistles. 5344 5345@end defmac 5346 5347 5348@defmac AC_HEADER_STDC 5349@acindex{HEADER_STDC} 5350@cvindex STDC_HEADERS 5351@hdrindex{stdlib.h} 5352@hdrindex{stdarg.h} 5353@hdrindex{string.h} 5354@hdrindex{float.h} 5355@hdrindex{ctype.h} 5356Define @code{STDC_HEADERS} if the system has C header files 5357conforming to @acronym{ANSI} C89 (@acronym{ISO} C90). 5358Specifically, this macro checks for @file{stdlib.h}, @file{stdarg.h}, 5359@file{string.h}, and @file{float.h}; if the system has those, it 5360probably has the rest of the C89 header files. This macro also 5361checks whether @file{string.h} declares @code{memchr} (and thus 5362presumably the other @code{mem} functions), whether @file{stdlib.h} 5363declare @code{free} (and thus presumably @code{malloc} and other related 5364functions), and whether the @file{ctype.h} macros work on characters 5365with the high bit set, as the C standard requires. 5366 5367If you use this macro, your code can refer to @code{STDC_HEADERS} to 5368determine whether the system has conforming header files (and probably C 5369library functions). 5370 5371This macro is obsolescent, as current systems have conforming header 5372files. New programs need not use this macro. 5373 5374@hdrindex{string.h} 5375@hdrindex{strings.h} 5376Nowadays @file{string.h} is part of the C standard and declares functions like 5377@code{strcpy}, and @file{strings.h} is standardized by Posix and declares 5378@acronym{BSD} functions like @code{bcopy}; but 5379historically, string functions were a major sticking point in this area. 5380If you still want to worry about portability to ancient systems without 5381standard headers, there is so much variation 5382that it is probably easier to declare the functions you use than to 5383figure out exactly what the system header files declare. Some ancient systems 5384contained a mix of functions from the C standard and from @acronym{BSD}; 5385some were mostly standard but lacked @samp{memmove}; some defined the 5386@acronym{BSD} functions as macros in @file{string.h} or 5387@file{strings.h}; some had only the @acronym{BSD} functions but 5388@file{string.h}; some declared the memory functions in @file{memory.h}, 5389some in @file{string.h}; etc. It is probably sufficient to check for 5390one string function and one memory function; if the library had the 5391standard versions of those then it probably had most of the others. 5392If you put the following in @file{configure.ac}: 5393 5394@example 5395# This example is obsolescent. 5396# Nowadays you can omit these macro calls. 5397AC_HEADER_STDC 5398AC_CHECK_FUNCS([strchr memcpy]) 5399@end example 5400 5401@noindent 5402then, in your code, you can use declarations like this: 5403 5404@example 5405@group 5406/* This example is obsolescent. 5407 Nowadays you can just #include <string.h>. */ 5408#ifdef STDC_HEADERS 5409# include <string.h> 5410#else 5411# ifndef HAVE_STRCHR 5412# define strchr index 5413# define strrchr rindex 5414# endif 5415char *strchr (), *strrchr (); 5416# ifndef HAVE_MEMCPY 5417# define memcpy(d, s, n) bcopy ((s), (d), (n)) 5418# define memmove(d, s, n) bcopy ((s), (d), (n)) 5419# endif 5420#endif 5421@end group 5422@end example 5423 5424@noindent 5425If you use a function like @code{memchr}, @code{memset}, @code{strtok}, 5426or @code{strspn}, which have no @acronym{BSD} equivalent, then macros don't 5427suffice to port to ancient hosts; you must provide an implementation of 5428each function. An easy 5429way to incorporate your implementations only when needed (since the ones 5430in system C libraries may be hand optimized) is to, taking @code{memchr} 5431for example, put it in @file{memchr.c} and use 5432@samp{AC_REPLACE_FUNCS([memchr])}. 5433@end defmac 5434 5435@defmac AC_HEADER_SYS_WAIT 5436@acindex{HEADER_SYS_WAIT} 5437@cvindex HAVE_SYS_WAIT_H 5438@hdrindex{sys/wait.h} 5439If @file{sys/wait.h} exists and is compatible with Posix, define 5440@code{HAVE_SYS_WAIT_H}. Incompatibility can occur if @file{sys/wait.h} 5441does not exist, or if it uses the old @acronym{BSD} @code{union wait} instead 5442of @code{int} to store a status value. If @file{sys/wait.h} is not 5443Posix compatible, then instead of including it, define the 5444Posix macros with their usual interpretations. Here is an 5445example: 5446 5447@example 5448@group 5449#include <sys/types.h> 5450#ifdef HAVE_SYS_WAIT_H 5451# include <sys/wait.h> 5452#endif 5453#ifndef WEXITSTATUS 5454# define WEXITSTATUS(stat_val) ((unsigned int) (stat_val) >> 8) 5455#endif 5456#ifndef WIFEXITED 5457# define WIFEXITED(stat_val) (((stat_val) & 255) == 0) 5458#endif 5459@end group 5460@end example 5461 5462@noindent 5463This macro is obsolescent, as current systems are compatible with Posix. 5464New programs need not use this macro. 5465@end defmac 5466 5467@cvindex _POSIX_VERSION 5468@hdrindex{unistd.h} 5469@code{_POSIX_VERSION} is defined when @file{unistd.h} is included on 5470Posix systems. If there is no @file{unistd.h}, it is definitely 5471not a Posix system. However, some non-Posix systems do 5472have @file{unistd.h}. 5473 5474The way to check whether the system supports Posix is: 5475 5476@example 5477@group 5478#ifdef HAVE_UNISTD_H 5479# include <sys/types.h> 5480# include <unistd.h> 5481#endif 5482 5483#ifdef _POSIX_VERSION 5484/* Code for Posix systems. */ 5485#endif 5486@end group 5487@end example 5488 5489@defmac AC_HEADER_TIME 5490@acindex{HEADER_TIME} 5491@cvindex TIME_WITH_SYS_TIME 5492@hdrindex{time.h} 5493@hdrindex{sys/time.h} 5494If a program may include both @file{time.h} and @file{sys/time.h}, 5495define @code{TIME_WITH_SYS_TIME}. On some ancient systems, 5496@file{sys/time.h} included @file{time.h}, but @file{time.h} was not 5497protected against multiple inclusion, so programs could not explicitly 5498include both files. This macro is useful in programs that use, for 5499example, @code{struct timeval} as well as 5500@code{struct tm}. It is best used in conjunction with 5501@code{HAVE_SYS_TIME_H}, which can be checked for using 5502@code{AC_CHECK_HEADERS([sys/time.h])}. 5503 5504@example 5505@group 5506#ifdef TIME_WITH_SYS_TIME 5507# include <sys/time.h> 5508# include <time.h> 5509#else 5510# ifdef HAVE_SYS_TIME_H 5511# include <sys/time.h> 5512# else 5513# include <time.h> 5514# endif 5515#endif 5516@end group 5517@end example 5518 5519@noindent 5520This macro is obsolescent, as current systems can include both files 5521when they exist. New programs need not use this macro. 5522@end defmac 5523 5524 5525@defmac AC_HEADER_TIOCGWINSZ 5526@acindex{HEADER_TIOCGWINSZ} 5527@cvindex GWINSZ_IN_SYS_IOCTL 5528@hdrindex{sys/ioctl.h} 5529@hdrindex{termios.h} 5530@c FIXME: I need clarifications from Jim. 5531If the use of @code{TIOCGWINSZ} requires @file{<sys/ioctl.h>}, then 5532define @code{GWINSZ_IN_SYS_IOCTL}. Otherwise @code{TIOCGWINSZ} can be 5533found in @file{<termios.h>}. 5534 5535Use: 5536 5537@example 5538@group 5539#ifdef HAVE_TERMIOS_H 5540# include <termios.h> 5541#endif 5542 5543#ifdef GWINSZ_IN_SYS_IOCTL 5544# include <sys/ioctl.h> 5545#endif 5546@end group 5547@end example 5548@end defmac 5549 5550@node Generic Headers 5551@subsection Generic Header Checks 5552 5553These macros are used to find system header files not covered by the 5554``particular'' test macros. If you need to check the contents of a header 5555as well as find out whether it is present, you have to write your own 5556test for it (@pxref{Writing Tests}). 5557 5558@defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5559@acindex{CHECK_HEADER} 5560If the system header file @var{header-file} is compilable, execute shell 5561commands @var{action-if-found}, otherwise execute 5562@var{action-if-not-found}. If you just want to define a symbol if the 5563header file is available, consider using @code{AC_CHECK_HEADERS} 5564instead. 5565 5566For compatibility issues with older versions of Autoconf, please read 5567below. 5568@end defmac 5569 5570@defmac AC_CHECK_HEADERS (@var{header-file}@dots{}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5571@acindex{CHECK_HEADERS} 5572@cvindex HAVE_@var{header} 5573For each given system header file @var{header-file} in the 5574blank-separated argument list that exists, define 5575@code{HAVE_@var{header-file}} (in all capitals). If @var{action-if-found} 5576is given, it is additional shell code to execute when one of the header 5577files is found. You can give it a value of @samp{break} to break out of 5578the loop on the first match. If @var{action-if-not-found} is given, it 5579is executed when one of the header files is not found. 5580 5581For compatibility issues with older versions of Autoconf, please read 5582below. 5583@end defmac 5584 5585Previous versions of Autoconf merely checked whether the header was 5586accepted by the preprocessor. This was changed because the old test was 5587inappropriate for typical uses. Headers are typically used to compile, 5588not merely to preprocess, and the old behavior sometimes accepted 5589headers that clashed at compile-time. If you need to check whether a 5590header is preprocessable, you can use @code{AC_PREPROC_IFELSE} 5591(@pxref{Running the Preprocessor}). 5592 5593This scheme, which improves the robustness of the test, also requires 5594that you make sure that headers that must be included before the 5595@var{header-file} be part of the @var{includes}, (@pxref{Default 5596Includes}). If looking for @file{bar.h}, which requires that 5597@file{foo.h} be included before if it exists, we suggest the following 5598scheme: 5599 5600@verbatim 5601AC_CHECK_HEADERS([foo.h]) 5602AC_CHECK_HEADERS([bar.h], [], [], 5603[#ifdef HAVE_FOO_H 5604# include <foo.h> 5605# endif 5606]) 5607@end verbatim 5608 5609The following variant generates smaller, faster @command{configure} 5610files if you do not need the full power of @code{AC_CHECK_HEADERS}. 5611 5612@defmac AC_CHECK_HEADERS_ONCE (@var{header-file}@dots{}) 5613@acindex{CHECK_HEADERS_ONCE} 5614@cvindex HAVE_@var{header} 5615For each given system header file @var{header-file} in the 5616blank-separated argument list that exists, define 5617@code{HAVE_@var{header-file}} (in all capitals). 5618This is a once-only variant of @code{AC_CHECK_HEADERS}. It generates the 5619checking code at most once, so that @command{configure} is smaller and 5620faster; but the checks cannot be conditionalized and are always done once, 5621early during the @command{configure} run. 5622@end defmac 5623 5624@node Declarations 5625@section Declarations 5626@cindex Declaration, checking 5627 5628The following macros check for the declaration of variables and 5629functions. If there is no macro specifically defined to check for a 5630symbol you need, then you can use the general macros (@pxref{Generic 5631Declarations}) or, for more complex tests, you may use 5632@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 5633 5634@menu 5635* Particular Declarations:: Macros to check for certain declarations 5636* Generic Declarations:: How to find other declarations 5637@end menu 5638 5639@node Particular Declarations 5640@subsection Particular Declaration Checks 5641 5642There are no specific macros for declarations. 5643 5644@node Generic Declarations 5645@subsection Generic Declaration Checks 5646 5647These macros are used to find declarations not covered by the ``particular'' 5648test macros. 5649 5650@defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5651@acindex{CHECK_DECL} 5652If @var{symbol} (a function, variable, or constant) is not declared in 5653@var{includes} and a declaration is needed, run the shell commands 5654@var{action-if-not-found}, otherwise @var{action-if-found}. If no 5655@var{includes} are specified, the default includes are used 5656(@pxref{Default Includes}). 5657 5658This macro actually tests whether @var{symbol} is defined as a macro or 5659can be used as an r-value, not whether it is really declared, because it 5660is much safer to avoid 5661introducing extra declarations when they are not needed. 5662@end defmac 5663 5664@defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5665@acindex{CHECK_DECLS} 5666@cvindex HAVE_DECL_@var{symbol} 5667For each of the @var{symbols} (@emph{comma}-separated list), define 5668@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 5669@var{symbol} is declared, otherwise to @samp{0}. If 5670@var{action-if-not-found} is given, it is additional shell code to 5671execute when one of the function declarations is needed, otherwise 5672@var{action-if-found} is executed. 5673 5674This macro uses an M4 list as first argument: 5675@example 5676AC_CHECK_DECLS([strdup]) 5677AC_CHECK_DECLS([strlen]) 5678AC_CHECK_DECLS([malloc, realloc, calloc, free]) 5679@end example 5680 5681Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not 5682declared, @code{HAVE_DECL_@var{symbol}} is defined to @samp{0} instead 5683of leaving @code{HAVE_DECL_@var{symbol}} undeclared. When you are 5684@emph{sure} that the check was performed, use 5685@code{HAVE_DECL_@var{symbol}} in @code{#if}: 5686 5687@example 5688#if !HAVE_DECL_SYMBOL 5689extern char *symbol; 5690#endif 5691@end example 5692 5693@noindent 5694If the test may have not been performed, however, because it is safer 5695@emph{not} to declare a symbol than to use a declaration that conflicts 5696with the system's one, you should use: 5697 5698@example 5699#if defined HAVE_DECL_MALLOC && !HAVE_DECL_MALLOC 5700void *malloc (size_t *s); 5701#endif 5702@end example 5703 5704@noindent 5705You fall into the second category only in extreme situations: either 5706your files may be used without being configured, or they are used during 5707the configuration. In most cases the traditional approach is enough. 5708@end defmac 5709 5710@defmac AC_CHECK_DECLS_ONCE (@var{symbols}) 5711@acindex{CHECK_DECLS_ONCE} 5712@cvindex HAVE_DECL_@var{symbol} 5713For each of the @var{symbols} (@emph{comma}-separated list), define 5714@code{HAVE_DECL_@var{symbol}} (in all capitals) to @samp{1} if 5715@var{symbol} is declared in the default include files, otherwise to 5716@samp{0}. This is a once-only variant of @code{AC_CHECK_DECLS}. It 5717generates the checking code at most once, so that @command{configure} is 5718smaller and faster; but the checks cannot be conditionalized and are 5719always done once, early during the @command{configure} run. 5720@end defmac 5721 5722 5723@node Structures 5724@section Structures 5725@cindex Structure, checking 5726 5727The following macros check for the presence of certain members in C 5728structures. If there is no macro specifically defined to check for a 5729member you need, then you can use the general structure-member macros 5730(@pxref{Generic Structures}) or, for more complex tests, you may use 5731@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}). 5732 5733@menu 5734* Particular Structures:: Macros to check for certain structure members 5735* Generic Structures:: How to find other structure members 5736@end menu 5737 5738@node Particular Structures 5739@subsection Particular Structure Checks 5740 5741The following macros check for certain structures or structure members. 5742 5743@defmac AC_STRUCT_DIRENT_D_INO 5744@acindex{STRUCT_DIRENT_D_INO} 5745@cvindex HAVE_STRUCT_DIRENT_D_INO 5746Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 5747Headers}). Then, if @code{struct dirent} contains a @code{d_ino} 5748member, define @code{HAVE_STRUCT_DIRENT_D_INO}. 5749 5750@code{HAVE_STRUCT_DIRENT_D_INO} indicates only the presence of 5751@code{d_ino}, not whether its contents are always reliable. 5752Traditionally, a zero @code{d_ino} indicated a deleted directory entry, 5753though current systems hide this detail from the user and never return 5754zero @code{d_ino} values. 5755Many current systems report an incorrect @code{d_ino} for a directory 5756entry that is a mount point. 5757@end defmac 5758 5759@defmac AC_STRUCT_DIRENT_D_TYPE 5760@acindex{STRUCT_DIRENT_D_TYPE} 5761@cvindex HAVE_STRUCT_DIRENT_D_TYPE 5762Perform all the actions of @code{AC_HEADER_DIRENT} (@pxref{Particular 5763Headers}). Then, if @code{struct dirent} contains a @code{d_type} 5764member, define @code{HAVE_STRUCT_DIRENT_D_TYPE}. 5765@end defmac 5766 5767@defmac AC_STRUCT_ST_BLKSIZE 5768@acindex{STRUCT_ST_BLKSIZE} 5769@cvindex HAVE_STRUCT_STAT_ST_BLKSIZE 5770@cvindex HAVE_ST_BLKSIZE 5771If @code{struct stat} contains an @code{st_blksize} member, define 5772@code{HAVE_STRUCT_STAT_ST_BLKSIZE}. The former name, 5773@code{HAVE_ST_BLKSIZE} is to be avoided, as its support will cease in 5774the future. This macro is obsoleted, and should be replaced by 5775 5776@example 5777AC_CHECK_MEMBERS([struct stat.st_blksize]) 5778@end example 5779@end defmac 5780 5781@defmac AC_STRUCT_ST_BLOCKS 5782@acindex{STRUCT_ST_BLOCKS} 5783@cvindex HAVE_STRUCT_STAT_ST_BLOCKS 5784@cvindex HAVE_ST_BLOCKS 5785@ovindex LIBOBJS 5786If @code{struct stat} contains an @code{st_blocks} member, define 5787@code{HAVE_STRUCT_STAT_ST_BLOCKS}. Otherwise, require an 5788@code{AC_LIBOBJ} replacement of @samp{fileblocks}. The former name, 5789@code{HAVE_ST_BLOCKS} is to be avoided, as its support will cease in the 5790future. 5791@end defmac 5792 5793@defmac AC_STRUCT_ST_RDEV 5794@acindex{STRUCT_ST_RDEV} 5795@cvindex HAVE_ST_RDEV 5796@cvindex HAVE_STRUCT_STAT_ST_RDEV 5797If @code{struct stat} contains an @code{st_rdev} member, define 5798@code{HAVE_STRUCT_STAT_ST_RDEV}. The former name for this macro, 5799@code{HAVE_ST_RDEV}, is to be avoided as it will cease to be supported 5800in the future. Actually, even the new macro is obsolete and should be 5801replaced by: 5802@example 5803AC_CHECK_MEMBERS([struct stat.st_rdev]) 5804@end example 5805@end defmac 5806 5807@defmac AC_STRUCT_TM 5808@acindex{STRUCT_TM} 5809@cvindex TM_IN_SYS_TIME 5810@hdrindex{time.h} 5811@hdrindex{sys/time.h} 5812If @file{time.h} does not define @code{struct tm}, define 5813@code{TM_IN_SYS_TIME}, which means that including @file{sys/time.h} 5814had better define @code{struct tm}. 5815 5816This macro is obsolescent, as @file{time.h} defines @code{struct tm} in 5817current systems. New programs need not use this macro. 5818@end defmac 5819 5820@defmac AC_STRUCT_TIMEZONE 5821@acindex{STRUCT_TIMEZONE} 5822@cvindex HAVE_TM_ZONE 5823@cvindex HAVE_TZNAME 5824Figure out how to get the current timezone. If @code{struct tm} has a 5825@code{tm_zone} member, define @code{HAVE_STRUCT_TM_TM_ZONE} (and the 5826obsoleted @code{HAVE_TM_ZONE}). Otherwise, if the external array 5827@code{tzname} is found, define @code{HAVE_TZNAME}; if it is declared, 5828define @code{HAVE_DECL_TZNAME}. 5829@end defmac 5830 5831@node Generic Structures 5832@subsection Generic Structure Checks 5833 5834These macros are used to find structure members not covered by the 5835``particular'' test macros. 5836 5837@defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5838@acindex{CHECK_MEMBER} 5839Check whether @var{member} is a member of the aggregate @var{aggregate}. 5840If no @var{includes} are specified, the default includes are used 5841(@pxref{Default Includes}). 5842 5843@example 5844AC_CHECK_MEMBER([struct passwd.pw_gecos], [], 5845 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])], 5846 [#include <pwd.h>]) 5847@end example 5848 5849You can use this macro for submembers: 5850 5851@example 5852AC_CHECK_MEMBER(struct top.middle.bot) 5853@end example 5854@end defmac 5855 5856@defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 5857@acindex{CHECK_MEMBERS} 5858Check for the existence of each @samp{@var{aggregate}.@var{member}} of 5859@var{members} using the previous macro. When @var{member} belongs to 5860@var{aggregate}, define @code{HAVE_@var{aggregate}_@var{member}} (in all 5861capitals, with spaces and dots replaced by underscores). If 5862@var{action-if-found} is given, it is executed for each of the found 5863members. If @var{action-if-not-found} is given, it is executed for each 5864of the members that could not be found. 5865 5866This macro uses M4 lists: 5867@example 5868AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize]) 5869@end example 5870@end defmac 5871 5872 5873@node Types 5874@section Types 5875@cindex Types 5876@cindex C types 5877 5878The following macros check for C types, either builtin or typedefs. If 5879there is no macro specifically defined to check for a type you need, and 5880you don't need to check for any special properties of it, then you can 5881use a general type-check macro. 5882 5883@menu 5884* Particular Types:: Special handling to find certain types 5885* Generic Types:: How to find other types 5886@end menu 5887 5888@node Particular Types 5889@subsection Particular Type Checks 5890 5891@hdrindex{sys/types.h} 5892@hdrindex{stdlib.h} 5893@hdrindex{stdint.h} 5894@hdrindex{inttypes.h} 5895These macros check for particular C types in @file{sys/types.h}, 5896@file{stdlib.h}, @file{stdint.h}, @file{inttypes.h} and others, if they 5897exist. 5898 5899The Gnulib @code{stdint} module is an alternate way to define many of 5900these symbols; it is useful if you prefer your code to assume a 5901C99-or-better environment. @xref{Gnulib}. 5902 5903@defmac AC_TYPE_GETGROUPS 5904@acindex{TYPE_GETGROUPS} 5905@cvindex GETGROUPS_T 5906Define @code{GETGROUPS_T} to be whichever of @code{gid_t} or @code{int} 5907is the base type of the array argument to @code{getgroups}. 5908@end defmac 5909 5910@defmac AC_TYPE_INT8_T 5911@acindex{TYPE_INT8_T} 5912@cvindex HAVE_INT8_T 5913@cvindex int8_t 5914If @file{stdint.h} or @file{inttypes.h} defines the type @code{int8_t}, 5915define @code{HAVE_INT8_T}. Otherwise, define @code{int8_t} to a signed 5916integer type that is exactly 8 bits wide and that uses two's complement 5917representation, if such a type exists. 5918@end defmac 5919 5920@defmac AC_TYPE_INT16_T 5921@acindex{TYPE_INT16_T} 5922@cvindex HAVE_INT16_T 5923@cvindex int16_t 5924This is like @code{AC_TYPE_INT8_T}, except for 16-bit integers. 5925@end defmac 5926 5927@defmac AC_TYPE_INT32_T 5928@acindex{TYPE_INT32_T} 5929@cvindex HAVE_INT32_T 5930@cvindex int32_t 5931This is like @code{AC_TYPE_INT8_T}, except for 32-bit integers. 5932@end defmac 5933 5934@defmac AC_TYPE_INT64_T 5935@acindex{TYPE_INT64_T} 5936@cvindex HAVE_INT64_T 5937@cvindex int64_t 5938This is like @code{AC_TYPE_INT8_T}, except for 64-bit integers. 5939@end defmac 5940 5941@defmac AC_TYPE_INTMAX_T 5942@acindex{TYPE_INTMAX_T} 5943@cvindex HAVE_INTMAX_T 5944@cvindex intmax_t 5945If @file{stdint.h} or @file{inttypes.h} defines the type @code{intmax_t}, 5946define @code{HAVE_INTMAX_T}. Otherwise, define @code{intmax_t} to the 5947widest signed integer type. 5948@end defmac 5949 5950@defmac AC_TYPE_INTPTR_T 5951@acindex{TYPE_INTPTR_T} 5952@cvindex HAVE_INTPTR_T 5953@cvindex intptr_t 5954If @file{stdint.h} or @file{inttypes.h} defines the type @code{intptr_t}, 5955define @code{HAVE_INTPTR_T}. Otherwise, define @code{intptr_t} to a 5956signed integer type wide enough to hold a pointer, if such a type 5957exists. 5958@end defmac 5959 5960@defmac AC_TYPE_LONG_DOUBLE 5961@acindex{TYPE_LONG_DOUBLE} 5962@cvindex HAVE_LONG_DOUBLE 5963If the C compiler supports a working @code{long double} type, define 5964@code{HAVE_LONG_DOUBLE}. The @code{long double} type might have the 5965same range and precision as @code{double}. 5966@end defmac 5967 5968@defmac AC_TYPE_LONG_DOUBLE_WIDER 5969@acindex{TYPE_LONG_DOUBLE_WIDER} 5970@cvindex HAVE_LONG_DOUBLE_WIDER 5971If the C compiler supports a working @code{long double} type with more 5972range or precision than the @code{double} type, define 5973@code{HAVE_LONG_DOUBLE_WIDER}. 5974@end defmac 5975 5976@defmac AC_TYPE_LONG_LONG_INT 5977@acindex{TYPE_LONG_LONG_INT} 5978@cvindex HAVE_LONG_LONG_INT 5979If the C compiler supports a working @code{long long int} type, define 5980@code{HAVE_LONG_LONG_INT}. 5981@end defmac 5982 5983@defmac AC_TYPE_MBSTATE_T 5984@acindex{TYPE_MBSTATE_T} 5985@cvindex mbstate_t 5986@hdrindex{wchar.h} 5987Define @code{HAVE_MBSTATE_T} if @code{<wchar.h>} declares the 5988@code{mbstate_t} type. Also, define @code{mbstate_t} to be a type if 5989@code{<wchar.h>} does not declare it. 5990@end defmac 5991 5992@defmac AC_TYPE_MODE_T 5993@acindex{TYPE_MODE_T} 5994@cvindex mode_t 5995Define @code{mode_t} to a suitable type, if standard headers do not 5996define it. 5997@end defmac 5998 5999@defmac AC_TYPE_OFF_T 6000@acindex{TYPE_OFF_T} 6001@cvindex off_t 6002Define @code{off_t} to a suitable type, if standard headers do not 6003define it. 6004@end defmac 6005 6006@defmac AC_TYPE_PID_T 6007@acindex{TYPE_PID_T} 6008@cvindex pid_t 6009Define @code{pid_t} to a suitable type, if standard headers do not 6010define it. 6011@end defmac 6012 6013@defmac AC_TYPE_SIGNAL 6014@acindex{TYPE_SIGNAL} 6015@cvindex RETSIGTYPE 6016@hdrindex{signal.h} 6017If @file{signal.h} declares @code{signal} as returning a pointer to a 6018function returning @code{void}, define @code{RETSIGTYPE} to be 6019@code{void}; otherwise, define it to be @code{int}. 6020 6021Define signal handlers as returning type @code{RETSIGTYPE}: 6022 6023@example 6024@group 6025RETSIGTYPE 6026hup_handler () 6027@{ 6028@dots{} 6029@} 6030@end group 6031@end example 6032@end defmac 6033 6034@defmac AC_TYPE_SIZE_T 6035@acindex{TYPE_SIZE_T} 6036@cvindex size_t 6037Define @code{size_t} to a suitable type, if standard headers do not 6038define it. 6039@end defmac 6040 6041@defmac AC_TYPE_SSIZE_T 6042@acindex{TYPE_SSIZE_T} 6043@cvindex ssize_t 6044Define @code{ssize_t} to a suitable type, if standard headers do not 6045define it. 6046@end defmac 6047 6048@defmac AC_TYPE_UID_T 6049@acindex{TYPE_UID_T} 6050@cvindex uid_t 6051@cvindex gid_t 6052Define @code{uid_t} and @code{gid_t} to suitable types, if standard 6053headers do not define them. 6054@end defmac 6055 6056@defmac AC_TYPE_UINT8_T 6057@acindex{TYPE_UINT8_T} 6058@cvindex HAVE_UINT8_T 6059@cvindex uint8_t 6060If @file{stdint.h} or @file{inttypes.h} defines the type @code{uint8_t}, 6061define @code{HAVE_UINT8_T}. Otherwise, define @code{uint8_t} to an 6062unsigned integer type that is exactly 8 bits wide, if such a type 6063exists. 6064@end defmac 6065 6066@defmac AC_TYPE_UINT16_T 6067@acindex{TYPE_UINT16_T} 6068@cvindex HAVE_UINT16_T 6069@cvindex uint16_t 6070This is like @code{AC_TYPE_UINT8_T}, except for 16-bit unsigned integers. 6071@end defmac 6072 6073@defmac AC_TYPE_UINT32_T 6074@acindex{TYPE_UINT32_T} 6075@cvindex HAVE_UINT32_T 6076@cvindex uint32_t 6077This is like @code{AC_TYPE_UINT8_T}, except for 32-bit unsigned integers. 6078@end defmac 6079 6080@defmac AC_TYPE_UINT64_T 6081@acindex{TYPE_UINT64_T} 6082@cvindex HAVE_UINT64_T 6083@cvindex uint64_t 6084This is like @code{AC_TYPE_UINT8_T}, except for 64-bit unsigned integers. 6085@end defmac 6086 6087@defmac AC_TYPE_UINTMAX_T 6088@acindex{TYPE_UINTMAX_T} 6089@cvindex HAVE_UINTMAX_T 6090@cvindex uintmax_t 6091If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintmax_t}, 6092define @code{HAVE_UINTMAX_T}. Otherwise, define @code{uintmax_t} to the 6093widest unsigned integer type. 6094@end defmac 6095 6096@defmac AC_TYPE_UINTPTR_T 6097@acindex{TYPE_UINTPTR_T} 6098@cvindex HAVE_UINTPTR_T 6099@cvindex uintptr_t 6100If @file{stdint.h} or @file{inttypes.h} defines the type @code{uintptr_t}, 6101define @code{HAVE_UINTPTR_T}. Otherwise, define @code{uintptr_t} to an 6102unsigned integer type wide enough to hold a pointer, if such a type 6103exists. 6104@end defmac 6105 6106@defmac AC_TYPE_UNSIGNED_LONG_LONG_INT 6107@acindex{TYPE_UNSIGNED_LONG_LONG_INT} 6108@cvindex HAVE_UNSIGNED_LONG_LONG_INT 6109If the C compiler supports a working @code{unsigned long long int} type, 6110define @code{HAVE_UNSIGNED_LONG_LONG_INT}. 6111@end defmac 6112 6113@node Generic Types 6114@subsection Generic Type Checks 6115 6116These macros are used to check for types not covered by the ``particular'' 6117test macros. 6118 6119@defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 6120@acindex{CHECK_TYPE} 6121Check whether @var{type} is defined. It may be a compiler builtin type 6122or defined by the @var{includes} (@pxref{Default Includes}). 6123@end defmac 6124 6125 6126@defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @ovar{action-if-not-found}, @dvar{includes, default-includes}) 6127@acindex{CHECK_TYPES} 6128For each @var{type} of the @var{types} that is defined, define 6129@code{HAVE_@var{type}} (in all capitals). If no @var{includes} are 6130specified, the default includes are used (@pxref{Default Includes}). If 6131@var{action-if-found} is given, it is additional shell code to execute 6132when one of the types is found. If @var{action-if-not-found} is given, 6133it is executed when one of the types is not found. 6134 6135This macro uses M4 lists: 6136@example 6137AC_CHECK_TYPES([ptrdiff_t]) 6138AC_CHECK_TYPES([unsigned long long int, uintmax_t]) 6139@end example 6140 6141@end defmac 6142 6143Autoconf, up to 2.13, used to provide to another version of 6144@code{AC_CHECK_TYPE}, broken by design. In order to keep backward 6145compatibility, a simple heuristics, quite safe but not totally, is 6146implemented. In case of doubt, read the documentation of the former 6147@code{AC_CHECK_TYPE}, see @ref{Obsolete Macros}. 6148 6149 6150@node Compilers and Preprocessors 6151@section Compilers and Preprocessors 6152@cindex Compilers 6153@cindex Preprocessors 6154 6155@ovindex EXEEXT 6156All the tests for compilers (@code{AC_PROG_CC}, @code{AC_PROG_CXX}, 6157@code{AC_PROG_F77}) define the output variable @code{EXEEXT} based on 6158the output of the compiler, typically to the empty string if 6159Posix and @samp{.exe} if a @acronym{DOS} variant. 6160 6161@ovindex OBJEXT 6162They also define the output variable @code{OBJEXT} based on the 6163output of the compiler, after @file{.c} files have been excluded, typically 6164to @samp{o} if Posix, @samp{obj} if a @acronym{DOS} variant. 6165 6166If the compiler being used does not produce executables, the tests fail. If 6167the executables can't be run, and cross-compilation is not enabled, they 6168fail too. @xref{Manual Configuration}, for more on support for cross 6169compiling. 6170 6171@menu 6172* Specific Compiler Characteristics:: Some portability issues 6173* Generic Compiler Characteristics:: Language independent tests and features 6174* C Compiler:: Checking its characteristics 6175* C++ Compiler:: Likewise 6176* Objective C Compiler:: Likewise 6177* Erlang Compiler and Interpreter:: Likewise 6178* Fortran Compiler:: Likewise 6179@end menu 6180 6181@node Specific Compiler Characteristics 6182@subsection Specific Compiler Characteristics 6183 6184Some compilers exhibit different behaviors. 6185 6186@table @asis 6187@item Static/Dynamic Expressions 6188Autoconf relies on a trick to extract one bit of information from the C 6189compiler: using negative array sizes. For instance the following 6190excerpt of a C source demonstrates how to test whether @samp{int} objects are 4 6191bytes wide: 6192 6193@example 6194static int test_array[sizeof (int) == 4 ? 1 : -1]; 6195@end example 6196 6197@noindent 6198To our knowledge, there is a single compiler that does not support this 6199trick: the @acronym{HP} C compilers (the real ones, not only the ``bundled'') on 6200@acronym{HP-UX} 11.00. 6201They incorrectly reject the above program with the diagnostic 6202``Variable-length arrays cannot have static storage.'' 6203This bug comes from @acronym{HP} compilers' mishandling of @code{sizeof (int)}, 6204not from the @code{? 1 : -1}, and 6205Autoconf works around this problem by casting @code{sizeof (int)} to 6206@code{long int} before comparing it. 6207@end table 6208 6209@node Generic Compiler Characteristics 6210@subsection Generic Compiler Characteristics 6211 6212@defmac AC_CHECK_SIZEOF (@var{type}, @ovar{unused}, @dvar{includes, default-includes}) 6213@acindex{CHECK_SIZEOF} 6214Define @code{SIZEOF_@var{type}} (@pxref{Standard Symbols}) to be the 6215size in bytes of @var{type}. If @samp{type} is unknown, it gets a size 6216of 0. If no @var{includes} are specified, the default includes are used 6217(@pxref{Default Includes}). 6218 6219This macro now works even when cross-compiling. The @var{unused} 6220argument was used when cross-compiling. 6221 6222For example, the call 6223 6224@example 6225AC_CHECK_SIZEOF([int *]) 6226@end example 6227 6228@noindent 6229defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems. 6230@end defmac 6231 6232@defmac AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes}) 6233@acindex{CHECK_ALIGNOF} 6234Define @code{ALIGNOF_@var{type}} (@pxref{Standard Symbols}) to be the 6235alignment in bytes of @var{type}. If @samp{type} is unknown, it gets a size 6236of 0. If no @var{includes} are specified, the default includes are used 6237(@pxref{Default Includes}). 6238@end defmac 6239 6240@defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @dvar{includes, default-includes}, @ovar{action-if-fails}) 6241@acindex{COMPUTE_INT} 6242Store into the shell variable @var{var} the value of the integer 6243@var{expression}. The 6244value should fit in an initializer in a C variable of type @code{signed 6245long}. To support cross compilation (in which case, the macro only works on 6246hosts that use twos-complement arithmetic), it should be possible to evaluate 6247the expression at compile-time. If no @var{includes} are specified, the default 6248includes are used (@pxref{Default Includes}). 6249 6250Execute @var{action-if-fails} if the value cannot be determined correctly. 6251@end defmac 6252 6253@defmac AC_LANG_WERROR 6254@acindex{LANG_WERROR} 6255Normally Autoconf ignores warnings generated by the compiler, linker, and 6256preprocessor. If this macro is used, warnings count as fatal 6257errors for the current language. This macro is useful when the 6258results of configuration are used where warnings are unacceptable; for 6259instance, if parts of a program are built with the @acronym{GCC} 6260@option{-Werror} 6261option. If the whole program is built using @option{-Werror} it is 6262often simpler to put @option{-Werror} in the compiler flags (@code{CFLAGS}, 6263etc.). 6264@end defmac 6265 6266@node C Compiler 6267@subsection C Compiler Characteristics 6268 6269The following macros provide ways to find and exercise a C Compiler. 6270There are a few constructs that ought to be avoided, but do not deserve 6271being checked for, since they can easily be worked around. 6272 6273@table @asis 6274@item Don't use lines containing solitary backslashes 6275They tickle a bug in the @acronym{HP-UX} C compiler (checked on 6276@acronym{HP-UX} 10.20, 627711.00, and 11i). When given the following source: 6278 6279@example 6280#ifdef __STDC__ 6281/\ 6282* A comment with backslash-newlines in it. %@{ %@} *\ 6283\ 6284/ 6285char str[] = "\\ 6286" A string with backslash-newlines in it %@{ %@} \\ 6287""; 6288char apostrophe = '\\ 6289\ 6290'\ 6291'; 6292#endif 6293@end example 6294 6295@noindent 6296the compiler incorrectly fails with the diagnostics ``Non-terminating 6297comment at end of file'' and ``Missing @samp{#endif} at end of file.'' 6298Removing the lines with solitary backslashes solves the problem. 6299 6300@item Don't compile several files at once if output matters to you 6301Some compilers, such as @acronym{HP}'s, report names of files being 6302compiled when given more than one file operand. For instance: 6303 6304@example 6305$ @kbd{cc a.c b.c} 6306a.c: 6307b.c: 6308@end example 6309 6310@noindent 6311This can cause problems if you observe the output of the compiler to 6312detect failures. Invoking @samp{cc -c a.c && cc -c b.c && cc -o c a.o 6313b.o} solves the issue. 6314 6315@item Don't rely on @code{#error} failing 6316The @sc{irix} C compiler does not fail when #error is preprocessed; it 6317simply emits a diagnostic and continues, exiting successfully. So, 6318instead of an error directive like @code{#error "Unsupported word size"} 6319it is more portable to use an invalid directive like @code{#Unsupported 6320word size} in Autoconf tests. In ordinary source code, @code{#error} is 6321OK, since installers with inadequate compilers like @sc{irix} can simply 6322examine these compilers' diagnostic output. 6323 6324@item Don't rely on correct @code{#line} support 6325On Solaris, @command{c89} (at least Sun C 5.3 through 5.8) 6326diagnoses @code{#line} directives whose line 6327numbers are greater than 32767. Nothing in Posix 6328makes this invalid. That is why Autoconf stopped issuing 6329@code{#line} directives. 6330@end table 6331 6332@defmac AC_PROG_CC (@ovar{compiler-search-list}) 6333@acindex{PROG_CC} 6334@ovindex CC 6335@ovindex CFLAGS 6336Determine a C compiler to use. If @code{CC} is not already set in the 6337environment, check for @code{gcc} and @code{cc}, then for other C 6338compilers. Set output variable @code{CC} to the name of the compiler 6339found. 6340 6341This macro may, however, be invoked with an optional first argument 6342which, if specified, must be a blank-separated list of C compilers to 6343search for. This just gives the user an opportunity to specify an 6344alternative search list for the C compiler. For example, if you didn't 6345like the default order, then you could invoke @code{AC_PROG_CC} like 6346this: 6347 6348@example 6349AC_PROG_CC([gcc cl cc]) 6350@end example 6351 6352If the C compiler does not handle function prototypes correctly by 6353default, try to add an option to output variable @code{CC} to make it 6354so. This macro tries various options that select standard-conformance 6355modes on various systems. 6356 6357After calling this macro you can check whether the C compiler has been 6358set to accept @acronym{ANSI} C89 (@acronym{ISO} C90); if not, the shell 6359variable 6360@code{ac_cv_prog_cc_c89} is set to @samp{no}. See also 6361@code{AC_C_PROTOTYPES} below. 6362 6363If using the @acronym{GNU} C compiler, set shell variable @code{GCC} to 6364@samp{yes}. If output variable @code{CFLAGS} was not already set, set 6365it to @option{-g -O2} for the @acronym{GNU} C compiler (@option{-O2} on systems 6366where @acronym{GCC} does not accept @option{-g}), or @option{-g} for 6367other compilers. 6368@end defmac 6369 6370@defmac AC_PROG_CC_C_O 6371@acindex{PROG_CC_C_O} 6372@cvindex NO_MINUS_C_MINUS_O 6373If the C compiler does not accept the @option{-c} and @option{-o} options 6374simultaneously, define @code{NO_MINUS_C_MINUS_O}. This macro actually 6375tests both the compiler found by @code{AC_PROG_CC}, and, if different, 6376the first @code{cc} in the path. The test fails if one fails. This 6377macro was created for @acronym{GNU} Make to choose the default C compilation 6378rule. 6379@end defmac 6380 6381 6382@defmac AC_PROG_CPP 6383@acindex{PROG_CPP} 6384@ovindex CPP 6385Set output variable @code{CPP} to a command that runs the 6386C preprocessor. If @samp{$CC -E} doesn't work, @file{/lib/cpp} is used. 6387It is only portable to run @code{CPP} on files with a @file{.c} 6388extension. 6389 6390Some preprocessors don't indicate missing include files by the error 6391status. For such preprocessors an internal variable is set that causes 6392other macros to check the standard error from the preprocessor and 6393consider the test failed if any warnings have been reported. 6394For most preprocessors, though, warnings do not cause include-file 6395tests to fail unless @code{AC_PROG_CPP_WERROR} is also specified. 6396@end defmac 6397 6398@defmac AC_PROG_CPP_WERROR 6399@acindex{PROG_CPP_WERROR} 6400@ovindex CPP 6401This acts like @code{AC_PROG_CPP}, except it treats warnings from the 6402preprocessor as errors even if the preprocessor exit status indicates 6403success. This is useful for avoiding headers that generate mandatory 6404warnings, such as deprecation notices. 6405@end defmac 6406 6407 6408The following macros check for C compiler or machine architecture 6409features. To check for characteristics not listed here, use 6410@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 6411@code{AC_RUN_IFELSE} (@pxref{Runtime}). 6412 6413@defmac AC_PROG_CC_STDC 6414@acindex{PROG_CC_STDC} 6415If the C compiler cannot compile @acronym{ISO} Standard C (currently 6416C99), try to add an option to output variable @code{CC} to make it work. 6417If the compiler does not support C99, fall back to supporting 6418@acronym{ANSI} C89 (@acronym{ISO} C90). 6419 6420After calling this macro you can check whether the C compiler has been 6421set to accept Standard C; if not, the shell variable 6422@code{ac_cv_prog_cc_stdc} is set to @samp{no}. 6423@end defmac 6424 6425@defmac AC_PROG_CC_C89 6426@acindex{PROG_CC_C89} 6427If the C compiler is not in @acronym{ANSI} C89 (@acronym{ISO} C90) mode by 6428default, try to add an option to output variable @code{CC} to make it 6429so. This macro tries various options that select @acronym{ANSI} C89 on 6430some system or another. It considers the compiler to be in 6431@acronym{ANSI} C89 mode if it handles function prototypes correctly. 6432 6433After calling this macro you can check whether the C compiler has been 6434set to accept @acronym{ANSI} C89; if not, the shell variable 6435@code{ac_cv_prog_cc_c89} is set to @samp{no}. 6436 6437This macro is called automatically by @code{AC_PROG_CC}. 6438@end defmac 6439 6440@defmac AC_PROG_CC_C99 6441@acindex{PROG_CC_C99} 6442If the C compiler is not in C99 mode by default, try to add an 6443option to output variable @code{CC} to make it so. This macro tries 6444various options that select C99 on some system or another. It 6445considers the compiler to be in C99 mode if it handles @code{_Bool}, 6446@code{//} comments, flexible array members, @code{inline}, @code{long 6447long int}, mixed code and declarations, named initialization of structs, 6448@code{restrict}, @code{va_copy}, varargs macros, variable declarations 6449in @code{for} loops, and variable length arrays. 6450 6451After calling this macro you can check whether the C compiler has been 6452set to accept C99; if not, the shell variable 6453@code{ac_cv_prog_cc_c99} is set to @samp{no}. 6454@end defmac 6455 6456@defmac AC_C_BACKSLASH_A 6457@acindex{HAVE_C_BACKSLASH_A} 6458Define @samp{HAVE_C_BACKSLASH_A} to 1 if the C compiler understands 6459@samp{\a}. 6460 6461This macro is obsolescent, as current C compilers understand @samp{\a}. 6462New programs need not use this macro. 6463@end defmac 6464 6465@defmac AC_C_BIGENDIAN (@ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-unknown}) 6466@acindex{C_BIGENDIAN} 6467@cvindex WORDS_BIGENDIAN 6468@cindex Endianness 6469If words are stored with the most significant byte first (like Motorola 6470and SPARC CPUs), execute @var{action-if-true}. If words are stored with 6471the least significant byte first (like Intel and VAX CPUs), execute 6472@var{action-if-false}. 6473 6474This macro runs a test-case if endianness cannot be determined from the 6475system header files. When cross-compiling, the test-case is not run but 6476grep'ed for some magic values. @var{action-if-unknown} is executed if 6477the latter case fails to determine the byte sex of the host system. 6478 6479The default for @var{action-if-true} is to define 6480@samp{WORDS_BIGENDIAN}. The default for @var{action-if-false} is to do 6481nothing. And finally, the default for @var{action-if-unknown} is to 6482abort configure and tell the installer which variable he should preset 6483to bypass this test. 6484@end defmac 6485 6486@defmac AC_C_CONST 6487@acindex{C_CONST} 6488@cvindex const 6489If the C compiler does not fully support the @code{const} keyword, 6490define @code{const} to be empty. Some C compilers that do 6491not define @code{__STDC__} do support @code{const}; some compilers that 6492define @code{__STDC__} do not completely support @code{const}. Programs 6493can simply use @code{const} as if every C compiler supported it; for 6494those that don't, the makefile or configuration header file 6495defines it as empty. 6496 6497Occasionally installers use a C++ compiler to compile C code, typically 6498because they lack a C compiler. This causes problems with @code{const}, 6499because C and C++ treat @code{const} differently. For example: 6500 6501@example 6502const int foo; 6503@end example 6504 6505@noindent 6506is valid in C but not in C++. These differences unfortunately cannot be 6507papered over by defining @code{const} to be empty. 6508 6509If @command{autoconf} detects this situation, it leaves @code{const} alone, 6510as this generally yields better results in practice. However, using a 6511C++ compiler to compile C code is not recommended or supported, and 6512installers who run into trouble in this area should get a C compiler 6513like @acronym{GCC} to compile their C code. 6514 6515This macro is obsolescent, as current C compilers support @code{const}. 6516New programs need not use this macro. 6517@end defmac 6518 6519@defmac AC_C_RESTRICT 6520@acindex{C_RESTRICT} 6521@cvindex restrict 6522If the C compiler recognizes the @code{restrict} keyword, don't do anything. 6523If it recognizes only a variant spelling (@code{__restrict}, 6524@code{__restrict__}, or @code{_Restrict}), then define 6525@code{restrict} to that. 6526Otherwise, define @code{restrict} to be empty. 6527Thus, programs may simply use @code{restrict} as if every C compiler 6528supported it; for those that do not, the makefile 6529or configuration header defines it away. 6530 6531Although support in C++ for the @code{restrict} keyword is not 6532required, several C++ compilers do accept the keyword. 6533This macro works for them, too. 6534@end defmac 6535 6536@defmac AC_C_VOLATILE 6537@acindex{C_VOLATILE} 6538@cvindex volatile 6539If the C compiler does not understand the keyword @code{volatile}, 6540define @code{volatile} to be empty. Programs can simply use 6541@code{volatile} as if every C compiler supported it; for those that do 6542not, the makefile or configuration header defines it as 6543empty. 6544 6545If the correctness of your program depends on the semantics of 6546@code{volatile}, simply defining it to be empty does, in a sense, break 6547your code. However, given that the compiler does not support 6548@code{volatile}, you are at its mercy anyway. At least your 6549program compiles, when it wouldn't before. 6550@xref{Volatile Objects}, for more about @code{volatile}. 6551 6552In general, the @code{volatile} keyword is a standard C feature, so 6553you might expect that @code{volatile} is available only when 6554@code{__STDC__} is defined. However, Ultrix 4.3's native compiler does 6555support volatile, but does not define @code{__STDC__}. 6556 6557This macro is obsolescent, as current C compilers support @code{volatile}. 6558New programs need not use this macro. 6559@end defmac 6560 6561@defmac AC_C_INLINE 6562@acindex{C_INLINE} 6563@cvindex inline 6564If the C compiler supports the keyword @code{inline}, do nothing. 6565Otherwise define @code{inline} to @code{__inline__} or @code{__inline} 6566if it accepts one of those, otherwise define @code{inline} to be empty. 6567@end defmac 6568 6569@defmac AC_C_CHAR_UNSIGNED 6570@acindex{C_CHAR_UNSIGNED} 6571@cvindex __CHAR_UNSIGNED__ 6572If the C type @code{char} is unsigned, define @code{__CHAR_UNSIGNED__}, 6573unless the C compiler predefines it. 6574@end defmac 6575 6576@defmac AC_C_STRINGIZE 6577@acindex{C_STRINGIZE} 6578@cvindex HAVE_STRINGIZE 6579If the C preprocessor supports the stringizing operator, define 6580@code{HAVE_STRINGIZE}. The stringizing operator is @samp{#} and is 6581found in macros such as this: 6582 6583@example 6584#define x(y) #y 6585@end example 6586 6587This macro is obsolescent, as current C compilers support the 6588stringizing operator. New programs need not use this macro. 6589@end defmac 6590 6591@defmac AC_C_FLEXIBLE_ARRAY_MEMBER 6592@acindex{C_FLEXIBLE_ARRAY_MEMBER} 6593@cvindex FLEXIBLE_ARRAY_MEMBER 6594If the C compiler supports flexible array members, define 6595@code{FLEXIBLE_ARRAY_MEMBER} to nothing; otherwise define it to 1. 6596That way, a declaration like this: 6597 6598@example 6599struct s 6600 @{ 6601 size_t n_vals; 6602 double val[FLEXIBLE_ARRAY_MEMBER]; 6603 @}; 6604@end example 6605 6606@noindent 6607will let applications use the ``struct hack'' even with compilers that 6608do not support flexible array members. To allocate and use such an 6609object, you can use code like this: 6610 6611@example 6612size_t i; 6613size_t n = compute_value_count (); 6614struct s *p = 6615 malloc (offsetof (struct s, val) 6616 + n * sizeof (double)); 6617p->n_vals = n; 6618for (i = 0; i < n; i++) 6619 p->val[i] = compute_value (i); 6620@end example 6621@end defmac 6622 6623@defmac AC_C_VARARRAYS 6624@acindex{C_VARARRAYS} 6625@cvindex HAVE_C_VARARRAYS 6626If the C compiler supports variable-length arrays, define 6627@code{HAVE_C_VARRAYS}. A variable-length array is an array of automatic 6628storage duration whose length is determined at run time, when the array 6629is declared. 6630@end defmac 6631 6632@defmac AC_C_TYPEOF 6633@acindex{C_TYPEOF} 6634@cvindex HAVE_TYPEOF 6635@cvindex typeof 6636If the C compiler supports @acronym{GCC}'s @code{typeof} syntax either 6637directly or 6638through a different spelling of the keyword (e.g., @code{__typeof__}), 6639define @code{HAVE_TYPEOF}. If the support is available only through a 6640different spelling, define @code{typeof} to that spelling. 6641@end defmac 6642 6643@defmac AC_C_PROTOTYPES 6644@acindex{C_PROTOTYPES} 6645@cvindex PROTOTYPES 6646@cvindex __PROTOTYPES 6647@cvindex PARAMS 6648If function prototypes are understood by the compiler (as determined by 6649@code{AC_PROG_CC}), define @code{PROTOTYPES} and @code{__PROTOTYPES}. 6650Defining @code{__PROTOTYPES} is for the benefit of 6651header files that cannot use macros that infringe on user name space. 6652 6653This macro is obsolescent, as current C compilers support prototypes. 6654New programs need not use this macro. 6655@end defmac 6656 6657@defmac AC_PROG_GCC_TRADITIONAL 6658@acindex{PROG_GCC_TRADITIONAL} 6659@ovindex CC 6660Add @option{-traditional} to output variable @code{CC} if using the 6661@acronym{GNU} C compiler and @code{ioctl} does not work properly without 6662@option{-traditional}. That usually happens when the fixed header files 6663have not been installed on an old system. 6664 6665This macro is obsolescent, since current versions of the @acronym{GNU} C 6666compiler fix the header files automatically when installed. 6667@end defmac 6668 6669 6670@node C++ Compiler 6671@subsection C++ Compiler Characteristics 6672 6673 6674@defmac AC_PROG_CXX (@ovar{compiler-search-list}) 6675@acindex{PROG_CXX} 6676@ovindex CXX 6677@ovindex CXXFLAGS 6678Determine a C++ compiler to use. Check whether the environment variable 6679@code{CXX} or @code{CCC} (in that order) is set; if so, then set output 6680variable @code{CXX} to its value. 6681 6682Otherwise, if the macro is invoked without an argument, then search for 6683a C++ compiler under the likely names (first @code{g++} and @code{c++} 6684then other names). If none of those checks succeed, then as a last 6685resort set @code{CXX} to @code{g++}. 6686 6687This macro may, however, be invoked with an optional first argument 6688which, if specified, must be a blank-separated list of C++ compilers to 6689search for. This just gives the user an opportunity to specify an 6690alternative search list for the C++ compiler. For example, if you 6691didn't like the default order, then you could invoke @code{AC_PROG_CXX} 6692like this: 6693 6694@example 6695AC_PROG_CXX([gcc cl KCC CC cxx cc++ xlC aCC c++ g++]) 6696@end example 6697 6698If using the @acronym{GNU} C++ compiler, set shell variable @code{GXX} to 6699@samp{yes}. If output variable @code{CXXFLAGS} was not already set, set 6700it to @option{-g -O2} for the @acronym{GNU} C++ compiler (@option{-O2} on 6701systems where G++ does not accept @option{-g}), or @option{-g} for other 6702compilers. 6703@end defmac 6704 6705@defmac AC_PROG_CXXCPP 6706@acindex{PROG_CXXCPP} 6707@ovindex CXXCPP 6708Set output variable @code{CXXCPP} to a command that runs the C++ 6709preprocessor. If @samp{$CXX -E} doesn't work, @file{/lib/cpp} is used. 6710It is portable to run @code{CXXCPP} only on files with a @file{.c}, 6711@file{.C}, @file{.cc}, or @file{.cpp} extension. 6712 6713Some preprocessors don't indicate missing include files by the error 6714status. For such preprocessors an internal variable is set that causes 6715other macros to check the standard error from the preprocessor and 6716consider the test failed if any warnings have been reported. However, 6717it is not known whether such broken preprocessors exist for C++. 6718@end defmac 6719 6720@defmac AC_PROG_CXX_C_O 6721@acindex{PROG_CXX_C_O} 6722@cvindex CXX_NO_MINUS_C_MINUS_O 6723Test whether the C++ compiler accepts the options @option{-c} and 6724@option{-o} simultaneously, and define @code{CXX_NO_MINUS_C_MINUS_O}, 6725if it does not. 6726@end defmac 6727 6728 6729@node Objective C Compiler 6730@subsection Objective C Compiler Characteristics 6731 6732 6733@defmac AC_PROG_OBJC (@ovar{compiler-search-list}) 6734@acindex{PROG_OBJC} 6735@ovindex OBJC 6736@ovindex OBJCFLAGS 6737Determine an Objective C compiler to use. If @code{OBJC} is not already 6738set in the environment, check for Objective C compilers. Set output 6739variable @code{OBJC} to the name of the compiler found. 6740 6741This macro may, however, be invoked with an optional first argument 6742which, if specified, must be a blank-separated list of Objective C compilers to 6743search for. This just gives the user an opportunity to specify an 6744alternative search list for the Objective C compiler. For example, if you 6745didn't like the default order, then you could invoke @code{AC_PROG_OBJC} 6746like this: 6747 6748@example 6749AC_PROG_OBJC([gcc objcc objc]) 6750@end example 6751 6752If using the @acronym{GNU} Objective C compiler, set shell variable 6753@code{GOBJC} to @samp{yes}. If output variable @code{OBJCFLAGS} was not 6754already set, set it to @option{-g -O2} for the @acronym{GNU} Objective C 6755compiler (@option{-O2} on systems where @command{gcc} does not accept 6756@option{-g}), or @option{-g} for other compilers. 6757@end defmac 6758 6759@defmac AC_PROG_OBJCCPP 6760@acindex{PROG_OBJCCPP} 6761@ovindex OBJCCPP 6762Set output variable @code{OBJCCPP} to a command that runs the Objective C 6763preprocessor. If @samp{$OBJC -E} doesn't work, @file{/lib/cpp} is used. 6764@end defmac 6765 6766 6767@node Erlang Compiler and Interpreter 6768@subsection Erlang Compiler and Interpreter Characteristics 6769@cindex Erlang 6770 6771Autoconf defines the following macros for determining paths to the essential 6772Erlang/OTP programs: 6773 6774@defmac AC_ERLANG_PATH_ERLC (@ovar{value-if-not-found}, @ovar{path}) 6775@acindex{ERLANG_PATH_ERLC} 6776@ovindex ERLC 6777@ovindex ERLCFLAGS 6778Determine an Erlang compiler to use. If @code{ERLC} is not already set in the 6779environment, check for @command{erlc}. Set output variable @code{ERLC} to the 6780complete path of the compiler command found. In addition, if @code{ERLCFLAGS} 6781is not set in the environment, set it to an empty value. 6782 6783The two optional arguments have the same meaning as the two last arguments of 6784macro @code{AC_PROG_PATH} for looking for the @command{erlc} program. For 6785example, to look for @command{erlc} only in the @file{/usr/lib/erlang/bin} 6786directory: 6787 6788@example 6789AC_ERLANG_PATH_ERLC([not found], [/usr/lib/erlang/bin]) 6790@end example 6791@end defmac 6792 6793@defmac AC_ERLANG_NEED_ERLC (@ovar{path}) 6794@acindex{ERLANG_NEED_ERLC} 6795A simplified variant of the @code{AC_ERLANG_PATH_ERLC} macro, that prints an 6796error message and exits the @command{configure} script if the @command{erlc} 6797program is not found. 6798@end defmac 6799 6800@defmac AC_ERLANG_PATH_ERL (@ovar{value-if-not-found}, @ovar{path}) 6801@acindex{ERLANG_PATH_ERL} 6802@ovindex ERL 6803Determine an Erlang interpreter to use. If @code{ERL} is not already set in the 6804environment, check for @command{erl}. Set output variable @code{ERL} to the 6805complete path of the interpreter command found. 6806 6807The two optional arguments have the same meaning as the two last arguments of 6808macro @code{AC_PROG_PATH} for looking for the @command{erl} program. For 6809example, to look for @command{erl} only in the @file{/usr/lib/erlang/bin} 6810directory: 6811 6812@example 6813AC_ERLANG_PATH_ERL([not found], [/usr/lib/erlang/bin]) 6814@end example 6815@end defmac 6816 6817@defmac AC_ERLANG_NEED_ERL (@ovar{path}) 6818@acindex{ERLANG_NEED_ERL} 6819A simplified variant of the @code{AC_ERLANG_PATH_ERL} macro, that prints an 6820error message and exits the @command{configure} script if the @command{erl} 6821program is not found. 6822@end defmac 6823 6824 6825@node Fortran Compiler 6826@subsection Fortran Compiler Characteristics 6827@cindex Fortran 6828@cindex F77 6829 6830The Autoconf Fortran support is divided into two categories: legacy 6831Fortran 77 macros (@code{F77}), and modern Fortran macros (@code{FC}). 6832The former are intended for traditional Fortran 77 code, and have output 6833variables like @code{F77}, @code{FFLAGS}, and @code{FLIBS}. The latter 6834are for newer programs that can (or must) compile under the newer 6835Fortran standards, and have output variables like @code{FC}, 6836@code{FCFLAGS}, and @code{FCLIBS}. 6837 6838Except for two new macros @code{AC_FC_SRCEXT} and 6839@code{AC_FC_FREEFORM} (see below), the @code{FC} and @code{F77} macros 6840behave almost identically, and so they are documented together in this 6841section. 6842 6843 6844@defmac AC_PROG_F77 (@ovar{compiler-search-list}) 6845@acindex{PROG_F77} 6846@ovindex F77 6847@ovindex FFLAGS 6848Determine a Fortran 77 compiler to use. If @code{F77} is not already 6849set in the environment, then check for @code{g77} and @code{f77}, and 6850then some other names. Set the output variable @code{F77} to the name 6851of the compiler found. 6852 6853This macro may, however, be invoked with an optional first argument 6854which, if specified, must be a blank-separated list of Fortran 77 6855compilers to search for. This just gives the user an opportunity to 6856specify an alternative search list for the Fortran 77 compiler. For 6857example, if you didn't like the default order, then you could invoke 6858@code{AC_PROG_F77} like this: 6859 6860@example 6861AC_PROG_F77([fl32 f77 fort77 xlf g77 f90 xlf90]) 6862@end example 6863 6864If using @code{g77} (the @acronym{GNU} Fortran 77 compiler), then 6865set the shell variable @code{G77} to @samp{yes}. 6866If the output variable @code{FFLAGS} was not already set in the 6867environment, then set it to @option{-g -02} for @code{g77} (or @option{-O2} 6868where @code{g77} does not accept @option{-g}). Otherwise, set 6869@code{FFLAGS} to @option{-g} for all other Fortran 77 compilers. 6870@end defmac 6871 6872@defmac AC_PROG_FC (@ovar{compiler-search-list}, @ovar{dialect}) 6873@acindex{PROG_FC} 6874@ovindex FC 6875@ovindex FCFLAGS 6876Determine a Fortran compiler to use. If @code{FC} is not already set in 6877the environment, then @code{dialect} is a hint to indicate what Fortran 6878dialect to search for; the default is to search for the newest available 6879dialect. Set the output variable @code{FC} to the name of the compiler 6880found. 6881 6882By default, newer dialects are preferred over older dialects, but if 6883@code{dialect} is specified then older dialects are preferred starting 6884with the specified dialect. @code{dialect} can currently be one of 6885Fortran 77, Fortran 90, or Fortran 95. However, this is only a hint of 6886which compiler @emph{name} to prefer (e.g., @code{f90} or @code{f95}), 6887and no attempt is made to guarantee that a particular language standard 6888is actually supported. Thus, it is preferable that you avoid the 6889@code{dialect} option, and use AC_PROG_FC only for code compatible with 6890the latest Fortran standard. 6891 6892This macro may, alternatively, be invoked with an optional first argument 6893which, if specified, must be a blank-separated list of Fortran 6894compilers to search for, just as in @code{AC_PROG_F77}. 6895 6896If the output variable @code{FCFLAGS} was not already set in the 6897environment, then set it to @option{-g -02} for @acronym{GNU} @code{g77} (or 6898@option{-O2} where @code{g77} does not accept @option{-g}). Otherwise, 6899set @code{FCFLAGS} to @option{-g} for all other Fortran compilers. 6900@end defmac 6901 6902@defmac AC_PROG_F77_C_O 6903@defmacx AC_PROG_FC_C_O 6904@acindex{PROG_F77_C_O} 6905@acindex{PROG_FC_C_O} 6906@cvindex F77_NO_MINUS_C_MINUS_O 6907@cvindex FC_NO_MINUS_C_MINUS_O 6908Test whether the Fortran compiler accepts the options @option{-c} and 6909@option{-o} simultaneously, and define @code{F77_NO_MINUS_C_MINUS_O} or 6910@code{FC_NO_MINUS_C_MINUS_O}, respectively, if it does not. 6911@end defmac 6912 6913The following macros check for Fortran compiler characteristics. 6914To check for characteristics not listed here, use 6915@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}) or 6916@code{AC_RUN_IFELSE} (@pxref{Runtime}), making sure to first set the 6917current language to Fortran 77 or Fortran via @code{AC_LANG([Fortran 77])} 6918or @code{AC_LANG(Fortran)} (@pxref{Language Choice}). 6919 6920 6921@defmac AC_F77_LIBRARY_LDFLAGS 6922@defmacx AC_FC_LIBRARY_LDFLAGS 6923@acindex{F77_LIBRARY_LDFLAGS} 6924@ovindex FLIBS 6925@acindex{FC_LIBRARY_LDFLAGS} 6926@ovindex FCLIBS 6927Determine the linker flags (e.g., @option{-L} and @option{-l}) for the 6928@dfn{Fortran intrinsic and runtime libraries} that are required to 6929successfully link a Fortran program or shared library. The output 6930variable @code{FLIBS} or @code{FCLIBS} is set to these flags (which 6931should be included after @code{LIBS} when linking). 6932 6933This macro is intended to be used in those situations when it is 6934necessary to mix, e.g., C++ and Fortran source code in a single 6935program or shared library (@pxref{Mixing Fortran 77 With C and C++, , , 6936automake, @acronym{GNU} Automake}). 6937 6938For example, if object files from a C++ and Fortran compiler must be 6939linked together, then the C++ compiler/linker must be used for linking 6940(since special C++-ish things need to happen at link time like calling 6941global constructors, instantiating templates, enabling exception 6942support, etc.). 6943 6944However, the Fortran intrinsic and runtime libraries must be linked in 6945as well, but the C++ compiler/linker doesn't know by default how to add 6946these Fortran 77 libraries. Hence, this macro was created to determine 6947these Fortran libraries. 6948 6949The macros @code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 6950@code{AC_F77_MAIN} and @code{AC_FC_MAIN} are probably also necessary to 6951link C/C++ with Fortran; see below. 6952@end defmac 6953 6954@defmac AC_F77_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found}) 6955@defmacx AC_FC_DUMMY_MAIN (@ovar{action-if-found}, @ovar{action-if-not-found}) 6956@acindex{F77_DUMMY_MAIN} 6957@cvindex F77_DUMMY_MAIN 6958With many compilers, the Fortran libraries detected by 6959@code{AC_F77_LIBRARY_LDFLAGS} or @code{AC_FC_LIBRARY_LDFLAGS} provide 6960their own @code{main} entry function that initializes things like 6961Fortran I/O, and which then calls a user-provided entry function named 6962(say) @code{MAIN__} to run the user's program. The 6963@code{AC_F77_DUMMY_MAIN} and @code{AC_FC_DUMMY_MAIN} or 6964@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros figure out how to deal with 6965this interaction. 6966 6967When using Fortran for purely numerical functions (no I/O, etc.)@: often 6968one prefers to provide one's own @code{main} and skip the Fortran 6969library initializations. In this case, however, one may still need to 6970provide a dummy @code{MAIN__} routine in order to prevent linking errors 6971on some systems. @code{AC_F77_DUMMY_MAIN} or @code{AC_FC_DUMMY_MAIN} 6972detects whether any such routine is @emph{required} for linking, and 6973what its name is; the shell variable @code{F77_DUMMY_MAIN} or 6974@code{FC_DUMMY_MAIN} holds this name, @code{unknown} when no solution 6975was found, and @code{none} when no such dummy main is needed. 6976 6977By default, @var{action-if-found} defines @code{F77_DUMMY_MAIN} or 6978@code{FC_DUMMY_MAIN} to the name of this routine (e.g., @code{MAIN__}) 6979@emph{if} it is required. @var{action-if-not-found} defaults to 6980exiting with an error. 6981 6982In order to link with Fortran routines, the user's C/C++ program should 6983then include the following code to define the dummy main if it is 6984needed: 6985 6986@example 6987#ifdef F77_DUMMY_MAIN 6988# ifdef __cplusplus 6989 extern "C" 6990# endif 6991 int F77_DUMMY_MAIN() @{ return 1; @} 6992#endif 6993@end example 6994 6995(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 6996 6997Note that this macro is called automatically from @code{AC_F77_WRAPPERS} 6998or @code{AC_FC_WRAPPERS}; there is generally no need to call it 6999explicitly unless one wants to change the default actions. 7000@end defmac 7001 7002@defmac AC_F77_MAIN 7003@defmacx AC_FC_MAIN 7004@acindex{F77_MAIN} 7005@cvindex F77_MAIN 7006@acindex{FC_MAIN} 7007@cvindex FC_MAIN 7008As discussed above, many Fortran libraries allow you to provide an entry 7009point called (say) @code{MAIN__} instead of the usual @code{main}, which 7010is then called by a @code{main} function in the Fortran libraries that 7011initializes things like Fortran I/O@. The 7012@code{AC_F77_MAIN} and @code{AC_FC_MAIN} macros detect whether it is 7013@emph{possible} to utilize such an alternate main function, and defines 7014@code{F77_MAIN} and @code{FC_MAIN} to the name of the function. (If no 7015alternate main function name is found, @code{F77_MAIN} and @code{FC_MAIN} are 7016simply defined to @code{main}.) 7017 7018Thus, when calling Fortran routines from C that perform things like I/O, 7019one should use this macro and name the "main" function 7020@code{F77_MAIN} or @code{FC_MAIN} instead of @code{main}. 7021@end defmac 7022 7023@defmac AC_F77_WRAPPERS 7024@defmacx AC_FC_WRAPPERS 7025@acindex{F77_WRAPPERS} 7026@cvindex F77_FUNC 7027@cvindex F77_FUNC_ 7028@acindex{FC_WRAPPERS} 7029@cvindex FC_FUNC 7030@cvindex FC_FUNC_ 7031Defines C macros @code{F77_FUNC (name, NAME)}, @code{FC_FUNC (name, NAME)}, 7032@code{F77_FUNC_(name, NAME)}, and @code{FC_FUNC_(name, NAME)} to properly 7033mangle the names of C/C++ identifiers, and identifiers with underscores, 7034respectively, so that they match the name-mangling scheme used by the 7035Fortran compiler. 7036 7037Fortran is case-insensitive, and in order to achieve this the Fortran 7038compiler converts all identifiers into a canonical case and format. To 7039call a Fortran subroutine from C or to write a C function that is 7040callable from Fortran, the C program must explicitly use identifiers in 7041the format expected by the Fortran compiler. In order to do this, one 7042simply wraps all C identifiers in one of the macros provided by 7043@code{AC_F77_WRAPPERS} or @code{AC_FC_WRAPPERS}. For example, suppose 7044you have the following Fortran 77 subroutine: 7045 7046@example 7047 subroutine foobar (x, y) 7048 double precision x, y 7049 y = 3.14159 * x 7050 return 7051 end 7052@end example 7053 7054You would then declare its prototype in C or C++ as: 7055 7056@example 7057#define FOOBAR_F77 F77_FUNC (foobar, FOOBAR) 7058#ifdef __cplusplus 7059extern "C" /* prevent C++ name mangling */ 7060#endif 7061void FOOBAR_F77(double *x, double *y); 7062@end example 7063 7064Note that we pass both the lowercase and uppercase versions of the 7065function name to @code{F77_FUNC} so that it can select the right one. 7066Note also that all parameters to Fortran 77 routines are passed as 7067pointers (@pxref{Mixing Fortran 77 With C and C++, , , automake, @acronym{GNU} 7068Automake}). 7069 7070(Replace @code{F77} with @code{FC} for Fortran instead of Fortran 77.) 7071 7072Although Autoconf tries to be intelligent about detecting the 7073name-mangling scheme of the Fortran compiler, there may be Fortran 7074compilers that it doesn't support yet. In this case, the above code 7075generates a compile-time error, but some other behavior 7076(e.g., disabling Fortran-related features) can be induced by checking 7077whether @code{F77_FUNC} or @code{FC_FUNC} is defined. 7078 7079Now, to call that routine from a C program, we would do something like: 7080 7081@example 7082@{ 7083 double x = 2.7183, y; 7084 FOOBAR_F77 (&x, &y); 7085@} 7086@end example 7087 7088If the Fortran identifier contains an underscore (e.g., @code{foo_bar}), 7089you should use @code{F77_FUNC_} or @code{FC_FUNC_} instead of 7090@code{F77_FUNC} or @code{FC_FUNC} (with the same arguments). This is 7091because some Fortran compilers mangle names differently if they contain 7092an underscore. 7093@end defmac 7094 7095@defmac AC_F77_FUNC (@var{name}, @ovar{shellvar}) 7096@defmacx AC_FC_FUNC (@var{name}, @ovar{shellvar}) 7097@acindex{F77_FUNC} 7098@acindex{FC_FUNC} 7099Given an identifier @var{name}, set the shell variable @var{shellvar} to 7100hold the mangled version @var{name} according to the rules of the 7101Fortran linker (see also @code{AC_F77_WRAPPERS} or 7102@code{AC_FC_WRAPPERS}). @var{shellvar} is optional; if it is not 7103supplied, the shell variable is simply @var{name}. The purpose of 7104this macro is to give the caller a way to access the name-mangling 7105information other than through the C preprocessor as above, for example, 7106to call Fortran routines from some language other than C/C++. 7107@end defmac 7108 7109@defmac AC_FC_SRCEXT (@var{ext}, @ovar{action-if-success}, @ovar{action-if-failure}) 7110@acindex{FC_SRCEXT} 7111By default, the @code{FC} macros perform their tests using a @file{.f} 7112extension for source-code files. Some compilers, however, only enable 7113newer language features for appropriately named files, e.g., Fortran 90 7114features only for @file{.f90} files. On the other hand, some other 7115compilers expect all source files to end in @file{.f} and require 7116special flags to support other file name extensions. The 7117@code{AC_FC_SRCEXT} macro deals with both of these issues. 7118 7119The @code{AC_FC_SRCEXT} tries to get the @code{FC} compiler to accept files 7120ending with the extension .@var{ext} (i.e., @var{ext} does @emph{not} 7121contain the dot). If any special compiler flags are needed for this, it 7122stores them in the output variable @code{FCFLAGS_}@var{ext}. This 7123extension and these flags are then used for all subsequent @code{FC} tests 7124(until @code{AC_FC_SRCEXT} is called again). 7125 7126For example, you would use @code{AC_FC_SRCEXT(f90)} to employ the 7127@file{.f90} extension in future tests, and it would set a 7128@code{FCFLAGS_f90} output variable with any extra flags that are needed 7129to compile such files. 7130 7131The @code{FCFLAGS_}@var{ext} can @emph{not} be simply absorbed into 7132@code{FCFLAGS}, for two reasons based on the limitations of some 7133compilers. First, only one @code{FCFLAGS_}@var{ext} can be used at a 7134time, so files with different extensions must be compiled separately. 7135Second, @code{FCFLAGS_}@var{ext} must appear @emph{immediately} before 7136the source-code file name when compiling. So, continuing the example 7137above, you might compile a @file{foo.f90} file in your makefile with the 7138command: 7139 7140@example 7141foo.o: foo.f90 7142 $(FC) -c $(FCFLAGS) $(FCFLAGS_f90) '$(srcdir)/foo.f90' 7143@end example 7144 7145If @code{AC_FC_SRCEXT} succeeds in compiling files with the @var{ext} 7146extension, it calls @var{action-if-success} (defaults to nothing). If 7147it fails, and cannot find a way to make the @code{FC} compiler accept such 7148files, it calls @var{action-if-failure} (defaults to exiting with an 7149error message). 7150 7151@end defmac 7152 7153@defmac AC_FC_FREEFORM (@ovar{action-if-success}, @ovar{action-if-failure}) 7154@acindex{FC_FREEFORM} 7155 7156The @code{AC_FC_FREEFORM} tries to ensure that the Fortran compiler 7157(@code{$FC}) allows free-format source code (as opposed to the older 7158fixed-format style from Fortran 77). If necessary, it may add some 7159additional flags to @code{FCFLAGS}. 7160 7161This macro is most important if you are using the default @file{.f} 7162extension, since many compilers interpret this extension as indicating 7163fixed-format source unless an additional flag is supplied. If you 7164specify a different extension with @code{AC_FC_SRCEXT}, such as 7165@file{.f90} or @file{.f95}, then @code{AC_FC_FREEFORM} ordinarily 7166succeeds without modifying @code{FCFLAGS}. 7167 7168If @code{AC_FC_FREEFORM} succeeds in compiling free-form source, it 7169calls @var{action-if-success} (defaults to nothing). If it fails, it 7170calls @var{action-if-failure} (defaults to exiting with an error 7171message). 7172@end defmac 7173 7174@node System Services 7175@section System Services 7176 7177The following macros check for operating system services or capabilities. 7178 7179@defmac AC_PATH_X 7180@acindex{PATH_X} 7181@evindex XMKMF 7182@cindex X Window System 7183Try to locate the X Window System include files and libraries. If the 7184user gave the command line options @option{--x-includes=@var{dir}} and 7185@option{--x-libraries=@var{dir}}, use those directories. 7186 7187If either or both were not given, get the missing values by running 7188@code{xmkmf} (or an executable pointed to by the @code{XMKMF} 7189environment variable) on a trivial @file{Imakefile} and examining the 7190makefile that it produces. Setting @code{XMKMF} to @samp{false} 7191disables this method. 7192 7193If this method fails to find the X Window System, @command{configure} 7194looks for the files in several directories where they often reside. 7195If either method is successful, set the shell variables 7196@code{x_includes} and @code{x_libraries} to their locations, unless they 7197are in directories the compiler searches by default. 7198 7199If both methods fail, or the user gave the command line option 7200@option{--without-x}, set the shell variable @code{no_x} to @samp{yes}; 7201otherwise set it to the empty string. 7202@end defmac 7203 7204@defmac AC_PATH_XTRA 7205@acindex{PATH_XTRA} 7206@ovindex X_CFLAGS 7207@ovindex X_LIBS 7208@ovindex X_EXTRA_LIBS 7209@ovindex X_PRE_LIBS 7210@cvindex X_DISPLAY_MISSING 7211An enhanced version of @code{AC_PATH_X}. It adds the C compiler flags 7212that X needs to output variable @code{X_CFLAGS}, and the X linker flags 7213to @code{X_LIBS}. Define @code{X_DISPLAY_MISSING} if X is not 7214available. 7215 7216This macro also checks for special libraries that some systems need in 7217order to compile X programs. It adds any that the system needs to 7218output variable @code{X_EXTRA_LIBS}. And it checks for special X11R6 7219libraries that need to be linked with before @option{-lX11}, and adds 7220any found to the output variable @code{X_PRE_LIBS}. 7221 7222@c This is an incomplete kludge. Make a real way to do it. 7223@c If you need to check for other X functions or libraries yourself, then 7224@c after calling this macro, add the contents of @code{X_EXTRA_LIBS} to 7225@c @code{LIBS} temporarily, like this: (FIXME - add example) 7226@end defmac 7227 7228@defmac AC_SYS_INTERPRETER 7229@acindex{SYS_INTERPRETER} 7230Check whether the system supports starting scripts with a line of the 7231form @samp{#!/bin/sh} to select the interpreter to use for the script. 7232After running this macro, shell code in @file{configure.ac} can check 7233the shell variable @code{interpval}; it is set to @samp{yes} 7234if the system supports @samp{#!}, @samp{no} if not. 7235@end defmac 7236 7237@defmac AC_SYS_LARGEFILE 7238@acindex{SYS_LARGEFILE} 7239@cvindex _FILE_OFFSET_BITS 7240@cvindex _LARGE_FILES 7241@ovindex CC 7242@cindex Large file support 7243@cindex LFS 7244Arrange for 7245@uref{http://www.unix-systems.org/@/version2/@/whatsnew/@/lfs20mar.html, 7246large-file support}. On some hosts, one must use special compiler 7247options to build programs that can access large files. Append any such 7248options to the output variable @code{CC}. Define 7249@code{_FILE_OFFSET_BITS} and @code{_LARGE_FILES} if necessary. 7250 7251Large-file support can be disabled by configuring with the 7252@option{--disable-largefile} option. 7253 7254If you use this macro, check that your program works even when 7255@code{off_t} is wider than @code{long int}, since this is common when 7256large-file support is enabled. For example, it is not correct to print 7257an arbitrary @code{off_t} value @code{X} with @code{printf ("%ld", 7258(long int) X)}. 7259 7260The LFS introduced the @code{fseeko} and @code{ftello} functions to 7261replace their C counterparts @code{fseek} and @code{ftell} that do not 7262use @code{off_t}. Take care to use @code{AC_FUNC_FSEEKO} to make their 7263prototypes available when using them and large-file support is 7264enabled. 7265@end defmac 7266 7267@defmac AC_SYS_LONG_FILE_NAMES 7268@acindex{SYS_LONG_FILE_NAMES} 7269@cvindex HAVE_LONG_FILE_NAMES 7270If the system supports file names longer than 14 characters, define 7271@code{HAVE_LONG_FILE_NAMES}. 7272@end defmac 7273 7274@defmac AC_SYS_POSIX_TERMIOS 7275@acindex{SYS_POSIX_TERMIOS} 7276@cindex Posix termios headers 7277@cindex termios Posix headers 7278Check to see if the Posix termios headers and functions are available on the 7279system. If so, set the shell variable @code{ac_cv_sys_posix_termios} to 7280@samp{yes}. If not, set the variable to @samp{no}. 7281@end defmac 7282 7283@node Posix Variants 7284@section Posix Variants 7285 7286The following macros check for certain operating systems that need 7287special treatment for some programs, due to exceptional oddities in 7288their header files or libraries. These macros are warts; they will be 7289replaced by a more systematic approach, based on the functions they make 7290available or the environments they provide. 7291 7292@defmac AC_AIX 7293@acindex{AIX} 7294@cvindex _ALL_SOURCE 7295If on @acronym{AIX}, define @code{_ALL_SOURCE}. 7296Allows the use of some @acronym{BSD} 7297functions. Should be called before any macros that run the C compiler. 7298@end defmac 7299 7300@defmac AC_GNU_SOURCE 7301@acindex{GNU_SOURCE} 7302@cvindex _GNU_SOURCE 7303If using the @acronym{GNU} C library, define @code{_GNU_SOURCE}. 7304Allows the use of some @acronym{GNU} functions. Should be called 7305before any macros that run the C compiler. 7306@end defmac 7307 7308@defmac AC_ISC_POSIX 7309@acindex{ISC_POSIX} 7310@ovindex LIBS 7311For @sc{interactive} Systems Corporation Unix, add @option{-lcposix} to output 7312variable @code{LIBS} if necessary for Posix facilities. Call this 7313after @code{AC_PROG_CC} and before any other macros that use Posix 7314interfaces. 7315 7316This macro is obsolescent, as @sc{interactive} Unix is obsolete, and Sun 7317dropped support for it on 2006-07-23. New programs need not use this 7318macro. 7319@end defmac 7320 7321@defmac AC_MINIX 7322@acindex{MINIX} 7323@cvindex _MINIX 7324@cvindex _POSIX_SOURCE 7325@cvindex _POSIX_1_SOURCE 7326If on Minix, define @code{_MINIX} and @code{_POSIX_SOURCE} and define 7327@code{_POSIX_1_SOURCE} to be 2. This allows the use of Posix 7328facilities. Should be called before any macros that run the C compiler. 7329@end defmac 7330 7331@defmac AC_USE_SYSTEM_EXTENSIONS 7332@acindex{USE_SYSTEM_EXTENSIONS} 7333@cvindex _ALL_SOURCE 7334@cvindex _GNU_SOURCE 7335@cvindex _MINIX 7336@cvindex _POSIX_1_SOURCE 7337@cvindex _POSIX_PTHREAD_SEMANTICS 7338@cvindex _POSIX_SOURCE 7339@cvindex _TANDEM_SOURCE 7340@cvindex __EXTENSIONS__ 7341If possible, enable extensions to Posix on hosts that normally disable 7342the extensions, typically due to standards-conformance namespace issues. 7343This may involve defining @code{__EXTENSIONS__} and 7344@code{_POSIX_PTHREAD_SEMANTICS}, which are macros used by Solaris. 7345It also defines @code{_TANDEM_SOURCE} for the @acronym{HP} NonStop platform. 7346This macro also has the combined effects of @code{AC_GNU_SOURCE}, 7347@code{AC_AIX}, and @code{AC_MINIX}. 7348@end defmac 7349 7350 7351@node Erlang Libraries 7352@section Erlang Libraries 7353@cindex Erlang, Library, checking 7354 7355The following macros check for an installation of Erlang/OTP, and for the 7356presence of certain Erlang libraries. All those macros require the 7357configuration of an Erlang interpreter and an Erlang compiler 7358(@pxref{Erlang Compiler and Interpreter}). 7359 7360@defmac AC_ERLANG_SUBST_ROOT_DIR 7361@acindex{ERLANG_SUBST_ROOT_DIR} 7362@ovindex ERLANG_ROOT_DIR 7363 7364Set the output variable @code{ERLANG_ROOT_DIR} to the path to the base directory 7365in which Erlang/OTP is installed (as returned by Erlang's @code{code:root_dir/0} 7366function). The result of this test is cached if caching is enabled when running 7367@command{configure}. 7368@end defmac 7369 7370@defmac AC_ERLANG_SUBST_LIB_DIR 7371@acindex{ERLANG_SUBST_LIB_DIR} 7372@ovindex ERLANG_LIB_DIR 7373 7374Set the output variable @code{ERLANG_LIB_DIR} to the path of the library 7375directory of Erlang/OTP (as returned by Erlang's 7376@code{code:lib_dir/0} function), which subdirectories each contain an installed 7377Erlang/OTP library. The result of this test is cached if caching is enabled 7378when running @command{configure}. 7379@end defmac 7380 7381@defmac AC_ERLANG_CHECK_LIB (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}) 7382@acindex{ERLANG_CHECK_LIB} 7383@ovindex ERLANG_LIB_DIR_@var{library} 7384@ovindex ERLANG_LIB_VER_@var{library} 7385 7386Test whether the Erlang/OTP library @var{library} is installed by 7387calling Erlang's @code{code:lib_dir/1} function. The result of this 7388test is cached if caching is enabled when running @command{configure}. 7389@var{action-if-found} is a list of shell commands to run if the library 7390is installed; @var{action-if-not-found} is a list of shell commands to 7391run if it is not. Additionally, if the library is installed, the output 7392variable @samp{ERLANG_LIB_DIR_@var{library}} is set to the path to the 7393library installation directory, and the output variable 7394@samp{ERLANG_LIB_VER_@var{library}} is set to the version number that is 7395part of the subdirectory name, if it is in the standard form 7396(@code{@var{library}-@var{version}}). If the directory name does not 7397have a version part, @samp{ERLANG_LIB_VER_@var{library}} is set to the 7398empty string. If the library is not installed, 7399@samp{ERLANG_LIB_DIR_@var{library}} and 7400@samp{ERLANG_LIB_VER_@var{library}} are set to @code{"not found"}. For 7401example, to check if library @code{stdlib} is installed: 7402 7403@example 7404AC_ERLANG_CHECK_LIB([stdlib], 7405 [echo "stdlib version \"$ERLANG_LIB_VER_stdlib\"" 7406 echo "is installed in \"$ERLANG_LIB_DIR_stdlib\""], 7407 [AC_MSG_ERROR([stdlib was not found!])]) 7408@end example 7409@end defmac 7410 7411In addition to the above macros, which test installed Erlang libraries, the 7412following macros determine the paths to the directories into which newly built 7413Erlang libraries are to be installed: 7414 7415@defmac AC_ERLANG_SUBST_INSTALL_LIB_DIR 7416@acindex{ERLANG_SUBST_INSTALL_LIB_DIR} 7417@ovindex ERLANG_INSTALL_LIB_DIR 7418 7419Set the @code{ERLANG_INSTALL_LIB_DIR} output variable to the directory into 7420which every built Erlang library should be installed in a separate subdirectory. 7421If this variable is not set in the environment when @command{configure} runs, 7422its default value is @code{$ERLANG_LIB_DIR}, which value is set by the 7423@code{AC_ERLANG_SUBST_LIB_DIR} macro. 7424@end defmac 7425 7426@defmac AC_ERLANG_SUBST_INSTALL_LIB_SUBDIR (@var{library}, @var{version}) 7427@acindex{ERLANG_SUBST_INSTALL_LIB_SUBDIR} 7428@ovindex ERLANG_INSTALL_LIB_DIR_@var{library} 7429 7430Set the @samp{ERLANG_INSTALL_LIB_DIR_@var{library}} output variable to the 7431directory into which the built Erlang library @var{library} version 7432@var{version} should be installed. If this variable is not set in the 7433environment when @command{configure} runs, its default value is 7434@samp{$ERLANG_INSTALL_LIB_DIR/@var{library}-@var{version}}, the value of the 7435@code{ERLANG_INSTALL_LIB_DIR} variable being set by the 7436@code{AC_ERLANG_SUBST_INSTALL_LIB_DIR} macro. 7437@end defmac 7438 7439 7440 7441 7442 7443@c ========================================================= Writing Tests 7444 7445@node Writing Tests 7446@chapter Writing Tests 7447 7448If the existing feature tests don't do something you need, you have to 7449write new ones. These macros are the building blocks. They provide 7450ways for other macros to check whether various kinds of features are 7451available and report the results. 7452 7453This chapter contains some suggestions and some of the reasons why the 7454existing tests are written the way they are. You can also learn a lot 7455about how to write Autoconf tests by looking at the existing ones. If 7456something goes wrong in one or more of the Autoconf tests, this 7457information can help you understand the assumptions behind them, which 7458might help you figure out how to best solve the problem. 7459 7460These macros check the output of the compiler system of the current 7461language (@pxref{Language Choice}). They do not cache the results of 7462their tests for future use (@pxref{Caching Results}), because they don't 7463know enough about the information they are checking for to generate a 7464cache variable name. They also do not print any messages, for the same 7465reason. The checks for particular kinds of features call these macros 7466and do cache their results and print messages about what they're 7467checking for. 7468 7469When you write a feature test that could be applicable to more than one 7470software package, the best thing to do is encapsulate it in a new macro. 7471@xref{Writing Autoconf Macros}, for how to do that. 7472 7473@menu 7474* Language Choice:: Selecting which language to use for testing 7475* Writing Test Programs:: Forging source files for compilers 7476* Running the Preprocessor:: Detecting preprocessor symbols 7477* Running the Compiler:: Detecting language or header features 7478* Running the Linker:: Detecting library features 7479* Runtime:: Testing for runtime features 7480* Systemology:: A zoology of operating systems 7481* Multiple Cases:: Tests for several possible values 7482@end menu 7483 7484@node Language Choice 7485@section Language Choice 7486@cindex Language 7487 7488Autoconf-generated @command{configure} scripts check for the C compiler and 7489its features by default. Packages that use other programming languages 7490(maybe more than one, e.g., C and C++) need to test features of the 7491compilers for the respective languages. The following macros determine 7492which programming language is used in the subsequent tests in 7493@file{configure.ac}. 7494 7495@defmac AC_LANG (@var{language}) 7496Do compilation tests using the compiler, preprocessor, and file 7497extensions for the specified @var{language}. 7498 7499Supported languages are: 7500 7501@table @samp 7502@item C 7503Do compilation tests using @code{CC} and @code{CPP} and use extension 7504@file{.c} for test programs. Use compilation flags: @code{CPPFLAGS} with 7505@code{CPP}, and both @code{CPPFLAGS} and @code{CFLAGS} with @code{CC}. 7506 7507@item C++ 7508Do compilation tests using @code{CXX} and @code{CXXCPP} and use 7509extension @file{.C} for test programs. Use compilation flags: 7510@code{CPPFLAGS} with @code{CXXPP}, and both @code{CPPFLAGS} and 7511@code{CXXFLAGS} with @code{CXX}. 7512 7513@item Fortran 77 7514Do compilation tests using @code{F77} and use extension @file{.f} for 7515test programs. Use compilation flags: @code{FFLAGS}. 7516 7517@item Fortran 7518Do compilation tests using @code{FC} and use extension @file{.f} (or 7519whatever has been set by @code{AC_FC_SRCEXT}) for test programs. Use 7520compilation flags: @code{FCFLAGS}. 7521 7522@item Erlang 7523@ovindex ERLC 7524@ovindex ERL 7525@ovindex ERLCFLAGS 7526Compile and execute tests using @code{ERLC} and @code{ERL} and use extension 7527@file{.erl} for test Erlang modules. Use compilation flags: @code{ERLCFLAGS}. 7528 7529@item Objective C 7530Do compilation tests using @code{OBJC} and @code{OBJCCPP} and use 7531extension @file{.m} for test programs. Use compilation flags: 7532@code{CPPFLAGS} with @code{OBJCPP}, and both @code{CPPFLAGS} and 7533@code{OBJCFLAGS} with @code{OBJC}. 7534@end table 7535@end defmac 7536 7537@defmac AC_LANG_PUSH (@var{language}) 7538@acindex{LANG_PUSH} 7539Remember the current language (as set by @code{AC_LANG}) on a stack, and 7540then select the @var{language}. Use this macro and @code{AC_LANG_POP} 7541in macros that need to temporarily switch to a particular language. 7542@end defmac 7543 7544@defmac AC_LANG_POP (@ovar{language}) 7545@acindex{LANG_POP} 7546Select the language that is saved on the top of the stack, as set by 7547@code{AC_LANG_PUSH}, and remove it from the stack. 7548 7549If given, @var{language} specifies the language we just @emph{quit}. It 7550is a good idea to specify it when it's known (which should be the 7551case@dots{}), since Autoconf detects inconsistencies. 7552 7553@example 7554AC_LANG_PUSH([Fortran 77]) 7555# Perform some tests on Fortran 77. 7556# @dots{} 7557AC_LANG_POP([Fortran 77]) 7558@end example 7559@end defmac 7560 7561@defmac AC_LANG_ASSERT (@var{language}) 7562@acindex{LANG_ASSERT} Check statically that the current language is 7563@var{language}. You should use this in your language specific macros 7564to avoid that they be called with an inappropriate language. 7565 7566This macro runs only at @command{autoconf} time, and incurs no cost at 7567@command{configure} time. Sadly enough and because Autoconf is a two 7568layer language @footnote{Because M4 is not aware of Sh code, 7569especially conditionals, some optimizations that look nice statically 7570may produce incorrect results at runtime.}, the macros 7571@code{AC_LANG_PUSH} and @code{AC_LANG_POP} cannot be ``optimizing'', 7572therefore as much as possible you ought to avoid using them to wrap 7573your code, rather, require from the user to run the macro with a 7574correct current language, and check it with @code{AC_LANG_ASSERT}. 7575And anyway, that may help the user understand she is running a Fortran 7576macro while expecting a result about her Fortran 77 compiler@dots{} 7577@end defmac 7578 7579 7580@defmac AC_REQUIRE_CPP 7581@acindex{REQUIRE_CPP} 7582Ensure that whichever preprocessor would currently be used for tests has 7583been found. Calls @code{AC_REQUIRE} (@pxref{Prerequisite Macros}) with an 7584argument of either @code{AC_PROG_CPP} or @code{AC_PROG_CXXCPP}, 7585depending on which language is current. 7586@end defmac 7587 7588 7589@node Writing Test Programs 7590@section Writing Test Programs 7591 7592Autoconf tests follow a common scheme: feed some program with some 7593input, and most of the time, feed a compiler with some source file. 7594This section is dedicated to these source samples. 7595 7596@menu 7597* Guidelines:: General rules for writing test programs 7598* Test Functions:: Avoiding pitfalls in test programs 7599* Generating Sources:: Source program boilerplate 7600@end menu 7601 7602@node Guidelines 7603@subsection Guidelines for Test Programs 7604 7605The most important rule to follow when writing testing samples is: 7606 7607@center @emph{Look for realism.} 7608 7609This motto means that testing samples must be written with the same 7610strictness as real programs are written. In particular, you should 7611avoid ``shortcuts'' and simplifications. 7612 7613Don't just play with the preprocessor if you want to prepare a 7614compilation. For instance, using @command{cpp} to check whether a header is 7615functional might let your @command{configure} accept a header which 7616causes some @emph{compiler} error. Do not hesitate to check a header with 7617other headers included before, especially required headers. 7618 7619Make sure the symbols you use are properly defined, i.e., refrain for 7620simply declaring a function yourself instead of including the proper 7621header. 7622 7623Test programs should not write to standard output. They 7624should exit with status 0 if the test succeeds, and with status 1 7625otherwise, so that success 7626can be distinguished easily from a core dump or other failure; 7627segmentation violations and other failures produce a nonzero exit 7628status. Unless you arrange for @code{exit} to be declared, test 7629programs should @code{return}, not @code{exit}, from @code{main}, 7630because on many systems @code{exit} is not declared by default. 7631 7632Test programs can use @code{#if} or @code{#ifdef} to check the values of 7633preprocessor macros defined by tests that have already run. For 7634example, if you call @code{AC_HEADER_STDBOOL}, then later on in 7635@file{configure.ac} you can have a test program that includes 7636@file{stdbool.h} conditionally: 7637 7638@example 7639@group 7640#ifdef HAVE_STDBOOL_H 7641# include <stdbool.h> 7642#endif 7643@end group 7644@end example 7645 7646Both @code{#if HAVE_STDBOOL_H} and @code{#ifdef HAVE_STDBOOL_H} will 7647work with any standard C compiler. Some developers prefer @code{#if} 7648because it is easier to read, while others prefer @code{#ifdef} because 7649it avoids diagnostics with picky compilers like @acronym{GCC} with the 7650@option{-Wundef} option. 7651 7652If a test program needs to use or create a data file, give it a name 7653that starts with @file{conftest}, such as @file{conftest.data}. The 7654@command{configure} script cleans up by running @samp{rm -f -r conftest*} 7655after running test programs and if the script is interrupted. 7656 7657@node Test Functions 7658@subsection Test Functions 7659 7660These days it's safe to assume support for function prototypes 7661(introduced in C89). 7662 7663Functions that test programs declare should also be conditionalized for 7664C++, which requires @samp{extern "C"} prototypes. Make sure to not 7665include any header files containing clashing prototypes. 7666 7667@example 7668#ifdef __cplusplus 7669extern "C" 7670#endif 7671void *valloc (size_t); 7672@end example 7673 7674If a test program calls a function with invalid parameters (just to see 7675whether it exists), organize the program to ensure that it never invokes 7676that function. You can do this by calling it in another function that is 7677never invoked. You can't do it by putting it after a call to 7678@code{exit}, because @acronym{GCC} version 2 knows that @code{exit} 7679never returns 7680and optimizes out any code that follows it in the same block. 7681 7682If you include any header files, be sure to call the functions 7683relevant to them with the correct number of arguments, even if they are 7684just 0, to avoid compilation errors due to prototypes. @acronym{GCC} 7685version 2 7686has internal prototypes for several functions that it automatically 7687inlines; for example, @code{memcpy}. To avoid errors when checking for 7688them, either pass them the correct number of arguments or redeclare them 7689with a different return type (such as @code{char}). 7690 7691 7692@node Generating Sources 7693@subsection Generating Sources 7694 7695Autoconf provides a set of macros that can be used to generate test 7696source files. They are written to be language generic, i.e., they 7697actually depend on the current language (@pxref{Language Choice}) to 7698``format'' the output properly. 7699 7700 7701@defmac AC_LANG_CONFTEST (@var{source}) 7702@acindex{LANG_CONFTEST} 7703Save the @var{source} text in the current test source file: 7704@file{conftest.@var{extension}} where the @var{extension} depends on the 7705current language. 7706 7707Note that the @var{source} is evaluated exactly once, like regular 7708Autoconf macro arguments, and therefore (i) you may pass a macro 7709invocation, (ii) if not, be sure to double quote if needed. 7710@end defmac 7711 7712@defmac AC_LANG_SOURCE (@var{source}) 7713@acindex{LANG_SOURCE} 7714Expands into the @var{source}, with the definition of 7715all the @code{AC_DEFINE} performed so far. 7716@end defmac 7717 7718For instance executing (observe the double quotation!): 7719 7720@example 7721AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 7722AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7723 [Greetings string.]) 7724AC_LANG(C) 7725AC_LANG_CONFTEST( 7726 [AC_LANG_SOURCE([[const char hw[] = "Hello, World\n";]])]) 7727gcc -E -dD -o - conftest.c 7728@end example 7729 7730@noindent 7731results in: 7732 7733@example 7734@dots{} 7735# 1 "conftest.c" 7736 7737#define PACKAGE_NAME "Hello" 7738#define PACKAGE_TARNAME "hello" 7739#define PACKAGE_VERSION "1.0" 7740#define PACKAGE_STRING "Hello 1.0" 7741#define PACKAGE_BUGREPORT "bug-hello@@example.org" 7742#define HELLO_WORLD "Hello, World\n" 7743 7744const char hw[] = "Hello, World\n"; 7745@end example 7746 7747When the test language is Fortran or Erlang, the @code{AC_DEFINE} definitions 7748are not automatically translated into constants in the source code by this 7749macro. 7750 7751@defmac AC_LANG_PROGRAM (@var{prologue}, @var{body}) 7752@acindex{LANG_PROGRAM} 7753Expands into a source file which consists of the @var{prologue}, and 7754then @var{body} as body of the main function (e.g., @code{main} in 7755C). Since it uses @code{AC_LANG_SOURCE}, the features of the latter are 7756available. 7757@end defmac 7758 7759For instance: 7760 7761@example 7762AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 7763AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7764 [Greetings string.]) 7765AC_LANG_CONFTEST( 7766[AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 7767 [[fputs (hw, stdout);]])]) 7768gcc -E -dD -o - conftest.c 7769@end example 7770 7771@noindent 7772results in: 7773 7774@example 7775@dots{} 7776# 1 "conftest.c" 7777 7778#define PACKAGE_NAME "Hello" 7779#define PACKAGE_TARNAME "hello" 7780#define PACKAGE_VERSION "1.0" 7781#define PACKAGE_STRING "Hello 1.0" 7782#define PACKAGE_BUGREPORT "bug-hello@@example.org" 7783#define HELLO_WORLD "Hello, World\n" 7784 7785const char hw[] = "Hello, World\n"; 7786int 7787main () 7788@{ 7789fputs (hw, stdout); 7790 ; 7791 return 0; 7792@} 7793@end example 7794 7795In Erlang tests, the created source file is that of an Erlang module called 7796@code{conftest} (@file{conftest.erl}). This module defines and exports at least 7797one @code{start/0} function, which is called to perform the test. The 7798@var{prologue} is optional code that is inserted between the module header and 7799the @code{start/0} function definition. @var{body} is the body of the 7800@code{start/0} function without the final period (@pxref{Runtime}, about 7801constraints on this function's behavior). 7802 7803For instance: 7804 7805@example 7806AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 7807AC_LANG(Erlang) 7808AC_LANG_CONFTEST( 7809[AC_LANG_PROGRAM([[-define(HELLO_WORLD, "Hello, world!").]], 7810 [[io:format("~s~n", [?HELLO_WORLD])]])]) 7811cat conftest.erl 7812@end example 7813 7814@noindent 7815results in: 7816 7817@example 7818-module(conftest). 7819-export([start/0]). 7820-define(HELLO_WORLD, "Hello, world!"). 7821start() -> 7822io:format("~s~n", [?HELLO_WORLD]) 7823. 7824@end example 7825 7826@defmac AC_LANG_CALL (@var{prologue}, @var{function}) 7827@acindex{LANG_CALL} 7828Expands into a source file which consists of the @var{prologue}, and 7829then a call to the @var{function} as body of the main function (e.g., 7830@code{main} in C). Since it uses @code{AC_LANG_PROGRAM}, the feature 7831of the latter are available. 7832 7833This function will probably be replaced in the future by a version 7834which would enable specifying the arguments. The use of this macro is 7835not encouraged, as it violates strongly the typing system. 7836 7837This macro cannot be used for Erlang tests. 7838@end defmac 7839 7840@defmac AC_LANG_FUNC_LINK_TRY (@var{function}) 7841@acindex{LANG_FUNC_LINK_TRY} 7842Expands into a source file which uses the @var{function} in the body of 7843the main function (e.g., @code{main} in C). Since it uses 7844@code{AC_LANG_PROGRAM}, the features of the latter are available. 7845 7846As @code{AC_LANG_CALL}, this macro is documented only for completeness. 7847It is considered to be severely broken, and in the future will be 7848removed in favor of actual function calls (with properly typed 7849arguments). 7850 7851This macro cannot be used for Erlang tests. 7852@end defmac 7853 7854@node Running the Preprocessor 7855@section Running the Preprocessor 7856 7857Sometimes one might need to run the preprocessor on some source file. 7858@emph{Usually it is a bad idea}, as you typically need to @emph{compile} 7859your project, not merely run the preprocessor on it; therefore you 7860certainly want to run the compiler, not the preprocessor. Resist the 7861temptation of following the easiest path. 7862 7863Nevertheless, if you need to run the preprocessor, then use 7864@code{AC_PREPROC_IFELSE}. 7865 7866The macros described in this section cannot be used for tests in Erlang or 7867Fortran, since those languages require no preprocessor. 7868 7869@defmac AC_PREPROC_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 7870@acindex{PREPROC_IFELSE} 7871Run the preprocessor of the current language (@pxref{Language Choice}) 7872on the @var{input}, run the shell commands @var{action-if-true} on 7873success, @var{action-if-false} otherwise. The @var{input} can be made 7874by @code{AC_LANG_PROGRAM} and friends. 7875 7876This macro uses @code{CPPFLAGS}, but not @code{CFLAGS}, because 7877@option{-g}, @option{-O}, etc.@: are not valid options to many C 7878preprocessors. 7879 7880It is customary to report unexpected failures with 7881@code{AC_MSG_FAILURE}. 7882@end defmac 7883 7884For instance: 7885 7886@example 7887AC_INIT([Hello], [1.0], [bug-hello@@example.org]) 7888AC_DEFINE([HELLO_WORLD], ["Hello, World\n"], 7889 [Greetings string.]) 7890AC_PREPROC_IFELSE( 7891 [AC_LANG_PROGRAM([[const char hw[] = "Hello, World\n";]], 7892 [[fputs (hw, stdout);]])], 7893 [AC_MSG_RESULT([OK])], 7894 [AC_MSG_FAILURE([unexpected preprocessor failure])]) 7895@end example 7896 7897@noindent 7898results in: 7899 7900@example 7901checking for gcc... gcc 7902checking for C compiler default output file name... a.out 7903checking whether the C compiler works... yes 7904checking whether we are cross compiling... no 7905checking for suffix of executables... 7906checking for suffix of object files... o 7907checking whether we are using the GNU C compiler... yes 7908checking whether gcc accepts -g... yes 7909checking for gcc option to accept ISO C89... none needed 7910checking how to run the C preprocessor... gcc -E 7911OK 7912@end example 7913 7914@sp 1 7915 7916The macro @code{AC_TRY_CPP} (@pxref{Obsolete Macros}) used to play the 7917role of @code{AC_PREPROC_IFELSE}, but double quotes its argument, making 7918it impossible to use it to elaborate sources. You are encouraged to 7919get rid of your old use of the macro @code{AC_TRY_CPP} in favor of 7920@code{AC_PREPROC_IFELSE}, but, in the first place, are you sure you need 7921to run the @emph{preprocessor} and not the compiler? 7922 7923@defmac AC_EGREP_HEADER (@var{pattern}, @var{header-file}, @var{action-if-found}, @ovar{action-if-not-found}) 7924@acindex{EGREP_HEADER} 7925If the output of running the preprocessor on the system header file 7926@var{header-file} matches the extended regular expression 7927@var{pattern}, execute shell commands @var{action-if-found}, otherwise 7928execute @var{action-if-not-found}. 7929@end defmac 7930 7931@defmac AC_EGREP_CPP (@var{pattern}, @var{program}, @ovar{action-if-found}, @ovar{action-if-not-found}) 7932@acindex{EGREP_CPP} 7933@var{program} is the text of a C or C++ program, on which shell 7934variable, back quote, and backslash substitutions are performed. If the 7935output of running the preprocessor on @var{program} matches the 7936extended regular expression @var{pattern}, execute shell commands 7937@var{action-if-found}, otherwise execute @var{action-if-not-found}. 7938@end defmac 7939 7940 7941 7942@node Running the Compiler 7943@section Running the Compiler 7944 7945To check for a syntax feature of the current language's (@pxref{Language 7946Choice}) compiler, such as whether it recognizes a certain keyword, or 7947simply to try some library feature, use @code{AC_COMPILE_IFELSE} to try 7948to compile a small program that uses that feature. 7949 7950@defmac AC_COMPILE_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 7951@acindex{COMPILE_IFELSE} 7952Run the compiler and compilation flags of the current language 7953(@pxref{Language Choice}) on the @var{input}, run the shell commands 7954@var{action-if-true} on success, @var{action-if-false} otherwise. The 7955@var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 7956 7957It is customary to report unexpected failures with 7958@code{AC_MSG_FAILURE}. This macro does not try to link; use 7959@code{AC_LINK_IFELSE} if you need to do that (@pxref{Running the 7960Linker}). 7961@end defmac 7962 7963@ovindex ERL 7964For tests in Erlang, the @var{input} must be the source code of a module named 7965@code{conftest}. @code{AC_COMPILE_IFELSE} generates a @file{conftest.beam} 7966file that can be interpreted by the Erlang virtual machine (@code{ERL}). It is 7967recommended to use @code{AC_LANG_PROGRAM} to specify the test program, to ensure 7968that the Erlang module has the right name. 7969 7970@node Running the Linker 7971@section Running the Linker 7972 7973To check for a library, a function, or a global variable, Autoconf 7974@command{configure} scripts try to compile and link a small program that 7975uses it. This is unlike Metaconfig, which by default uses @code{nm} or 7976@code{ar} on the C library to try to figure out which functions are 7977available. Trying to link with the function is usually a more reliable 7978approach because it avoids dealing with the variations in the options 7979and output formats of @code{nm} and @code{ar} and in the location of the 7980standard libraries. It also allows configuring for cross-compilation or 7981checking a function's runtime behavior if needed. On the other hand, 7982it can be slower than scanning the libraries once, but accuracy is more 7983important than speed. 7984 7985@code{AC_LINK_IFELSE} is used to compile test programs to test for 7986functions and global variables. It is also used by @code{AC_CHECK_LIB} 7987to check for libraries (@pxref{Libraries}), by adding the library being 7988checked for to @code{LIBS} temporarily and trying to link a small 7989program. 7990 7991 7992@defmac AC_LINK_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 7993@acindex{LINK_IFELSE} 7994Run the compiler (and compilation flags) and the linker of the current 7995language (@pxref{Language Choice}) on the @var{input}, run the shell 7996commands @var{action-if-true} on success, @var{action-if-false} 7997otherwise. The @var{input} can be made by @code{AC_LANG_PROGRAM} and 7998friends. 7999 8000@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 8001current compilation flags. 8002 8003It is customary to report unexpected failures with 8004@code{AC_MSG_FAILURE}. This macro does not try to execute the program; 8005use @code{AC_RUN_IFELSE} if you need to do that (@pxref{Runtime}). 8006@end defmac 8007 8008The @code{AC_LINK_IFELSE} macro cannot be used for Erlang tests, since Erlang 8009programs are interpreted and do not require linking. 8010 8011 8012 8013@node Runtime 8014@section Checking Runtime Behavior 8015 8016Sometimes you need to find out how a system performs at runtime, such 8017as whether a given function has a certain capability or bug. If you 8018can, make such checks when your program runs instead of when it is 8019configured. You can check for things like the machine's endianness when 8020your program initializes itself. 8021 8022If you really need to test for a runtime behavior while configuring, 8023you can write a test program to determine the result, and compile and 8024run it using @code{AC_RUN_IFELSE}. Avoid running test programs if 8025possible, because this prevents people from configuring your package for 8026cross-compiling. 8027 8028@defmac AC_RUN_IFELSE (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling}) 8029@acindex{RUN_IFELSE} 8030If @var{program} compiles and links successfully and returns an exit 8031status of 0 when executed, run shell commands @var{action-if-true}. 8032Otherwise, run shell commands @var{action-if-false}. 8033 8034The @var{input} can be made by @code{AC_LANG_PROGRAM} and friends. 8035@code{LDFLAGS} and @code{LIBS} are used for linking, in addition to the 8036compilation flags of the current language (@pxref{Language Choice}). 8037 8038If the compiler being used does not produce executables that run on the 8039system where @command{configure} is being run, then the test program is 8040not run. If the optional shell commands @var{action-if-cross-compiling} 8041are given, they are run instead. Otherwise, @command{configure} prints 8042an error message and exits. 8043 8044In the @var{action-if-false} section, the failing exit status is 8045available in the shell variable @samp{$?}. This exit status might be 8046that of a failed compilation, or it might be that of a failed program 8047execution. 8048 8049It is customary to report unexpected failures with 8050@code{AC_MSG_FAILURE}. 8051@end defmac 8052 8053Try to provide a pessimistic default value to use when cross-compiling 8054makes runtime tests impossible. You do this by passing the optional 8055last argument to @code{AC_RUN_IFELSE}. @command{autoconf} prints a 8056warning message when creating @command{configure} each time it 8057encounters a call to @code{AC_RUN_IFELSE} with no 8058@var{action-if-cross-compiling} argument given. You may ignore the 8059warning, though users cannot configure your package for 8060cross-compiling. A few of the macros distributed with Autoconf produce 8061this warning message. 8062 8063To configure for cross-compiling you can also choose a value for those 8064parameters based on the canonical system name (@pxref{Manual 8065Configuration}). Alternatively, set up a test results cache file with 8066the correct values for the host system (@pxref{Caching Results}). 8067 8068@ovindex cross_compiling 8069To provide a default for calls of @code{AC_RUN_IFELSE} that are embedded 8070in other macros, including a few of the ones that come with Autoconf, 8071you can test whether the shell variable @code{cross_compiling} is set to 8072@samp{yes}, and then use an alternate method to get the results instead 8073of calling the macros. 8074 8075A C or C++ runtime test should be portable. 8076@xref{Portable C and C++}. 8077 8078Erlang tests must exit themselves the Erlang VM by calling the @code{halt/1} 8079function: the given status code is used to determine the success of the test 8080(status is @code{0}) or its failure (status is different than @code{0}), as 8081explained above. It must be noted that data output through the standard output 8082(e.g., using @code{io:format/2}) may be truncated when halting the VM. 8083Therefore, if a test must output configuration information, it is recommended 8084to create and to output data into the temporary file named @file{conftest.out}, 8085using the functions of module @code{file}. The @code{conftest.out} file is 8086automatically deleted by the @code{AC_RUN_IFELSE} macro. For instance, a 8087simplified implementation of Autoconf's @code{AC_ERLANG_SUBST_LIB_DIR} macro is: 8088 8089@example 8090AC_INIT([LibdirTest], [1.0], [bug-libdirtest@@example.org]) 8091AC_ERLANG_NEED_ERL 8092AC_LANG(Erlang) 8093AC_RUN_IFELSE( 8094 [AC_LANG_PROGRAM([], [dnl 8095 file:write_file("conftest.out", code:lib_dir()), 8096 halt(0)])], 8097 [echo "code:lib_dir() returned: `cat conftest.out`"], 8098 [AC_MSG_FAILURE([test Erlang program execution failed])]) 8099@end example 8100 8101 8102@node Systemology 8103@section Systemology 8104@cindex Systemology 8105 8106This section aims at presenting some systems and pointers to 8107documentation. It may help you addressing particular problems reported 8108by users. 8109 8110@uref{http://www.opengroup.org/susv3, Posix-conforming systems} are 8111derived from the @uref{http://www.bell-labs.com/history/unix/, Unix 8112operating system}. 8113 8114The @uref{http://bhami.com/rosetta.html, Rosetta Stone for Unix} 8115contains a table correlating the features of various Posix-conforming 8116systems. @uref{http://www.levenez.com/unix/, Unix History} is a 8117simplified diagram of how many Unix systems were derived from each 8118other. 8119 8120@uref{http://heirloom.sourceforge.net/, The Heirloom Project} 8121provides some variants of traditional implementations of Unix utilities. 8122 8123@table @asis 8124@item Darwin 8125@cindex Darwin 8126Darwin is also known as Mac OS X@. Beware that the file system @emph{can} be 8127case-preserving, but case insensitive. This can cause nasty problems, 8128since for instance the installation attempt for a package having an 8129@file{INSTALL} file can result in @samp{make install} report that 8130nothing was to be done! 8131 8132That's all dependent on whether the file system is a UFS (case 8133sensitive) or HFS+ (case preserving). By default Apple wants you to 8134install the OS on HFS+. Unfortunately, there are some pieces of 8135software which really need to be built on UFS@. We may want to rebuild 8136Darwin to have both UFS and HFS+ available (and put the /local/build 8137tree on the UFS). 8138 8139@item @acronym{QNX} 4.25 8140@cindex @acronym{QNX} 4.25 8141@c FIXME: Please, if you feel like writing something more precise, 8142@c it'd be great. In particular, I can't understand the difference with 8143@c QNX Neutrino. 8144@acronym{QNX} is a realtime operating system running on Intel architecture 8145meant to be scalable from the small embedded systems to the hundred 8146processor super-computer. It claims to be Posix certified. More 8147information is available on the 8148@uref{http://www.qnx.com/, @acronym{QNX} home page}. 8149 8150@item Tru64 8151@cindex Tru64 8152@uref{http://h30097.www3.hp.com/@/docs/, 8153Documentation of several versions of Tru64} is available in different 8154formats. 8155 8156@item Unix version 7 8157@cindex Unix version 7 8158@cindex V7 8159Officially this was called the ``Seventh Edition'' of ``the @sc{unix} 8160time-sharing system'' but we use the more-common name ``Unix version 7''. 8161Documentation is available in the 8162@uref{http://plan9.bell-labs.com/@/7thEdMan/, Unix Seventh Edition Manual}. 8163Previous versions of Unix are called ``Unix version 6'', etc., but 8164they were not as widely used. 8165@end table 8166 8167 8168@node Multiple Cases 8169@section Multiple Cases 8170 8171Some operations are accomplished in several possible ways, depending on 8172the OS variant. Checking for them essentially requires a ``case 8173statement''. Autoconf does not directly provide one; however, it is 8174easy to simulate by using a shell variable to keep track of whether a 8175way to perform the operation has been found yet. 8176 8177Here is an example that uses the shell variable @code{fstype} to keep 8178track of whether the remaining cases need to be checked. 8179 8180@example 8181@group 8182AC_MSG_CHECKING([how to get file system type]) 8183fstype=no 8184# The order of these tests is important. 8185AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statvfs.h> 8186#include <sys/fstyp.h>]])], 8187 [AC_DEFINE([FSTYPE_STATVFS], [1], 8188 [Define if statvfs exists.]) 8189 fstype=SVR4]) 8190if test $fstype = no; then 8191 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 8192#include <sys/fstyp.h>]])], 8193 [AC_DEFINE([FSTYPE_USG_STATFS], [1], 8194 [Define if USG statfs.]) 8195 fstype=SVR3]) 8196fi 8197if test $fstype = no; then 8198 AC_COMPILE_IFELSE([AC_LANG_PROGRAM([[#include <sys/statfs.h> 8199#include <sys/vmount.h>]])]), 8200 [AC_DEFINE([FSTYPE_AIX_STATFS], [1], 8201 [Define if AIX statfs.]) 8202 fstype=AIX]) 8203fi 8204# (more cases omitted here) 8205AC_MSG_RESULT([$fstype]) 8206@end group 8207@end example 8208 8209@c ====================================================== Results of Tests. 8210 8211@node Results 8212@chapter Results of Tests 8213 8214Once @command{configure} has determined whether a feature exists, what can 8215it do to record that information? There are four sorts of things it can 8216do: define a C preprocessor symbol, set a variable in the output files, 8217save the result in a cache file for future @command{configure} runs, and 8218print a message letting the user know the result of the test. 8219 8220@menu 8221* Defining Symbols:: Defining C preprocessor symbols 8222* Setting Output Variables:: Replacing variables in output files 8223* Special Chars in Variables:: Characters to beware of in variables 8224* Caching Results:: Speeding up subsequent @command{configure} runs 8225* Printing Messages:: Notifying @command{configure} users 8226@end menu 8227 8228@node Defining Symbols 8229@section Defining C Preprocessor Symbols 8230 8231A common action to take in response to a feature test is to define a C 8232preprocessor symbol indicating the results of the test. That is done by 8233calling @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED}. 8234 8235By default, @code{AC_OUTPUT} places the symbols defined by these macros 8236into the output variable @code{DEFS}, which contains an option 8237@option{-D@var{symbol}=@var{value}} for each symbol defined. Unlike in 8238Autoconf version 1, there is no variable @code{DEFS} defined while 8239@command{configure} is running. To check whether Autoconf macros have 8240already defined a certain C preprocessor symbol, test the value of the 8241appropriate cache variable, as in this example: 8242 8243@example 8244AC_CHECK_FUNC([vprintf], [AC_DEFINE([HAVE_VPRINTF], [1], 8245 [Define if vprintf exists.])]) 8246if test "$ac_cv_func_vprintf" != yes; then 8247 AC_CHECK_FUNC([_doprnt], [AC_DEFINE([HAVE_DOPRNT], [1], 8248 [Define if _doprnt exists.])]) 8249fi 8250@end example 8251 8252If @code{AC_CONFIG_HEADERS} has been called, then instead of creating 8253@code{DEFS}, @code{AC_OUTPUT} creates a header file by substituting the 8254correct values into @code{#define} statements in a template file. 8255@xref{Configuration Headers}, for more information about this kind of 8256output. 8257 8258@defmac AC_DEFINE (@var{variable}, @var{value}, @ovar{description}) 8259@defmacx AC_DEFINE (@var{variable}) 8260@acindex{DEFINE} 8261Define the C preprocessor variable @var{variable} to @var{value} (verbatim). 8262@var{value} should not contain literal newlines, and if you are not 8263using @code{AC_CONFIG_HEADERS} it should not contain any @samp{#} 8264characters, as @command{make} tends to eat them. To use a shell variable, 8265use @code{AC_DEFINE_UNQUOTED} instead. 8266@var{description} is only useful if you are using 8267@code{AC_CONFIG_HEADERS}. In this case, @var{description} is put into 8268the generated @file{config.h.in} as the comment before the macro define. 8269The following example defines the C preprocessor variable 8270@code{EQUATION} to be the string constant @samp{"$a > $b"}: 8271 8272@example 8273AC_DEFINE([EQUATION], ["$a > $b"], 8274 [Equation string.]) 8275@end example 8276 8277If neither @var{value} nor @var{description} are given, then 8278@var{value} defaults to 1 instead of to the empty string. This is for 8279backwards compatibility with older versions of Autoconf, but this usage 8280is obsolescent and may be withdrawn in future versions of Autoconf. 8281 8282If the @var{variable} is a literal string, it is passed to 8283@code{m4_pattern_allow} (@pxref{Forbidden Patterns}). 8284@end defmac 8285 8286@defmac AC_DEFINE_UNQUOTED (@var{variable}, @var{value}, @ovar{description}) 8287@defmacx AC_DEFINE_UNQUOTED (@var{variable}) 8288@acindex{DEFINE_UNQUOTED} 8289Like @code{AC_DEFINE}, but three shell expansions are 8290performed---once---on @var{variable} and @var{value}: variable expansion 8291(@samp{$}), command substitution (@samp{`}), and backslash escaping 8292(@samp{\}). Single and double quote characters in the value have no 8293special meaning. Use this macro instead of @code{AC_DEFINE} when 8294@var{variable} or @var{value} is a shell variable. Examples: 8295 8296@example 8297AC_DEFINE_UNQUOTED([config_machfile], ["$machfile"], 8298 [Configuration machine file.]) 8299AC_DEFINE_UNQUOTED([GETGROUPS_T], [$ac_cv_type_getgroups], 8300 [getgroups return type.]) 8301AC_DEFINE_UNQUOTED([$ac_tr_hdr], [1], 8302 [Translated header name.]) 8303@end example 8304@end defmac 8305 8306Due to a syntactical bizarreness of the Bourne shell, do not use 8307semicolons to separate @code{AC_DEFINE} or @code{AC_DEFINE_UNQUOTED} 8308calls from other macro calls or shell code; that can cause syntax errors 8309in the resulting @command{configure} script. Use either blanks or 8310newlines. That is, do this: 8311 8312@example 8313AC_CHECK_HEADER([elf.h], 8314 [AC_DEFINE([SVR4], [1], [System V Release 4]) LIBS="-lelf $LIBS"]) 8315@end example 8316 8317@noindent 8318or this: 8319 8320@example 8321AC_CHECK_HEADER([elf.h], 8322 [AC_DEFINE([SVR4], [1], [System V Release 4]) 8323 LIBS="-lelf $LIBS"]) 8324@end example 8325 8326@noindent 8327instead of this: 8328 8329@example 8330AC_CHECK_HEADER([elf.h], 8331 [AC_DEFINE([SVR4], [1], [System V Release 4]); LIBS="-lelf $LIBS"]) 8332@end example 8333 8334@node Setting Output Variables 8335@section Setting Output Variables 8336@cindex Output variables 8337 8338Another way to record the results of tests is to set @dfn{output 8339variables}, which are shell variables whose values are substituted into 8340files that @command{configure} outputs. The two macros below create new 8341output variables. @xref{Preset Output Variables}, for a list of output 8342variables that are always available. 8343 8344@defmac AC_SUBST (@var{variable}, @ovar{value}) 8345@acindex{SUBST} 8346Create an output variable from a shell variable. Make @code{AC_OUTPUT} 8347substitute the variable @var{variable} into output files (typically one 8348or more makefiles). This means that @code{AC_OUTPUT} 8349replaces instances of @samp{@@@var{variable}@@} in input files with the 8350value that the shell variable @var{variable} has when @code{AC_OUTPUT} 8351is called. The value can contain newlines. 8352The substituted value is not rescanned for more output variables; 8353occurrences of @samp{@@@var{variable}@@} in the value are inserted 8354literally into the output file. (The algorithm uses the special marker 8355@code{|#_!!_#|} internally, so the substituted value cannot contain 8356@code{|#_!!_#|}.) 8357 8358If @var{value} is given, in addition assign it to @var{variable}. 8359 8360The string @var{variable} is passed to @code{m4_pattern_allow} 8361(@pxref{Forbidden Patterns}). 8362@end defmac 8363 8364@defmac AC_SUBST_FILE (@var{variable}) 8365@acindex{SUBST_FILE} 8366Another way to create an output variable from a shell variable. Make 8367@code{AC_OUTPUT} insert (without substitutions) the contents of the file 8368named by shell variable @var{variable} into output files. This means 8369that @code{AC_OUTPUT} replaces instances of 8370@samp{@@@var{variable}@@} in output files (such as @file{Makefile.in}) 8371with the contents of the file that the shell variable @var{variable} 8372names when @code{AC_OUTPUT} is called. Set the variable to 8373@file{/dev/null} for cases that do not have a file to insert. 8374This substitution occurs only when the @samp{@@@var{variable}@@} is on a 8375line by itself, optionally surrounded by spaces and tabs. The 8376substitution replaces the whole line, including the spaces, tabs, and 8377the terminating newline. 8378 8379This macro is useful for inserting makefile fragments containing 8380special dependencies or other @code{make} directives for particular host 8381or target types into makefiles. For example, @file{configure.ac} 8382could contain: 8383 8384@example 8385AC_SUBST_FILE([host_frag]) 8386host_frag=$srcdir/conf/sun4.mh 8387@end example 8388 8389@noindent 8390and then a @file{Makefile.in} could contain: 8391 8392@example 8393@@host_frag@@ 8394@end example 8395 8396The string @var{variable} is passed to @code{m4_pattern_allow} 8397(@pxref{Forbidden Patterns}). 8398@end defmac 8399 8400@cindex Precious Variable 8401@cindex Variable, Precious 8402Running @command{configure} in varying environments can be extremely 8403dangerous. If for instance the user runs @samp{CC=bizarre-cc 8404./configure}, then the cache, @file{config.h}, and many other output 8405files depend upon @command{bizarre-cc} being the C compiler. If 8406for some reason the user runs @command{./configure} again, or if it is 8407run via @samp{./config.status --recheck}, (@xref{Automatic Remaking}, 8408and @pxref{config.status Invocation}), then the configuration can be 8409inconsistent, composed of results depending upon two different 8410compilers. 8411 8412Environment variables that affect this situation, such as @samp{CC} 8413above, are called @dfn{precious variables}, and can be declared as such 8414by @code{AC_ARG_VAR}. 8415 8416@defmac AC_ARG_VAR (@var{variable}, @var{description}) 8417@acindex{ARG_VAR} 8418Declare @var{variable} is a precious variable, and include its 8419@var{description} in the variable section of @samp{./configure --help}. 8420 8421Being precious means that 8422@itemize @minus 8423@item 8424@var{variable} is substituted via @code{AC_SUBST}. 8425 8426@item 8427The value of @var{variable} when @command{configure} was launched is 8428saved in the cache, including if it was not specified on the command 8429line but via the environment. Indeed, while @command{configure} can 8430notice the definition of @code{CC} in @samp{./configure CC=bizarre-cc}, 8431it is impossible to notice it in @samp{CC=bizarre-cc ./configure}, 8432which, unfortunately, is what most users do. 8433 8434We emphasize that it is the @emph{initial} value of @var{variable} which 8435is saved, not that found during the execution of @command{configure}. 8436Indeed, specifying @samp{./configure FOO=foo} and letting 8437@samp{./configure} guess that @code{FOO} is @code{foo} can be two 8438different things. 8439 8440@item 8441@var{variable} is checked for consistency between two 8442@command{configure} runs. For instance: 8443 8444@example 8445$ @kbd{./configure --silent --config-cache} 8446$ @kbd{CC=cc ./configure --silent --config-cache} 8447configure: error: `CC' was not set in the previous run 8448configure: error: changes in the environment can compromise \ 8449the build 8450configure: error: run `make distclean' and/or \ 8451`rm config.cache' and start over 8452@end example 8453 8454@noindent 8455and similarly if the variable is unset, or if its content is changed. 8456 8457 8458@item 8459@var{variable} is kept during automatic reconfiguration 8460(@pxref{config.status Invocation}) as if it had been passed as a command 8461line argument, including when no cache is used: 8462 8463@example 8464$ @kbd{CC=/usr/bin/cc ./configure undeclared_var=raboof --silent} 8465$ @kbd{./config.status --recheck} 8466running CONFIG_SHELL=/bin/sh /bin/sh ./configure undeclared_var=raboof \ 8467 CC=/usr/bin/cc --no-create --no-recursion 8468@end example 8469@end itemize 8470@end defmac 8471 8472@node Special Chars in Variables 8473@section Special Characters in Output Variables 8474@cindex Output variables, special characters in 8475 8476Many output variables are intended to be evaluated both by 8477@command{make} and by the shell. Some characters are expanded 8478differently in these two contexts, so to avoid confusion these 8479variables' values should not contain any of the following characters: 8480 8481@example 8482" # $ & ' ( ) * ; < > ? [ \ ^ ` | 8483@end example 8484 8485Also, these variables' values should neither contain newlines, nor start 8486with @samp{~}, nor contain white space or @samp{:} immediately followed 8487by @samp{~}. The values can contain nonempty sequences of white space 8488characters like tabs and spaces, but each such sequence might 8489arbitrarily be replaced by a single space during substitution. 8490 8491These restrictions apply both to the values that @command{configure} 8492computes, and to the values set directly by the user. For example, the 8493following invocations of @command{configure} are problematic, since they 8494attempt to use special characters within @code{CPPFLAGS} and white space 8495within @code{$(srcdir)}: 8496 8497@example 8498CPPFLAGS='-DOUCH="&\"#$*?"' '../My Source/ouch-1.0/configure' 8499 8500'../My Source/ouch-1.0/configure' CPPFLAGS='-DOUCH="&\"#$*?"' 8501@end example 8502 8503@node Caching Results 8504@section Caching Results 8505@cindex Cache 8506 8507To avoid checking for the same features repeatedly in various 8508@command{configure} scripts (or in repeated runs of one script), 8509@command{configure} can optionally save the results of many checks in a 8510@dfn{cache file} (@pxref{Cache Files}). If a @command{configure} script 8511runs with caching enabled and finds a cache file, it reads the results 8512of previous runs from the cache and avoids rerunning those checks. As a 8513result, @command{configure} can then run much faster than if it had to 8514perform all of the checks every time. 8515 8516@defmac AC_CACHE_VAL (@var{cache-id}, @var{commands-to-set-it}) 8517@acindex{CACHE_VAL} 8518Ensure that the results of the check identified by @var{cache-id} are 8519available. If the results of the check were in the cache file that was 8520read, and @command{configure} was not given the @option{--quiet} or 8521@option{--silent} option, print a message saying that the result was 8522cached; otherwise, run the shell commands @var{commands-to-set-it}. If 8523the shell commands are run to determine the value, the value is 8524saved in the cache file just before @command{configure} creates its output 8525files. @xref{Cache Variable Names}, for how to choose the name of the 8526@var{cache-id} variable. 8527 8528The @var{commands-to-set-it} @emph{must have no side effects} except for 8529setting the variable @var{cache-id}, see below. 8530@end defmac 8531 8532@defmac AC_CACHE_CHECK (@var{message}, @var{cache-id}, @var{commands-to-set-it}) 8533@acindex{CACHE_CHECK} 8534A wrapper for @code{AC_CACHE_VAL} that takes care of printing the 8535messages. This macro provides a convenient shorthand for the most 8536common way to use these macros. It calls @code{AC_MSG_CHECKING} for 8537@var{message}, then @code{AC_CACHE_VAL} with the @var{cache-id} and 8538@var{commands} arguments, and @code{AC_MSG_RESULT} with @var{cache-id}. 8539 8540The @var{commands-to-set-it} @emph{must have no side effects} except for 8541setting the variable @var{cache-id}, see below. 8542@end defmac 8543 8544It is common to find buggy macros using @code{AC_CACHE_VAL} or 8545@code{AC_CACHE_CHECK}, because people are tempted to call 8546@code{AC_DEFINE} in the @var{commands-to-set-it}. Instead, the code that 8547@emph{follows} the call to @code{AC_CACHE_VAL} should call 8548@code{AC_DEFINE}, by examining the value of the cache variable. For 8549instance, the following macro is broken: 8550 8551@example 8552@group 8553AC_DEFUN([AC_SHELL_TRUE], 8554[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], 8555 [ac_cv_shell_true_works=no 8556 (true) 2>/dev/null && ac_cv_shell_true_works=yes 8557 if test "$ac_cv_shell_true_works" = yes; then 8558 AC_DEFINE([TRUE_WORKS], [1], 8559 [Define if `true(1)' works properly.]) 8560 fi]) 8561]) 8562@end group 8563@end example 8564 8565@noindent 8566This fails if the cache is enabled: the second time this macro is run, 8567@code{TRUE_WORKS} @emph{will not be defined}. The proper implementation 8568is: 8569 8570@example 8571@group 8572AC_DEFUN([AC_SHELL_TRUE], 8573[AC_CACHE_CHECK([whether true(1) works], [ac_cv_shell_true_works], 8574 [ac_cv_shell_true_works=no 8575 (true) 2>/dev/null && ac_cv_shell_true_works=yes]) 8576 if test "$ac_cv_shell_true_works" = yes; then 8577 AC_DEFINE([TRUE_WORKS], [1], 8578 [Define if `true(1)' works properly.]) 8579 fi 8580]) 8581@end group 8582@end example 8583 8584Also, @var{commands-to-set-it} should not print any messages, for 8585example with @code{AC_MSG_CHECKING}; do that before calling 8586@code{AC_CACHE_VAL}, so the messages are printed regardless of whether 8587the results of the check are retrieved from the cache or determined by 8588running the shell commands. 8589 8590@menu 8591* Cache Variable Names:: Shell variables used in caches 8592* Cache Files:: Files @command{configure} uses for caching 8593* Cache Checkpointing:: Loading and saving the cache file 8594@end menu 8595 8596@node Cache Variable Names 8597@subsection Cache Variable Names 8598@cindex Cache variable 8599 8600The names of cache variables should have the following format: 8601 8602@example 8603@var{package-prefix}_cv_@var{value-type}_@var{specific-value}_@ovar{additional-options} 8604@end example 8605 8606@noindent 8607for example, @samp{ac_cv_header_stat_broken} or 8608@samp{ac_cv_prog_gcc_traditional}. The parts of the variable name are: 8609 8610@table @asis 8611@item @var{package-prefix} 8612An abbreviation for your package or organization; the same prefix you 8613begin local Autoconf macros with, except lowercase by convention. 8614For cache values used by the distributed Autoconf macros, this value is 8615@samp{ac}. 8616 8617@item @code{_cv_} 8618Indicates that this shell variable is a cache value. This string 8619@emph{must} be present in the variable name, including the leading 8620underscore. 8621 8622@item @var{value-type} 8623A convention for classifying cache values, to produce a rational naming 8624system. The values used in Autoconf are listed in @ref{Macro Names}. 8625 8626@item @var{specific-value} 8627Which member of the class of cache values this test applies to. 8628For example, which function (@samp{alloca}), program (@samp{gcc}), or 8629output variable (@samp{INSTALL}). 8630 8631@item @var{additional-options} 8632Any particular behavior of the specific member that this test applies to. 8633For example, @samp{broken} or @samp{set}. This part of the name may 8634be omitted if it does not apply. 8635@end table 8636 8637The values assigned to cache variables may not contain newlines. 8638Usually, their values are Boolean (@samp{yes} or @samp{no}) or the 8639names of files or functions; so this is not an important restriction. 8640 8641@node Cache Files 8642@subsection Cache Files 8643 8644A cache file is a shell script that caches the results of configure 8645tests run on one system so they can be shared between configure scripts 8646and configure runs. It is not useful on other systems. If its contents 8647are invalid for some reason, the user may delete or edit it. 8648 8649By default, @command{configure} uses no cache file, 8650to avoid problems caused by accidental 8651use of stale cache files. 8652 8653To enable caching, @command{configure} accepts @option{--config-cache} (or 8654@option{-C}) to cache results in the file @file{config.cache}. 8655Alternatively, @option{--cache-file=@var{file}} specifies that 8656@var{file} be the cache file. The cache file is created if it does not 8657exist already. When @command{configure} calls @command{configure} scripts in 8658subdirectories, it uses the @option{--cache-file} argument so that they 8659share the same cache. @xref{Subdirectories}, for information on 8660configuring subdirectories with the @code{AC_CONFIG_SUBDIRS} macro. 8661 8662@file{config.status} only pays attention to the cache file if it is 8663given the @option{--recheck} option, which makes it rerun 8664@command{configure}. 8665 8666It is wrong to try to distribute cache files for particular system types. 8667There is too much room for error in doing that, and too much 8668administrative overhead in maintaining them. For any features that 8669can't be guessed automatically, use the standard method of the canonical 8670system type and linking files (@pxref{Manual Configuration}). 8671 8672The site initialization script can specify a site-wide cache file to 8673use, instead of the usual per-program cache. In this case, the cache 8674file gradually accumulates information whenever someone runs a new 8675@command{configure} script. (Running @command{configure} merges the new cache 8676results with the existing cache file.) This may cause problems, 8677however, if the system configuration (e.g., the installed libraries or 8678compilers) changes and the stale cache file is not deleted. 8679 8680@node Cache Checkpointing 8681@subsection Cache Checkpointing 8682 8683If your configure script, or a macro called from @file{configure.ac}, happens 8684to abort the configure process, it may be useful to checkpoint the cache 8685a few times at key points using @code{AC_CACHE_SAVE}. Doing so 8686reduces the amount of time it takes to rerun the configure script with 8687(hopefully) the error that caused the previous abort corrected. 8688 8689@c FIXME: Do we really want to document this guy? 8690@defmac AC_CACHE_LOAD 8691@acindex{CACHE_LOAD} 8692Loads values from existing cache file, or creates a new cache file if a 8693cache file is not found. Called automatically from @code{AC_INIT}. 8694@end defmac 8695 8696@defmac AC_CACHE_SAVE 8697@acindex{CACHE_SAVE} 8698Flushes all cached values to the cache file. Called automatically from 8699@code{AC_OUTPUT}, but it can be quite useful to call 8700@code{AC_CACHE_SAVE} at key points in @file{configure.ac}. 8701@end defmac 8702 8703For instance: 8704 8705@example 8706@r{ @dots{} AC_INIT, etc. @dots{}} 8707@group 8708# Checks for programs. 8709AC_PROG_CC 8710AC_PROG_AWK 8711@r{ @dots{} more program checks @dots{}} 8712AC_CACHE_SAVE 8713@end group 8714 8715@group 8716# Checks for libraries. 8717AC_CHECK_LIB([nsl], [gethostbyname]) 8718AC_CHECK_LIB([socket], [connect]) 8719@r{ @dots{} more lib checks @dots{}} 8720AC_CACHE_SAVE 8721@end group 8722 8723@group 8724# Might abort@dots{} 8725AM_PATH_GTK([1.0.2], [], [AC_MSG_ERROR([GTK not in path])]) 8726AM_PATH_GTKMM([0.9.5], [], [AC_MSG_ERROR([GTK not in path])]) 8727@end group 8728@r{ @dots{} AC_OUTPUT, etc. @dots{}} 8729@end example 8730 8731@node Printing Messages 8732@section Printing Messages 8733@cindex Messages, from @command{configure} 8734 8735@command{configure} scripts need to give users running them several kinds 8736of information. The following macros print messages in ways appropriate 8737for each kind. The arguments to all of them get enclosed in shell 8738double quotes, so the shell performs variable and back-quote 8739substitution on them. 8740 8741These macros are all wrappers around the @command{echo} shell command. 8742They direct output to the appropriate file descriptor (@pxref{File 8743Descriptor Macros}). 8744@command{configure} scripts should rarely need to run @command{echo} directly 8745to print messages for the user. Using these macros makes it easy to 8746change how and when each kind of message is printed; such changes need 8747only be made to the macro definitions and all the callers change 8748automatically. 8749 8750To diagnose static issues, i.e., when @command{autoconf} is run, see 8751@ref{Reporting Messages}. 8752 8753@defmac AC_MSG_CHECKING (@var{feature-description}) 8754@acindex{MSG_CHECKING} 8755Notify the user that @command{configure} is checking for a particular 8756feature. This macro prints a message that starts with @samp{checking } 8757and ends with @samp{...} and no newline. It must be followed by a call 8758to @code{AC_MSG_RESULT} to print the result of the check and the 8759newline. The @var{feature-description} should be something like 8760@samp{whether the Fortran compiler accepts C++ comments} or @samp{for 8761c89}. 8762 8763This macro prints nothing if @command{configure} is run with the 8764@option{--quiet} or @option{--silent} option. 8765@end defmac 8766 8767@defmac AC_MSG_RESULT (@var{result-description}) 8768@acindex{MSG_RESULT} 8769Notify the user of the results of a check. @var{result-description} is 8770almost always the value of the cache variable for the check, typically 8771@samp{yes}, @samp{no}, or a file name. This macro should follow a call 8772to @code{AC_MSG_CHECKING}, and the @var{result-description} should be 8773the completion of the message printed by the call to 8774@code{AC_MSG_CHECKING}. 8775 8776This macro prints nothing if @command{configure} is run with the 8777@option{--quiet} or @option{--silent} option. 8778@end defmac 8779 8780@defmac AC_MSG_NOTICE (@var{message}) 8781@acindex{MSG_NOTICE} 8782Deliver the @var{message} to the user. It is useful mainly to print a 8783general description of the overall purpose of a group of feature checks, 8784e.g., 8785 8786@example 8787AC_MSG_NOTICE([checking if stack overflow is detectable]) 8788@end example 8789 8790This macro prints nothing if @command{configure} is run with the 8791@option{--quiet} or @option{--silent} option. 8792@end defmac 8793 8794@defmac AC_MSG_ERROR (@var{error-description}, @ovar{exit-status}) 8795@acindex{MSG_ERROR} 8796Notify the user of an error that prevents @command{configure} from 8797completing. This macro prints an error message to the standard error 8798output and exits @command{configure} with @var{exit-status} (1 by default). 8799@var{error-description} should be something like @samp{invalid value 8800$HOME for \$HOME}. 8801 8802The @var{error-description} should start with a lower-case letter, and 8803``cannot'' is preferred to ``can't''. 8804@end defmac 8805 8806@defmac AC_MSG_FAILURE (@var{error-description}, @ovar{exit-status}) 8807@acindex{MSG_FAILURE} 8808This @code{AC_MSG_ERROR} wrapper notifies the user of an error that 8809prevents @command{configure} from completing @emph{and} that additional 8810details are provided in @file{config.log}. This is typically used when 8811abnormal results are found during a compilation. 8812@end defmac 8813 8814@defmac AC_MSG_WARN (@var{problem-description}) 8815@acindex{MSG_WARN} 8816Notify the @command{configure} user of a possible problem. This macro 8817prints the message to the standard error output; @command{configure} 8818continues running afterward, so macros that call @code{AC_MSG_WARN} should 8819provide a default (back-up) behavior for the situations they warn about. 8820@var{problem-description} should be something like @samp{ln -s seems to 8821make hard links}. 8822@end defmac 8823 8824 8825 8826@c ====================================================== Programming in M4. 8827 8828@node Programming in M4 8829@chapter Programming in M4 8830@cindex M4 8831 8832Autoconf is written on top of two layers: @dfn{M4sugar}, which provides 8833convenient macros for pure M4 programming, and @dfn{M4sh}, which 8834provides macros dedicated to shell script generation. 8835 8836As of this version of Autoconf, these two layers are still experimental, 8837and their interface might change in the future. As a matter of fact, 8838@emph{anything that is not documented must not be used}. 8839 8840@menu 8841* M4 Quotation:: Protecting macros from unwanted expansion 8842* Using autom4te:: The Autoconf executables backbone 8843* Programming in M4sugar:: Convenient pure M4 macros 8844* Programming in M4sh:: Common shell Constructs 8845* File Descriptor Macros:: File descriptor macros for input and output 8846@end menu 8847 8848@node M4 Quotation 8849@section M4 Quotation 8850@cindex M4 quotation 8851@cindex quotation 8852 8853@c FIXME: Grmph, yet another quoting myth: quotation has *never* 8854@c prevented `expansion' of $1. Unless it refers to the expansion 8855@c of the value of $1? Anyway, we need a rewrite here@enddots{} 8856 8857The most common problem with existing macros is an improper quotation. 8858This section, which users of Autoconf can skip, but which macro writers 8859@emph{must} read, first justifies the quotation scheme that was chosen 8860for Autoconf and then ends with a rule of thumb. Understanding the 8861former helps one to follow the latter. 8862 8863@menu 8864* Active Characters:: Characters that change the behavior of M4 8865* One Macro Call:: Quotation and one macro call 8866* Quotation and Nested Macros:: Macros calling macros 8867* Changequote is Evil:: Worse than INTERCAL: M4 + changequote 8868* Quadrigraphs:: Another way to escape special characters 8869* Quotation Rule Of Thumb:: One parenthesis, one quote 8870@end menu 8871 8872@node Active Characters 8873@subsection Active Characters 8874 8875To fully understand where proper quotation is important, you first need 8876to know what the special characters are in Autoconf: @samp{#} introduces 8877a comment inside which no macro expansion is performed, @samp{,} 8878separates arguments, @samp{[} and @samp{]} are the quotes themselves, 8879and finally @samp{(} and @samp{)} (which M4 tries to match by 8880pairs). 8881 8882In order to understand the delicate case of macro calls, we first have 8883to present some obvious failures. Below they are ``obvious-ified'', 8884but when you find them in real life, they are usually in disguise. 8885 8886Comments, introduced by a hash and running up to the newline, are opaque 8887tokens to the top level: active characters are turned off, and there is 8888no macro expansion: 8889 8890@example 8891# define([def], ine) 8892@result{}# define([def], ine) 8893@end example 8894 8895Each time there can be a macro expansion, there is a quotation 8896expansion, i.e., one level of quotes is stripped: 8897 8898@example 8899int tab[10]; 8900@result{}int tab10; 8901[int tab[10];] 8902@result{}int tab[10]; 8903@end example 8904 8905Without this in mind, the reader might try hopelessly to use her macro 8906@code{array}: 8907 8908@example 8909define([array], [int tab[10];]) 8910array 8911@result{}int tab10; 8912[array] 8913@result{}array 8914@end example 8915 8916@noindent 8917How can you correctly output the intended results@footnote{Using 8918@code{defn}.}? 8919 8920 8921@node One Macro Call 8922@subsection One Macro Call 8923 8924Let's proceed on the interaction between active characters and macros 8925with this small macro, which just returns its first argument: 8926 8927@example 8928define([car], [$1]) 8929@end example 8930 8931@noindent 8932The two pairs of quotes above are not part of the arguments of 8933@code{define}; rather, they are understood by the top level when it 8934tries to find the arguments of @code{define}. Therefore, assuming 8935@code{car} is not already defined, it is equivalent to write: 8936 8937@example 8938define(car, $1) 8939@end example 8940 8941@noindent 8942But, while it is acceptable for a @file{configure.ac} to avoid unnecessary 8943quotes, it is bad practice for Autoconf macros which must both be more 8944robust and also advocate perfect style. 8945 8946At the top level, there are only two possibilities: either you 8947quote or you don't: 8948 8949@example 8950car(foo, bar, baz) 8951@result{}foo 8952[car(foo, bar, baz)] 8953@result{}car(foo, bar, baz) 8954@end example 8955 8956Let's pay attention to the special characters: 8957 8958@example 8959car(#) 8960@error{}EOF in argument list 8961@end example 8962 8963The closing parenthesis is hidden in the comment; with a hypothetical 8964quoting, the top level understood it this way: 8965 8966@example 8967car([#)] 8968@end example 8969 8970@noindent 8971Proper quotation, of course, fixes the problem: 8972 8973@example 8974car([#]) 8975@result{}# 8976@end example 8977 8978Here are more examples: 8979 8980@example 8981car(foo, bar) 8982@result{}foo 8983car([foo, bar]) 8984@result{}foo, bar 8985car((foo, bar)) 8986@result{}(foo, bar) 8987car([(foo], [bar)]) 8988@result{}(foo 8989define([a], [b]) 8990@result{} 8991car(a) 8992@result{}b 8993car([a]) 8994@result{}b 8995car([[a]]) 8996@result{}a 8997car([[[a]]]) 8998@result{}[a] 8999@end example 9000 9001With this in mind, we can explore the cases where macros invoke 9002macros@enddots{} 9003 9004 9005@node Quotation and Nested Macros 9006@subsection Quotation and Nested Macros 9007 9008The examples below use the following macros: 9009 9010@example 9011define([car], [$1]) 9012define([active], [ACT, IVE]) 9013define([array], [int tab[10]]) 9014@end example 9015 9016Each additional embedded macro call introduces other possible 9017interesting quotations: 9018 9019@example 9020car(active) 9021@result{}ACT 9022car([active]) 9023@result{}ACT, IVE 9024car([[active]]) 9025@result{}active 9026@end example 9027 9028In the first case, the top level looks for the arguments of @code{car}, 9029and finds @samp{active}. Because M4 evaluates its arguments 9030before applying the macro, @samp{active} is expanded, which results in: 9031 9032@example 9033car(ACT, IVE) 9034@result{}ACT 9035@end example 9036 9037@noindent 9038In the second case, the top level gives @samp{active} as first and only 9039argument of @code{car}, which results in: 9040 9041@example 9042active 9043@result{}ACT, IVE 9044@end example 9045 9046@noindent 9047i.e., the argument is evaluated @emph{after} the macro that invokes it. 9048In the third case, @code{car} receives @samp{[active]}, which results in: 9049 9050@example 9051[active] 9052@result{}active 9053@end example 9054 9055@noindent 9056exactly as we already saw above. 9057 9058The example above, applied to a more realistic example, gives: 9059 9060@example 9061car(int tab[10];) 9062@result{}int tab10; 9063car([int tab[10];]) 9064@result{}int tab10; 9065car([[int tab[10];]]) 9066@result{}int tab[10]; 9067@end example 9068 9069@noindent 9070Huh? The first case is easily understood, but why is the second wrong, 9071and the third right? To understand that, you must know that after 9072M4 expands a macro, the resulting text is immediately subjected 9073to macro expansion and quote removal. This means that the quote removal 9074occurs twice---first before the argument is passed to the @code{car} 9075macro, and second after the @code{car} macro expands to the first 9076argument. 9077 9078As the author of the Autoconf macro @code{car}, you then consider it to 9079be incorrect that your users have to double-quote the arguments of 9080@code{car}, so you ``fix'' your macro. Let's call it @code{qar} for 9081quoted car: 9082 9083@example 9084define([qar], [[$1]]) 9085@end example 9086 9087@noindent 9088and check that @code{qar} is properly fixed: 9089 9090@example 9091qar([int tab[10];]) 9092@result{}int tab[10]; 9093@end example 9094 9095@noindent 9096Ahhh! That's much better. 9097 9098But note what you've done: now that the arguments are literal strings, 9099if the user wants to use the results of expansions as arguments, she has 9100to use an @emph{unquoted} macro call: 9101 9102@example 9103qar(active) 9104@result{}ACT 9105@end example 9106 9107@noindent 9108where she wanted to reproduce what she used to do with @code{car}: 9109 9110@example 9111car([active]) 9112@result{}ACT, IVE 9113@end example 9114 9115@noindent 9116Worse yet: she wants to use a macro that produces a set of @code{cpp} 9117macros: 9118 9119@example 9120define([my_includes], [#include <stdio.h>]) 9121car([my_includes]) 9122@result{}#include <stdio.h> 9123qar(my_includes) 9124@error{}EOF in argument list 9125@end example 9126 9127This macro, @code{qar}, because it double quotes its arguments, forces 9128its users to leave their macro calls unquoted, which is dangerous. 9129Commas and other active symbols are interpreted by M4 before 9130they are given to the macro, often not in the way the users expect. 9131Also, because @code{qar} behaves differently from the other macros, 9132it's an exception that should be avoided in Autoconf. 9133 9134@node Changequote is Evil 9135@subsection @code{changequote} is Evil 9136@cindex @code{changequote} 9137 9138The temptation is often high to bypass proper quotation, in particular 9139when it's late at night. Then, many experienced Autoconf hackers 9140finally surrender to the dark side of the force and use the ultimate 9141weapon: @code{changequote}. 9142 9143The M4 builtin @code{changequote} belongs to a set of primitives that 9144allow one to adjust the syntax of the language to adjust it to one's 9145needs. For instance, by default M4 uses @samp{`} and @samp{'} as 9146quotes, but in the context of shell programming (and actually of most 9147programming languages), that's about the worst choice one can make: 9148because of strings and back-quoted expressions in shell code (such as 9149@samp{'this'} and @samp{`that`}), because of literal characters in usual 9150programming languages (as in @samp{'0'}), there are many unbalanced 9151@samp{`} and @samp{'}. Proper M4 quotation then becomes a nightmare, if 9152not impossible. In order to make M4 useful in such a context, its 9153designers have equipped it with @code{changequote}, which makes it 9154possible to choose another pair of quotes. M4sugar, M4sh, Autoconf, and 9155Autotest all have chosen to use @samp{[} and @samp{]}. Not especially 9156because they are unlikely characters, but @emph{because they are 9157characters unlikely to be unbalanced}. 9158 9159There are other magic primitives, such as @code{changecom} to specify 9160what syntactic forms are comments (it is common to see 9161@samp{changecom(<!--, -->)} when M4 is used to produce HTML pages), 9162@code{changeword} and @code{changesyntax} to change other syntactic 9163details (such as the character to denote the @var{n}th argument, @samp{$} by 9164default, the parenthesis around arguments, etc.). 9165 9166These primitives are really meant to make M4 more useful for specific 9167domains: they should be considered like command line options: 9168@option{--quotes}, @option{--comments}, @option{--words}, and 9169@option{--syntax}. Nevertheless, they are implemented as M4 builtins, as 9170it makes M4 libraries self contained (no need for additional options). 9171 9172There lies the problem@enddots{} 9173 9174@sp 1 9175 9176The problem is that it is then tempting to use them in the middle of an 9177M4 script, as opposed to its initialization. This, if not carefully 9178thought out, can lead to disastrous effects: @emph{you are changing the 9179language in the middle of the execution}. Changing and restoring the 9180syntax is often not enough: if you happened to invoke macros in between, 9181these macros are lost, as the current syntax is probably not 9182the one they were implemented with. 9183 9184@c FIXME: I've been looking for a short, real case example, but I 9185@c lost them all :( 9186 9187 9188@node Quadrigraphs 9189@subsection Quadrigraphs 9190@cindex quadrigraphs 9191@cindex @samp{@@S|@@} 9192@cindex @samp{@@&t@@} 9193@c Info cannot handle `:' in index entries. 9194@c @cindex @samp{@@<:@@} 9195@c @cindex @samp{@@:>@@} 9196@c @cindex @samp{@@%:@@} 9197 9198When writing an Autoconf macro you may occasionally need to generate 9199special characters that are difficult to express with the standard 9200Autoconf quoting rules. For example, you may need to output the regular 9201expression @samp{[^[]}, which matches any character other than @samp{[}. 9202This expression contains unbalanced brackets so it cannot be put easily 9203into an M4 macro. 9204 9205You can work around this problem by using one of the following 9206@dfn{quadrigraphs}: 9207 9208@table @samp 9209@item @@<:@@ 9210@samp{[} 9211@item @@:>@@ 9212@samp{]} 9213@item @@S|@@ 9214@samp{$} 9215@item @@%:@@ 9216@samp{#} 9217@item @@&t@@ 9218Expands to nothing. 9219@end table 9220 9221Quadrigraphs are replaced at a late stage of the translation process, 9222after @command{m4} is run, so they do not get in the way of M4 quoting. 9223For example, the string @samp{^@@<:@@}, independently of its quotation, 9224appears as @samp{^[} in the output. 9225 9226The empty quadrigraph can be used: 9227 9228@itemize @minus 9229@item to mark trailing spaces explicitly 9230 9231Trailing spaces are smashed by @command{autom4te}. This is a feature. 9232 9233@item to produce other quadrigraphs 9234 9235For instance @samp{@@<@@&t@@:@@} produces @samp{@@<:@@}. 9236 9237@item to escape @emph{occurrences} of forbidden patterns 9238 9239For instance you might want to mention @code{AC_FOO} in a comment, while 9240still being sure that @command{autom4te} still catches unexpanded 9241@samp{AC_*}. Then write @samp{AC@@&t@@_FOO}. 9242@end itemize 9243 9244The name @samp{@@&t@@} was suggested by Paul Eggert: 9245 9246@quotation 9247I should give some credit to the @samp{@@&t@@} pun. The @samp{&} is my 9248own invention, but the @samp{t} came from the source code of the 9249@sc{algol68c} compiler, written by Steve Bourne (of Bourne shell fame), 9250and which used @samp{mt} to denote the empty string. In C, it would 9251have looked like something like: 9252 9253@example 9254char const mt[] = ""; 9255@end example 9256 9257@noindent 9258but of course the source code was written in Algol 68. 9259 9260I don't know where he got @samp{mt} from: it could have been his own 9261invention, and I suppose it could have been a common pun around the 9262Cambridge University computer lab at the time. 9263@end quotation 9264 9265@node Quotation Rule Of Thumb 9266@subsection Quotation Rule Of Thumb 9267 9268To conclude, the quotation rule of thumb is: 9269 9270@center @emph{One pair of quotes per pair of parentheses.} 9271 9272Never over-quote, never under-quote, in particular in the definition of 9273macros. In the few places where the macros need to use brackets 9274(usually in C program text or regular expressions), properly quote 9275@emph{the arguments}! 9276 9277It is common to read Autoconf programs with snippets like: 9278 9279@example 9280AC_TRY_LINK( 9281changequote(<<, >>)dnl 9282<<#include <time.h> 9283#ifndef tzname /* For SGI. */ 9284extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 9285#endif>>, 9286changequote([, ])dnl 9287[atoi (*tzname);], ac_cv_var_tzname=yes, ac_cv_var_tzname=no) 9288@end example 9289 9290@noindent 9291which is incredibly useless since @code{AC_TRY_LINK} is @emph{already} 9292double quoting, so you just need: 9293 9294@example 9295AC_TRY_LINK( 9296[#include <time.h> 9297#ifndef tzname /* For SGI. */ 9298extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 9299#endif], 9300 [atoi (*tzname);], 9301 [ac_cv_var_tzname=yes], 9302 [ac_cv_var_tzname=no]) 9303@end example 9304 9305@noindent 9306The M4-fluent reader might note that these two examples are rigorously 9307equivalent, since M4 swallows both the @samp{changequote(<<, >>)} 9308and @samp{<<} @samp{>>} when it @dfn{collects} the arguments: these 9309quotes are not part of the arguments! 9310 9311Simplified, the example above is just doing this: 9312 9313@example 9314changequote(<<, >>)dnl 9315<<[]>> 9316changequote([, ])dnl 9317@end example 9318 9319@noindent 9320instead of simply: 9321 9322@example 9323[[]] 9324@end example 9325 9326With macros that do not double quote their arguments (which is the 9327rule), double-quote the (risky) literals: 9328 9329@example 9330AC_LINK_IFELSE([AC_LANG_PROGRAM( 9331[[#include <time.h> 9332#ifndef tzname /* For SGI. */ 9333extern char *tzname[]; /* RS6000 and others reject char **tzname. */ 9334#endif]], 9335 [atoi (*tzname);])], 9336 [ac_cv_var_tzname=yes], 9337 [ac_cv_var_tzname=no]) 9338@end example 9339 9340Please note that the macro @code{AC_TRY_LINK} is obsolete, so you really 9341should be using @code{AC_LINK_IFELSE} instead. 9342 9343@xref{Quadrigraphs}, for what to do if you run into a hopeless case 9344where quoting does not suffice. 9345 9346When you create a @command{configure} script using newly written macros, 9347examine it carefully to check whether you need to add more quotes in 9348your macros. If one or more words have disappeared in the M4 9349output, you need more quotes. When in doubt, quote. 9350 9351However, it's also possible to put on too many layers of quotes. If 9352this happens, the resulting @command{configure} script may contain 9353unexpanded macros. The @command{autoconf} program checks for this problem 9354by looking for the string @samp{AC_} in @file{configure}. However, this 9355heuristic does not work in general: for example, it does not catch 9356overquoting in @code{AC_DEFINE} descriptions. 9357 9358 9359@c ---------------------------------------- Using autom4te 9360 9361@node Using autom4te 9362@section Using @command{autom4te} 9363 9364The Autoconf suite, including M4sugar, M4sh, and Autotest, in addition 9365to Autoconf per se, heavily rely on M4. All these different uses 9366revealed common needs factored into a layer over M4: 9367@command{autom4te}@footnote{ 9368@c 9369Yet another great name from Lars J. Aas. 9370@c 9371}. 9372 9373@command{autom4te} is a preprocessor that is like @command{m4}. 9374It supports M4 extensions designed for use in tools like Autoconf. 9375 9376@menu 9377* autom4te Invocation:: A @acronym{GNU} M4 wrapper 9378* Customizing autom4te:: Customizing the Autoconf package 9379@end menu 9380 9381@node autom4te Invocation 9382@subsection Invoking @command{autom4te} 9383 9384The command line arguments are modeled after M4's: 9385 9386@example 9387autom4te @var{options} @var{files} 9388@end example 9389 9390@noindent 9391@evindex M4 9392where the @var{files} are directly passed to @command{m4}. By default, 9393@acronym{GNU} M4 is found during configuration, but the environment 9394variable 9395@env{M4} can be set to tell @command{autom4te} where to look. In addition 9396to the regular expansion, it handles the replacement of the quadrigraphs 9397(@pxref{Quadrigraphs}), and of @samp{__oline__}, the current line in the 9398output. It supports an extended syntax for the @var{files}: 9399 9400@table @file 9401@item @var{file}.m4f 9402This file is an M4 frozen file. Note that @emph{all the previous files 9403are ignored}. See the option @option{--melt} for the rationale. 9404 9405@item @var{file}? 9406If found in the library path, the @var{file} is included for expansion, 9407otherwise it is ignored instead of triggering a failure. 9408@end table 9409 9410@sp 1 9411 9412Of course, it supports the Autoconf common subset of options: 9413 9414@table @option 9415@item --help 9416@itemx -h 9417Print a summary of the command line options and exit. 9418 9419@item --version 9420@itemx -V 9421Print the version number of Autoconf and exit. 9422 9423@item --verbose 9424@itemx -v 9425Report processing steps. 9426 9427@item --debug 9428@itemx -d 9429Don't remove the temporary files and be even more verbose. 9430 9431@item --include=@var{dir} 9432@itemx -I @var{dir} 9433Also look for input files in @var{dir}. Multiple invocations 9434accumulate. 9435 9436@item --output=@var{file} 9437@itemx -o @var{file} 9438Save output (script or trace) to @var{file}. The file @option{-} stands 9439for the standard output. 9440@end table 9441 9442@sp 1 9443 9444As an extension of @command{m4}, it includes the following options: 9445 9446@table @option 9447@item --warnings=@var{category} 9448@itemx -W @var{category} 9449@evindex WARNINGS 9450@c FIXME: Point to the M4sugar macros, not Autoconf's. 9451Report the warnings related to @var{category} (which can actually be a 9452comma separated list). @xref{Reporting Messages}, macro 9453@code{AC_DIAGNOSE}, for a comprehensive list of categories. Special 9454values include: 9455 9456@table @samp 9457@item all 9458report all the warnings 9459 9460@item none 9461report none 9462 9463@item error 9464treats warnings as errors 9465 9466@item no-@var{category} 9467disable warnings falling into @var{category} 9468@end table 9469 9470Warnings about @samp{syntax} are enabled by default, and the environment 9471variable @env{WARNINGS}, a comma separated list of categories, is 9472honored. @samp{autom4te -W @var{category}} actually 9473behaves as if you had run: 9474 9475@example 9476autom4te --warnings=syntax,$WARNINGS,@var{category} 9477@end example 9478 9479@noindent 9480For example, if you want to disable defaults and @env{WARNINGS} 9481of @command{autom4te}, but enable the warnings about obsolete 9482constructs, you would use @option{-W none,obsolete}. 9483 9484@cindex Back trace 9485@cindex Macro invocation stack 9486@command{autom4te} displays a back trace for errors, but not for 9487warnings; if you want them, just pass @option{-W error}. 9488 9489@item --melt 9490@itemx -M 9491Do not use frozen files. Any argument @code{@var{file}.m4f} is 9492replaced by @code{@var{file}.m4}. This helps tracing the macros which 9493are executed only when the files are frozen, typically 9494@code{m4_define}. For instance, running: 9495 9496@example 9497autom4te --melt 1.m4 2.m4f 3.m4 4.m4f input.m4 9498@end example 9499 9500@noindent 9501is roughly equivalent to running: 9502 9503@example 9504m4 1.m4 2.m4 3.m4 4.m4 input.m4 9505@end example 9506 9507@noindent 9508while 9509 9510@example 9511autom4te 1.m4 2.m4f 3.m4 4.m4f input.m4 9512@end example 9513 9514@noindent 9515is equivalent to: 9516 9517@example 9518m4 --reload-state=4.m4f input.m4 9519@end example 9520 9521@item --freeze 9522@itemx -f 9523Produce a frozen state file. @command{autom4te} freezing is stricter 9524than M4's: it must produce no warnings, and no output other than empty 9525lines (a line with white space is @emph{not} empty) and comments 9526(starting with @samp{#}). Unlike @command{m4}'s similarly-named option, 9527this option takes no argument: 9528 9529@example 9530autom4te 1.m4 2.m4 3.m4 --freeze --output=3.m4f 9531@end example 9532 9533@noindent 9534corresponds to 9535 9536@example 9537m4 1.m4 2.m4 3.m4 --freeze-state=3.m4f 9538@end example 9539 9540@item --mode=@var{octal-mode} 9541@itemx -m @var{octal-mode} 9542Set the mode of the non-traces output to @var{octal-mode}; by default 9543@samp{0666}. 9544@end table 9545 9546@sp 1 9547 9548@cindex @file{autom4te.cache} 9549As another additional feature over @command{m4}, @command{autom4te} 9550caches its results. @acronym{GNU} M4 is able to produce a regular 9551output and traces at the same time. Traces are heavily used in the 9552@acronym{GNU} Build System: @command{autoheader} uses them to build 9553@file{config.h.in}, @command{autoreconf} to determine what 9554@acronym{GNU} Build System components are used, @command{automake} to 9555``parse'' @file{configure.ac} etc. To avoid recomputation, 9556traces are cached while performing regular expansion, 9557and conversely. This cache is (actually, the caches are) stored in 9558the directory @file{autom4te.cache}. @emph{It can safely be removed} 9559at any moment (especially if for some reason @command{autom4te} 9560considers it is trashed). 9561 9562@table @option 9563@item --cache=@var{directory} 9564@itemx -C @var{directory} 9565Specify the name of the directory where the result should be cached. 9566Passing an empty value disables caching. Be sure to pass a relative 9567file name, as for the time being, global caches are not supported. 9568 9569@item --no-cache 9570Don't cache the results. 9571 9572@item --force 9573@itemx -f 9574If a cache is used, consider it obsolete (but update it anyway). 9575@end table 9576 9577@sp 1 9578 9579Because traces are so important to the @acronym{GNU} Build System, 9580@command{autom4te} provides high level tracing features as compared to 9581M4, and helps exploiting the cache: 9582 9583@table @option 9584@item --trace=@var{macro}[:@var{format}] 9585@itemx -t @var{macro}[:@var{format}] 9586Trace the invocations of @var{macro} according to the @var{format}. 9587Multiple @option{--trace} arguments can be used to list several macros. 9588Multiple @option{--trace} arguments for a single macro are not 9589cumulative; instead, you should just make @var{format} as long as 9590needed. 9591 9592The @var{format} is a regular string, with newlines if desired, and 9593several special escape codes. It defaults to @samp{$f:$l:$n:$%}. It can 9594use the following special escapes: 9595 9596@table @samp 9597@item $$ 9598The character @samp{$}. 9599 9600@item $f 9601The file name from which @var{macro} is called. 9602 9603@item $l 9604The line number from which @var{macro} is called. 9605 9606@item $d 9607The depth of the @var{macro} call. This is an M4 technical detail that 9608you probably don't want to know about. 9609 9610@item $n 9611The name of the @var{macro}. 9612 9613@item $@var{num} 9614The @var{num}th argument of the call to @var{macro}. 9615 9616@item $@@ 9617@itemx $@var{sep}@@ 9618@itemx $@{@var{separator}@}@@ 9619All the arguments passed to @var{macro}, separated by the character 9620@var{sep} or the string @var{separator} (@samp{,} by default). Each 9621argument is quoted, i.e., enclosed in a pair of square brackets. 9622 9623@item $* 9624@itemx $@var{sep}* 9625@itemx $@{@var{separator}@}* 9626As above, but the arguments are not quoted. 9627 9628@item $% 9629@itemx $@var{sep}% 9630@itemx $@{@var{separator}@}% 9631As above, but the arguments are not quoted, all new line characters in 9632the arguments are smashed, and the default separator is @samp{:}. 9633 9634The escape @samp{$%} produces single-line trace outputs (unless you put 9635newlines in the @samp{separator}), while @samp{$@@} and @samp{$*} do 9636not. 9637@end table 9638 9639@xref{autoconf Invocation}, for examples of trace uses. 9640 9641@item --preselect=@var{macro} 9642@itemx -p @var{macro} 9643Cache the traces of @var{macro}, but do not enable traces. This is 9644especially important to save CPU cycles in the future. For instance, 9645when invoked, @command{autoconf} preselects all the macros that 9646@command{autoheader}, @command{automake}, @command{autoreconf}, etc., 9647trace, so that running @command{m4} is not needed to trace them: the 9648cache suffices. This results in a huge speed-up. 9649@end table 9650 9651@sp 1 9652 9653@cindex Autom4te Library 9654Finally, @command{autom4te} introduces the concept of @dfn{Autom4te 9655libraries}. They consists in a powerful yet extremely simple feature: 9656sets of combined command line arguments: 9657 9658@table @option 9659@item --language=@var{language} 9660@itemx -l @var{language} 9661Use the @var{language} Autom4te library. Current languages include: 9662 9663@table @code 9664@item M4sugar 9665create M4sugar output. 9666 9667@item M4sh 9668create M4sh executable shell scripts. 9669 9670@item Autotest 9671create Autotest executable test suites. 9672 9673@item Autoconf-without-aclocal-m4 9674create Autoconf executable configure scripts without 9675reading @file{aclocal.m4}. 9676 9677@item Autoconf 9678create Autoconf executable configure scripts. This language inherits 9679all the characteristics of @code{Autoconf-without-aclocal-m4} and 9680additionally reads @file{aclocal.m4}. 9681@end table 9682 9683@item --prepend-include=@var{dir} 9684@item -B @var{dir} 9685Prepend directory @var{dir} to the search path. This is used to include 9686the language-specific files before any third-party macros. 9687 9688@end table 9689 9690@cindex @file{autom4te.cfg} 9691As an example, if Autoconf is installed in its default location, 9692@file{/usr/local}, the command @samp{autom4te -l m4sugar foo.m4} is 9693strictly equivalent to the command: 9694 9695@example 9696autom4te --prepend-include /usr/local/share/autoconf \ 9697 m4sugar/m4sugar.m4f --warnings syntax foo.m4 9698@end example 9699 9700@noindent 9701Recursive expansion applies here: the command @samp{autom4te -l m4sh foo.m4} 9702is the same as @samp{autom4te --language M4sugar m4sugar/m4sh.m4f 9703foo.m4}, i.e.: 9704 9705@example 9706autom4te --prepend-include /usr/local/share/autoconf \ 9707 m4sugar/m4sugar.m4f m4sugar/m4sh.m4f --mode 777 foo.m4 9708@end example 9709 9710@noindent 9711The definition of the languages is stored in @file{autom4te.cfg}. 9712 9713@node Customizing autom4te 9714@subsection Customizing @command{autom4te} 9715 9716One can customize @command{autom4te} via @file{~/.autom4te.cfg} (i.e., 9717as found in the user home directory), and @file{./.autom4te.cfg} (i.e., 9718as found in the directory from which @command{autom4te} is run). The 9719order is first reading @file{autom4te.cfg}, then @file{~/.autom4te.cfg}, 9720then @file{./.autom4te.cfg}, and finally the command line arguments. 9721 9722In these text files, comments are introduced with @code{#}, and empty 9723lines are ignored. Customization is performed on a per-language basis, 9724wrapped in between a @samp{begin-language: "@var{language}"}, 9725@samp{end-language: "@var{language}"} pair. 9726 9727Customizing a language stands for appending options (@pxref{autom4te 9728Invocation}) to the current definition of the language. Options, and 9729more generally arguments, are introduced by @samp{args: 9730@var{arguments}}. You may use the traditional shell syntax to quote the 9731@var{arguments}. 9732 9733As an example, to disable Autoconf caches (@file{autom4te.cache}) 9734globally, include the following lines in @file{~/.autom4te.cfg}: 9735 9736@verbatim 9737## ------------------ ## 9738## User Preferences. ## 9739## ------------------ ## 9740 9741begin-language: "Autoconf-without-aclocal-m4" 9742args: --no-cache 9743end-language: "Autoconf-without-aclocal-m4" 9744@end verbatim 9745 9746 9747@node Programming in M4sugar 9748@section Programming in M4sugar 9749 9750@cindex M4sugar 9751M4 by itself provides only a small, but sufficient, set of all-purpose 9752macros. M4sugar introduces additional generic macros. Its name was 9753coined by Lars J. Aas: ``Readability And Greater Understanding Stands 4 9754M4sugar''. 9755 9756@menu 9757* Redefined M4 Macros:: M4 builtins changed in M4sugar 9758* Looping constructs:: Iteration in M4 9759* Evaluation Macros:: More quotation and evaluation control 9760* Text processing Macros:: String manipulation in M4 9761* Forbidden Patterns:: Catching unexpanded macros 9762@end menu 9763 9764@node Redefined M4 Macros 9765@subsection Redefined M4 Macros 9766 9767@msindex{builtin} 9768@msindex{decr} 9769@msindex{define} 9770@msindex{dumpdef} 9771@msindex{errprint} 9772@msindex{esyscmd} 9773@msindex{eval} 9774@msindex{format} 9775@msindex{ifdef} 9776@msindex{incr} 9777@msindex{index} 9778@msindex{indir} 9779@msindex{len} 9780@msindex{pushdef} 9781@msindex{shift} 9782@msindex{substr} 9783@msindex{syscmd} 9784@msindex{sysval} 9785@msindex{translit} 9786@msindex{undefine} 9787With a few exceptions, all the M4 native macros are moved in the 9788@samp{m4_} pseudo-namespace, e.g., M4sugar renames @code{define} as 9789@code{m4_define} etc. 9790 9791Some M4 macros are redefined, and are slightly incompatible with their 9792native equivalent. 9793 9794@defmac dnl 9795@msindex{dnl} 9796This macro kept its original name: no @code{m4_dnl} is defined. 9797@end defmac 9798 9799@defmac m4_defn (@var{macro}) 9800@msindex{defn} 9801Unlike the M4 builtin, this macro fails if @var{macro} is not 9802defined. See @code{m4_undefine}. 9803@end defmac 9804 9805@defmac m4_exit (@var{exit-status}) 9806@msindex{exit} 9807This macro corresponds to @code{m4exit}. 9808@end defmac 9809 9810@defmac m4_if (@var{comment}) 9811@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @ovar{not-equal}) 9812@defmacx m4_if (@var{string-1}, @var{string-2}, @var{equal}, @dots{}) 9813@msindex{if} 9814This macro corresponds to @code{ifelse}. 9815@end defmac 9816 9817@defmac m4_include (@var{file}) 9818@defmacx m4_sinclude (@var{file}) 9819@msindex{include} 9820@msindex{sinclude} 9821Like the M4 builtins, but warn against multiple inclusions of @var{file}. 9822@end defmac 9823 9824@defmac m4_bpatsubst (@var{string}, @var{regexp}, @ovar{replacement}) 9825@msindex{bpatsubst} 9826This macro corresponds to @code{patsubst}. The name @code{m4_patsubst} 9827is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will 9828provide extended regular expression syntax via @code{epatsubst}. 9829@end defmac 9830 9831@defmac m4_popdef (@var{macro}) 9832@msindex{popdef} 9833Unlike the M4 builtin, this macro fails if @var{macro} is not 9834defined. See @code{m4_undefine}. 9835@end defmac 9836 9837@defmac m4_bregexp (@var{string}, @var{regexp}, @ovar{replacement}) 9838@msindex{bregexp} 9839This macro corresponds to @code{regexp}. The name @code{m4_regexp} 9840is kept for future versions of M4sh, on top of @acronym{GNU} M4 which will 9841provide extended regular expression syntax via @code{eregexp}. 9842@end defmac 9843 9844@defmac m4_wrap (@var{text}) 9845@msindex{wrap} 9846This macro corresponds to @code{m4wrap}. 9847 9848Posix requires arguments of multiple @code{m4wrap} calls to be 9849reprocessed at @acronym{EOF} in the same order as the original calls. 9850@acronym{GNU} M4 versions through 1.4.x, however, reprocess them in 9851reverse order. Your code should not depend on the order. 9852 9853Also, Posix requires @code{m4wrap} to ignore its second and succeeding 9854arguments, but @acronym{GNU} M4 versions through 1.4.x concatenate the 9855arguments with intervening spaces. Your code should not pass more than 9856one argument. 9857 9858You are encouraged to end @var{text} with @samp{[]}, to avoid unexpected 9859token pasting between consecutive invocations of @code{m4_wrap}, as in: 9860 9861@example 9862m4_define([foo], [bar]) 9863m4_define([foofoo], [OUCH]) 9864m4_wrap([foo]) 9865m4_wrap([foo]) 9866@result{}OUCH 9867@end example 9868@end defmac 9869 9870@defmac m4_undefine (@var{macro}) 9871@msindex{undefine} 9872Unlike the M4 builtin, this macro fails if @var{macro} is not 9873defined. Use 9874 9875@example 9876m4_ifdef([@var{macro}], [m4_undefine([@var{macro}])]) 9877@end example 9878 9879@noindent 9880to recover the behavior of the builtin. 9881@end defmac 9882 9883@defmac m4_maketemp (@var{template}) 9884@defmacx m4_mkstemp (@var{template}) 9885@msindex{maketemp} 9886@msindex{mkstemp} 9887Posix requires @code{maketemp} to replace the trailing @samp{X} 9888characters in @var{template} with the process id, without regards to the 9889existence of a file by that name, but this a security hole. When this 9890was pointed out to the Posix folks, they agreed to invent a new macro 9891@code{mkstemp} that always creates a uniquely named file, but not all 9892versions of @acronym{GNU} M4 support the new macro. In M4sugar, 9893@code{m4_maketemp} and @code{m4_mkstemp} are synonyms for each other, 9894and both have the secure semantics regardless of which macro the 9895underlying M4 provides. 9896@end defmac 9897 9898 9899@node Looping constructs 9900@subsection Looping constructs 9901 9902The following macros implement loops in M4. 9903 9904@defmac m4_for (@var{var}, @var{first}, @var{last}, @ovar{step}, @var{expression}) 9905@msindex{for} 9906Loop over the numeric values between @var{first} and @var{last} 9907including bounds by increments of @var{step}. For each iteration, 9908expand @var{expression} with the numeric value assigned to @var{var}. 9909If @var{step} is omitted, it defaults to @samp{1} or @samp{-1} depending 9910on the order of the limits. If given, @var{step} has to match this 9911order. 9912@end defmac 9913 9914@defmac m4_foreach (@var{var}, @var{list}, @var{expression}) 9915@msindex{foreach} 9916Loop over the comma-separated M4 list @var{list}, assigning each value 9917to @var{var}, and expand @var{expression}. The following example 9918outputs two lines: 9919 9920@example 9921m4_foreach([myvar], [[foo], [bar, baz]], 9922 [echo myvar 9923]) 9924 9925@end example 9926@end defmac 9927 9928@defmac m4_foreach_w (@var{var}, @var{list}, @var{expression}) 9929@msindex{foreach_w} 9930Loop over the white-space-separated list @var{list}, assigning each value 9931to @var{var}, and expand @var{expression}. 9932 9933The deprecated macro @code{AC_FOREACH} is an alias of 9934@code{m4_foreach_w}. 9935@end defmac 9936 9937 9938 9939@node Evaluation Macros 9940@subsection Evaluation Macros 9941 9942The following macros give some control over the order of the evaluation 9943by adding or removing levels of quotes. They are meant for hard-core M4 9944programmers. 9945 9946@defmac m4_dquote (@var{arg1}, @dots{}) 9947@msindex{dquote} 9948Return the arguments as a quoted list of quoted arguments. 9949@end defmac 9950 9951@defmac m4_quote (@var{arg1}, @dots{}) 9952@msindex{quote} 9953Return the arguments as a single entity, i.e., wrap them into a pair of 9954quotes. 9955@end defmac 9956 9957The following example aims at emphasizing the difference between (i), not 9958using these macros, (ii), using @code{m4_quote}, and (iii), using 9959@code{m4_dquote}. 9960 9961@example 9962$ @kbd{cat example.m4} 9963# Overquote, so that quotes are visible. 9964m4_define([show], [$[]1 = [$1], $[]@@ = [$@@]]) 9965m4_define([mkargs], [1, 2, 3]) 9966m4_define([arg1], [[$1]]) 9967m4_divert(0)dnl 9968show(a, b) 9969show(m4_quote(a, b)) 9970show(m4_dquote(a, b)) 9971arg1(mkargs) 9972arg1([mkargs]) 9973arg1(m4_defn([mkargs])) 9974arg1(m4_quote(mkargs)) 9975arg1(m4_dquote(mkargs)) 9976$ @kbd{autom4te -l m4sugar example.m4} 9977$1 = a, $@@ = [a],[b] 9978$1 = a,b, $@@ = [a,b] 9979$1 = [a],[b], $@@ = [[a],[b]] 99801 9981mkargs 99821, 2, 3 99831,2,3 9984[1],[2],[3] 9985@end example 9986 9987 9988 9989@node Text processing Macros 9990@subsection Text processing Macros 9991 9992The following macros may be used to manipulate strings in M4. 9993They are not intended for casual use. 9994 9995@defmac m4_re_escape (@var{string}) 9996@msindex{re_escape} 9997Backslash-escape all characters in @var{string} that are active in 9998regexps. 9999@end defmac 10000 10001@defmac m4_tolower (@var{string}) 10002@defmacx m4_toupper (@var{string}) 10003@msindex{tolower} 10004@msindex{toupper} 10005Return @var{string} with letters converted to upper or lower case, 10006respectively. 10007@end defmac 10008 10009@defmac m4_split (@var{string}, @ovar{regexp}) 10010@msindex{split} 10011Split @var{string} into an M4 list of elements quoted by @samp{[} and 10012@samp{]}, while keeping white space at the beginning and at the end. 10013If @var{regexp} is given, use it instead of @samp{[\t ]+} for splitting. 10014If @var{string} is empty, the result is an empty list. 10015@end defmac 10016 10017@defmac m4_normalize (@var{string}) 10018@msindex{normalize} 10019Remove leading and trailing spaces and tabs, sequences of 10020backslash-then-newline, and replace multiple spaces and tabs with a 10021single space. 10022@end defmac 10023 10024@defmac m4_append (@var{macro-name}, @var{string}, @ovar{separator}) 10025@defmacx m4_append_uniq (@var{macro-name}, @var{string}, @ovar{separator}) 10026@msindex{append} 10027@msindex{append_uniq} 10028Redefine @var{macro-name} to its former contents with @var{separator} 10029and @var{string} added at the end. If @var{macro-name} was undefined 10030before (but not if it was defined but empty), then no @var{separator} is 10031added. @code{m4_append} can be used to grow strings, and 10032@code{m4_append_uniq} to grow strings without duplicating substrings. 10033@end defmac 10034 10035 10036 10037@node Forbidden Patterns 10038@subsection Forbidden Patterns 10039@cindex Forbidden patterns 10040@cindex Patterns, forbidden 10041 10042M4sugar provides a means to define suspicious patterns, patterns 10043describing tokens which should not be found in the output. For 10044instance, if an Autoconf @file{configure} script includes tokens such as 10045@samp{AC_DEFINE}, or @samp{dnl}, then most probably something went 10046wrong (typically a macro was not evaluated because of overquotation). 10047 10048M4sugar forbids all the tokens matching @samp{^m4_} and @samp{^dnl$}. 10049 10050@defmac m4_pattern_forbid (@var{pattern}) 10051@msindex{pattern_forbid} 10052Declare that no token matching @var{pattern} must be found in the output. 10053Comments are not checked; this can be a problem if, for instance, you 10054have some macro left unexpanded after an @samp{#include}. No consensus 10055is currently found in the Autoconf community, as some people consider it 10056should be valid to name macros in comments (which doesn't make sense to 10057the author of this documentation, as @samp{#}-comments should document 10058the output, not the input, documented by @samp{dnl} comments). 10059@end defmac 10060 10061Of course, you might encounter exceptions to these generic rules, for 10062instance you might have to refer to @samp{$m4_flags}. 10063 10064@defmac m4_pattern_allow (@var{pattern}) 10065@msindex{pattern_allow} 10066Any token matching @var{pattern} is allowed, including if it matches an 10067@code{m4_pattern_forbid} pattern. 10068@end defmac 10069 10070@node Programming in M4sh 10071@section Programming in M4sh 10072 10073@c FIXME: Eventually will become a chapter, as it is not related to 10074@c programming in M4 per se. 10075 10076M4sh, pronounced ``mash'', is aiming at producing portable Bourne shell 10077scripts. This name was coined by Lars J. Aas, who notes that, 10078according to the Webster's Revised Unabridged Dictionary (1913): 10079 10080@quotation 10081Mash \Mash\, n. [Akin to G. meisch, maisch, meische, maische, mash, 10082wash, and prob.@: to AS. miscian to mix. See ``Mix''.] 10083 10084@enumerate 1 10085@item 10086A mass of mixed ingredients reduced to a soft pulpy state by beating or 10087pressure@enddots{} 10088 10089@item 10090A mixture of meal or bran and water fed to animals. 10091 10092@item 10093A mess; trouble. [Obs.] --Beau.@: & Fl. 10094@end enumerate 10095@end quotation 10096 10097 10098For the time being, it is not mature enough to be widely used. 10099 10100M4sh provides portable alternatives for some common shell constructs 10101that unfortunately are not portable in practice. 10102 10103@c Deprecated, to be replaced by a better API 10104@ignore 10105@defmac AS_BASENAME (@var{file-name}) 10106@asindex{BASENAME} 10107Output the non-directory portion of @var{file-name}. For example, 10108if @code{$file} is @samp{/one/two/three}, the command 10109@code{base=`AS_BASENAME(["$file"])`} sets @code{base} to @samp{three}. 10110@end defmac 10111@end ignore 10112 10113@defmac AS_BOURNE_COMPATIBLE 10114@asindex{BOURNE_COMPATIBLE} 10115Set up the shell to be more compatible with the Bourne shell as 10116standardized by Posix, if possible. This may involve setting 10117environment variables, or setting options, or similar 10118implementation-specific actions. 10119@end defmac 10120 10121@defmac AS_CASE (@var{word}, @ovar{pattern1}, @ovar{if-matched1}, @dots{}, @ovar{default}) 10122@asindex{CASE} 10123Expand into a shell @samp{case} statement, where @var{word} is matched 10124against one or more patterns. @var{if-matched} is run if the 10125corresponding pattern matched @var{word}, else @var{default} is run. 10126@end defmac 10127 10128@defmac AS_DIRNAME (@var{file-name}) 10129@asindex{DIRNAME} 10130Output the directory portion of @var{file-name}. For example, 10131if @code{$file} is @samp{/one/two/three}, the command 10132@code{dir=`AS_DIRNAME(["$file"])`} sets @code{dir} to @samp{/one/two}. 10133@end defmac 10134 10135@defmac AS_IF (@var{test1}, @ovar{run-if-true1}, @dots{}, @ovar{run-if-false}) 10136@asindex{IF} 10137Run shell code @var{test1}. If @var{test1} exits with a zero status then 10138run shell code @var{run-if-true1}, else examine further tests. If no test 10139exits with a zero status, run shell code @var{run-if-false}, with 10140simplifications if either @var{run-if-true1} or @var{run-if-false1} 10141is empty. For example, 10142 10143@example 10144AS_IF([test "$foo" = yes], [HANDLE_FOO([yes])], 10145 [test "$foo" != no], [HANDLE_FOO([maybe])], 10146 [echo foo not specified]) 10147@end example 10148 10149@noindent 10150ensures any required macros of @code{HANDLE_FOO} 10151are expanded before the first test. 10152@end defmac 10153 10154@defmac AS_MKDIR_P (@var{file-name}) 10155@asindex{MKDIR_P} 10156Make the directory @var{file-name}, including intervening directories 10157as necessary. This is equivalent to @samp{mkdir -p @var{file-name}}, 10158except that it is portable to older versions of @command{mkdir} that 10159lack support for the @option{-p} option. Also, @code{AS_MKDIR_P} 10160succeeds if @var{file-name} is a symbolic link to an existing directory, 10161even though Posix is unclear whether @samp{mkdir -p} should 10162succeed in that case. If creation of @var{file-name} fails, exit the 10163script. 10164 10165Also see the @code{AC_PROG_MKDIR_P} macro (@pxref{Particular Programs}). 10166@end defmac 10167 10168@defmac AS_SHELL_SANITIZE 10169@asindex{SHELL_SANITIZE} 10170Initialize the shell suitably for @code{configure} scripts. This has 10171the effect of @code{AS_BOURNE_COMPATIBLE}, and sets some other 10172environment variables for predictable results from configuration tests. 10173For example, it sets @env{LC_ALL} to change to the default C locale. 10174@xref{Special Shell Variables}. 10175@end defmac 10176 10177@defmac AS_TR_CPP (@var{expression}) 10178@asindex{TR_CPP} 10179Transform @var{expression} into a valid right-hand side for a C @code{#define}. 10180For example: 10181 10182@example 10183# This outputs "#define HAVE_CHAR_P 1". 10184type="char *" 10185echo "#define AS_TR_CPP([HAVE_$type]) 1" 10186@end example 10187@end defmac 10188 10189@defmac AS_TR_SH (@var{expression}) 10190@asindex{TR_SH} 10191Transform @var{expression} into a valid shell variable name. For example: 10192 10193@example 10194# This outputs "Have it!". 10195header="sys/some file.h" 10196AS_TR_SH([HAVE_$header])=yes 10197if test "$HAVE_sys_some_file_h" = yes; then echo "Have it!"; fi 10198@end example 10199@end defmac 10200 10201@defmac AS_SET_CATFILE (@var{var}, @var{dir}, @var{file}) 10202@asindex{SET_CATFILE} 10203Set the shell variable @var{var} to @var{dir}/@var{file}, but 10204optimizing the common cases (@var{dir} or @var{file} is @samp{.}, 10205@var{file} is absolute, etc.). 10206@end defmac 10207 10208 10209@node File Descriptor Macros 10210@section File Descriptor Macros 10211@cindex input 10212@cindex standard input 10213@cindex file descriptors 10214@cindex descriptors 10215@cindex low-level output 10216@cindex output, low-level 10217 10218The following macros define file descriptors used to output messages 10219(or input values) from @file{configure} scripts. 10220For example: 10221 10222@example 10223echo "$wombats found" >&AS_MESSAGE_LOG_FD 10224echo 'Enter desired kangaroo count:' >&AS_MESSAGE_FD 10225read kangaroos <&AS_ORIGINAL_STDIN_FD` 10226@end example 10227 10228@noindent 10229However doing so is seldom needed, because Autoconf provides higher 10230level macros as described below. 10231 10232@defmac AS_MESSAGE_FD 10233@asindex{MESSAGE_FD} 10234The file descriptor for @samp{checking for...} messages and results. 10235Normally this directs messages to the standard output, however when 10236@command{configure} is run with the @option{-q} option, messages sent to 10237@code{AS_MESSAGE_FD} are discarded. 10238 10239If you want to display some messages, consider using one of the printing 10240macros (@pxref{Printing Messages}) instead. Copies of messages output 10241via these macros are also recorded in @file{config.log}. 10242@end defmac 10243 10244@defmac AS_MESSAGE_LOG_FD 10245@asindex{MESSAGE_LOG_FD} 10246 10247The file descriptor for messages logged to @file{config.log}. Macros 10248that run tools, like @code{AC_COMPILE_IFELSE} (@pxref{Running the 10249Compiler}), redirect all output to this descriptor. You may want to do 10250so if you develop such a low-level macro. 10251@end defmac 10252 10253@defmac AS_ORIGINAL_STDIN_FD 10254@asindex{ORIGINAL_STDIN_FD} 10255The file descriptor for the original standard input. 10256 10257When @command{configure} runs, it may accidentally execute an 10258interactive command that has the same name as the non-interactive meant 10259to be used or checked. If the standard input was the terminal, such 10260interactive programs would cause @command{configure} to stop, pending 10261some user input. Therefore @command{configure} redirects its standard 10262input from @file{/dev/null} during its initialization. This is not 10263normally a problem, since @command{configure} normally does not need 10264user input. 10265 10266In the extreme case where your @file{configure} script really needs to 10267obtain some values from the original standard input, you can read them 10268explicitly from @code{AS_ORIGINAL_STDIN_FD}. 10269@end defmac 10270 10271 10272@c =================================================== Writing Autoconf Macros. 10273 10274@node Writing Autoconf Macros 10275@chapter Writing Autoconf Macros 10276 10277When you write a feature test that could be applicable to more than one 10278software package, the best thing to do is encapsulate it in a new macro. 10279Here are some instructions and guidelines for writing Autoconf macros. 10280 10281@menu 10282* Macro Definitions:: Basic format of an Autoconf macro 10283* Macro Names:: What to call your new macros 10284* Reporting Messages:: Notifying @command{autoconf} users 10285* Dependencies Between Macros:: What to do when macros depend on other macros 10286* Obsoleting Macros:: Warning about old ways of doing things 10287* Coding Style:: Writing Autoconf macros @`a la Autoconf 10288@end menu 10289 10290@node Macro Definitions 10291@section Macro Definitions 10292 10293@acindex{DEFUN} 10294Autoconf macros are defined using the @code{AC_DEFUN} macro, which is 10295similar to the M4 builtin @code{m4_define} macro. In addition to 10296defining a macro, @code{AC_DEFUN} adds to it some code that is used to 10297constrain the order in which macros are called (@pxref{Prerequisite 10298Macros}). 10299 10300An Autoconf macro definition looks like this: 10301 10302@example 10303AC_DEFUN(@var{macro-name}, @var{macro-body}) 10304@end example 10305 10306You can refer to any arguments passed to the macro as @samp{$1}, 10307@samp{$2}, etc. @xref{Definitions, , How to define new macros, m4.info, 10308@acronym{GNU} M4}, for more complete information on writing M4 macros. 10309 10310Be sure to properly quote both the @var{macro-body} @emph{and} the 10311@var{macro-name} to avoid any problems if the macro happens to have 10312been previously defined. 10313 10314Each macro should have a header comment that gives its prototype, and a 10315brief description. When arguments have default values, display them in 10316the prototype. For example: 10317 10318@example 10319# AC_MSG_ERROR(ERROR, [EXIT-STATUS = 1]) 10320# -------------------------------------- 10321m4_define([AC_MSG_ERROR], 10322 [@{ AS_MESSAGE([error: $1], [2]) 10323 exit m4_default([$2], [1]); @}]) 10324@end example 10325 10326Comments about the macro should be left in the header comment. Most 10327other comments make their way into @file{configure}, so just keep 10328using @samp{#} to introduce comments. 10329 10330@cindex @code{dnl} 10331If you have some special comments about pure M4 code, comments 10332that make no sense in @file{configure} and in the header comment, then 10333use the builtin @code{dnl}: it causes M4 to discard the text 10334through the next newline. 10335 10336Keep in mind that @code{dnl} is rarely needed to introduce comments; 10337@code{dnl} is more useful to get rid of the newlines following macros 10338that produce no output, such as @code{AC_REQUIRE}. 10339 10340 10341@node Macro Names 10342@section Macro Names 10343 10344All of the Autoconf macros have all-uppercase names starting with 10345@samp{AC_} to prevent them from accidentally conflicting with other 10346text. All shell variables that they use for internal purposes have 10347mostly-lowercase names starting with @samp{ac_}. To ensure that your 10348macros don't conflict with present or future Autoconf macros, you should 10349prefix your own macro names and any shell variables they use with some 10350other sequence. Possibilities include your initials, or an abbreviation 10351for the name of your organization or software package. 10352 10353Most of the Autoconf macros' names follow a structured naming convention 10354that indicates the kind of feature check by the name. The macro names 10355consist of several words, separated by underscores, going from most 10356general to most specific. The names of their cache variables use the 10357same convention (@pxref{Cache Variable Names}, for more information on 10358them). 10359 10360The first word of the name after @samp{AC_} usually tells the category 10361of the feature being tested. Here are the categories used in Autoconf for 10362specific test macros, the kind of macro that you are more likely to 10363write. They are also used for cache variables, in all-lowercase. Use 10364them where applicable; where they're not, invent your own categories. 10365 10366@table @code 10367@item C 10368C language builtin features. 10369@item DECL 10370Declarations of C variables in header files. 10371@item FUNC 10372Functions in libraries. 10373@item GROUP 10374Posix group owners of files. 10375@item HEADER 10376Header files. 10377@item LIB 10378C libraries. 10379@item PATH 10380Absolute names of files, including programs. 10381@item PROG 10382The base names of programs. 10383@item MEMBER 10384Members of aggregates. 10385@item SYS 10386Operating system features. 10387@item TYPE 10388C builtin or declared types. 10389@item VAR 10390C variables in libraries. 10391@end table 10392 10393After the category comes the name of the particular feature being 10394tested. Any further words in the macro name indicate particular aspects 10395of the feature. For example, @code{AC_PROG_CC_STDC} checks whether the 10396C compiler supports @acronym{ISO} Standard C. 10397 10398An internal macro should have a name that starts with an underscore; 10399Autoconf internals should therefore start with @samp{_AC_}. 10400Additionally, a macro that is an internal subroutine of another macro 10401should have a name that starts with an underscore and the name of that 10402other macro, followed by one or more words saying what the internal 10403macro does. For example, @code{AC_PATH_X} has internal macros 10404@code{_AC_PATH_X_XMKMF} and @code{_AC_PATH_X_DIRECT}. 10405 10406@node Reporting Messages 10407@section Reporting Messages 10408@cindex Messages, from @command{autoconf} 10409 10410When macros statically diagnose abnormal situations, benign or fatal, 10411they should report them using these macros. For dynamic issues, i.e., 10412when @command{configure} is run, see @ref{Printing Messages}. 10413 10414@defmac AC_DIAGNOSE (@var{category}, @var{message}) 10415@acindex{DIAGNOSE} 10416Report @var{message} as a warning (or as an error if requested by the 10417user) if warnings of the @var{category} are turned on. You are 10418encouraged to use standard categories, which currently include: 10419 10420@table @samp 10421@item all 10422messages that don't fall into one of the following categories. Use of an 10423empty @var{category} is equivalent. 10424 10425@item cross 10426related to cross compilation issues. 10427 10428@item obsolete 10429use of an obsolete construct. 10430 10431@item syntax 10432dubious syntactic constructs, incorrectly ordered macro calls. 10433@end table 10434@end defmac 10435 10436@defmac AC_WARNING (@var{message}) 10437@acindex{WARNING} 10438Equivalent to @samp{AC_DIAGNOSE([syntax], @var{message})}, but you are 10439strongly encouraged to use a finer grained category. 10440@end defmac 10441 10442@defmac AC_FATAL (@var{message}) 10443@acindex{FATAL} 10444Report a severe error @var{message}, and have @command{autoconf} die. 10445@end defmac 10446 10447When the user runs @samp{autoconf -W error}, warnings from 10448@code{AC_DIAGNOSE} and @code{AC_WARNING} are reported as error, see 10449@ref{autoconf Invocation}. 10450 10451@node Dependencies Between Macros 10452@section Dependencies Between Macros 10453@cindex Dependencies between macros 10454 10455Some Autoconf macros depend on other macros having been called first in 10456order to work correctly. Autoconf provides a way to ensure that certain 10457macros are called if needed and a way to warn the user if macros are 10458called in an order that might cause incorrect operation. 10459 10460@menu 10461* Prerequisite Macros:: Ensuring required information 10462* Suggested Ordering:: Warning about possible ordering problems 10463* One-Shot Macros:: Ensuring a macro is called only once 10464@end menu 10465 10466@node Prerequisite Macros 10467@subsection Prerequisite Macros 10468@cindex Prerequisite macros 10469@cindex Macros, prerequisites 10470 10471A macro that you write might need to use values that have previously 10472been computed by other macros. For example, @code{AC_DECL_YYTEXT} 10473examines the output of @code{flex} or @code{lex}, so it depends on 10474@code{AC_PROG_LEX} having been called first to set the shell variable 10475@code{LEX}. 10476 10477Rather than forcing the user of the macros to keep track of the 10478dependencies between them, you can use the @code{AC_REQUIRE} macro to do 10479it automatically. @code{AC_REQUIRE} can ensure that a macro is only 10480called if it is needed, and only called once. 10481 10482@defmac AC_REQUIRE (@var{macro-name}) 10483@acindex{REQUIRE} 10484If the M4 macro @var{macro-name} has not already been called, call it 10485(without any arguments). Make sure to quote @var{macro-name} with 10486square brackets. @var{macro-name} must have been defined using 10487@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 10488that it has been called. 10489 10490@code{AC_REQUIRE} must be used inside a macro defined by @code{AC_DEFUN}; it 10491must not be called from the top level. 10492@end defmac 10493 10494@code{AC_REQUIRE} is often misunderstood. It really implements 10495dependencies between macros in the sense that if one macro depends upon 10496another, the latter is expanded @emph{before} the body of the 10497former. To be more precise, the required macro is expanded before 10498the outermost defined macro in the current expansion stack. 10499In particular, @samp{AC_REQUIRE([FOO])} is not replaced with the body of 10500@code{FOO}. For instance, this definition of macros: 10501 10502@example 10503@group 10504AC_DEFUN([TRAVOLTA], 10505[test "$body_temperature_in_celsius" -gt "38" && 10506 dance_floor=occupied]) 10507AC_DEFUN([NEWTON_JOHN], 10508[test "$hair_style" = "curly" && 10509 dance_floor=occupied]) 10510@end group 10511 10512@group 10513AC_DEFUN([RESERVE_DANCE_FLOOR], 10514[if date | grep '^Sat.*pm' >/dev/null 2>&1; then 10515 AC_REQUIRE([TRAVOLTA]) 10516 AC_REQUIRE([NEWTON_JOHN]) 10517fi]) 10518@end group 10519@end example 10520 10521@noindent 10522with this @file{configure.ac} 10523 10524@example 10525AC_INIT([Dance Manager], [1.0], [bug-dance@@example.org]) 10526RESERVE_DANCE_FLOOR 10527if test "$dance_floor" = occupied; then 10528 AC_MSG_ERROR([cannot pick up here, let's move]) 10529fi 10530@end example 10531 10532@noindent 10533does not leave you with a better chance to meet a kindred soul at 10534other times than Saturday night since it expands into: 10535 10536@example 10537@group 10538test "$body_temperature_in_Celsius" -gt "38" && 10539 dance_floor=occupied 10540test "$hair_style" = "curly" && 10541 dance_floor=occupied 10542fi 10543if date | grep '^Sat.*pm' >/dev/null 2>&1; then 10544 10545 10546fi 10547@end group 10548@end example 10549 10550This behavior was chosen on purpose: (i) it prevents messages in 10551required macros from interrupting the messages in the requiring macros; 10552(ii) it avoids bad surprises when shell conditionals are used, as in: 10553 10554@example 10555@group 10556if @dots{}; then 10557 AC_REQUIRE([SOME_CHECK]) 10558fi 10559@dots{} 10560SOME_CHECK 10561@end group 10562@end example 10563 10564The helper macros @code{AS_IF} and @code{AS_CASE} may be used to 10565enforce expansion of required macros outside of shell conditional 10566constructs. You are furthermore encouraged to put all @code{AC_REQUIRE} calls 10567at the beginning of a macro. You can use @code{dnl} to avoid the empty 10568lines they leave. 10569 10570@node Suggested Ordering 10571@subsection Suggested Ordering 10572@cindex Macros, ordering 10573@cindex Ordering macros 10574 10575Some macros should be run before another macro if both are called, but 10576neither @emph{requires} that the other be called. For example, a macro 10577that changes the behavior of the C compiler should be called before any 10578macros that run the C compiler. Many of these dependencies are noted in 10579the documentation. 10580 10581Autoconf provides the @code{AC_BEFORE} macro to warn users when macros 10582with this kind of dependency appear out of order in a 10583@file{configure.ac} file. The warning occurs when creating 10584@command{configure} from @file{configure.ac}, not when running 10585@command{configure}. 10586 10587For example, @code{AC_PROG_CPP} checks whether the C compiler 10588can run the C preprocessor when given the @option{-E} option. It should 10589therefore be called after any macros that change which C compiler is 10590being used, such as @code{AC_PROG_CC}. So @code{AC_PROG_CC} contains: 10591 10592@example 10593AC_BEFORE([$0], [AC_PROG_CPP])dnl 10594@end example 10595 10596@noindent 10597This warns the user if a call to @code{AC_PROG_CPP} has already occurred 10598when @code{AC_PROG_CC} is called. 10599 10600@defmac AC_BEFORE (@var{this-macro-name}, @var{called-macro-name}) 10601@acindex{BEFORE} 10602Make M4 print a warning message to the standard error output if 10603@var{called-macro-name} has already been called. @var{this-macro-name} 10604should be the name of the macro that is calling @code{AC_BEFORE}. The 10605macro @var{called-macro-name} must have been defined using 10606@code{AC_DEFUN} or else contain a call to @code{AC_PROVIDE} to indicate 10607that it has been called. 10608@end defmac 10609 10610@node One-Shot Macros 10611@subsection One-Shot Macros 10612@cindex One-shot macros 10613@cindex Macros, called once 10614 10615Some macros should be called only once, either because calling them 10616multiple time is unsafe, or because it is bad style. For instance 10617Autoconf ensures that @code{AC_CANONICAL_BUILD} and cousins 10618(@pxref{Canonicalizing}) are evaluated only once, because it makes no 10619sense to run these expensive checks more than once. Such one-shot 10620macros can be defined using @code{AC_DEFUN_ONCE}. 10621 10622@defmac AC_DEFUN_ONCE (@var{macro-name}, @var{macro-body}) 10623@acindex{DEFUN_ONCE} 10624 10625Declare macro @var{macro-name} like @code{AC_DEFUN} would (@pxref{Macro 10626Definitions}), and emit a warning any time the macro is called more than 10627once. 10628@end defmac 10629 10630Obviously it is not sensible to evaluate a macro defined by 10631@code{AC_DEFUN_ONCE} in a macro defined by @code{AC_DEFUN}. 10632Most of the time you want to use @code{AC_REQUIRE} (@pxref{Prerequisite 10633Macros}). 10634 10635@node Obsoleting Macros 10636@section Obsoleting Macros 10637@cindex Obsoleting macros 10638@cindex Macros, obsoleting 10639 10640Configuration and portability technology has evolved over the years. 10641Often better ways of solving a particular problem are developed, or 10642ad-hoc approaches are systematized. This process has occurred in many 10643parts of Autoconf. One result is that some of the macros are now 10644considered @dfn{obsolete}; they still work, but are no longer considered 10645the best thing to do, hence they should be replaced with more modern 10646macros. Ideally, @command{autoupdate} should replace the old macro calls 10647with their modern implementation. 10648 10649Autoconf provides a simple means to obsolete a macro. 10650 10651@defmac AU_DEFUN (@var{old-macro}, @var{implementation}, @ovar{message}) 10652@auindex{DEFUN} 10653Define @var{old-macro} as @var{implementation}. The only difference 10654with @code{AC_DEFUN} is that the user is warned that 10655@var{old-macro} is now obsolete. 10656 10657If she then uses @command{autoupdate}, the call to @var{old-macro} is 10658replaced by the modern @var{implementation}. @var{message} should 10659include information on what to do after running @command{autoupdate}; 10660@command{autoupdate} prints it as a warning, and includes it 10661in the updated @file{configure.ac} file. 10662 10663The details of this macro are hairy: if @command{autoconf} encounters an 10664@code{AU_DEFUN}ed macro, all macros inside its second argument are expanded 10665as usual. However, when @command{autoupdate} is run, only M4 and M4sugar 10666macros are expanded here, while all other macros are disabled and 10667appear literally in the updated @file{configure.ac}. 10668@end defmac 10669 10670@defmac AU_ALIAS (@var{old-name}, @var{new-name}) 10671@auindex{ALIAS} 10672Used if the @var{old-name} is to be replaced by a call to @var{new-macro} 10673with the same parameters. This happens for example if the macro was renamed. 10674@end defmac 10675 10676@node Coding Style 10677@section Coding Style 10678@cindex Coding style 10679 10680The Autoconf macros follow a strict coding style. You are encouraged to 10681follow this style, especially if you intend to distribute your macro, 10682either by contributing it to Autoconf itself, or via other means. 10683 10684The first requirement is to pay great attention to the quotation. For 10685more details, see @ref{Autoconf Language}, and @ref{M4 Quotation}. 10686 10687Do not try to invent new interfaces. It is likely that there is a macro 10688in Autoconf that resembles the macro you are defining: try to stick to 10689this existing interface (order of arguments, default values, etc.). We 10690@emph{are} conscious that some of these interfaces are not perfect; 10691nevertheless, when harmless, homogeneity should be preferred over 10692creativity. 10693 10694Be careful about clashes both between M4 symbols and between shell 10695variables. 10696 10697If you stick to the suggested M4 naming scheme (@pxref{Macro Names}), 10698you are unlikely to generate conflicts. Nevertheless, when you need to 10699set a special value, @emph{avoid using a regular macro name}; rather, 10700use an ``impossible'' name. For instance, up to version 2.13, the macro 10701@code{AC_SUBST} used to remember what @var{symbol} macros were already defined 10702by setting @code{AC_SUBST_@var{symbol}}, which is a regular macro name. 10703But since there is a macro named @code{AC_SUBST_FILE}, it was just 10704impossible to @samp{AC_SUBST(FILE)}! In this case, 10705@code{AC_SUBST(@var{symbol})} or @code{_AC_SUBST(@var{symbol})} should 10706have been used (yes, with the parentheses). 10707@c or better yet, high-level macros such as @code{m4_expand_once} 10708 10709No Autoconf macro should ever enter the user-variable name space; i.e., 10710except for the variables that are the actual result of running the 10711macro, all shell variables should start with @code{ac_}. In 10712addition, small macros or any macro that is likely to be embedded in 10713other macros should be careful not to use obvious names. 10714 10715@cindex @code{dnl} 10716Do not use @code{dnl} to introduce comments: most of the comments you 10717are likely to write are either header comments which are not output 10718anyway, or comments that should make their way into @file{configure}. 10719There are exceptional cases where you do want to comment special M4 10720constructs, in which case @code{dnl} is right, but keep in mind that it 10721is unlikely. 10722 10723M4 ignores the leading blanks and newlines before each argument. 10724Use this feature to 10725indent in such a way that arguments are (more or less) aligned with the 10726opening parenthesis of the macro being called. For instance, instead of 10727 10728@example 10729AC_CACHE_CHECK(for EMX OS/2 environment, 10730ac_cv_emxos2, 10731[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, [return __EMX__;])], 10732[ac_cv_emxos2=yes], [ac_cv_emxos2=no])]) 10733@end example 10734 10735@noindent 10736write 10737 10738@example 10739AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 10740[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 10741 [ac_cv_emxos2=yes], 10742 [ac_cv_emxos2=no])]) 10743@end example 10744 10745@noindent 10746or even 10747 10748@example 10749AC_CACHE_CHECK([for EMX OS/2 environment], 10750 [ac_cv_emxos2], 10751 [AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], 10752 [return __EMX__;])], 10753 [ac_cv_emxos2=yes], 10754 [ac_cv_emxos2=no])]) 10755@end example 10756 10757When using @code{AC_RUN_IFELSE} or any macro that cannot work when 10758cross-compiling, provide a pessimistic value (typically @samp{no}). 10759 10760Feel free to use various tricks to prevent auxiliary tools, such as 10761syntax-highlighting editors, from behaving improperly. For instance, 10762instead of: 10763 10764@example 10765m4_bpatsubst([$1], [$"]) 10766@end example 10767 10768@noindent 10769use 10770 10771@example 10772m4_bpatsubst([$1], [$""]) 10773@end example 10774 10775@noindent 10776so that Emacsen do not open an endless ``string'' at the first quote. 10777For the same reasons, avoid: 10778 10779@example 10780test $[#] != 0 10781@end example 10782 10783@noindent 10784and use: 10785 10786@example 10787test $[@@%:@@] != 0 10788@end example 10789 10790@noindent 10791Otherwise, the closing bracket would be hidden inside a @samp{#}-comment, 10792breaking the bracket-matching highlighting from Emacsen. Note the 10793preferred style to escape from M4: @samp{$[1]}, @samp{$[@@]}, etc. Do 10794not escape when it is unnecessary. Common examples of useless quotation 10795are @samp{[$]$1} (write @samp{$$1}), @samp{[$]var} (use @samp{$var}), 10796etc. If you add portability issues to the picture, you'll prefer 10797@samp{$@{1+"$[@@]"@}} to @samp{"[$]@@"}, and you'll prefer do something 10798better than hacking Autoconf @code{:-)}. 10799 10800When using @command{sed}, don't use @option{-e} except for indenting 10801purposes. With the @code{s} and @code{y} commands, the preferred 10802separator is @samp{/} unless @samp{/} itself might appear in the pattern 10803or replacement, in which case you should use @samp{|}, or optionally 10804@samp{,} if you know the pattern and replacement cannot contain a file 10805name. If none of these characters will do, choose a printable character 10806that cannot appear in the pattern or replacement. Characters from the 10807set @samp{"#$&'()*;<=>?`|~} are good choices if the pattern or 10808replacement might contain a file name, since they have special meaning 10809to the shell and are less likely to occur in file names. 10810 10811@xref{Macro Definitions}, for details on how to define a macro. If a 10812macro doesn't use @code{AC_REQUIRE}, is expected to never be the object 10813of an @code{AC_REQUIRE} directive, and macros required by other macros 10814inside arguments do not need to be expanded before this macro, then 10815use @code{m4_define}. In case of doubt, use @code{AC_DEFUN}. 10816All the @code{AC_REQUIRE} statements should be at the beginning of the 10817macro, and each statement should be followed by @code{dnl}. 10818 10819You should not rely on the number of arguments: instead of checking 10820whether an argument is missing, test that it is not empty. It provides 10821both a simpler and a more predictable interface to the user, and saves 10822room for further arguments. 10823 10824Unless the macro is short, try to leave the closing @samp{])} at the 10825beginning of a line, followed by a comment that repeats the name of the 10826macro being defined. This introduces an additional newline in 10827@command{configure}; normally, that is not a problem, but if you want to 10828remove it you can use @samp{[]dnl} on the last line. You can similarly 10829use @samp{[]dnl} after a macro call to remove its newline. @samp{[]dnl} 10830is recommended instead of @samp{dnl} to ensure that M4 does not 10831interpret the @samp{dnl} as being attached to the preceding text or 10832macro output. For example, instead of: 10833 10834@example 10835AC_DEFUN([AC_PATH_X], 10836[AC_MSG_CHECKING([for X]) 10837AC_REQUIRE_CPP() 10838@r{# @dots{}omitted@dots{}} 10839 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 10840fi]) 10841@end example 10842 10843@noindent 10844you would write: 10845 10846@example 10847AC_DEFUN([AC_PATH_X], 10848[AC_REQUIRE_CPP()[]dnl 10849AC_MSG_CHECKING([for X]) 10850@r{# @dots{}omitted@dots{}} 10851 AC_MSG_RESULT([libraries $x_libraries, headers $x_includes]) 10852fi[]dnl 10853])# AC_PATH_X 10854@end example 10855 10856If the macro is long, try to split it into logical chunks. Typically, 10857macros that check for a bug in a function and prepare its 10858@code{AC_LIBOBJ} replacement should have an auxiliary macro to perform 10859this setup. Do not hesitate to introduce auxiliary macros to factor 10860your code. 10861 10862In order to highlight the recommended coding style, here is a macro 10863written the old way: 10864 10865@example 10866dnl Check for EMX on OS/2. 10867dnl _AC_EMXOS2 10868AC_DEFUN(_AC_EMXOS2, 10869[AC_CACHE_CHECK(for EMX OS/2 environment, ac_cv_emxos2, 10870[AC_COMPILE_IFELSE([AC_LANG_PROGRAM(, return __EMX__;)], 10871ac_cv_emxos2=yes, ac_cv_emxos2=no)]) 10872test "$ac_cv_emxos2" = yes && EMXOS2=yes]) 10873@end example 10874 10875@noindent 10876and the new way: 10877 10878@example 10879# _AC_EMXOS2 10880# ---------- 10881# Check for EMX on OS/2. 10882m4_define([_AC_EMXOS2], 10883[AC_CACHE_CHECK([for EMX OS/2 environment], [ac_cv_emxos2], 10884[AC_COMPILE_IFELSE([AC_LANG_PROGRAM([], [return __EMX__;])], 10885 [ac_cv_emxos2=yes], 10886 [ac_cv_emxos2=no])]) 10887test "$ac_cv_emxos2" = yes && EMXOS2=yes[]dnl 10888])# _AC_EMXOS2 10889@end example 10890 10891 10892 10893 10894@c ============================================= Portable Shell Programming 10895 10896@node Portable Shell 10897@chapter Portable Shell Programming 10898@cindex Portable shell programming 10899 10900When writing your own checks, there are some shell-script programming 10901techniques you should avoid in order to make your code portable. The 10902Bourne shell and upward-compatible shells like the Korn shell and Bash 10903have evolved over the years, but to prevent trouble, do not take 10904advantage of features that were added after Unix version 7, circa 109051977 (@pxref{Systemology}). 10906 10907You should not use shell functions, aliases, negated character 10908classes, or other features that are not found in all Bourne-compatible 10909shells; restrict yourself to the lowest common denominator. Even 10910@code{unset} is not supported by all shells! 10911 10912Some ancient systems have quite 10913small limits on the length of the @samp{#!} line; for instance, 32 10914bytes (not including the newline) on SunOS 4. 10915A few ancient 4.2@acronym{BSD} based systems (such as Dynix circa 1984) 10916required a single space between the @samp{#!} and the @samp{/}. 10917However, these ancient systems are no longer of practical concern. 10918 10919The set of external programs you should run in a @command{configure} script 10920is fairly small. @xref{Utilities in Makefiles, , Utilities in 10921Makefiles, standards, @acronym{GNU} Coding Standards}, for the list. This 10922restriction allows users to start out with a fairly small set of 10923programs and build the rest, avoiding too many interdependencies between 10924packages. 10925 10926Some of these external utilities have a portable subset of features; see 10927@ref{Limitations of Usual Tools}. 10928 10929There are other sources of documentation about shells. The 10930specification for the Posix 10931@uref{http://www.opengroup.org/@/susv3/@/utilities/@/xcu_chap02.html, Shell 10932Command Language}, though more generous than the restrictive shell 10933subset described above, is fairly portable nowadays. Also please see 10934@uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/, the Shell FAQs}. 10935 10936@menu 10937* Shellology:: A zoology of shells 10938* Here-Documents:: Quirks and tricks 10939* File Descriptors:: FDs and redirections 10940* File System Conventions:: File names 10941* Shell Substitutions:: Variable and command expansions 10942* Assignments:: Varying side effects of assignments 10943* Parentheses:: Parentheses in shell scripts 10944* Slashes:: Slashes in shell scripts 10945* Special Shell Variables:: Variables you should not change 10946* Limitations of Builtins:: Portable use of not so portable /bin/sh 10947* Limitations of Usual Tools:: Portable use of portable tools 10948@end menu 10949 10950@node Shellology 10951@section Shellology 10952@cindex Shellology 10953 10954There are several families of shells, most prominently the Bourne family 10955and the C shell family which are deeply incompatible. If you want to 10956write portable shell scripts, avoid members of the C shell family. The 10957@uref{http://www.faqs.org/@/faqs/@/unix-faq/@/shell/@/shell-differences/, the 10958Shell difference FAQ} includes a small history of Posix shells, and a 10959comparison between several of them. 10960 10961Below we describe some of the members of the Bourne shell family. 10962 10963@table @asis 10964@item Ash 10965@cindex Ash 10966Ash is often used on @acronym{GNU}/Linux and @acronym{BSD} 10967systems as a light-weight Bourne-compatible shell. Ash 0.2 has some 10968bugs that are fixed in the 0.3.x series, but portable shell scripts 10969should work around them, since version 0.2 is still shipped with many 10970@acronym{GNU}/Linux distributions. 10971 10972To be compatible with Ash 0.2: 10973 10974@itemize @minus 10975@item 10976don't use @samp{$?} after expanding empty or unset variables, 10977or at the start of an @command{eval}: 10978 10979@example 10980foo= 10981false 10982$foo 10983echo "Do not use it: $?" 10984false 10985eval 'echo "Do not use it: $?"' 10986@end example 10987 10988@item 10989don't use command substitution within variable expansion: 10990 10991@example 10992cat $@{FOO=`bar`@} 10993@end example 10994 10995@item 10996beware that single builtin substitutions are not performed by a 10997subshell, hence their effect applies to the current shell! @xref{Shell 10998Substitutions}, item ``Command Substitution''. 10999@end itemize 11000 11001@item Bash 11002@cindex Bash 11003To detect whether you are running Bash, test whether 11004@code{BASH_VERSION} is set. To require 11005Posix compatibility, run @samp{set -o posix}. @xref{Bash POSIX 11006Mode, , Bash Posix Mode, bash, The @acronym{GNU} Bash Reference 11007Manual}, for details. 11008 11009@item Bash 2.05 and later 11010@cindex Bash 2.05 and later 11011Versions 2.05 and later of Bash use a different format for the 11012output of the @command{set} builtin, designed to make evaluating its 11013output easier. However, this output is not compatible with earlier 11014versions of Bash (or with many other shells, probably). So if 11015you use Bash 2.05 or higher to execute @command{configure}, 11016you'll need to use Bash 2.05 for all other build tasks as well. 11017 11018@item Ksh 11019@cindex Ksh 11020@cindex Korn shell 11021@prindex @samp{ksh} 11022@prindex @samp{ksh88} 11023@prindex @samp{ksh93} 11024The Korn shell is compatible with the Bourne family and it mostly 11025conforms to Posix. It has two major variants commonly 11026called @samp{ksh88} and @samp{ksh93}, named after the years of initial 11027release. It is usually called @command{ksh}, but is called @command{sh} 11028on some hosts if you set your path appropriately. 11029 11030Solaris systems have three variants: 11031@prindex @command{/usr/bin/ksh} on Solaris 11032@command{/usr/bin/ksh} is @samp{ksh88}; it is 11033standard on Solaris 2.0 and later. 11034@prindex @command{/usr/xpg4/bin/sh} on Solaris 11035@command{/usr/xpg4/bin/sh} is a Posix-compliant variant of 11036@samp{ksh88}; it is standard on Solaris 9 and later. 11037@prindex @command{/usr/dt/bin/dtksh} on Solaris 11038@command{/usr/dt/bin/dtksh} is @samp{ksh93}. 11039Variants that are not standard may be parts of optional 11040packages. There is no extra charge for these packages, but they are 11041not part of a minimal OS install and therefore some installations may 11042not have it. 11043 11044Starting with Tru64 Version 4.0, the Korn shell @command{/usr/bin/ksh} 11045is also available as @command{/usr/bin/posix/sh}. If the environment 11046variable @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 11047the standard shell conform to Posix. 11048 11049@item Pdksh 11050@prindex @samp{pdksh} 11051A public-domain clone of the Korn shell called @command{pdksh} is widely 11052available: it has most of the @samp{ksh88} features along with a few of 11053its own. It usually sets @code{KSH_VERSION}, except if invoked as 11054@command{/bin/sh} on Open@acronym{BSD}, and similarly to Bash you can require 11055Posix compatibility by running @samp{set -o posix}. Unfortunately, with 11056@command{pdksh} 5.2.14 (the latest stable version as of February 2006) 11057Posix mode is buggy and causes @command{pdksh} to depart from Posix in 11058at least one respect: 11059 11060@example 11061$ @kbd{echo "`echo \"hello\"`"} 11062hello 11063$ @kbd{set -o posix} 11064$ @kbd{echo "`echo \"hello\"`"} 11065"hello" 11066@end example 11067 11068The last line of output contains spurious quotes. This is yet another 11069reason why portable shell code should not contain 11070@code{"`@dots{}\"@dots{}\"@dots{}`"} constructs (@pxref{Shell 11071Substitutions}). 11072 11073@item Zsh 11074@cindex Zsh 11075To detect whether you are running @command{zsh}, test whether 11076@code{ZSH_VERSION} is set. By default @command{zsh} is @emph{not} 11077compatible with the Bourne shell: you must execute @samp{emulate sh}, 11078and for @command{zsh} versions before 3.1.6-dev-18 you must also 11079set @code{NULLCMD} to @samp{:}. @xref{Compatibility, , Compatibility, 11080zsh, The Z Shell Manual}, for details. 11081 11082The default Mac OS X @command{sh} was originally Zsh; it was changed to 11083Bash in Mac OS X 10.2. 11084@end table 11085 11086The following discussion between Russ Allbery and Robert Lipe is worth 11087reading: 11088 11089@noindent 11090Russ Allbery: 11091 11092@quotation 11093The @acronym{GNU} assumption that @command{/bin/sh} is the one and only shell 11094leads to a permanent deadlock. Vendors don't want to break users' 11095existing shell scripts, and there are some corner cases in the Bourne 11096shell that are not completely compatible with a Posix shell. Thus, 11097vendors who have taken this route will @emph{never} (OK@dots{}``never say 11098never'') replace the Bourne shell (as @command{/bin/sh}) with a 11099Posix shell. 11100@end quotation 11101 11102@noindent 11103Robert Lipe: 11104 11105@quotation 11106This is exactly the problem. While most (at least most System V's) do 11107have a Bourne shell that accepts shell functions most vendor 11108@command{/bin/sh} programs are not the Posix shell. 11109 11110So while most modern systems do have a shell @emph{somewhere} that meets the 11111Posix standard, the challenge is to find it. 11112@end quotation 11113 11114@node Here-Documents 11115@section Here-Documents 11116@cindex Here-documents 11117@cindex Shell here-documents 11118 11119Don't rely on @samp{\} being preserved just because it has no special 11120meaning together with the next symbol. In the native @command{sh} 11121on Open@acronym{BSD} 2.7 @samp{\"} expands to @samp{"} in here-documents with 11122unquoted delimiter. As a general rule, if @samp{\\} expands to @samp{\} 11123use @samp{\\} to get @samp{\}. 11124 11125With Open@acronym{BSD} 2.7's @command{sh} 11126 11127@example 11128@group 11129$ @kbd{cat <<EOF 11130> \" \\ 11131> EOF} 11132" \ 11133@end group 11134@end example 11135 11136@noindent 11137and with Bash: 11138 11139@example 11140@group 11141bash-2.04$ @kbd{cat <<EOF 11142> \" \\ 11143> EOF} 11144\" \ 11145@end group 11146@end example 11147 11148Some shells mishandle large here-documents: for example, 11149Solaris 10 @command{dtksh} and the UnixWare 7.1.1 Posix shell, which are 11150derived from Korn shell version M-12/28/93d, mishandle braced variable 11151expansion that crosses a 1024- or 4096-byte buffer boundary 11152within a here-document. Only the part of the variable name after the boundary 11153is used. For example, @code{$@{variable@}} could be replaced by the expansion 11154of @code{$@{ble@}}. If the end of the variable name is aligned with the block 11155boundary, the shell reports an error, as if you used @code{$@{@}}. 11156Instead of @code{$@{variable-default@}}, the shell may expand 11157@code{$@{riable-default@}}, or even @code{$@{fault@}}. This bug can often 11158be worked around by omitting the braces: @code{$variable}. The bug was fixed in 11159@samp{ksh93g} (1998-04-30) but as of 2006 many operating systems were 11160still shipping older versions with the bug. 11161 11162Many older shells (including the Bourne shell) implement here-documents 11163inefficiently. In particular, some shells can be extremely inefficient when 11164a single statement contains many here-documents. For instance if your 11165@file{configure.ac} includes something like: 11166 11167@example 11168@group 11169if <cross_compiling>; then 11170 assume this and that 11171else 11172 check this 11173 check that 11174 check something else 11175 @dots{} 11176 on and on forever 11177 @dots{} 11178fi 11179@end group 11180@end example 11181 11182A shell parses the whole @code{if}/@code{fi} construct, creating 11183temporary files for each here-document in it. Some shells create links 11184for such here-documents on every @code{fork}, so that the clean-up code 11185they had installed correctly removes them. It is creating the links 11186that can take the shell forever. 11187 11188Moving the tests out of the @code{if}/@code{fi}, or creating multiple 11189@code{if}/@code{fi} constructs, would improve the performance 11190significantly. Anyway, this kind of construct is not exactly the 11191typical use of Autoconf. In fact, it's even not recommended, because M4 11192macros can't look into shell conditionals, so we may fail to expand a 11193macro when it was expanded before in a conditional path, and the 11194condition turned out to be false at runtime, and we end up not 11195executing the macro at all. 11196 11197@node File Descriptors 11198@section File Descriptors 11199@cindex Descriptors 11200@cindex File descriptors 11201@cindex Shell file descriptors 11202 11203Most shells, if not all (including Bash, Zsh, Ash), output traces on 11204stderr, even for subshells. This might result in undesirable content 11205if you meant to capture the standard-error output of the inner command: 11206 11207@example 11208$ @kbd{ash -x -c '(eval "echo foo >&2") 2>stderr'} 11209$ @kbd{cat stderr} 11210+ eval echo foo >&2 11211+ echo foo 11212foo 11213$ @kbd{bash -x -c '(eval "echo foo >&2") 2>stderr'} 11214$ @kbd{cat stderr} 11215+ eval 'echo foo >&2' 11216++ echo foo 11217foo 11218$ @kbd{zsh -x -c '(eval "echo foo >&2") 2>stderr'} 11219@i{# Traces on startup files deleted here.} 11220$ @kbd{cat stderr} 11221+zsh:1> eval echo foo >&2 11222+zsh:1> echo foo 11223foo 11224@end example 11225 11226@noindent 11227One workaround is to grep out uninteresting lines, hoping not to remove 11228good ones. 11229 11230If you intend to redirect both standard error and standard output, 11231redirect standard output first. This works better with @acronym{HP-UX}, 11232since its shell mishandles tracing if standard error is redirected 11233first: 11234 11235@example 11236$ @kbd{sh -x -c ': 2>err >out'} 11237+ : 11238+ 2> err $ @kbd{cat err} 112391> out 11240@end example 11241 11242Don't try to redirect the standard error of a command substitution. It 11243must be done @emph{inside} the command substitution. When running 11244@samp{: `cd /zorglub` 2>/dev/null} expect the error message to 11245escape, while @samp{: `cd /zorglub 2>/dev/null`} works properly. 11246 11247It is worth noting that Zsh (but not Ash nor Bash) makes it possible 11248in assignments though: @samp{foo=`cd /zorglub` 2>/dev/null}. 11249 11250Don't redirect the same file descriptor several times, as you are doomed 11251to failure under Ultrix. 11252 11253@example 11254ULTRIX V4.4 (Rev. 69) System #31: Thu Aug 10 19:42:23 GMT 1995 11255UWS V4.4 (Rev. 11) 11256$ @kbd{eval 'echo matter >fullness' >void} 11257illegal io 11258$ @kbd{eval '(echo matter >fullness)' >void} 11259illegal io 11260$ @kbd{(eval '(echo matter >fullness)') >void} 11261Ambiguous output redirect. 11262@end example 11263 11264@noindent 11265In each case the expected result is of course @file{fullness} containing 11266@samp{matter} and @file{void} being empty. 11267 11268Don't rely on file descriptors 0, 1, and 2 remaining closed in a 11269subsidiary program. If any of these descriptors is closed, the 11270operating system may open an unspecified file for the descriptor in the 11271new process image. Posix says this may be done only if the subsidiary 11272program is set-user-ID or set-group-ID, but @acronym{HP-UX} 11.23 does it even for 11273ordinary programs. 11274 11275Don't rely on open file descriptors being open in child processes. In 11276@command{ksh}, file descriptors above 2 which are opened using 11277@samp{exec @var{n}>file} are closed by a subsequent @samp{exec} (such as 11278that involved in the fork-and-exec which runs a program or script). 11279Thus, using @command{sh}, we have: 11280 11281@example 11282$ @kbd{cat ./descrips} 11283#!/bin/sh - 11284echo hello >&5 11285$ @kbd{exec 5>t} 11286$ @kbd{./descrips} 11287$ @kbd{cat t} 11288$ 11289hello 11290@end example 11291 11292@noindent 11293But using ksh: 11294 11295@example 11296$ @kbd{exec 5>t} 11297$ @kbd{./descrips} 11298hello 11299$ @kbd{cat t} 11300$ 11301@end example 11302 11303@noindent 11304Within the process which runs the @samp{descrips} script, file 11305descriptor 5 is closed. 11306 11307@acronym{DOS} variants cannot rename or remove open files, such as in 11308@samp{mv foo bar >foo} or @samp{rm foo >foo}, even though this is 11309perfectly portable among Posix hosts. 11310 11311A few ancient systems reserved some file descriptors. By convention, 11312file descriptor 3 was opened to @file{/dev/tty} when you logged into 11313Eighth Edition (1985) through Tenth Edition Unix (1989). File 11314descriptor 4 had a special use on the Stardent/Kubota Titan (circa 113151990), though we don't now remember what it was. Both these systems are 11316obsolete, so it's now safe to treat file descriptors 3 and 4 like any 11317other file descriptors. 11318 11319@node File System Conventions 11320@section File System Conventions 11321@cindex File system conventions 11322 11323Autoconf uses shell-script processing extensively, so the file names 11324that it processes should not contain characters that are special to the 11325shell. Special characters include space, tab, newline, @sc{nul}, and 11326the following: 11327 11328@example 11329" # $ & ' ( ) * ; < = > ? [ \ ` | 11330@end example 11331 11332Also, file names should not begin with @samp{~} or @samp{-}, and should 11333contain neither @samp{-} immediately after @samp{/} nor @samp{~} 11334immediately after @samp{:}. On Posix-like platforms, directory names 11335should not contain @samp{:}, as this runs afoul of @samp{:} used as the 11336path separator. 11337 11338These restrictions apply not only to the files that you distribute, but 11339also to the absolute file names of your source, build, and destination 11340directories. 11341 11342On some Posix-like platforms, @samp{!} and @samp{^} are special too, so 11343they should be avoided. 11344 11345Posix lets implementations treat leading @file{//} specially, but 11346requires leading @file{///} and beyond to be equivalent to @file{/}. 11347Most Unix variants treat @file{//} like @file{/}. However, some treat 11348@file{//} as a ``super-root'' that can provide access to files that are 11349not otherwise reachable from @file{/}. The super-root tradition began 11350with Apollo Domain/OS, which died out long ago, but unfortunately Cygwin 11351has revived it. 11352 11353While @command{autoconf} and friends are usually run on some Posix 11354variety, they can be used on other systems, most notably @acronym{DOS} 11355variants. This impacts several assumptions regarding file names. 11356 11357@noindent 11358For example, the following code: 11359 11360@example 11361case $foo_dir in 11362 /*) # Absolute 11363 ;; 11364 *) 11365 foo_dir=$dots$foo_dir ;; 11366esac 11367@end example 11368 11369@noindent 11370fails to properly detect absolute file names on those systems, because 11371they can use a drivespec, and usually use a backslash as directory 11372separator. If you want to be portable to @acronym{DOS} variants (at the 11373price of rejecting valid but oddball Posix file names like @file{a:\b}), 11374you can check for absolute file names like this: 11375 11376@example 11377case $foo_dir in 11378 [\\/]* | ?:[\\/]* ) # Absolute 11379 ;; 11380 *) 11381 foo_dir=$dots$foo_dir ;; 11382esac 11383@end example 11384 11385@noindent 11386Make sure you quote the brackets if appropriate and keep the backslash as 11387first character (@pxref{Limitations of Builtins}). 11388 11389Also, because the colon is used as part of a drivespec, these systems don't 11390use it as path separator. When creating or accessing paths, you can use the 11391@code{PATH_SEPARATOR} output variable instead. @command{configure} sets this 11392to the appropriate value (@samp{:} or @samp{;}) when it starts up. 11393 11394File names need extra care as well. While @acronym{DOS} variants 11395that are Posixy enough to run @command{autoconf} (such as @acronym{DJGPP}) 11396are usually able to handle long file names properly, there are still 11397limitations that can seriously break packages. Several of these issues 11398can be easily detected by the 11399@uref{ftp://ftp.gnu.org/gnu/non-gnu/doschk/doschk-1.1.tar.gz, doschk} 11400package. 11401 11402A short overview follows; problems are marked with @sc{sfn}/@sc{lfn} to 11403indicate where they apply: @sc{sfn} means the issues are only relevant to 11404plain @acronym{DOS}, not to @acronym{DOS} under Microsoft Windows 11405variants, while @sc{lfn} identifies problems that exist even under 11406Microsoft Windows variants. 11407 11408@table @asis 11409@item No multiple dots (@sc{sfn}) 11410@acronym{DOS} cannot handle multiple dots in file names. This is an especially 11411important thing to remember when building a portable configure script, 11412as @command{autoconf} uses a .in suffix for template files. 11413 11414This is perfectly OK on Posix variants: 11415 11416@example 11417AC_CONFIG_HEADERS([config.h]) 11418AC_CONFIG_FILES([source.c foo.bar]) 11419AC_OUTPUT 11420@end example 11421 11422@noindent 11423but it causes problems on @acronym{DOS}, as it requires @samp{config.h.in}, 11424@samp{source.c.in} and @samp{foo.bar.in}. To make your package more portable 11425to @acronym{DOS}-based environments, you should use this instead: 11426 11427@example 11428AC_CONFIG_HEADERS([config.h:config.hin]) 11429AC_CONFIG_FILES([source.c:source.cin foo.bar:foobar.in]) 11430AC_OUTPUT 11431@end example 11432 11433@item No leading dot (@sc{sfn}) 11434@acronym{DOS} cannot handle file names that start with a dot. This is usually 11435not important for @command{autoconf}. 11436 11437@item Case insensitivity (@sc{lfn}) 11438@acronym{DOS} is case insensitive, so you cannot, for example, have both a 11439file called @samp{INSTALL} and a directory called @samp{install}. This 11440also affects @command{make}; if there's a file called @samp{INSTALL} in 11441the directory, @samp{make install} does nothing (unless the 11442@samp{install} target is marked as PHONY). 11443 11444@item The 8+3 limit (@sc{sfn}) 11445Because the @acronym{DOS} file system only stores the first 8 characters of 11446the file name and the first 3 of the extension, those must be unique. 11447That means that @file{foobar-part1.c}, @file{foobar-part2.c} and 11448@file{foobar-prettybird.c} all resolve to the same file name 11449(@file{FOOBAR-P.C}). The same goes for @file{foo.bar} and 11450@file{foo.bartender}. 11451 11452The 8+3 limit is not usually a problem under Microsoft Windows, as it 11453uses numeric 11454tails in the short version of file names to make them unique. However, a 11455registry setting can turn this behavior off. While this makes it 11456possible to share file trees containing long file names between @sc{sfn} 11457and @sc{lfn} environments, it also means the above problem applies there 11458as well. 11459 11460@item Invalid characters (@sc{lfn}) 11461Some characters are invalid in @acronym{DOS} file names, and should therefore 11462be avoided. In a @sc{lfn} environment, these are @samp{/}, @samp{\}, 11463@samp{?}, @samp{*}, @samp{:}, @samp{<}, @samp{>}, @samp{|} and @samp{"}. 11464In a @sc{sfn} environment, other characters are also invalid. These 11465include @samp{+}, @samp{,}, @samp{[} and @samp{]}. 11466 11467@item Invalid names (@sc{lfn}) 11468Some @acronym{DOS} file names are reserved, and cause problems if you 11469try to use files with those names. These names include @file{CON}, 11470@file{AUX}, @file{COM1}, @file{COM2}, @file{COM3}, @file{COM4}, 11471@file{LPT1}, @file{LPT2}, @file{LPT3}, @file{NUL}, and @file{PRN}. 11472File names are case insensitive, so even names like 11473@file{aux/config.guess} are disallowed. 11474 11475@end table 11476 11477@node Shell Substitutions 11478@section Shell Substitutions 11479@cindex Shell substitutions 11480 11481Contrary to a persistent urban legend, the Bourne shell does not 11482systematically split variables and back-quoted expressions, in particular 11483on the right-hand side of assignments and in the argument of @code{case}. 11484For instance, the following code: 11485 11486@example 11487case "$given_srcdir" in 11488.) top_srcdir="`echo "$dots" | sed 's,/$,,'`" ;; 11489*) top_srcdir="$dots$given_srcdir" ;; 11490esac 11491@end example 11492 11493@noindent 11494is more readable when written as: 11495 11496@example 11497case $given_srcdir in 11498.) top_srcdir=`echo "$dots" | sed 's,/$,,'` ;; 11499*) top_srcdir=$dots$given_srcdir ;; 11500esac 11501@end example 11502 11503@noindent 11504and in fact it is even @emph{more} portable: in the first case of the 11505first attempt, the computation of @code{top_srcdir} is not portable, 11506since not all shells properly understand @code{"`@dots{}"@dots{}"@dots{}`"}. 11507Worse yet, not all shells understand @code{"`@dots{}\"@dots{}\"@dots{}`"} 11508the same way. There is just no portable way to use double-quoted 11509strings inside double-quoted back-quoted expressions (pfew!). 11510 11511@table @code 11512@item $@@ 11513@cindex @samp{"$@@"} 11514One of the most famous shell-portability issues is related to 11515@samp{"$@@"}. When there are no positional arguments, Posix says 11516that @samp{"$@@"} is supposed to be equivalent to nothing, but the 11517original Unix version 7 Bourne shell treated it as equivalent to 11518@samp{""} instead, and this behavior survives in later implementations 11519like Digital Unix 5.0. 11520 11521The traditional way to work around this portability problem is to use 11522@samp{$@{1+"$@@"@}}. Unfortunately this method does not work with 11523Zsh (3.x and 4.x), which is used on Mac OS X@. When emulating 11524the Bourne shell, Zsh performs word splitting on @samp{$@{1+"$@@"@}}: 11525 11526@example 11527zsh $ @kbd{emulate sh} 11528zsh $ @kbd{for i in "$@@"; do echo $i; done} 11529Hello World 11530! 11531zsh $ @kbd{for i in $@{1+"$@@"@}; do echo $i; done} 11532Hello 11533World 11534! 11535@end example 11536 11537@noindent 11538Zsh handles plain @samp{"$@@"} properly, but we can't use plain 11539@samp{"$@@"} because of the portability problems mentioned above. 11540One workaround relies on Zsh's ``global aliases'' to convert 11541@samp{$@{1+"$@@"@}} into @samp{"$@@"} by itself: 11542 11543@example 11544test "$@{ZSH_VERSION+set@}" = set && alias -g '$@{1+"$@@"@}'='"$@@"' 11545@end example 11546 11547A more conservative workaround is to avoid @samp{"$@@"} if it is 11548possible that there may be no positional arguments. For example, 11549instead of: 11550 11551@example 11552cat conftest.c "$@@" 11553@end example 11554 11555you can use this instead: 11556 11557@example 11558case $# in 115590) cat conftest.c;; 11560*) cat conftest.c "$@@";; 11561esac 11562@end example 11563 11564Autoconf macros often use the @command{set} command to update 11565@samp{$@@}, so if you are writing shell code intended for 11566@command{configure} you should not assume that the value of @samp{$@@} 11567persists for any length of time. 11568 11569 11570@item $@{10@} 11571@cindex positional parameters 11572The 10th, 11th, @dots{} positional parameters can be accessed only after 11573a @code{shift}. The 7th Edition shell reported an error if given 11574@code{$@{10@}}, and 11575Solaris 10 @command{/bin/sh} still acts that way: 11576 11577@example 11578$ @kbd{set 1 2 3 4 5 6 7 8 9 10} 11579$ @kbd{echo $@{10@}} 11580bad substitution 11581@end example 11582 11583@item $@{@var{var}:-@var{value}@} 11584@c Info cannot handle `:' in index entries. 11585@c @cindex $@{@var{var}:-@var{value}@} 11586Old @acronym{BSD} shells, including the Ultrix @code{sh}, don't accept the 11587colon for any shell substitution, and complain and die. 11588 11589@item $@{@var{var}=@var{literal}@} 11590@cindex $@{@var{var}=@var{literal}@} 11591Be sure to quote: 11592 11593@example 11594: $@{var='Some words'@} 11595@end example 11596 11597@noindent 11598otherwise some shells, such as on Digital Unix V 5.0, die because 11599of a ``bad substitution''. 11600 11601@sp 1 11602 11603Solaris @command{/bin/sh} has a frightening bug in its interpretation 11604of this. Imagine you need set a variable to a string containing 11605@samp{@}}. This @samp{@}} character confuses Solaris @command{/bin/sh} 11606when the affected variable was already set. This bug can be exercised 11607by running: 11608 11609@example 11610$ @kbd{unset foo} 11611$ @kbd{foo=$@{foo='@}'@}} 11612$ @kbd{echo $foo} 11613@} 11614$ @kbd{foo=$@{foo='@}' # no error; this hints to what the bug is} 11615$ @kbd{echo $foo} 11616@} 11617$ @kbd{foo=$@{foo='@}'@}} 11618$ @kbd{echo $foo} 11619@}@} 11620 ^ ugh! 11621@end example 11622 11623It seems that @samp{@}} is interpreted as matching @samp{$@{}, even 11624though it is enclosed in single quotes. The problem doesn't happen 11625using double quotes. 11626 11627@item $@{@var{var}=@var{expanded-value}@} 11628@cindex $@{@var{var}=@var{expanded-value}@} 11629On Ultrix, 11630running 11631 11632@example 11633default="yu,yaa" 11634: $@{var="$default"@} 11635@end example 11636 11637@noindent 11638sets @var{var} to @samp{M-yM-uM-,M-yM-aM-a}, i.e., the 8th bit of 11639each char is set. You don't observe the phenomenon using a simple 11640@samp{echo $var} since apparently the shell resets the 8th bit when it 11641expands $var. Here are two means to make this shell confess its sins: 11642 11643@example 11644$ @kbd{cat -v <<EOF 11645$var 11646EOF} 11647@end example 11648 11649@noindent 11650and 11651 11652@example 11653$ @kbd{set | grep '^var=' | cat -v} 11654@end example 11655 11656One classic incarnation of this bug is: 11657 11658@example 11659default="a b c" 11660: $@{list="$default"@} 11661for c in $list; do 11662 echo $c 11663done 11664@end example 11665 11666@noindent 11667You'll get @samp{a b c} on a single line. Why? Because there are no 11668spaces in @samp{$list}: there are @samp{M- }, i.e., spaces with the 8th 11669bit set, hence no IFS splitting is performed!!! 11670 11671One piece of good news is that Ultrix works fine with @samp{: 11672$@{list=$default@}}; i.e., if you @emph{don't} quote. The bad news is 11673then that @acronym{QNX} 4.25 then sets @var{list} to the @emph{last} item of 11674@var{default}! 11675 11676The portable way out consists in using a double assignment, to switch 11677the 8th bit twice on Ultrix: 11678 11679@example 11680list=$@{list="$default"@} 11681@end example 11682 11683@noindent 11684@dots{}but beware of the @samp{@}} bug from Solaris (see above). For safety, 11685use: 11686 11687@example 11688test "$@{var+set@}" = set || var=@var{@{value@}} 11689@end example 11690 11691 11692@item `@var{commands}` 11693@cindex `@var{commands}` 11694@cindex Command Substitution 11695Posix requires shells to trim all trailing newlines from command 11696output before substituting it, so assignments like 11697@samp{dir=`echo "$file" | tr a A`} do not work as expected if 11698@samp{$file} ends in a newline. 11699 11700While in general it makes no sense, do not substitute a single builtin 11701with side effects, because Ash 0.2, trying to optimize, does not fork a 11702subshell to perform the command. 11703 11704For instance, if you wanted to check that @command{cd} is silent, do not 11705use @samp{test -z "`cd /`"} because the following can happen: 11706 11707@example 11708$ @kbd{pwd} 11709/tmp 11710$ @kbd{test -z "`cd /`" && pwd} 11711/ 11712@end example 11713 11714@noindent 11715The result of @samp{foo=`exit 1`} is left as an exercise to the reader. 11716 11717The MSYS shell leaves a stray byte in the expansion of a double-quoted 11718command substitution of a native program, if the end of the substution 11719is not aligned with the end of the double quote. This may be worked 11720around by inserting another pair of quotes: 11721 11722@example 11723$ @kbd{echo "`printf 'foo\r\n'` bar" > broken} 11724$ @kbd{echo "`printf 'foo\r\n'`"" bar" | cmp - broken} 11725- broken differ: char 4, line 1 11726@end example 11727 11728 11729@item $(@var{commands}) 11730@cindex $(@var{commands}) 11731This construct is meant to replace @samp{`@var{commands}`}, 11732and it has most of the problems listed under @code{`@var{commands}`}. 11733 11734This construct can be 11735nested while this is impossible to do portably with back quotes. 11736Unfortunately it is not yet universally supported. Most notably, even recent 11737releases of Solaris don't support it: 11738 11739@example 11740$ @kbd{showrev -c /bin/sh | grep version} 11741Command version: SunOS 5.10 Generic 121004-01 Oct 2005 11742$ @kbd{echo $(echo blah)} 11743syntax error: `(' unexpected 11744@end example 11745 11746@noindent 11747nor does @sc{irix} 6.5's Bourne shell: 11748@example 11749$ @kbd{uname -a} 11750IRIX firebird-image 6.5 07151432 IP22 11751$ @kbd{echo $(echo blah)} 11752$(echo blah) 11753@end example 11754 11755If you do use @samp{$(@var{commands})}, make sure that the commands 11756do not start with a parenthesis, as that would cause confusion with 11757a different notation @samp{$((@var{expression}))} that in modern 11758shells is an arithmetic expression not a command. To avoid the 11759confusion, insert a space between the two opening parentheses. 11760 11761Avoid @var{commands} that contain unbalanced parentheses in 11762here-documents, comments, or case statement patterns, as many shells 11763mishandle them. For example, Bash 3.1, @samp{ksh88}, @command{pdksh} 117645.2.14, and Zsh 4.2.6 all mishandle the following valid command: 11765 11766@example 11767echo $(case x in x) echo hello;; esac) 11768@end example 11769 11770@item ^ 11771@cindex ^ quoting 11772Always quote @samp{^}, otherwise traditional shells such as 11773@command{/bin/sh} on Solaris 10 treat this like @samp{|}. 11774 11775@end table 11776 11777 11778@node Assignments 11779@section Assignments 11780@cindex Shell assignments 11781 11782When setting several variables in a row, be aware that the order of the 11783evaluation is undefined. For instance @samp{foo=1 foo=2; echo $foo} 11784gives @samp{1} with Solaris @command{/bin/sh}, but @samp{2} with Bash. 11785You must use 11786@samp{;} to enforce the order: @samp{foo=1; foo=2; echo $foo}. 11787 11788Don't rely on the following to find @file{subdir/program}: 11789 11790@example 11791PATH=subdir$PATH_SEPARATOR$PATH program 11792@end example 11793 11794@noindent 11795as this does not work with Zsh 3.0.6. Use something like this 11796instead: 11797 11798@example 11799(PATH=subdir$PATH_SEPARATOR$PATH; export PATH; exec program) 11800@end example 11801 11802Don't rely on the exit status of an assignment: Ash 0.2 does not change 11803the status and propagates that of the last statement: 11804 11805@example 11806$ @kbd{false || foo=bar; echo $?} 118071 11808$ @kbd{false || foo=`:`; echo $?} 118090 11810@end example 11811 11812@noindent 11813and to make things even worse, @acronym{QNX} 4.25 just sets the exit status 11814to 0 in any case: 11815 11816@example 11817$ @kbd{foo=`exit 1`; echo $?} 118180 11819@end example 11820 11821To assign default values, follow this algorithm: 11822 11823@enumerate 11824@item 11825If the default value is a literal and does not contain any closing 11826brace, use: 11827 11828@example 11829: $@{var='my literal'@} 11830@end example 11831 11832@item 11833If the default value contains no closing brace, has to be expanded, and 11834the variable being initialized is not intended to be IFS-split 11835(i.e., it's not a list), then use: 11836 11837@example 11838: $@{var="$default"@} 11839@end example 11840 11841@item 11842If the default value contains no closing brace, has to be expanded, and 11843the variable being initialized is intended to be IFS-split (i.e., it's a list), 11844then use: 11845 11846@example 11847var=$@{var="$default"@} 11848@end example 11849 11850@item 11851If the default value contains a closing brace, then use: 11852 11853@example 11854test "$@{var+set@}" = set || var="has a '@}'" 11855@end example 11856@end enumerate 11857 11858In most cases @samp{var=$@{var="$default"@}} is fine, but in case of 11859doubt, just use the last form. @xref{Shell Substitutions}, items 11860@samp{$@{@var{var}:-@var{value}@}} and @samp{$@{@var{var}=@var{value}@}} 11861for the rationale. 11862 11863@node Parentheses 11864@section Parentheses in Shell Scripts 11865@cindex Shell parentheses 11866 11867Beware of two opening parentheses in a row, as some shell 11868implementations mishandle them. For example, @samp{pdksh} 5.2.14 11869misparses the following code: 11870 11871@example 11872if ((true) || false); then 11873 echo ok 11874fi 11875@end example 11876 11877@noindent 11878To work around this problem, insert a space between the two opening 11879parentheses. There is a similar problem and workaround with 11880@samp{$((}; see @ref{Shell Substitutions}. 11881 11882Posix requires support for @code{case} patterns with opening 11883parentheses like this: 11884 11885@example 11886case $file_name in 11887(*.c) echo "C source code";; 11888esac 11889@end example 11890 11891@noindent 11892but the @code{(} in this example is not portable to many older Bourne 11893shell implementations. It can be omitted safely. 11894 11895@node Slashes 11896@section Slashes in Shell Scripts 11897@cindex Shell slashes 11898 11899Unpatched Tru64 5.1 @command{sh} omits the last slash of command-line 11900arguments that contain two trailing slashes: 11901 11902@example 11903$ @kbd{echo / // /// //// .// //.} 11904/ / // /// ./ //. 11905$ @kbd{x=//} 11906$ @kbd{eval "echo \$x"} 11907/ 11908$ @kbd{set -x} 11909$ @kbd{echo abc | tr -t ab //} 11910+ echo abc 11911+ tr -t ab / 11912/bc 11913@end example 11914 11915Unpatched Tru64 4.0 @command{sh} adds a slash after @samp{"$var"} if the 11916variable is empty and the second double-quote is followed by a word that 11917begins and ends with slash: 11918 11919@example 11920$ @kbd{sh -xc 'p=; echo "$p"/ouch/'} 11921p= 11922+ echo //ouch/ 11923//ouch/ 11924@end example 11925 11926However, our understanding is that patches are available, so perhaps 11927it's not worth worrying about working around these horrendous bugs. 11928 11929@node Special Shell Variables 11930@section Special Shell Variables 11931@cindex Shell variables 11932@cindex Special shell variables 11933 11934Some shell variables should not be used, since they can have a deep 11935influence on the behavior of the shell. In order to recover a sane 11936behavior from the shell, some variables should be unset, but 11937@command{unset} is not portable (@pxref{Limitations of Builtins}) and a 11938fallback value is needed. 11939 11940As a general rule, shell variable names containing a lower-case letter 11941are safe; you can define and use these variables without worrying about 11942their effect on the underlying system, and without worrying about 11943whether the shell changes them unexpectedly. (The exception is the 11944shell variable @code{status}, as described below.) 11945 11946Here is a list of names that are known to cause trouble. This list is 11947not exhaustive, but you should be safe if you avoid the name 11948@code{status} and names containing only upper-case letters and 11949underscores. 11950 11951@c Alphabetical order, case insensitive, `A' before `a'. 11952@table @code 11953@item _ 11954Many shells reserve @samp{$_} for various purposes, e.g., the name of 11955the last command executed. 11956 11957@item BIN_SH 11958@evindex BIN_SH 11959In Tru64, if @env{BIN_SH} is set to @code{xpg4}, subsidiary invocations of 11960the standard shell conform to Posix. 11961 11962@item CDPATH 11963@evindex CDPATH 11964When this variable is set it specifies a list of directories to search 11965when invoking @code{cd} with a relative file name that did not start 11966with @samp{./} or @samp{../}. Posix 119671003.1-2001 says that if a nonempty directory name from @env{CDPATH} 11968is used successfully, @code{cd} prints the resulting absolute 11969file name. Unfortunately this output can break idioms like 11970@samp{abs=`cd src && pwd`} because @code{abs} receives the name twice. 11971Also, many shells do not conform to this part of Posix; for 11972example, @command{zsh} prints the result only if a directory name 11973other than @file{.} was chosen from @env{CDPATH}. 11974 11975In practice the shells that have this problem also support 11976@command{unset}, so you can work around the problem as follows: 11977 11978@example 11979(unset CDPATH) >/dev/null 2>&1 && unset CDPATH 11980@end example 11981 11982You can also avoid output by ensuring that your directory name is 11983absolute or anchored at @samp{./}, as in @samp{abs=`cd ./src && pwd`}. 11984 11985Autoconf-generated scripts automatically unset @env{CDPATH} if 11986possible, so you need not worry about this problem in those scripts. 11987 11988@item DUALCASE 11989@evindex DUALCASE 11990In the MKS shell, case statements and file name generation are 11991case-insensitive unless @env{DUALCASE} is nonzero. 11992Autoconf-generated scripts export this variable when they start up. 11993 11994@item ENV 11995@itemx MAIL 11996@itemx MAILPATH 11997@itemx PS1 11998@itemx PS2 11999@itemx PS4 12000@evindex ENV 12001@evindex MAIL 12002@evindex MAILPATH 12003@evindex PS1 12004@evindex PS2 12005@evindex PS4 12006These variables should not matter for shell scripts, since they are 12007supposed to affect only interactive shells. However, at least one 12008shell (the pre-3.0 @sc{uwin} Korn shell) gets confused about 12009whether it is interactive, which means that (for example) a @env{PS1} 12010with a side effect can unexpectedly modify @samp{$?}. To work around 12011this bug, Autoconf-generated scripts do something like this: 12012 12013@example 12014(unset ENV) >/dev/null 2>&1 && unset ENV MAIL MAILPATH 12015PS1='$ ' 12016PS2='> ' 12017PS4='+ ' 12018@end example 12019 12020@item IFS 12021@evindex IFS 12022Long ago, shell scripts inherited @env{IFS} from the environment, 12023but this caused many problems so modern shells ignore any environment 12024settings for @env{IFS}. 12025 12026Don't set the first character of @code{IFS} to backslash. Indeed, 12027Bourne shells use the first character (backslash) when joining the 12028components in @samp{"$@@"} and some shells then reinterpret (!)@: the 12029backslash escapes, so you can end up with backspace and other strange 12030characters. 12031 12032The proper value for @code{IFS} (in regular code, not when performing 12033splits) is @samp{@key{SPC}@key{TAB}@key{RET}}. The first character is 12034especially important, as it is used to join the arguments in @samp{$*}; 12035however, note that traditional shells, but also bash-2.04, fail to adhere 12036to this and join with a space anyway. 12037 12038@item LANG 12039@itemx LC_ALL 12040@itemx LC_COLLATE 12041@itemx LC_CTYPE 12042@itemx LC_MESSAGES 12043@itemx LC_MONETARY 12044@itemx LC_NUMERIC 12045@itemx LC_TIME 12046@evindex LANG 12047@evindex LC_ALL 12048@evindex LC_COLLATE 12049@evindex LC_CTYPE 12050@evindex LC_MESSAGES 12051@evindex LC_MONETARY 12052@evindex LC_NUMERIC 12053@evindex LC_TIME 12054 12055Autoconf-generated scripts normally set all these variables to 12056@samp{C} because so much configuration code assumes the C locale and 12057Posix requires that locale environment variables be set to 12058@samp{C} if the C locale is desired. However, some older, nonstandard 12059systems (notably @acronym{SCO}) break if locale environment variables 12060are set to @samp{C}, so when running on these systems 12061Autoconf-generated scripts unset the variables instead. 12062 12063@item LANGUAGE 12064@evindex LANGUAGE 12065 12066@env{LANGUAGE} is not specified by Posix, but it is a @acronym{GNU} 12067extension that overrides @env{LC_ALL} in some cases, so 12068Autoconf-generated scripts set it too. 12069 12070@item LC_ADDRESS 12071@itemx LC_IDENTIFICATION 12072@itemx LC_MEASUREMENT 12073@itemx LC_NAME 12074@itemx LC_PAPER 12075@itemx LC_TELEPHONE 12076@evindex LC_ADDRESS 12077@evindex LC_IDENTIFICATION 12078@evindex LC_MEASUREMENT 12079@evindex LC_NAME 12080@evindex LC_PAPER 12081@evindex LC_TELEPHONE 12082 12083These locale environment variables are @acronym{GNU} extensions. They 12084are treated like their Posix brethren (@env{LC_COLLATE}, 12085etc.)@: as described above. 12086 12087@item LINENO 12088Most modern shells provide the current line number in @code{LINENO}. 12089Its value is the line number of the beginning of the current command. 12090Autoconf attempts to execute @command{configure} with a shell that 12091supports @code{LINENO}. 12092If no such shell is available, it attempts to implement @code{LINENO} 12093with a Sed prepass that replaces each instance of the string 12094@code{$LINENO} (not followed by an alphanumeric character) with the 12095line's number. 12096 12097You should not rely on @code{LINENO} within @command{eval}, as the 12098behavior differs in practice. Also, the possibility of the Sed 12099prepass means that you should not rely on @code{$LINENO} when quoted, 12100when in here-documents, or when in long commands that cross line 12101boundaries. Subshells should be OK, though. In the following 12102example, lines 1, 6, and 9 are portable, but the other instances of 12103@code{LINENO} are not: 12104 12105@example 12106@group 12107$ @kbd{cat lineno} 12108echo 1. $LINENO 12109cat <<EOF 121103. $LINENO 121114. $LINENO 12112EOF 12113( echo 6. $LINENO ) 12114eval 'echo 7. $LINENO' 12115echo 8. '$LINENO' 12116echo 9. $LINENO ' 1211710.' $LINENO 12118@end group 12119@group 12120$ @kbd{bash-2.05 lineno} 121211. 1 121223. 2 121234. 2 121246. 6 121257. 1 121268. $LINENO 121279. 9 1212810. 9 12129@end group 12130@group 12131$ @kbd{zsh-3.0.6 lineno} 121321. 1 121333. 2 121344. 2 121356. 6 121367. 7 121378. $LINENO 121389. 9 1213910. 9 12140@end group 12141@group 12142$ @kbd{pdksh-5.2.14 lineno} 121431. 1 121443. 2 121454. 2 121466. 6 121477. 0 121488. $LINENO 121499. 9 1215010. 9 12151@end group 12152@group 12153$ @kbd{sed '=' <lineno |} 12154> @kbd{ sed '} 12155> @kbd{ N} 12156> @kbd{ s,$,-,} 12157> @kbd{ t loop} 12158> @kbd{ :loop} 12159> @kbd{ s,^\([0-9]*\)\(.*\)[$]LINENO\([^a-zA-Z0-9_]\),\1\2\1\3,} 12160> @kbd{ t loop} 12161> @kbd{ s,-$,,} 12162> @kbd{ s,^[0-9]*\n,,} 12163> @kbd{ ' |} 12164> @kbd{ sh} 121651. 1 121663. 3 121674. 4 121686. 6 121697. 7 121708. 8 121719. 9 1217210. 10 12173@end group 12174@end example 12175 12176@item NULLCMD 12177@evindex NULLCMD 12178When executing the command @samp{>foo}, @command{zsh} executes 12179@samp{$NULLCMD >foo} unless it is operating in Bourne shell 12180compatibility mode and the @command{zsh} version is newer 12181than 3.1.6-dev-18. If you are using an older @command{zsh} 12182and forget to set @env{NULLCMD}, 12183your script might be suspended waiting for data on its standard input. 12184 12185@item PATH_SEPARATOR 12186@evindex PATH_SEPARATOR 12187On @acronym{DJGPP} systems, the @env{PATH_SEPARATOR} environment 12188variable can be set to either @samp{:} or @samp{;} to control the path 12189separator Bash uses to set up certain environment variables (such as 12190@env{PATH}). You can set this variable to @samp{;} if you want 12191@command{configure} to use @samp{;} as a separator; this might be useful 12192if you plan to use non-Posix shells to execute files. @xref{File System 12193Conventions}, for more information about @code{PATH_SEPARATOR}. 12194 12195@item PWD 12196@evindex PWD 12197Posix 1003.1-2001 requires that @command{cd} and 12198@command{pwd} must update the @env{PWD} environment variable to point 12199to the logical name of the current directory, but traditional shells 12200do not support this. This can cause confusion if one shell instance 12201maintains @env{PWD} but a subsidiary and different shell does not know 12202about @env{PWD} and executes @command{cd}; in this case @env{PWD} 12203points to the wrong directory. Use @samp{`pwd`} rather than 12204@samp{$PWD}. 12205 12206@item RANDOM 12207Many shells provide @code{RANDOM}, a variable that returns a different 12208integer each time it is used. Most of the time, its value does not 12209change when it is not used, but on @sc{irix} 6.5 the value changes all 12210the time. This can be observed by using @command{set}. It is common 12211practice to use @code{$RANDOM} as part of a file name, but code 12212shouldn't rely on @code{$RANDOM} expanding to a nonempty string. 12213 12214@item status 12215This variable is an alias to @samp{$?} for @code{zsh} (at least 3.1.6), 12216hence read-only. Do not use it. 12217@end table 12218 12219@node Limitations of Builtins 12220@section Limitations of Shell Builtins 12221@cindex Shell builtins 12222@cindex Limitations of shell builtins 12223 12224No, no, we are serious: some shells do have limitations! :) 12225 12226You should always keep in mind that any builtin or command may support 12227options, and therefore differ in behavior with arguments 12228starting with a dash. For instance, the innocent @samp{echo "$word"} 12229can give unexpected results when @code{word} starts with a dash. It is 12230often possible to avoid this problem using @samp{echo "x$word"}, taking 12231the @samp{x} into account later in the pipe. 12232 12233@table @asis 12234@item @command{.} 12235@prindex @command{.} 12236Use @command{.} only with regular files (use @samp{test -f}). Bash 122372.03, for instance, chokes on @samp{. /dev/null}. Also, remember that 12238@command{.} uses @env{PATH} if its argument contains no slashes, so if 12239you want to use @command{.} on a file @file{foo} in the current 12240directory, you must use @samp{. ./foo}. 12241 12242@item @command{!} 12243@prindex @command{!} 12244The Unix version 7 shell did not support 12245negating the exit status of commands with @command{!}, and this feature 12246is still absent from some shells (e.g., Solaris @command{/bin/sh}). 12247Shell code like this: 12248 12249@example 12250if ! cmp file1 file2 >/dev/null 2>&1; then 12251 echo files differ or trouble 12252fi 12253@end example 12254 12255is therefore not portable in practice. Typically it is easy to rewrite 12256such code, e.g.: 12257 12258@example 12259cmp file1 file2 >/dev/null 2>&1 || 12260 echo files differ or trouble 12261@end example 12262 12263More generally, one can always rewrite @samp{! @var{command}} as: 12264 12265@example 12266if @var{command}; then (exit 1); else :; fi 12267@end example 12268 12269@item @command{break} 12270@c ------------------ 12271@prindex @command{break} 12272The use of @samp{break 2} etc.@: is safe. 12273 12274 12275@item @command{case} 12276@c ----------------- 12277@prindex @command{case} 12278You don't need to quote the argument; no splitting is performed. 12279 12280You don't need the final @samp{;;}, but you should use it. 12281 12282Because of a bug in its @code{fnmatch}, Bash fails to properly 12283handle backslashes in character classes: 12284 12285@example 12286bash-2.02$ @kbd{case /tmp in [/\\]*) echo OK;; esac} 12287bash-2.02$ 12288@end example 12289 12290@noindent 12291This is extremely unfortunate, since you are likely to use this code to 12292handle Posix or @sc{ms-dos} absolute file names. To work around this 12293bug, always put the backslash first: 12294 12295@example 12296bash-2.02$ @kbd{case '\TMP' in [\\/]*) echo OK;; esac} 12297OK 12298bash-2.02$ @kbd{case /tmp in [\\/]*) echo OK;; esac} 12299OK 12300@end example 12301 12302Many Bourne shells cannot handle closing brackets in character classes 12303correctly. 12304 12305Some shells also have problems with backslash escaping in case you do not want 12306to match the backslash: both a backslash and the escaped character match this 12307pattern. To work around this, specify the character class in a variable, so 12308that quote removal does not apply afterwards, and the special characters don't 12309have to be backslash-escaped: 12310 12311@example 12312$ @kbd{case '\' in [\<]) echo OK;; esac} 12313OK 12314$ @kbd{scanset='[<]'; case '\' in $scanset) echo OK;; esac} 12315$ 12316@end example 12317 12318Even with this, Solaris @command{ksh} matches a backslash if the set 12319contains any 12320of the characters @samp{|}, @samp{&}, @samp{(}, or @samp{)}. 12321 12322Conversely, Tru64 @command{ksh} (circa 2003) erroneously always matches 12323a closing parenthesis if not specified in a character class: 12324 12325@example 12326$ @kbd{case foo in *\)*) echo fail ;; esac} 12327fail 12328$ @kbd{case foo in *')'*) echo fail ;; esac} 12329fail 12330@end example 12331 12332Some shells, such as Ash 0.3.8, are confused by an empty 12333@code{case}/@code{esac}: 12334 12335@example 12336ash-0.3.8 $ @kbd{case foo in esac;} 12337@error{}Syntax error: ";" unexpected (expecting ")") 12338@end example 12339 12340Many shells still do not support parenthesized cases, which is a pity 12341for those of us using tools that rely on balanced parentheses. For 12342instance, Solaris @command{/bin/sh}: 12343 12344@example 12345$ @kbd{case foo in (foo) echo foo;; esac} 12346@error{}syntax error: `(' unexpected 12347@end example 12348 12349 12350@item @command{cd} 12351@c --------------- 12352@prindex @command{cd} 12353Posix 1003.1-2001 requires that @command{cd} must support 12354the @option{-L} (``logical'') and @option{-P} (``physical'') options, 12355with @option{-L} being the default. However, traditional shells do 12356not support these options, and their @command{cd} command has the 12357@option{-P} behavior. 12358 12359Portable scripts should assume neither option is supported, and should 12360assume neither behavior is the default. This can be a bit tricky, 12361since the Posix default behavior means that, for example, 12362@samp{ls ..} and @samp{cd ..} may refer to different directories if 12363the current logical directory is a symbolic link. It is safe to use 12364@command{cd @var{dir}} if @var{dir} contains no @file{..} components. 12365Also, Autoconf-generated scripts check for this problem when computing 12366variables like @code{ac_top_srcdir} (@pxref{Configuration Actions}), 12367so it is safe to @command{cd} to these variables. 12368 12369See @xref{Special Shell Variables}, for portability problems involving 12370@command{cd} and the @env{CDPATH} environment variable. 12371Also please see the discussion of the @command{pwd} command. 12372 12373 12374@item @command{echo} 12375@c ----------------- 12376@prindex @command{echo} 12377The simple @command{echo} is probably the most surprising source of 12378portability troubles. It is not possible to use @samp{echo} portably 12379unless both options and escape sequences are omitted. New applications 12380which are not aiming at portability should use @samp{printf} instead of 12381@samp{echo}. 12382 12383Don't expect any option. @xref{Preset Output Variables}, @code{ECHO_N} 12384etc.@: for a means to simulate @option{-n}. 12385 12386Do not use backslashes in the arguments, as there is no consensus on 12387their handling. For @samp{echo '\n' | wc -l}, the @command{sh} of 12388Solaris outputs 2, but Bash and Zsh (in @command{sh} emulation mode) output 1. 12389The problem is truly @command{echo}: all the shells 12390understand @samp{'\n'} as the string composed of a backslash and an 12391@samp{n}. 12392 12393Because of these problems, do not pass a string containing arbitrary 12394characters to @command{echo}. For example, @samp{echo "$foo"} is safe 12395if you know that @var{foo}'s value cannot contain backslashes and cannot 12396start with @samp{-}, but otherwise you should use a here-document like 12397this: 12398 12399@example 12400cat <<EOF 12401$foo 12402EOF 12403@end example 12404 12405 12406@item @command{eval} 12407@c ----------------- 12408@prindex @command{eval} 12409The @command{eval} command is useful in limited circumstances, e.g., 12410using commands like @samp{eval table_$key=\$value} and @samp{eval 12411value=table_$key} to simulate a hash table when the key is known to be 12412alphanumeric. However, @command{eval} is tricky to use on arbitrary 12413arguments, even when it is implemented correctly. 12414 12415It is obviously unwise to use @samp{eval $cmd} if the string value of 12416@samp{cmd} was derived from an untrustworthy source. But even if the 12417string value is valid, @samp{eval $cmd} might not work as intended, 12418since it causes field splitting and file name expansion to occur twice, 12419once for the @command{eval} and once for the command itself. It is 12420therefore safer to use @samp{eval "$cmd"}. For example, if @var{cmd} 12421has the value @samp{cat test?.c}, @samp{eval $cmd} might expand to the 12422equivalent of @samp{cat test;.c} if there happens to be a file named 12423@file{test;.c} in the current directory; and this in turn 12424mistakenly attempts to invoke @command{cat} on the file @file{test} and 12425then execute the command @command{.c}. To avoid this problem, use 12426@samp{eval "$cmd"} rather than @samp{eval $cmd}. 12427 12428However, suppose that you want to output the text of the evaluated 12429command just before executing it. Assuming the previous example, 12430@samp{echo "Executing: $cmd"} outputs @samp{Executing: cat test?.c}, but 12431this output doesn't show the user that @samp{test;.c} is the actual name 12432of the copied file. Conversely, @samp{eval "echo Executing: $cmd"} 12433works on this example, but it fails with @samp{cmd='cat foo >bar'}, 12434since it mistakenly replaces the contents of @file{bar} by the 12435string @samp{cat foo}. No simple, general, and portable solution to 12436this problem is known. 12437 12438You should also be wary of common bugs in @command{eval} implementations. 12439In some shell implementations (e.g., older @command{ash}, Open@acronym{BSD} 3.8 12440@command{sh}, @command{pdksh} v5.2.14 99/07/13.2, and @command{zsh} 124414.2.5), the arguments of @samp{eval} are evaluated in a context where 12442@samp{$?} is 0, so they exhibit behavior like this: 12443 12444@example 12445$ @kbd{false; eval 'echo $?'} 124460 12447@end example 12448 12449The correct behavior here is to output a nonzero value, 12450but portable scripts should not rely on this. 12451 12452You should not rely on @code{LINENO} within @command{eval}. 12453@xref{Special Shell Variables}. 12454 12455@item @command{exit} 12456@c ----------------- 12457@prindex @command{exit} 12458The default value of @command{exit} is supposed to be @code{$?}; 12459unfortunately, some shells, such as the @acronym{DJGPP} port of Bash 2.04, just 12460perform @samp{exit 0}. 12461 12462@example 12463bash-2.04$ @kbd{foo=`exit 1` || echo fail} 12464fail 12465bash-2.04$ @kbd{foo=`(exit 1)` || echo fail} 12466fail 12467bash-2.04$ @kbd{foo=`(exit 1); exit` || echo fail} 12468bash-2.04$ 12469@end example 12470 12471Using @samp{exit $?} restores the expected behavior. 12472 12473Some shell scripts, such as those generated by @command{autoconf}, use a 12474trap to clean up before exiting. If the last shell command exited with 12475nonzero status, the trap also exits with nonzero status so that the 12476invoker can tell that an error occurred. 12477 12478Unfortunately, in some shells, such as Solaris @command{/bin/sh}, an exit 12479trap ignores the @code{exit} command's argument. In these shells, a trap 12480cannot determine whether it was invoked by plain @code{exit} or by 12481@code{exit 1}. Instead of calling @code{exit} directly, use the 12482@code{AC_MSG_ERROR} macro that has a workaround for this problem. 12483 12484 12485@item @command{export} 12486@c ------------------- 12487@prindex @command{export} 12488The builtin @command{export} dubs a shell variable @dfn{environment 12489variable}. Each update of exported variables corresponds to an update 12490of the environment variables. Conversely, each environment variable 12491received by the shell when it is launched should be imported as a shell 12492variable marked as exported. 12493 12494Alas, many shells, such as Solaris @command{/bin/sh}, 12495@sc{irix} 6.3, @sc{irix} 5.2, 12496@acronym{AIX} 4.1.5, and Digital Unix 4.0, forget to 12497@command{export} the environment variables they receive. As a result, 12498two variables coexist: the environment variable and the shell 12499variable. The following code demonstrates this failure: 12500 12501@example 12502#!/bin/sh 12503echo $FOO 12504FOO=bar 12505echo $FOO 12506exec /bin/sh $0 12507@end example 12508 12509@noindent 12510when run with @samp{FOO=foo} in the environment, these shells print 12511alternately @samp{foo} and @samp{bar}, although they should print only 12512@samp{foo} and then a sequence of @samp{bar}s. 12513 12514Therefore you should @command{export} again each environment variable 12515that you update. 12516 12517 12518@item @command{false} 12519@c ------------------ 12520@prindex @command{false} 12521Don't expect @command{false} to exit with status 1: in native 12522Solaris @file{/bin/false} exits with status 255. 12523 12524 12525@item @command{for} 12526@c ---------------- 12527@prindex @command{for} 12528To loop over positional arguments, use: 12529 12530@example 12531for arg 12532do 12533 echo "$arg" 12534done 12535@end example 12536 12537@noindent 12538You may @emph{not} leave the @code{do} on the same line as @code{for}, 12539since some shells improperly grok: 12540 12541@example 12542for arg; do 12543 echo "$arg" 12544done 12545@end example 12546 12547If you want to explicitly refer to the positional arguments, given the 12548@samp{$@@} bug (@pxref{Shell Substitutions}), use: 12549 12550@example 12551for arg in $@{1+"$@@"@}; do 12552 echo "$arg" 12553done 12554@end example 12555 12556@noindent 12557But keep in mind that Zsh, even in Bourne shell emulation mode, performs 12558word splitting on @samp{$@{1+"$@@"@}}; see @ref{Shell Substitutions}, 12559item @samp{$@@}, for more. 12560 12561 12562@item @command{if} 12563@c --------------- 12564@prindex @command{if} 12565Using @samp{!} is not portable. Instead of: 12566 12567@example 12568if ! cmp -s file file.new; then 12569 mv file.new file 12570fi 12571@end example 12572 12573@noindent 12574use: 12575 12576@example 12577if cmp -s file file.new; then :; else 12578 mv file.new file 12579fi 12580@end example 12581 12582There are shells that do not reset the exit status from an @command{if}: 12583 12584@example 12585$ @kbd{if (exit 42); then true; fi; echo $?} 1258642 12587@end example 12588 12589@noindent 12590whereas a proper shell should have printed @samp{0}. This is especially 12591bad in makefiles since it produces false failures. This is why properly 12592written makefiles, such as Automake's, have such hairy constructs: 12593 12594@example 12595if test -f "$file"; then 12596 install "$file" "$dest" 12597else 12598 : 12599fi 12600@end example 12601 12602 12603@item @command{printf} 12604@c ------------------ 12605@prindex @command{printf} 12606A format string starting with a @samp{-} can cause problems. 12607Bash (e.g., 2.05b) interprets it as an options argument and 12608gives an error. And @samp{--} to mark the end of options is not good 12609in the Net@acronym{BSD} Almquist shell (e.g., 0.4.6) which takes that 12610literally as the format string. Putting the @samp{-} in a @samp{%c} 12611or @samp{%s} is probably the easiest way to avoid doubt, 12612 12613@example 12614printf %s -foo 12615@end example 12616 12617 12618@item @command{read} 12619@c ------------------ 12620@prindex @command{read} 12621Not all shells support @option{-r} (Solaris @command{/bin/sh} for example). 12622 12623 12624@item @command{pwd} 12625@c ---------------- 12626@prindex @command{pwd} 12627With modern shells, plain @command{pwd} outputs a ``logical'' 12628directory name, some of whose components may be symbolic links. These 12629directory names are in contrast to ``physical'' directory names, whose 12630components are all directories. 12631 12632Posix 1003.1-2001 requires that @command{pwd} must support 12633the @option{-L} (``logical'') and @option{-P} (``physical'') options, 12634with @option{-L} being the default. However, traditional shells do 12635not support these options, and their @command{pwd} command has the 12636@option{-P} behavior. 12637 12638Portable scripts should assume neither option is supported, and should 12639assume neither behavior is the default. Also, on many hosts 12640@samp{/bin/pwd} is equivalent to @samp{pwd -P}, but Posix 12641does not require this behavior and portable scripts should not rely on 12642it. 12643 12644Typically it's best to use plain @command{pwd}. On modern hosts this 12645outputs logical directory names, which have the following advantages: 12646 12647@itemize @bullet 12648@item 12649Logical names are what the user specified. 12650@item 12651Physical names may not be portable from one installation 12652host to another due to network file system gymnastics. 12653@item 12654On modern hosts @samp{pwd -P} may fail due to lack of permissions to 12655some parent directory, but plain @command{pwd} cannot fail for this 12656reason. 12657@end itemize 12658 12659Also please see the discussion of the @command{cd} command. 12660 12661 12662@item @command{set} 12663@c ---------------- 12664@prindex @command{set} 12665With the Free@acronym{BSD} 6.0 shell, the @command{set} command (without 12666any options) does not sort its output. 12667 12668The @command{set} builtin faces the usual problem with arguments starting with a 12669dash. Modern shells such as Bash or Zsh understand @option{--} to specify 12670the end of the options (any argument after @option{--} is a parameter, 12671even @samp{-x} for instance), but many traditional shells (e.g., Solaris 1267210 @command{/bin/sh}) simply stop option 12673processing as soon as a non-option argument is found. Therefore, use 12674@samp{dummy} or simply @samp{x} to end the option processing, and use 12675@command{shift} to pop it out: 12676 12677@example 12678set x $my_list; shift 12679@end example 12680 12681Avoid @samp{set -}, e.g., @samp{set - $my_list}. Posix no 12682longer requires support for this command, and in traditional shells 12683@samp{set - $my_list} resets the @option{-v} and @option{-x} options, which 12684makes scripts harder to debug. 12685 12686Some nonstandard shells do not recognize more than one option 12687(e.g., @samp{set -e -x} assigns @samp{-x} to the command line). It is 12688better to combine them: 12689 12690@example 12691set -ex 12692@end example 12693 12694The @acronym{BSD} shell has had several problems with the @option{-e} 12695option, partly because @acronym{BSD} @command{make} traditionally used 12696@option{-e} even though this was incompatible with Posix 12697(@pxref{Failure in Make Rules}). Older versions of the @acronym{BSD} 12698shell (circa 1990) mishandled @samp{&&}, @samp{||}, @samp{if}, and 12699@samp{case} when @option{-e} was in effect, causing the shell to exit 12700unexpectedly in some cases. This was particularly a problem with 12701makefiles, and led to circumlocutions like @samp{sh -c 'test -f file || 12702touch file'}, where the seemingly-unnecessary @samp{sh -c '@dots{}'} 12703wrapper works around the bug. 12704 12705Even relatively-recent versions of the @acronym{BSD} shell (e.g., 12706Open@acronym{BSD} 3.4) wrongly exit with @option{-e} if a command within 12707@samp{&&} fails inside a compound statement. For example: 12708 12709@example 12710#! /bin/sh 12711set -e 12712foo='' 12713test -n "$foo" && exit 1 12714echo one 12715if :; then 12716 test -n "$foo" && exit 1 12717fi 12718echo two 12719@end example 12720 12721@noindent 12722does not print @samp{two}. One workaround is to use @samp{if test -n 12723"$foo"; then exit 1; fi} rather than @samp{test -n "$foo" && exit 1}. 12724Another possibility is to warn @acronym{BSD} users not to use @samp{sh -e}. 12725 12726 12727@item @command{shift} 12728@c ------------------ 12729@prindex @command{shift} 12730Not only is @command{shift}ing a bad idea when there is nothing left to 12731shift, but in addition it is not portable: the shell of @acronym{MIPS 12732RISC/OS} 4.52 refuses to do it. 12733 12734Don't use @samp{shift 2} etc.; it was not in the 7th Edition Bourne shell, 12735and it is also absent in many pre-Posix shells. 12736 12737 12738@item @command{source} 12739@c ------------------- 12740@prindex @command{source} 12741This command is not portable, as Posix does not require it; use 12742@command{.} instead. 12743 12744 12745@item @command{test} 12746@c ----------------- 12747@prindex @command{test} 12748The @code{test} program is the way to perform many file and string 12749tests. It is often invoked by the alternate name @samp{[}, but using 12750that name in Autoconf code is asking for trouble since it is an M4 quote 12751character. 12752 12753If you need to make multiple checks using @code{test}, combine them with 12754the shell operators @samp{&&} and @samp{||} instead of using the 12755@code{test} operators @option{-a} and @option{-o}. On System V, the 12756precedence of @option{-a} and @option{-o} is wrong relative to the unary 12757operators; consequently, Posix does not specify them, so using them 12758is nonportable. If you combine @samp{&&} and @samp{||} in the same 12759statement, keep in mind that they have equal precedence. 12760 12761It is safe to use @samp{!} as a @command{test} operator. For example, 12762@samp{if test ! -d foo; @dots{}} is portable even though @samp{if ! test 12763-d foo; @dots{}} is not. 12764 12765 12766@item @command{test} (files) 12767@c ------------------------- 12768To enable @command{configure} scripts to support cross-compilation, they 12769shouldn't do anything that tests features of the build system instead of 12770the host system. But occasionally you may find it necessary to check 12771whether some arbitrary file exists. To do so, use @samp{test -f} or 12772@samp{test -r}. Do not use @samp{test -x}, because 4.3@acronym{BSD} does not 12773have it. Do not use @samp{test -e} either, because Solaris @command{/bin/sh} 12774lacks it. To test for symbolic links on systems that have them, use 12775@samp{test -h} rather than @samp{test -L}; either form conforms to 12776Posix 1003.1-2001, but older shells like Solaris 8 12777@code{/bin/sh} support only @option{-h}. 12778 12779@item @command{test} (strings) 12780@c --------------------------- 12781Avoid @samp{test "@var{string}"}, in particular if @var{string} might 12782start with a dash, since @code{test} might interpret its argument as an 12783option (e.g., @samp{@var{string} = "-n"}). 12784 12785Contrary to a common belief, @samp{test -n @var{string}} and 12786@samp{test -z @var{string}} @strong{are} portable. Nevertheless many 12787shells (such as Solaris, @acronym{AIX} 3.2, @sc{unicos} 10.0.0.6, 12788Digital Unix 4, etc.)@: have bizarre precedence and may be confused if 12789@var{string} looks like an operator: 12790 12791@example 12792$ @kbd{test -n =} 12793test: argument expected 12794@end example 12795 12796If there are risks, use @samp{test "x@var{string}" = x} or @samp{test 12797"x@var{string}" != x} instead. 12798 12799It is common to find variations of the following idiom: 12800 12801@example 12802test -n "`echo $ac_feature | sed 's/[-a-zA-Z0-9_]//g'`" && 12803 @var{action} 12804@end example 12805 12806@noindent 12807to take an action when a token matches a given pattern. Such constructs 12808should always be avoided by using: 12809 12810@example 12811echo "$ac_feature" | grep '[^-a-zA-Z0-9_]' >/dev/null 2>&1 && 12812 @var{action} 12813@end example 12814 12815@noindent 12816Use @code{case} where possible since it is faster, being a shell builtin: 12817 12818 12819@example 12820case $ac_feature in 12821 *[!-a-zA-Z0-9_]*) @var{action};; 12822esac 12823@end example 12824 12825Alas, negated character classes are probably not portable, although no 12826shell is known to not support the Posix syntax @samp{[!@dots{}]} 12827(when in interactive mode, @command{zsh} is confused by the 12828@samp{[!@dots{}]} syntax and looks for an event in its history because of 12829@samp{!}). Many shells do not support the alternative syntax 12830@samp{[^@dots{}]} (Solaris, Digital Unix, etc.). 12831 12832One solution can be: 12833 12834@example 12835expr "$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && 12836 @var{action} 12837@end example 12838 12839@noindent 12840or better yet 12841 12842@example 12843expr "X$ac_feature" : '.*[^-a-zA-Z0-9_]' >/dev/null && 12844 @var{action} 12845@end example 12846 12847@samp{expr "X@var{foo}" : "X@var{bar}"} is more robust than @samp{echo 12848"X@var{foo}" | grep "^X@var{bar}"}, because it avoids problems when 12849@samp{@var{foo}} contains backslashes. 12850 12851 12852@item @command{trap} 12853@c ----------------- 12854@prindex @command{trap} 12855It is safe to trap at least the signals 1, 2, 13, and 15. You can also 12856trap 0, i.e., have the @command{trap} run when the script ends (either via an 12857explicit @command{exit}, or the end of the script). The trap for 0 should be 12858installed outside of a shell function, or @acronym{AIX} 5.3 @command{/bin/sh} 12859will invoke the trap at the end of this function. 12860 12861Posix says that @samp{trap - 1 2 13 15} resets the traps for the 12862specified signals to their default values, but many common shells (e.g., 12863Solaris @command{/bin/sh}) misinterpret this and attempt to execute a 12864``command'' named @command{-} when the specified conditions arise. 12865There is no portable workaround, except for @samp{trap - 0}, for which 12866@samp{trap '' 0} is a portable substitute. 12867 12868Although Posix is not absolutely clear on this point, it is widely 12869admitted that when entering the trap @samp{$?} should be set to the exit 12870status of the last command run before the trap. The ambiguity can be 12871summarized as: ``when the trap is launched by an @command{exit}, what is 12872the @emph{last} command run: that before @command{exit}, or 12873@command{exit} itself?'' 12874 12875Bash considers @command{exit} to be the last command, while Zsh and 12876Solaris @command{/bin/sh} consider that when the trap is run it is 12877@emph{still} in the @command{exit}, hence it is the previous exit status 12878that the trap receives: 12879 12880@example 12881$ @kbd{cat trap.sh} 12882trap 'echo $?' 0 12883(exit 42); exit 0 12884$ @kbd{zsh trap.sh} 1288542 12886$ @kbd{bash trap.sh} 128870 12888@end example 12889 12890The portable solution is then simple: when you want to @samp{exit 42}, 12891run @samp{(exit 42); exit 42}, the first @command{exit} being used to 12892set the exit status to 42 for Zsh, and the second to trigger the trap 12893and pass 42 as exit status for Bash. 12894 12895The shell in Free@acronym{BSD} 4.0 has the following bug: @samp{$?} is 12896reset to 0 by empty lines if the code is inside @command{trap}. 12897 12898@example 12899$ @kbd{trap 'false} 12900 12901echo $?' 0 12902$ @kbd{exit} 129030 12904@end example 12905 12906@noindent 12907Fortunately, this bug only affects @command{trap}. 12908 12909@item @command{true} 12910@c ----------------- 12911@prindex @command{true} 12912@c Info cannot handle `:' in index entries. 12913@c @prindex @command{:} 12914Don't worry: as far as we know @command{true} is portable. 12915Nevertheless, it's not always a builtin (e.g., Bash 1.x), and the 12916portable shell community tends to prefer using @command{:}. This has a 12917funny side effect: when asked whether @command{false} is more portable 12918than @command{true} Alexandre Oliva answered: 12919 12920@quotation 12921In a sense, yes, because if it doesn't exist, the shell will produce an 12922exit status of failure, which is correct for @command{false}, but not 12923for @command{true}. 12924@end quotation 12925 12926 12927@item @command{unset} 12928@c ------------------ 12929@prindex @command{unset} 12930In some nonconforming shells (e.g., Bash 2.05a), @code{unset FOO} fails 12931when @code{FOO} is not set. Also, Bash 2.01 mishandles @code{unset 12932MAIL} in some cases and dumps core. 12933 12934A few ancient shells lack @command{unset} entirely. Nevertheless, because 12935it is extremely useful to disable embarrassing variables such as 12936@code{PS1}, you can test for its existence and use 12937it @emph{provided} you give a neutralizing value when @command{unset} is 12938not supported: 12939 12940@smallexample 12941# "|| exit" suppresses any "Segmentation fault" message. 12942if ( (MAIL=60; unset MAIL) || exit) >/dev/null 2>&1; then 12943 unset=unset 12944else 12945 unset=false 12946fi 12947$unset PS1 || PS1='$ ' 12948@end smallexample 12949 12950@noindent 12951@xref{Special Shell Variables}, for some neutralizing values. Also, see 12952@ref{Limitations of Builtins}, documentation of @command{export}, for 12953the case of environment variables. 12954@end table 12955 12956@node Limitations of Usual Tools 12957@section Limitations of Usual Tools 12958@cindex Limitations of usual tools 12959 12960The small set of tools you can expect to find on any machine can still 12961include some limitations you should be aware of. 12962 12963@table @asis 12964@item Awk 12965@c ------ 12966@prindex Awk 12967Don't leave white space before the opening parenthesis in a user function call. 12968Posix does not allow this and @acronym{GNU} Awk rejects it: 12969 12970@example 12971$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 12972 BEGIN @{ die () @}'} 12973gawk: cmd. line:2: BEGIN @{ die () @} 12974gawk: cmd. line:2: ^ parse error 12975$ @kbd{gawk 'function die () @{ print "Aaaaarg!" @} 12976 BEGIN @{ die() @}'} 12977Aaaaarg! 12978@end example 12979 12980If you want your program to be deterministic, don't depend on @code{for} 12981on arrays: 12982 12983@example 12984$ @kbd{cat for.awk} 12985END @{ 12986 arr["foo"] = 1 12987 arr["bar"] = 1 12988 for (i in arr) 12989 print i 12990@} 12991$ @kbd{gawk -f for.awk </dev/null} 12992foo 12993bar 12994$ @kbd{nawk -f for.awk </dev/null} 12995bar 12996foo 12997@end example 12998 12999Some Awk implementations, such as @acronym{HP-UX} 11.0's native one, mishandle anchors: 13000 13001@example 13002$ @kbd{echo xfoo | $AWK '/foo|^bar/ @{ print @}'} 13003$ @kbd{echo bar | $AWK '/foo|^bar/ @{ print @}'} 13004bar 13005$ @kbd{echo xfoo | $AWK '/^bar|foo/ @{ print @}'} 13006xfoo 13007$ @kbd{echo bar | $AWK '/^bar|foo/ @{ print @}'} 13008bar 13009@end example 13010 13011@noindent 13012Either do not depend on such patterns (i.e., use @samp{/^(.*foo|bar)/}, 13013or use a simple test to reject such implementations. 13014 13015@acronym{AIX} version 5.2 has an arbitrary limit of 399 on the 13016length of regular expressions and literal strings in an Awk program. 13017 13018Traditional Awk implementations derived from Unix version 7, such as 13019Solaris @command{/bin/awk}, have many limitations and do not 13020conform to Posix. Nowadays @code{AC_PROG_AWK} (@pxref{Particular 13021Programs}) finds you an Awk that doesn't have these problems, but if 13022for some reason you prefer not to use @code{AC_PROG_AWK} you may need to 13023address them. 13024 13025Traditional Awk does not support multidimensional arrays or user-defined 13026functions. 13027 13028Traditional Awk does not support the @option{-v} option. You can use 13029assignments after the program instead, e.g., @command{$AWK '@{print v 13030$1@}' v=x}; however, don't forget that such assignments are not 13031evaluated until they are encountered (e.g., after any @code{BEGIN} 13032action). 13033 13034Traditional Awk does not support the keywords @code{delete} or @code{do}. 13035 13036Traditional Awk does not support the expressions 13037@code{@var{a}?@var{b}:@var{c}}, @code{!@var{a}}, @code{@var{a}^@var{b}}, 13038or @code{@var{a}^=@var{b}}. 13039 13040Traditional Awk does not support the predefined @code{CONVFMT} variable. 13041 13042Traditional Awk supports only the predefined functions @code{exp}, 13043@code{int}, @code{length}, @code{log}, @code{split}, @code{sprintf}, 13044@code{sqrt}, and @code{substr}. 13045 13046Traditional Awk @code{getline} is not at all compatible with Posix; 13047avoid it. 13048 13049Traditional Awk @code{split} supports only two arguments. 13050 13051Traditional Awk has a limit of 99 13052fields in a record. You may be able to circumvent this problem by using 13053@code{split}. 13054 13055 13056@item @command{basename} 13057@c --------------------- 13058@prindex @command{basename} 13059Not all hosts have a working @command{basename}. 13060You can use @command{expr} instead. 13061 13062@c AS_BASENAME is to be replaced by a better API. 13063@ignore 13064Not all hosts have a working @command{basename}, and you should instead 13065use @code{AS_BASENAME} (@pxref{Programming in M4sh}), followed by 13066@command{expr} if you need to strip a suffix. For example: 13067 13068@example 13069a=`basename "$aname"` # This is not portable. 13070a=`AS_BASENAME(["$aname"])` # This is more portable. 13071 13072# This is not portable. 13073c=`basename "$cname" .c` 13074 13075# This is more portable. 13076c=`AS_BASENAME(["$cname"])` 13077case $c in 13078?*.c) c=`expr "X$c" : 'X\(.*\)\.c'`;; 13079esac 13080@end example 13081@end ignore 13082 13083 13084@item @command{cat} 13085@c ---------------- 13086@prindex @command{cat} 13087Don't rely on any option. 13088 13089 13090@item @command{cc} 13091@c --------------- 13092@prindex @command{cc} 13093The command @samp{cc -c foo.c} traditionally produces an object file 13094named @file{foo.o}. Most compilers allow @option{-c} to be combined 13095with @option{-o} to specify a different object file name, but 13096Posix does not require this combination and a few compilers 13097lack support for it. @xref{C Compiler}, for how @acronym{GNU} Make 13098tests for this feature with @code{AC_PROG_CC_C_O}. 13099 13100When a compilation such as @samp{cc -o foo foo.c} fails, some compilers 13101(such as @sc{cds} on Reliant Unix) leave a @file{foo.o}. 13102 13103@acronym{HP-UX} @command{cc} doesn't accept @file{.S} files to preprocess and 13104assemble. @samp{cc -c foo.S} appears to succeed, but in fact does 13105nothing. 13106 13107The default executable, produced by @samp{cc foo.c}, can be 13108 13109@itemize 13110@item @file{a.out} --- usual Posix convention. 13111@item @file{b.out} --- i960 compilers (including @command{gcc}). 13112@item @file{a.exe} --- @acronym{DJGPP} port of @command{gcc}. 13113@item @file{a_out.exe} --- GNV @command{cc} wrapper for DEC C on OpenVMS. 13114@item @file{foo.exe} --- various MS-DOS compilers. 13115@end itemize 13116 13117The C compiler's traditional name is @command{cc}, but other names like 13118@command{gcc} are common. Posix 1003.1-2001 specifies the 13119name @command{c99}, but older Posix editions specified 13120@command{c89} and anyway these standard names are rarely used in 13121practice. Typically the C compiler is invoked from makefiles that use 13122@samp{$(CC)}, so the value of the @samp{CC} make variable selects the 13123compiler name. 13124 13125 13126@item @command{chmod} 13127@c ------------------ 13128@prindex @command{chmod} 13129Avoid usages like @samp{chmod -w file}; use @samp{chmod a-w file} 13130instead, for two reasons. First, plain @option{-w} does not necessarily 13131make the file unwritable, since it does not affect mode bits that 13132correspond to bits in the file mode creation mask. Second, 13133Posix says that the @option{-w} might be interpreted as an 13134implementation-specific option, not as a mode; Posix suggests 13135using @samp{chmod -- -w file} to avoid this confusion, but unfortunately 13136@samp{--} does not work on some older hosts. 13137 13138 13139@item @command{cmp} 13140@c ---------------- 13141@prindex @command{cmp} 13142@command{cmp} performs a raw data comparison of two files, while 13143@command{diff} compares two text files. Therefore, if you might compare 13144DOS files, even if only checking whether two files are different, use 13145@command{diff} to avoid spurious differences due to differences of 13146newline encoding. 13147 13148 13149@item @command{cp} 13150@c --------------- 13151@prindex @command{cp} 13152Avoid the @option{-r} option, since Posix 1003.1-2004 marks it as 13153obsolescent and its behavior on special files is implementation-defined. 13154Use @option{-R} instead. On @acronym{GNU} hosts the two options 13155are equivalent, but on Solaris hosts (for example) @command{cp -r} 13156reads from pipes instead of replicating them. 13157 13158Some @command{cp} implementations (e.g., @acronym{BSD/OS} 4.2) do not allow 13159trailing slashes at the end of nonexistent destination directories. To 13160avoid this problem, omit the trailing slashes. For example, use 13161@samp{cp -R source /tmp/newdir} rather than @samp{cp -R source 13162/tmp/newdir/} if @file{/tmp/newdir} does not exist. 13163 13164@c This is thanks to Ian. 13165The ancient SunOS 4 @command{cp} does not support @option{-f}, although 13166its @command{mv} does. 13167 13168@cindex timestamp resolution 13169Traditionally, file timestamps had 1-second resolution, and @samp{cp 13170-p} copied the timestamps exactly. However, many modern file systems 13171have timestamps with 1-nanosecond resolution. Unfortunately, @samp{cp 13172-p} implementations truncate timestamps when copying files, so this 13173can result in the destination file appearing to be older than the 13174source. The exact amount of truncation depends on the resolution of 13175the system calls that @command{cp} uses; traditionally this was 13176@code{utime}, which has 1-second resolution, but some newer 13177@command{cp} implementations use @code{utimes}, which has 131781-microsecond resolution. These newer implementations include @acronym{GNU} 13179Core Utilities 5.0.91 or later, and Solaris 8 (sparc) patch 109933-02 or 13180later. Unfortunately as of January 2006 there is still no system 13181call to set timestamps to the full nanosecond resolution. 13182 13183Bob Proulx notes that @samp{cp -p} always @emph{tries} to copy 13184ownerships. But whether it actually does copy ownerships or not is a 13185system dependent policy decision implemented by the kernel. If the 13186kernel allows it then it happens. If the kernel does not allow it then 13187it does not happen. It is not something @command{cp} itself has control 13188over. 13189 13190In Unix System V any user can chown files to any other user, and System 13191V also has a non-sticky @file{/tmp}. That probably derives from the 13192heritage of System V in a business environment without hostile users. 13193@acronym{BSD} changed this 13194to be a more secure model where only root can @command{chown} files and 13195a sticky @file{/tmp} is used. That undoubtedly derives from the heritage 13196of @acronym{BSD} in a campus environment. 13197 13198@acronym{GNU}/Linux and Solaris by default follow @acronym{BSD}, but 13199can be configured to allow a System V style @command{chown}. On the 13200other hand, @acronym{HP-UX} follows System V, but can 13201be configured to use the modern security model and disallow 13202@command{chown}. Since it is an administrator-configurable parameter 13203you can't use the name of the kernel as an indicator of the behavior. 13204 13205 13206 13207@item @command{date} 13208@c ----------------- 13209@prindex @command{date} 13210Some versions of @command{date} do not recognize special @samp{%} directives, 13211and unfortunately, instead of complaining, they just pass them through, 13212and exit with success: 13213 13214@example 13215$ @kbd{uname -a} 13216OSF1 medusa.sis.pasteur.fr V5.1 732 alpha 13217$ @kbd{date "+%s"} 13218%s 13219@end example 13220 13221 13222@item @command{diff} 13223@c ----------------- 13224@prindex @command{diff} 13225Option @option{-u} is nonportable. 13226 13227Some implementations, such as Tru64's, fail when comparing to 13228@file{/dev/null}. Use an empty file instead. 13229 13230 13231@item @command{dirname} 13232@c -------------------- 13233@prindex @command{dirname} 13234Not all hosts have a working @command{dirname}, and you should instead 13235use @code{AS_DIRNAME} (@pxref{Programming in M4sh}). For example: 13236 13237@example 13238dir=`dirname "$file"` # This is not portable. 13239dir=`AS_DIRNAME(["$file"])` # This is more portable. 13240@end example 13241 13242 13243@item @command{egrep} 13244@c ------------------ 13245@prindex @command{egrep} 13246Posix 1003.1-2001 no longer requires @command{egrep}, 13247but many older hosts do not yet support the Posix 13248replacement @code{grep -E}. Also, some traditional implementations do 13249not work on long input lines. To work around these problems, invoke 13250@code{AC_PROG_EGREP} and then use @code{$EGREP}. 13251 13252Portable extended regular expressions should use @samp{\} only to escape 13253characters in the string @samp{$()*+.?[\^@{|}. For example, @samp{\@}} 13254is not portable, even though it typically matches @samp{@}}. 13255 13256The empty alternative is not portable. Use @samp{?} instead. For 13257instance with Digital Unix v5.0: 13258 13259@example 13260> printf "foo\n|foo\n" | $EGREP '^(|foo|bar)$' 13261|foo 13262> printf "bar\nbar|\n" | $EGREP '^(foo|bar|)$' 13263bar| 13264> printf "foo\nfoo|\n|bar\nbar\n" | $EGREP '^(foo||bar)$' 13265foo 13266|bar 13267@end example 13268 13269@command{$EGREP} also suffers the limitations of @command{grep}. 13270 13271@item @command{expr} 13272@c ----------------- 13273@prindex @command{expr} 13274No @command{expr} keyword starts with @samp{X}, so use @samp{expr 13275X"@var{word}" : 'X@var{regex}'} to keep @command{expr} from 13276misinterpreting @var{word}. 13277 13278Don't use @code{length}, @code{substr}, @code{match} and @code{index}. 13279 13280@item @command{expr} (@samp{|}) 13281@prindex @command{expr} (@samp{|}) 13282You can use @samp{|}. Although Posix does require that @samp{expr 13283''} return the empty string, it does not specify the result when you 13284@samp{|} together the empty string (or zero) with the empty string. For 13285example: 13286 13287@example 13288expr '' \| '' 13289@end example 13290 13291Posix 1003.2-1992 returns the empty string 13292for this case, but traditional Unix returns @samp{0} (Solaris is 13293one such example). In Posix 1003.1-2001, the specification was 13294changed to match traditional Unix's behavior (which is 13295bizarre, but it's too late to fix this). Please note that the same 13296problem does arise when the empty string results from a computation, 13297as in: 13298 13299@example 13300expr bar : foo \| foo : bar 13301@end example 13302 13303@noindent 13304Avoid this portability problem by avoiding the empty string. 13305 13306 13307@item @command{expr} (@samp{:}) 13308@c ---------------------------- 13309@prindex @command{expr} 13310Portable @command{expr} regular expressions should use @samp{\} to 13311escape only characters in the string @samp{$()*.0123456789[\^n@{@}}. 13312For example, alternation, @samp{\|}, is common but Posix does not 13313require its support, so it should be avoided in portable scripts. 13314Similarly, @samp{\+} and @samp{\?} should be avoided. 13315 13316Portable @command{expr} regular expressions should not begin with 13317@samp{^}. Patterns are automatically anchored so leading @samp{^} is 13318not needed anyway. 13319 13320The Posix standard is ambiguous as to whether 13321@samp{expr 'a' : '\(b\)'} outputs @samp{0} or the empty string. 13322In practice, it outputs the empty string on most platforms, but portable 13323scripts should not assume this. For instance, the @acronym{QNX} 4.25 native 13324@command{expr} returns @samp{0}. 13325 13326One might think that a way to get a uniform behavior would be to use 13327the empty string as a default value: 13328 13329@example 13330expr a : '\(b\)' \| '' 13331@end example 13332 13333@noindent 13334Unfortunately this behaves exactly as the original expression; see the 13335@command{expr} (@samp{|}) entry for more information. 13336 13337Ancient @command{expr} implementations (e.g., SunOS 4 @command{expr} and 13338Solaris 8 @command{/usr/ucb/expr}) have a silly length limit that causes 13339@command{expr} to fail if the matched substring is longer than 120 13340bytes. In this case, you might want to fall back on @samp{echo|sed} if 13341@command{expr} fails. Nowadays this is of practical importance only for 13342the rare installer who mistakenly puts @file{/usr/ucb} before 13343@file{/usr/bin} in @env{PATH}. 13344 13345On Mac OS X 10.4, @command{expr} mishandles the pattern @samp{[^-]} in 13346some cases. For example, the command 13347@example 13348expr Xpowerpc-apple-darwin8.1.0 : 'X[^-]*-[^-]*-\(.*\)' 13349@end example 13350 13351@noindent 13352outputs @samp{apple-darwin8.1.0} rather than the correct @samp{darwin8.1.0}. 13353This particular case can be worked around by substituting @samp{[^--]} 13354for @samp{[^-]}. 13355 13356Don't leave, there is some more! 13357 13358The @acronym{QNX} 4.25 @command{expr}, in addition of preferring @samp{0} to 13359the empty string, has a funny behavior in its exit status: it's always 1 13360when parentheses are used! 13361 13362@example 13363$ @kbd{val=`expr 'a' : 'a'`; echo "$?: $val"} 133640: 1 13365$ @kbd{val=`expr 'a' : 'b'`; echo "$?: $val"} 133661: 0 13367 13368$ @kbd{val=`expr 'a' : '\(a\)'`; echo "?: $val"} 133691: a 13370$ @kbd{val=`expr 'a' : '\(b\)'`; echo "?: $val"} 133711: 0 13372@end example 13373 13374@noindent 13375In practice this can be a big problem if you are ready to catch failures 13376of @command{expr} programs with some other method (such as using 13377@command{sed}), since you may get twice the result. For instance 13378 13379@example 13380$ @kbd{expr 'a' : '\(a\)' || echo 'a' | sed 's/^\(a\)$/\1/'} 13381@end example 13382 13383@noindent 13384outputs @samp{a} on most hosts, but @samp{aa} on @acronym{QNX} 4.25. A 13385simple workaround consists of testing @command{expr} and using a variable 13386set to @command{expr} or to @command{false} according to the result. 13387 13388Tru64 @command{expr} incorrectly treats the result as a number, if it 13389can be interpreted that way: 13390 13391@example 13392$ @kbd{expr 00001 : '.*\(...\)'} 133931 13394@end example 13395 13396 13397@item @command{fgrep} 13398@c ------------------ 13399@prindex @command{fgrep} 13400Posix 1003.1-2001 no longer requires @command{fgrep}, 13401but many older hosts do not yet support the Posix 13402replacement @code{grep -F}. Also, some traditional implementations do 13403not work on long input lines. To work around these problems, invoke 13404@code{AC_PROG_FGREP} and then use @code{$FGREP}. 13405 13406 13407@item @command{find} 13408@c ----------------- 13409@prindex @command{find} 13410The option @option{-maxdepth} seems to be @acronym{GNU} specific. 13411Tru64 v5.1, Net@acronym{BSD} 1.5 and Solaris @command{find} 13412commands do not understand it. 13413 13414The replacement of @samp{@{@}} is guaranteed only if the argument is 13415exactly @emph{@{@}}, not if it's only a part of an argument. For 13416instance on DU, and @acronym{HP-UX} 10.20 and @acronym{HP-UX} 11: 13417 13418@example 13419$ @kbd{touch foo} 13420$ @kbd{find . -name foo -exec echo "@{@}-@{@}" \;} 13421@{@}-@{@} 13422@end example 13423 13424@noindent 13425while @acronym{GNU} @command{find} reports @samp{./foo-./foo}. 13426 13427 13428@item @command{grep} 13429@c ----------------- 13430@prindex @command{grep} 13431Portable scripts can rely on the @command{grep} options @option{-c}, 13432@option{-l}, @option{-n}, and @option{-v}, but should avoid other 13433options. For example, don't use @option{-w}, as Posix does not require 13434it and Irix 6.5.16m's @command{grep} does not support it. Also, 13435portable scripts should not combine @option{-c} with @option{-l}, 13436as Posix does not allow this. 13437 13438Some of the options required by Posix are not portable in practice. 13439Don't use @samp{grep -q} to suppress output, because many @command{grep} 13440implementations (e.g., Solaris) do not support @option{-q}. 13441Don't use @samp{grep -s} to suppress output either, because Posix 13442says @option{-s} does not suppress output, only some error messages; 13443also, the @option{-s} option of traditional @command{grep} behaved 13444like @option{-q} does in most modern implementations. Instead, 13445redirect the standard output and standard error (in case the file 13446doesn't exist) of @code{grep} to @file{/dev/null}. Check the exit 13447status of @code{grep} to determine whether it found a match. 13448 13449Some traditional @command{grep} implementations do not work on long 13450input lines. On AIX the default @code{grep} silently truncates long 13451lines on the input before matching. 13452 13453Also, many implementations do not support multiple regexps 13454with @option{-e}: they either reject @option{-e} entirely (e.g., Solaris) 13455or honor only the last pattern (e.g., @acronym{IRIX} 6.5 and NeXT). To 13456work around these problems, invoke @code{AC_PROG_GREP} and then use 13457@code{$GREP}. 13458 13459Another possible workaround for the multiple @option{-e} problem is to 13460separate the patterns by newlines, for example: 13461 13462@example 13463grep 'foo 13464bar' in.txt 13465@end example 13466 13467@noindent 13468except that this fails with traditional @command{grep} 13469implementations and with Open@acronym{BSD} 3.8 @command{grep}. 13470 13471Traditional @command{grep} implementations (e.g., Solaris) do not 13472support the @option{-E} or @option{-F} options. To work around these 13473problems, invoke @code{AC_PROG_EGREP} and then use @code{$EGREP}, and 13474similarly for @code{AC_PROG_FGREP} and @code{$FGREP}. Even if you are 13475willing to require support for Posix @command{grep}, your script should 13476not use both @option{-E} and @option{-F}, since Posix does not allow 13477this combination. 13478 13479Portable @command{grep} regular expressions should use @samp{\} only to 13480escape characters in the string @samp{$()*.0123456789[\^@{@}}. For example, 13481alternation, @samp{\|}, is common but Posix does not require its 13482support in basic regular expressions, so it should be avoided in 13483portable scripts. Solaris @command{grep} does not support it. 13484Similarly, @samp{\+} and @samp{\?} should be avoided. 13485 13486 13487@item @command{join} 13488@c ----------------- 13489@prindex @command{join} 13490Solaris 8 @command{join} has bugs when the second operand is standard 13491input, and when standard input is a pipe. For example, the following 13492shell script causes Solaris 8 @command{join} to loop forever: 13493 13494@example 13495cat >file <<'EOF' 134961 x 134972 y 13498EOF 13499cat file | join file - 13500@end example 13501 13502Use @samp{join - file} instead. 13503 13504 13505@item @command{ln} 13506@c --------------- 13507@prindex @command{ln} 13508@cindex Symbolic links 13509Don't rely on @command{ln} having a @option{-f} option. Symbolic links 13510are not available on old systems; use @samp{$(LN_S)} as a portable substitute. 13511 13512For versions of the @acronym{DJGPP} before 2.04, 13513@command{ln} emulates symbolic links 13514to executables by generating a stub that in turn calls the real 13515program. This feature also works with nonexistent files like in the 13516Posix spec. So @samp{ln -s file link} generates @file{link.exe}, 13517which attempts to call @file{file.exe} if run. But this feature only 13518works for executables, so @samp{cp -p} is used instead for these 13519systems. @acronym{DJGPP} versions 2.04 and later have full support 13520for symbolic links. 13521 13522 13523@item @command{ls} 13524@c --------------- 13525@prindex @command{ls} 13526@cindex Listing directories 13527The portable options are @option{-acdilrtu}. Current practice is for 13528@option{-l} to output both owner and group, even though ancient versions 13529of @command{ls} omitted the group. 13530 13531On ancient hosts, @samp{ls foo} sent the diagnostic @samp{foo not found} 13532to standard output if @file{foo} did not exist. Hence a shell command 13533like @samp{sources=`ls *.c 2>/dev/null`} did not always work, since it 13534was equivalent to @samp{sources='*.c not found'} in the absence of 13535@samp{.c} files. This is no longer a practical problem, since current 13536@command{ls} implementations send diagnostics to standard error. 13537 13538@item @command{mkdir} 13539@c ------------------ 13540@prindex @command{mkdir} 13541@cindex Making directories 13542No @command{mkdir} option is portable to older systems. Instead of 13543@samp{mkdir -p @var{file-name}}, you should use 13544@code{AS_MKDIR_P(@var{file-name})} (@pxref{Programming in M4sh}) 13545or @code{AC_PROG_MKDIR_P} (@pxref{Particular Programs}). 13546 13547Combining the @option{-m} and @option{-p} options, as in @samp{mkdir -m 13548go-w -p @var{dir}}, often leads to trouble. Free@acronym{BSD} 13549@command{mkdir} incorrectly attempts to change the permissions of 13550@var{dir} even if it already exists. @acronym{HP-UX} 11.23 and 13551@acronym{IRIX} 6.5 @command{mkdir} often assign the wrong permissions to 13552any newly-created parents of @var{dir}. 13553 13554Posix does not clearly specify whether @samp{mkdir -p foo} 13555should succeed when @file{foo} is a symbolic link to an already-existing 13556directory. The @acronym{GNU} Core Utilities 5.1.0 @command{mkdir} 13557succeeds, but Solaris @command{mkdir} fails. 13558 13559Traditional @code{mkdir -p} implementations suffer from race conditions. 13560For example, if you invoke @code{mkdir -p a/b} and @code{mkdir -p a/c} 13561at the same time, both processes might detect that @file{a} is missing, 13562one might create @file{a}, then the other might try to create @file{a} 13563and fail with a @code{File exists} diagnostic. The @acronym{GNU} Core 13564Utilities (@samp{fileutils} version 4.1), Free@acronym{BSD} 5.0, 13565Net@acronym{BSD} 2.0.2, and Open@acronym{BSD} 2.4 are known to be 13566race-free when two processes invoke @code{mkdir -p} simultaneously, but 13567earlier versions are vulnerable. Solaris @command{mkdir} is still 13568vulnerable as of Solaris 10, and other traditional Unix systems are 13569probably vulnerable too. This possible race is harmful in parallel 13570builds when several Make rules call @code{mkdir -p} to 13571construct directories. You may use 13572@code{install-sh -d} as a safe replacement, provided this script is 13573recent enough; the copy shipped with Autoconf 2.60 and Automake 1.10 is 13574OK, but copies from older versions are vulnerable. 13575 13576 13577@item @command{mktemp} 13578@c ------------------- 13579@prindex @command{mktemp} 13580@cindex Creating temporary files 13581Shell scripts can use temporary files safely with @command{mktemp}, but 13582it does not exist on all systems. A portable way to create a safe 13583temporary file name is to create a temporary directory with mode 700 and 13584use a file inside this directory. Both methods prevent attackers from 13585gaining control, though @command{mktemp} is far less likely to fail 13586gratuitously under attack. 13587 13588Here is sample code to create a new temporary directory safely: 13589 13590@example 13591# Create a temporary directory $tmp in $TMPDIR (default /tmp). 13592# Use mktemp if possible; otherwise fall back on mkdir, 13593# with $RANDOM to make collisions less likely. 13594: $@{TMPDIR=/tmp@} 13595@{ 13596 tmp=` 13597 (umask 077 && mktemp -d "$TMPDIR/fooXXXXXX") 2>/dev/null 13598 ` && 13599 test -n "$tmp" && test -d "$tmp" 13600@} || @{ 13601 tmp=$TMPDIR/foo$$-$RANDOM 13602 (umask 077 && mkdir "$tmp") 13603@} || exit $? 13604@end example 13605 13606 13607@item @command{mv} 13608@c --------------- 13609@prindex @command{mv} 13610@cindex Moving open files 13611The only portable options are @option{-f} and @option{-i}. 13612 13613Moving individual files between file systems is portable (it was in Unix 13614version 6), 13615but it is not always atomic: when doing @samp{mv new existing}, there's 13616a critical section where neither the old nor the new version of 13617@file{existing} actually exists. 13618 13619On some systems moving files from @file{/tmp} can sometimes cause 13620undesirable (but perfectly valid) warnings, even if you created these 13621files. This is because @file{/tmp} belongs to a group that ordinary 13622users are not members of, and files created in @file{/tmp} inherit 13623the group of @file{/tmp}. When the file is copied, @command{mv} issues 13624a diagnostic without failing: 13625 13626@smallexample 13627$ @kbd{touch /tmp/foo} 13628$ @kbd{mv /tmp/foo .} 13629@error{}mv: ./foo: set owner/group (was: 100/0): Operation not permitted 13630$ @kbd{echo $?} 136310 13632$ @kbd{ls foo} 13633foo 13634@end smallexample 13635 13636@noindent 13637This annoying behavior conforms to Posix, unfortunately. 13638 13639Moving directories across mount points is not portable, use @command{cp} 13640and @command{rm}. 13641 13642@acronym{DOS} variants cannot rename or remove open files, and do not 13643support commands like @samp{mv foo bar >foo}, even though this is 13644perfectly portable among Posix hosts. 13645 13646 13647@item @command{od} 13648@c --------------- 13649@prindex @command{od} 13650 13651In Mac OS X 10.3, @command{od} does not support the 13652standard Posix options @option{-A}, @option{-j}, @option{-N}, or 13653@option{-t}, or the @acronym{XSI} option @option{-s}. The only 13654supported Posix option is @option{-v}, and the only supported 13655@acronym{XSI} options are those in @option{-bcdox}. The @acronym{BSD} 13656@command{hexdump} program can be used instead. 13657 13658This problem no longer exists in Mac OS X 10.4.3. 13659 13660 13661@item @command{rm} 13662@c --------------- 13663@prindex @command{rm} 13664The @option{-f} and @option{-r} options are portable. 13665 13666It is not portable to invoke @command{rm} without operands. For 13667example, on many systems @samp{rm -f -r} (with no other arguments) 13668silently succeeds without doing anything, but it fails with a diagnostic 13669on Net@acronym{BSD} 2.0.2. 13670 13671A file might not be removed even if its parent directory is writable 13672and searchable. Many Posix hosts cannot remove a mount point, a named 13673stream, a working directory, or a last link to a file that is being 13674executed. 13675 13676@acronym{DOS} variants cannot rename or remove open files, and do not 13677support commands like @samp{rm foo >foo}, even though this is 13678perfectly portable among Posix hosts. 13679 13680 13681@item @command{sed} 13682@c ---------------- 13683@prindex @command{sed} 13684Patterns should not include the separator (unless escaped), even as part 13685of a character class. In conformance with Posix, the Cray 13686@command{sed} rejects @samp{s/[^/]*$//}: use @samp{s,[^/]*$,,}. 13687 13688Avoid empty patterns within parentheses (i.e., @samp{\(\)}). Posix does 13689not require support for empty patterns, and Unicos 9 @command{sed} rejects 13690them. 13691 13692Unicos 9 @command{sed} loops endlessly on patterns like @samp{.*\n.*}. 13693 13694Sed scripts should not use branch labels longer than 8 characters and 13695should not contain comments. @acronym{HP-UX} sed has a limit of 99 commands 13696(not counting @samp{:} commands) and 1369748 labels, which can not be circumvented by using more than one script 13698file. It can execute up to 19 reads with the @samp{r} command per cycle. 13699Solaris @command{/usr/ucb/sed} rejects usages that exceed an limit of 13700about 6000 bytes for the internal representation of commands. 13701 13702Avoid redundant @samp{;}, as some @command{sed} implementations, such as 13703Net@acronym{BSD} 1.4.2's, incorrectly try to interpret the second 13704@samp{;} as a command: 13705 13706@example 13707$ @kbd{echo a | sed 's/x/x/;;s/x/x/'} 13708sed: 1: "s/x/x/;;s/x/x/": invalid command code ; 13709@end example 13710 13711Input should not have unreasonably long lines, since some @command{sed} 13712implementations have an input buffer limited to 4000 bytes. 13713 13714Portable @command{sed} regular expressions should use @samp{\} only to escape 13715characters in the string @samp{$()*.0123456789[\^n@{@}}. For example, 13716alternation, @samp{\|}, is common but Posix does not require its 13717support, so it should be avoided in portable scripts. Solaris 13718@command{sed} does not support alternation; e.g., @samp{sed '/a\|b/d'} 13719deletes only lines that contain the literal string @samp{a|b}. 13720Similarly, @samp{\+} and @samp{\?} should be avoided. 13721 13722Anchors (@samp{^} and @samp{$}) inside groups are not portable. 13723 13724Nested parenthesization in patterns (e.g., @samp{\(\(a*\)b*)\)}) is 13725quite portable to current hosts, but was not supported by some ancient 13726@command{sed} implementations like SVR3. 13727 13728Some @command{sed} implementations, e.g., Solaris, 13729restrict the special role of the asterisk to one-character regular expressions. 13730This may lead to unexpected behavior: 13731 13732@example 13733$ @kbd{echo '1*23*4' | /usr/bin/sed 's/\(.\)*/x/g'} 13734x2x4 13735$ @kbd{echo '1*23*4' | /usr/xpg4/bin/sed 's/\(.\)*/x/g'} 13736x 13737@end example 13738 13739The @option{-e} option is portable, so long as its argument 13740does not begin with @samp{a}, @samp{c}, or @samp{i} 13741(as this runs afoul of a Tru64 5.1 bug). 13742Some people prefer to use @samp{-e}: 13743 13744@example 13745sed -e '@var{command-1}' \ 13746 -e '@var{command-2}' 13747@end example 13748 13749@noindent 13750as opposed to the equivalent: 13751 13752@example 13753sed ' 13754 @var{command-1} 13755 @var{command-2} 13756' 13757@end example 13758 13759@noindent 13760The following usage is sometimes equivalent: 13761 13762@example 13763sed '@var{command-1};@var{command-2}' 13764@end example 13765 13766but Posix says that this use of a semicolon has undefined effect if 13767@var{command-1}'s verb is @samp{@{}, @samp{a}, @samp{b}, @samp{c}, 13768@samp{i}, @samp{r}, @samp{t}, @samp{w}, @samp{:}, or @samp{#}, so you 13769should use semicolon only with simple scripts that do not use these 13770verbs. 13771 13772Commands inside @{ @} brackets are further restricted. Posix says that 13773they cannot be preceded by addresses, @samp{!}, or @samp{;}, and that 13774each command must be followed immediately by a newline, without any 13775intervening blanks or semicolons. The closing bracket must be alone on 13776a line, other than white space preceding or following it. 13777 13778Contrary to yet another urban legend, you may portably use @samp{&} in 13779the replacement part of the @code{s} command to mean ``what was 13780matched''. All descendants of Unix version 7 @command{sed} 13781(at least; we 13782don't have first hand experience with older @command{sed} implementations) have 13783supported it. 13784 13785Posix requires that you must not have any white space between 13786@samp{!} and the following command. It is OK to have blanks between 13787the address and the @samp{!}. For instance, on Solaris: 13788 13789@example 13790$ @kbd{echo "foo" | sed -n '/bar/ ! p'} 13791@error{}Unrecognized command: /bar/ ! p 13792$ @kbd{echo "foo" | sed -n '/bar/! p'} 13793@error{}Unrecognized command: /bar/! p 13794$ @kbd{echo "foo" | sed -n '/bar/ !p'} 13795foo 13796@end example 13797 13798Posix also says that you should not combine @samp{!} and @samp{;}. If 13799you use @samp{!}, it is best to put it on a command that is delimited by 13800newlines rather than @samp{;}. 13801 13802Also note that Posix requires that the @samp{b}, @samp{t}, @samp{r}, and 13803@samp{w} commands be followed by exactly one space before their argument. 13804On the other hand, no white space is allowed between @samp{:} and the 13805subsequent label name. 13806 13807If a sed script is specified on the command line and ends in an 13808@samp{a}, @samp{c}, or @samp{i} command, the last line of inserted text 13809should be followed by a newline. Otherwise some @command{sed} 13810implementations (e.g., Open@acronym{BSD} 3.9) do not append a newline to the 13811inserted text. 13812 13813Many @command{sed} implementations (e.g., MacOS X 10.4, 13814Open@acronym{BSD} 3.9, Solaris 10 13815@command{/usr/ucb/sed}) strip leading white space from the text of 13816@samp{a}, @samp{c}, and @samp{i} commands. Prepend a backslash to 13817work around this incompatibility with Posix: 13818 13819@example 13820$ @kbd{echo flushleft | sed 'a\} 13821> @kbd{ indented} 13822> @kbd{'} 13823flushleft 13824indented 13825$ @kbd{echo foo | sed 'a\} 13826> @kbd{\ indented} 13827> @kbd{'} 13828flushleft 13829 indented 13830@end example 13831 13832 13833@item @command{sed} (@samp{t}) 13834@c --------------------------- 13835@prindex @command{sed} (@samp{t}) 13836Some old systems have @command{sed} that ``forget'' to reset their 13837@samp{t} flag when starting a new cycle. For instance on @acronym{MIPS 13838RISC/OS}, and on @sc{irix} 5.3, if you run the following @command{sed} 13839script (the line numbers are not actual part of the texts): 13840 13841@example 13842s/keep me/kept/g # a 13843t end # b 13844s/.*/deleted/g # c 13845:end # d 13846@end example 13847 13848@noindent 13849on 13850 13851@example 13852delete me # 1 13853delete me # 2 13854keep me # 3 13855delete me # 4 13856@end example 13857 13858@noindent 13859you get 13860 13861@example 13862deleted 13863delete me 13864kept 13865deleted 13866@end example 13867 13868@noindent 13869instead of 13870 13871@example 13872deleted 13873deleted 13874kept 13875deleted 13876@end example 13877 13878Why? When processing line 1, (c) matches, therefore sets the @samp{t} 13879flag, and the output is produced. When processing 13880line 2, the @samp{t} flag is still set (this is the bug). Command (a) 13881fails to match, but @command{sed} is not supposed to clear the @samp{t} 13882flag when a substitution fails. Command (b) sees that the flag is set, 13883therefore it clears it, and jumps to (d), hence you get @samp{delete me} 13884instead of @samp{deleted}. When processing line (3), @samp{t} is clear, 13885(a) matches, so the flag is set, hence (b) clears the flags and jumps. 13886Finally, since the flag is clear, line 4 is processed properly. 13887 13888There are two things one should remember about @samp{t} in @command{sed}. 13889Firstly, always remember that @samp{t} jumps if @emph{some} substitution 13890succeeded, not only the immediately preceding substitution. Therefore, 13891always use a fake @samp{t clear} followed by a @samp{:clear} on the next 13892line, to reset the @samp{t} flag where needed. 13893 13894Secondly, you cannot rely on @command{sed} to clear the flag at each new 13895cycle. 13896 13897One portable implementation of the script above is: 13898 13899@example 13900t clear 13901:clear 13902s/keep me/kept/g 13903t end 13904s/.*/deleted/g 13905:end 13906@end example 13907 13908@item @command{touch} 13909@c ------------------ 13910@prindex @command{touch} 13911@cindex timestamp resolution 13912If you specify the desired timestamp (e.g., with the @option{-r} 13913option), @command{touch} typically uses the @code{utime} or 13914@code{utimes} system call, which can result in the same kind of 13915timestamp truncation problems that @samp{cp -p} has. 13916 13917On ancient @acronym{BSD} systems, @command{touch} or any command that 13918results in an empty file does not update the timestamps, so use a 13919command like @command{echo} as a workaround. 13920Also, 13921@acronym{GNU} @command{touch} 3.16r (and presumably all before that) 13922fails to work on SunOS 4.1.3 when the empty file is on an 13923@acronym{NFS}-mounted 4.2 volume. 13924However, these problems are no longer of practical concern. 13925 13926@end table 13927 13928 13929@node Portable Make 13930@chapter Portable Make Programming 13931@prindex @command{make} 13932@cindex Limitations of @command{make} 13933 13934Writing portable makefiles is an art. Since a makefile's commands are 13935executed by the shell, you must consider the shell portability issues 13936already mentioned. However, other issues are specific to @command{make} 13937itself. 13938 13939@menu 13940* $< in Ordinary Make Rules:: $< in ordinary rules 13941* Failure in Make Rules:: Failing portably in rules 13942* Special Chars in Names:: Special Characters in Macro Names 13943* Backslash-Newline-Newline:: Empty last lines in macro definitions 13944* Backslash-Newline Comments:: Spanning comments across line boundaries 13945* Long Lines in Makefiles:: Line length limitations 13946* Macros and Submakes:: @code{make macro=value} and submakes 13947* The Make Macro MAKEFLAGS:: @code{$(MAKEFLAGS)} portability issues 13948* The Make Macro SHELL:: @code{$(SHELL)} portability issues 13949* Comments in Make Rules:: Other problems with Make comments 13950* obj/ and Make:: Don't name a subdirectory @file{obj} 13951* make -k Status:: Exit status of @samp{make -k} 13952* VPATH and Make:: @code{VPATH} woes 13953* Single Suffix Rules:: Single suffix rules and separated dependencies 13954* Timestamps and Make:: Subsecond timestamp resolution 13955@end menu 13956 13957@node $< in Ordinary Make Rules 13958@section @code{$<} in Ordinary Make Rules 13959 13960Posix says that the @samp{$<} construct in makefiles can be 13961used only in inference rules and in the @samp{.DEFAULT} rule; its 13962meaning in ordinary rules is unspecified. Solaris @command{make} 13963for instance replaces it with the empty string. Open@acronym{BSD} (3.0 and 13964later) @command{make} diagnoses these uses and errors out. 13965 13966@node Failure in Make Rules 13967@section Failure in Make Rules 13968 13969Since 1992 Posix has required that @command{make} must invoke 13970each command with the equivalent of a @samp{sh -c} subshell. However, 13971many @command{make} implementations, including @acronym{BSD} make through 2004, 13972use @samp{sh -e -c} instead, and the @option{-e} option causes the 13973subshell to exit immediately if a subsidiary simple-command fails. For 13974example, the command @samp{touch T; rm -f U} always attempts to 13975remove @file{U} with Posix make, but incompatible 13976@command{make} implementations skip the @command{rm} if the 13977@command{touch} fails. One way to work around this is to reword the 13978affected simple-commands so that they always succeed, e.g., @samp{touch 13979T || :; rm -f U}. 13980However, even this approach can run into common bugs in @acronym{BSD} 13981implementations of the @option{-e} option of @command{sh} and 13982@command{set} (@pxref{Limitations of Builtins}), so if you are worried 13983about porting to buggy @acronym{BSD} shells it may be simpler to migrate 13984complicated @command{make} actions into separate scripts. 13985 13986@node Special Chars in Names 13987@section Special Characters in Make Macro Names 13988 13989Posix limits macro names to nonempty strings containing only 13990@acronym{ASCII} letters and digits, @samp{.}, and @samp{_}. Many 13991@command{make} implementations allow a wider variety of characters, but 13992portable makefiles should avoid them. It is portable to start a name 13993with a special character, e.g., @samp{$(.FOO)}. 13994 13995Some ancient @command{make} implementations don't support leading 13996underscores in macro names. An example is @acronym{NEWS-OS} 4.2R. 13997 13998@example 13999$ @kbd{cat Makefile} 14000_am_include = # 14001_am_quote = 14002all:; @@echo this is test 14003$ @kbd{make} 14004Make: Must be a separator on rules line 2. Stop. 14005$ @kbd{cat Makefile2} 14006am_include = # 14007am_quote = 14008all:; @@echo this is test 14009$ @kbd{make -f Makefile2} 14010this is test 14011@end example 14012 14013@noindent 14014However, this problem is no longer of practical concern. 14015 14016@node Backslash-Newline-Newline 14017@section Backslash-Newline-Newline in Make Macro Values 14018 14019@c This has been seen on ia64 hpux 11.20, and on one hppa hpux 10.20, 14020@c but another hppa hpux 10.20 didn't have it. Bob Proulx 14021@c <bob@proulx.com> thinks it was in hpux 8.0 too. 14022On some versions of @acronym{HP-UX}, @command{make} reads multiple newlines 14023following a backslash, continuing to the next non-empty line. For 14024example, 14025 14026@example 14027FOO = one \ 14028 14029BAR = two 14030 14031test: 14032 : FOO is "$(FOO)" 14033 : BAR is "$(BAR)" 14034@end example 14035 14036@noindent 14037shows @code{FOO} equal to @code{one BAR = two}. Other implementations 14038sensibly let a backslash continue only to the immediately following 14039line. 14040 14041@node Backslash-Newline Comments 14042@section Backslash-Newline in Make Comments 14043 14044According to Posix, Make comments start with @code{#} 14045and continue until an unescaped newline is reached. 14046 14047@example 14048$ @kbd{cat Makefile} 14049# A = foo \ 14050 bar \ 14051 baz 14052 14053all: 14054 @@echo ok 14055$ @kbd{make} # GNU make 14056ok 14057@end example 14058 14059@noindent 14060However this is not always the case. Some implementations 14061discard everything from @code{#} through the end of the line, ignoring any 14062trailing backslash. 14063 14064@example 14065$ @kbd{pmake} # BSD make 14066"Makefile", line 3: Need an operator 14067Fatal errors encountered -- cannot continue 14068@end example 14069 14070@noindent 14071Therefore, if you want to comment out a multi-line definition, prefix each 14072line with @code{#}, not only the first. 14073 14074@example 14075# A = foo \ 14076# bar \ 14077# baz 14078@end example 14079 14080@node Long Lines in Makefiles 14081@section Long Lines in Makefiles 14082 14083Tru64 5.1's @command{make} has been reported to crash when given a 14084makefile with lines longer than around 20 kB. Earlier versions are 14085reported to exit with @code{Line too long} diagnostics. 14086 14087@node Macros and Submakes 14088@section @code{make macro=value} and Submakes 14089 14090A command-line variable definition such as @code{foo=bar} overrides any 14091definition of @code{foo} in a makefile. Some @command{make} 14092implementations (such as @acronym{GNU} @command{make}) propagate this 14093override to subsidiary invocations of @command{make}. Some other 14094implementations do not pass the substitution along to submakes. 14095 14096@example 14097$ @kbd{cat Makefile} 14098foo = foo 14099one: 14100 @@echo $(foo) 14101 $(MAKE) two 14102two: 14103 @@echo $(foo) 14104$ @kbd{make foo=bar} # GNU make 3.79.1 14105bar 14106make two 14107make[1]: Entering directory `/home/adl' 14108bar 14109make[1]: Leaving directory `/home/adl' 14110$ @kbd{pmake foo=bar} # BSD make 14111bar 14112pmake two 14113foo 14114@end example 14115 14116You have a few possibilities if you do want the @code{foo=bar} override 14117to propagate to submakes. One is to use the @option{-e} 14118option, which causes all environment variables to have precedence over 14119the makefile macro definitions, and declare foo as an environment 14120variable: 14121 14122@example 14123$ @kbd{env foo=bar make -e} 14124@end example 14125 14126The @option{-e} option is propagated to submakes automatically, 14127and since the environment is inherited between @command{make} 14128invocations, the @code{foo} macro is overridden in 14129submakes as expected. 14130 14131This syntax (@code{foo=bar make -e}) is portable only when used 14132outside of a makefile, for instance from a script or from the 14133command line. When run inside a @command{make} rule, @acronym{GNU} 14134@command{make} 3.80 and prior versions forget to propagate the 14135@option{-e} option to submakes. 14136 14137Moreover, using @option{-e} could have unexpected side effects if your 14138environment contains some other macros usually defined by the 14139makefile. (See also the note about @code{make -e} and @code{SHELL} 14140below.) 14141 14142Another way to propagate overrides to submakes is to do it 14143manually, from your makefile: 14144 14145@example 14146foo = foo 14147one: 14148 @@echo $(foo) 14149 $(MAKE) foo=$(foo) two 14150two: 14151 @@echo $(foo) 14152@end example 14153 14154You need to foresee all macros that a user might want to override if 14155you do that. 14156 14157@node The Make Macro MAKEFLAGS 14158@section The Make Macro MAKEFLAGS 14159@cindex @code{MAKEFLAGS} and @command{make} 14160@cindex @command{make} and @code{MAKEFLAGS} 14161 14162Posix requires @command{make} to use @code{MAKEFLAGS} to affect the 14163current and recursive invocations of make, but allows implementations 14164several formats for the variable. It is tricky to parse 14165@code{$MAKEFLAGS} to determine whether @option{-s} for silent execution 14166or @option{-k} for continued execution are in effect. For example, you 14167cannot assume that the first space-separated word in @code{$MAKEFLAGS} 14168contains single-letter options, since in the Cygwin version of 14169@acronym{GNU} @command{make} it is either @option{--unix} or 14170@option{--win32} with the second word containing single-letter options. 14171 14172@example 14173$ @kbd{cat Makefile} 14174all: 14175 @@echo MAKEFLAGS = $(MAKEFLAGS) 14176$ @kbd{make} 14177MAKEFLAGS = --unix 14178$ @kbd{make -k} 14179MAKEFLAGS = --unix -k 14180@end example 14181 14182@node The Make Macro SHELL 14183@section The Make Macro @code{SHELL} 14184@cindex @code{SHELL} and @command{make} 14185@cindex @command{make} and @code{SHELL} 14186 14187Posix-compliant @command{make} internally uses the @code{$(SHELL)} 14188macro to spawn shell processes and execute Make rules. This 14189is a builtin macro supplied by @command{make}, but it can be modified 14190by a makefile or by a command-line argument. 14191 14192Not all @command{make} implementations define this @code{SHELL} macro. 14193Tru64 14194@command{make} is an example; this implementation always uses 14195@code{/bin/sh}. So it's a good idea to always define @code{SHELL} in 14196your makefiles. If you use Autoconf, do 14197 14198@example 14199SHELL = @@SHELL@@ 14200@end example 14201 14202Do not force @code{SHELL = /bin/sh} because that is not correct 14203everywhere. For instance @acronym{DJGPP} lacks @code{/bin/sh}, and when 14204its @acronym{GNU} @code{make} port sees such a setting it enters a special 14205emulation mode where features like pipes and redirections are emulated 14206on top of DOS's @command{command.com}. Unfortunately this emulation is 14207incomplete; for instance it does not handle command substitutions. 14208On @acronym{DJGPP} @code{SHELL} should point to Bash. 14209 14210Posix-compliant @command{make} should never acquire the value of 14211$(SHELL) from the environment, even when @code{make -e} is used 14212(otherwise, think about what would happen to your rules if 14213@code{SHELL=/bin/tcsh}). 14214 14215However not all @command{make} implementations have this exception. 14216For instance it's not surprising that Tru64 @command{make} doesn't 14217protect @code{SHELL}, since it doesn't use it. 14218 14219@example 14220$ @kbd{cat Makefile} 14221SHELL = /bin/sh 14222FOO = foo 14223all: 14224 @@echo $(SHELL) 14225 @@echo $(FOO) 14226$ @kbd{env SHELL=/bin/tcsh FOO=bar make -e} # Tru64 Make 14227/bin/tcsh 14228bar 14229$ @kbd{env SHELL=/bin/tcsh FOO=bar gmake -e} # GNU make 14230/bin/sh 14231bar 14232@end example 14233 14234@node Comments in Make Rules 14235@section Comments in Make Rules 14236@cindex Comments in @file{Makefile} rules 14237@cindex @file{Makefile} rules and comments 14238 14239Never put comments in a rule. 14240 14241Some @command{make} treat anything starting with a tab as a command for 14242the current rule, even if the tab is immediately followed by a @code{#}. 14243The @command{make} from Tru64 Unix V5.1 is one of them. The following 14244makefile runs @code{# foo} through the shell. 14245 14246@example 14247all: 14248 # foo 14249@end example 14250 14251@node obj/ and Make 14252@section The @file{obj/} Subdirectory and Make 14253@cindex @file{obj/}, subdirectory 14254@cindex @acronym{BSD} @command{make} and @file{obj/} 14255 14256Never name one of your subdirectories @file{obj/} if you don't like 14257surprises. 14258 14259If an @file{obj/} directory exists, @acronym{BSD} @command{make} enters it 14260before reading the makefile. Hence the makefile in the 14261current directory is not read. 14262 14263@example 14264$ @kbd{cat Makefile} 14265all: 14266 echo Hello 14267$ @kbd{cat obj/Makefile} 14268all: 14269 echo World 14270$ @kbd{make} # GNU make 14271echo Hello 14272Hello 14273$ @kbd{pmake} # BSD make 14274echo World 14275World 14276@end example 14277 14278@node make -k Status 14279@section Exit Status of @code{make -k} 14280@cindex @code{make -k} 14281 14282Do not rely on the exit status of @code{make -k}. Some implementations 14283reflect whether they encountered an error in their exit status; other 14284implementations always succeed. 14285 14286@example 14287$ @kbd{cat Makefile} 14288all: 14289 false 14290$ @kbd{make -k; echo exit status: $?} # GNU make 14291false 14292make: *** [all] Error 1 14293exit status: 2 14294$ @kbd{pmake -k; echo exit status: $?} # BSD make 14295false 14296*** Error code 1 (continuing) 14297exit status: 0 14298@end example 14299 14300@node VPATH and Make 14301@section @code{VPATH} and Make 14302@cindex @code{VPATH} 14303 14304Posix does not specify the semantics of @code{VPATH}. Typically, 14305@command{make} supports @code{VPATH}, but its implementation is not 14306consistent. 14307 14308Autoconf and Automake support makefiles whose usages of @code{VPATH} are 14309portable to recent-enough popular implementations of @command{make}, but 14310to keep the resulting makefiles portable, a package's makefile 14311prototypes must take the following issues into account. These issues 14312are complicated and are often poorly understood, and installers who use 14313@code{VPATH} should expect to find many bugs in this area. If you use 14314@code{VPATH}, the simplest way to avoid these portability bugs is to 14315stick with @acronym{GNU} @command{make}, since it is the most 14316commonly-used @command{make} among Autoconf users. 14317 14318Here are some known issues with some @code{VPATH} 14319implementations. 14320 14321@menu 14322* VPATH and Double-colon:: Problems with @samp{::} on ancient hosts 14323* $< in Explicit Rules:: @code{$<} does not work in ordinary rules 14324* Automatic Rule Rewriting:: @code{VPATH} goes wild on Solaris 14325* Tru64 Directory Magic:: @command{mkdir} goes wild on Tru64 14326* Make Target Lookup:: More details about @code{VPATH} lookup 14327@end menu 14328 14329@node VPATH and Double-colon 14330@subsection @code{VPATH} and Double-colon Rules 14331@cindex @code{VPATH} and double-colon rules 14332@cindex double-colon rules and @code{VPATH} 14333 14334With ancient versions of Sun @command{make}, 14335any assignment to @code{VPATH} causes @command{make} to execute only 14336the first set of double-colon rules. 14337However, this problem is no longer of practical concern. 14338 14339@node $< in Explicit Rules 14340@subsection @code{$<} Not Supported in Explicit Rules 14341@cindex explicit rules, @code{$<}, and @code{VPATH} 14342@cindex @code{$<}, explicit rules, and @code{VPATH} 14343@cindex @code{VPATH}, explicit rules, and @code{$<} 14344 14345Using @code{$<} in explicit rules is not portable. 14346The prerequisite file must be named explicitly in the rule. If you want 14347to find the prerequisite via a @code{VPATH} search, you have to code the 14348whole thing manually. @xref{Build Directories}. 14349 14350@node Automatic Rule Rewriting 14351@subsection Automatic Rule Rewriting 14352@cindex @code{VPATH} and automatic rule rewriting 14353@cindex automatic rule rewriting and @code{VPATH} 14354 14355Some @command{make} implementations, such as Solaris and Tru64, 14356search for prerequisites in @code{VPATH} and 14357then rewrite each occurrence as a plain word in the rule. 14358For instance: 14359 14360@example 14361# This isn't portable to GNU make. 14362VPATH = ../pkg/src 14363f.c: if.c 14364 cp if.c f.c 14365@end example 14366 14367@noindent 14368executes @code{cp ../pkg/src/if.c f.c} if @file{if.c} is 14369found in @file{../pkg/src}. 14370 14371However, this rule leads to real problems in practice. For example, if 14372the source directory contains an ordinary file named @file{test} that is 14373used in a dependency, Solaris @command{make} rewrites commands like 14374@samp{if test -r foo; @dots{}} to @samp{if ../pkg/src/test -r foo; 14375@dots{}}, which is typically undesirable. To avoid this problem, 14376portable makefiles should never mention a source file whose name is that 14377of a shell keyword like @file{until} or a shell command like 14378@command{cat} or @command{gcc} or @command{test}. 14379 14380Because of these problems @acronym{GNU} @command{make} and many other 14381@command{make} implementations do not rewrite commands, so portable 14382makefiles should 14383search @code{VPATH} manually. It is tempting to write this: 14384 14385@smallexample 14386# This isn't portable to Solaris make. 14387VPATH = ../pkg/src 14388f.c: if.c 14389 cp `test -f if.c || echo $(VPATH)/`if.c f.c 14390@end smallexample 14391 14392@noindent 14393However, the ``prerequisite rewriting'' still applies here. So if 14394@file{if.c} is in @file{../pkg/src}, Solaris and Tru64 @command{make} 14395execute 14396 14397@smallexample 14398cp `test -f ../pkg/src/if.c || echo ../pkg/src/`if.c f.c 14399@end smallexample 14400 14401@noindent 14402which reduces to 14403 14404@example 14405cp if.c f.c 14406@end example 14407 14408@noindent 14409and thus fails. Oops. 14410 14411A simple workaround, and good practice anyway, is to use @samp{$?} and 14412@samp{$@@} when possible: 14413 14414@smallexample 14415VPATH = ../pkg/src 14416f.c: if.c 14417 cp $? $@@ 14418@end smallexample 14419 14420@noindent 14421but this does not generalize well to commands with multiple 14422prerequisites. A more general workaround is to rewrite the rule so that 14423the prerequisite @file{if.c} never appears as a plain word. For 14424example, these three rules would be safe, assuming @file{if.c} is in 14425@file{../pkg/src} and the other files are in the working directory: 14426 14427@smallexample 14428VPATH = ../pkg/src 14429f.c: if.c f1.c 14430 cat `test -f ./if.c || echo $(VPATH)/`if.c f1.c >$@@ 14431g.c: if.c g1.c 14432 cat `test -f 'if.c' || echo $(VPATH)/`if.c g1.c >$@@ 14433h.c: if.c h1.c 14434 cat `test -f "if.c" || echo $(VPATH)/`if.c h1.c >$@@ 14435@end smallexample 14436 14437Things get worse when your prerequisites are in a macro. 14438 14439@example 14440VPATH = ../pkg/src 14441HEADERS = f.h g.h h.h 14442install-HEADERS: $(HEADERS) 14443 for i in $(HEADERS); do \ 14444 $(INSTALL) -m 644 \ 14445 `test -f $$i || echo $(VPATH)/`$$i \ 14446 $(DESTDIR)$(includedir)/$$i; \ 14447 done 14448@end example 14449 14450The above @code{install-HEADERS} rule is not Solaris-proof because @code{for 14451i in $(HEADERS);} is expanded to @code{for i in f.h g.h h.h;} 14452where @code{f.h} and @code{g.h} are plain words and are hence 14453subject to @code{VPATH} adjustments. 14454 14455If the three files are in @file{../pkg/src}, the rule is run as: 14456 14457@example 14458for i in ../pkg/src/f.h ../pkg/src/g.h h.h; do \ 14459 install -m 644 \ 14460 `test -f $i || echo ../pkg/src/`$i \ 14461 /usr/local/include/$i; \ 14462done 14463@end example 14464 14465where the two first @command{install} calls fail. For instance, 14466consider the @code{f.h} installation: 14467 14468@example 14469install -m 644 \ 14470 `test -f ../pkg/src/f.h || \ 14471 echo ../pkg/src/ \ 14472 `../pkg/src/f.h \ 14473 /usr/local/include/../pkg/src/f.h; 14474@end example 14475 14476@noindent 14477It reduces to: 14478 14479@example 14480install -m 644 \ 14481 ../pkg/src/f.h \ 14482 /usr/local/include/../pkg/src/f.h; 14483@end example 14484 14485Note that the manual @code{VPATH} search did not cause any problems here; 14486however this command installs @file{f.h} in an incorrect directory. 14487 14488Trying to quote @code{$(HEADERS)} in some way, as we did for 14489@code{foo.c} a few makefiles ago, does not help: 14490 14491@example 14492install-HEADERS: $(HEADERS) 14493 headers='$(HEADERS)'; \ 14494 for i in $$headers; do \ 14495 $(INSTALL) -m 644 \ 14496 `test -f $$i || echo $(VPATH)/`$$i \ 14497 $(DESTDIR)$(includedir)/$$i; \ 14498 done 14499@end example 14500 14501Now, @code{headers='$(HEADERS)'} macroexpands to: 14502 14503@example 14504headers='f.h g.h h.h' 14505@end example 14506 14507@noindent 14508but @code{g.h} is still a plain word. (As an aside, the idiom 14509@code{headers='$(HEADERS)'; for i in $$headers;} is a good 14510idea if @code{$(HEADERS)} can be empty, because some shells diagnose a 14511syntax error on @code{for i in;}.) 14512 14513One workaround is to strip this unwanted @file{../pkg/src/} prefix manually: 14514 14515@example 14516VPATH = ../pkg/src 14517HEADERS = f.h g.h h.h 14518install-HEADERS: $(HEADERS) 14519 headers='$(HEADERS)'; \ 14520 for i in $$headers; do \ 14521 i=`expr "$$i" : '$(VPATH)/\(.*\)'`; 14522 $(INSTALL) -m 644 \ 14523 `test -f $$i || echo $(VPATH)/`$$i \ 14524 $(DESTDIR)$(includedir)/$$i; \ 14525 done 14526@end example 14527 14528Automake does something similar. However the above hack works only if 14529the files listed in @code{HEADERS} are in the current directory or a 14530subdirectory; they should not be in an enclosing directory. If we had 14531@code{HEADERS = ../f.h}, the above fragment would fail in a VPATH 14532build with Tru64 @command{make}. The reason is that not only does 14533Tru64 @command{make} rewrite dependencies, but it also simplifies 14534them. Hence @code{../f.h} becomes @code{../pkg/f.h} instead of 14535@code{../pkg/src/../f.h}. This obviously defeats any attempt to strip 14536a leading @file{../pkg/src/} component. 14537 14538The following example makes the behavior of Tru64 @command{make} 14539more apparent. 14540 14541@example 14542$ @kbd{cat Makefile} 14543VPATH = sub 14544all: ../foo 14545 echo ../foo 14546$ @kbd{ls} 14547Makefile foo 14548$ @kbd{make} 14549echo foo 14550foo 14551@end example 14552 14553@noindent 14554Dependency @file{../foo} was found in @file{sub/../foo}, but Tru64 14555@command{make} simplified it as @file{foo}. (Note that the @file{sub/} 14556directory does not even exist, this just means that the simplification 14557occurred before the file was checked for.) 14558 14559For the record here is how SunOS 4 @command{make} behaves on this 14560example. 14561 14562@smallexample 14563$ @kbd{make} 14564make: Fatal error: Don't know how to make target `../foo' 14565$ @kbd{mkdir sub} 14566$ @kbd{make} 14567echo sub/../foo 14568sub/../foo 14569@end smallexample 14570 14571 14572@node Tru64 Directory Magic 14573@subsection Tru64 @command{make} Creates Prerequisite Directories Magically 14574@cindex @code{VPATH} and prerequisite directories 14575@cindex prerequisite directories and @code{VPATH} 14576 14577When a prerequisite is a subdirectory of @code{VPATH}, Tru64 14578@command{make} creates it in the current directory. 14579 14580@example 14581$ @kbd{mkdir -p foo/bar build} 14582$ @kbd{cd build} 14583$ @kbd{cat >Makefile <<END 14584VPATH = .. 14585all: foo/bar 14586END} 14587$ @kbd{make} 14588mkdir foo 14589mkdir foo/bar 14590@end example 14591 14592This can yield unexpected results if a rule uses a manual @code{VPATH} 14593search as presented before. 14594 14595@example 14596VPATH = .. 14597all : foo/bar 14598 command `test -d foo/bar || echo ../`foo/bar 14599@end example 14600 14601The above @command{command} is run on the empty @file{foo/bar} 14602directory that was created in the current directory. 14603 14604@node Make Target Lookup 14605@subsection Make Target Lookup 14606@cindex @code{VPATH}, resolving target pathnames 14607 14608@acronym{GNU} @command{make} uses a complex algorithm to decide when it 14609should use files found via a @code{VPATH} search. @xref{Search 14610Algorithm, , How Directory Searches are Performed, make, The @acronym{GNU} Make 14611Manual}. 14612 14613If a target needs to be rebuilt, @acronym{GNU} @command{make} discards the 14614file name found during the @code{VPATH} search for this target, and 14615builds the file locally using the file name given in the makefile. 14616If a target does not need to be rebuilt, @acronym{GNU} @command{make} uses the 14617file name found during the @code{VPATH} search. 14618 14619Other @command{make} implementations, like Net@acronym{BSD} @command{make}, are 14620easier to describe: the file name found during the @code{VPATH} search 14621is used whether the target needs to be rebuilt or not. Therefore 14622new files are created locally, but existing files are updated at their 14623@code{VPATH} location. 14624 14625Open@acronym{BSD} and Free@acronym{BSD} @command{make}, however, 14626never perform a 14627@code{VPATH} search for a dependency that has an explicit rule. 14628This is extremely annoying. 14629 14630When attempting a @code{VPATH} build for an autoconfiscated package 14631(e.g., @code{mkdir build && cd build && ../configure}), this means 14632@acronym{GNU} 14633@command{make} builds everything locally in the @file{build} 14634directory, while @acronym{BSD} @command{make} builds new files locally and 14635updates existing files in the source directory. 14636 14637@example 14638$ @kbd{cat Makefile} 14639VPATH = .. 14640all: foo.x bar.x 14641foo.x bar.x: newer.x 14642 @@echo Building $@@ 14643$ @kbd{touch ../bar.x} 14644$ @kbd{touch ../newer.x} 14645$ @kbd{make} # GNU make 14646Building foo.x 14647Building bar.x 14648$ @kbd{pmake} # NetBSD make 14649Building foo.x 14650Building ../bar.x 14651$ @kbd{fmake} # FreeBSD make, OpenBSD make 14652Building foo.x 14653Building bar.x 14654$ @kbd{tmake} # Tru64 make 14655Building foo.x 14656Building bar.x 14657$ @kbd{touch ../bar.x} 14658$ @kbd{make} # GNU make 14659Building foo.x 14660$ @kbd{pmake} # NetBSD make 14661Building foo.x 14662$ @kbd{fmake} # FreeBSD make, OpenBSD make 14663Building foo.x 14664Building bar.x 14665$ @kbd{tmake} # Tru64 make 14666Building foo.x 14667Building bar.x 14668@end example 14669 14670Note how Net@acronym{BSD} @command{make} updates @file{../bar.x} in its 14671VPATH location, and how Free@acronym{BSD}, Open@acronym{BSD}, and Tru64 14672@command{make} always 14673update @file{bar.x}, even when @file{../bar.x} is up to date. 14674 14675Another point worth mentioning is that once @acronym{GNU} @command{make} has 14676decided to ignore a @code{VPATH} file name (e.g., it ignored 14677@file{../bar.x} in the above example) it continues to ignore it when 14678the target occurs as a prerequisite of another rule. 14679 14680The following example shows that @acronym{GNU} @command{make} does not look up 14681@file{bar.x} in @code{VPATH} before performing the @code{.x.y} rule, 14682because it ignored the @code{VPATH} result of @file{bar.x} while running 14683the @code{bar.x: newer.x} rule. 14684 14685@example 14686$ @kbd{cat Makefile} 14687VPATH = .. 14688all: bar.y 14689bar.x: newer.x 14690 @@echo Building $@@ 14691.SUFFIXES: .x .y 14692.x.y: 14693 cp $< $@@ 14694$ @kbd{touch ../bar.x} 14695$ @kbd{touch ../newer.x} 14696$ @kbd{make} # GNU make 14697Building bar.x 14698cp bar.x bar.y 14699cp: cannot stat `bar.x': No such file or directory 14700make: *** [bar.y] Error 1 14701$ @kbd{pmake} # NetBSD make 14702Building ../bar.x 14703cp ../bar.x bar.y 14704$ @kbd{rm bar.y} 14705$ @kbd{fmake} # FreeBSD make, OpenBSD make 14706echo Building bar.x 14707cp bar.x bar.y 14708cp: cannot stat `bar.x': No such file or directory 14709*** Error code 1 14710$ @kbd{tmake} # Tru64 make 14711Building bar.x 14712cp: bar.x: No such file or directory 14713*** Exit 1 14714@end example 14715 14716Note that if you drop away the command from the @code{bar.x: newer.x} 14717rule, @acronym{GNU} @command{make} magically starts to work: it 14718knows that @code{bar.x} hasn't been updated, therefore it doesn't 14719discard the result from @code{VPATH} (@file{../bar.x}) in succeeding 14720uses. Tru64 also works, but Free@acronym{BSD} and Open@acronym{BSD} 14721still don't. 14722 14723@example 14724$ @kbd{cat Makefile} 14725VPATH = .. 14726all: bar.y 14727bar.x: newer.x 14728.SUFFIXES: .x .y 14729.x.y: 14730 cp $< $@@ 14731$ @kbd{touch ../bar.x} 14732$ @kbd{touch ../newer.x} 14733$ @kbd{make} # GNU make 14734cp ../bar.x bar.y 14735$ @kbd{rm bar.y} 14736$ @kbd{pmake} # NetBSD make 14737cp ../bar.x bar.y 14738$ @kbd{rm bar.y} 14739$ @kbd{fmake} # FreeBSD make, OpenBSD make 14740cp bar.x bar.y 14741cp: cannot stat `bar.x': No such file or directory 14742*** Error code 1 14743$ @kbd{tmake} # Tru64 make 14744cp ../bar.x bar.y 14745@end example 14746 14747It seems the sole solution that would please every @command{make} 14748implementation is to never rely on @code{VPATH} searches for targets. 14749In other words, @code{VPATH} should be reserved to unbuilt sources. 14750 14751 14752@node Single Suffix Rules 14753@section Single Suffix Rules and Separated Dependencies 14754@cindex Single Suffix Inference Rule 14755@cindex Rule, Single Suffix Inference 14756A @dfn{Single Suffix Rule} is basically a usual suffix (inference) rule 14757(@samp{.from.to:}), but which @emph{destination} suffix is empty 14758(@samp{.from:}). 14759 14760@cindex Separated Dependencies 14761@dfn{Separated dependencies} simply refers to listing the prerequisite 14762of a target, without defining a rule. Usually one can list on the one 14763hand side, the rules, and on the other hand side, the dependencies. 14764 14765Solaris @command{make} does not support separated dependencies for 14766targets defined by single suffix rules: 14767 14768@example 14769$ @kbd{cat Makefile} 14770.SUFFIXES: .in 14771foo: foo.in 14772.in: 14773 cp $< $@@ 14774$ @kbd{touch foo.in} 14775$ @kbd{make} 14776$ @kbd{ls} 14777Makefile foo.in 14778@end example 14779 14780@noindent 14781while @acronym{GNU} Make does: 14782 14783@example 14784$ @kbd{gmake} 14785cp foo.in foo 14786$ @kbd{ls} 14787Makefile foo foo.in 14788@end example 14789 14790Note it works without the @samp{foo: foo.in} dependency. 14791 14792@example 14793$ @kbd{cat Makefile} 14794.SUFFIXES: .in 14795.in: 14796 cp $< $@@ 14797$ @kbd{make foo} 14798cp foo.in foo 14799@end example 14800 14801@noindent 14802and it works with double suffix inference rules: 14803 14804@example 14805$ @kbd{cat Makefile} 14806foo.out: foo.in 14807.SUFFIXES: .in .out 14808.in.out: 14809 cp $< $@@ 14810$ @kbd{make} 14811cp foo.in foo.out 14812@end example 14813 14814As a result, in such a case, you have to write target rules. 14815 14816@node Timestamps and Make 14817@section Timestamp Resolution and Make 14818@cindex timestamp resolution 14819Traditionally, file timestamps had 1-second resolution, and 14820@command{make} used those timestamps to determine whether one file was 14821newer than the other. However, many modern file systems have 14822timestamps with 1-nanosecond resolution. Some @command{make} 14823implementations look at the entire timestamp; others ignore the 14824fractional part, which can lead to incorrect results. Normally this 14825is not a problem, but in some extreme cases you may need to use tricks 14826like @samp{sleep 1} to work around timestamp truncation bugs. 14827 14828Commands like @samp{cp -p} and @samp{touch -r} typically do not copy 14829file timestamps to their full resolutions (@pxref{Limitations of Usual 14830Tools}). Hence you should be wary of rules like this: 14831 14832@example 14833dest: src 14834 cp -p src dest 14835@end example 14836 14837as @file{dest} often appears to be older than @file{src} after the 14838timestamp is truncated, and this can cause @command{make} to do 14839needless rework the next time it is invoked. To work around this 14840problem, you can use a timestamp file, e.g.: 14841 14842@example 14843dest-stamp: src 14844 cp -p src dest 14845 date >dest-stamp 14846@end example 14847 14848 14849 14850 14851@c ======================================== Portable C and C++ Programming 14852 14853@node Portable C and C++ 14854@chapter Portable C and C++ Programming 14855@cindex Portable C and C++ programming 14856 14857C and C++ programs often use low-level features of the underlying 14858system, and therefore are often more difficult to make portable to other 14859platforms. 14860 14861Several standards have been developed to help make your programs more 14862portable. If you write programs with these standards in mind, you can 14863have greater confidence that your programs work on a wide variety 14864of systems. @xref{Standards, , Language Standards Supported by 14865@acronym{GCC}, gcc, Using the @acronym{GNU} Compiler Collection 14866(@acronym{GCC})}, for a list of C-related 14867standards. Many programs also assume the 14868@uref{http://www.opengroup.org/susv3, Posix standard}. 14869 14870Some old code is written to be portable to K&R C, which predates any C 14871standard. K&R C compilers are no longer of practical interest, though, 14872and the rest of section assumes at least C89, the first C standard. 14873 14874Program portability is a huge topic, and this section can only briefly 14875introduce common pitfalls. @xref{System Portability, , Portability 14876between System Types, standards, @acronym{GNU} Coding Standards}, for 14877more information. 14878 14879@menu 14880* Varieties of Unportability:: How to make your programs unportable 14881* Integer Overflow:: When integers get too large 14882* Null Pointers:: Properties of null pointers 14883* Buffer Overruns:: Subscript errors and the like 14884* Volatile Objects:: @code{volatile} and signals 14885* Floating Point Portability:: Portable floating-point arithmetic 14886* Exiting Portably:: Exiting and the exit status 14887@end menu 14888 14889@node Varieties of Unportability 14890@section Varieties of Unportability 14891@cindex portability 14892 14893Autoconf tests and ordinary programs often need to test what is allowed 14894on a system, and therefore they may need to deliberately exceed the 14895boundaries of what the standards allow, if only to see whether an 14896optional feature is present. When you write such a program, you should 14897keep in mind the difference between constraints, unspecified behavior, 14898and undefined behavior. 14899 14900In C, a @dfn{constraint} is a rule that the compiler must enforce. An 14901example constraint is that C programs must not declare a bit-field with 14902negative width. Tests can therefore reliably assume that programs with 14903negative-width bit-fields are rejected by a compiler that conforms 14904to the standard. 14905 14906@dfn{Unspecified behavior} is valid behavior, where the standard allows 14907multiple possibilities. For example, the order of evaluation of 14908function arguments is unspecified. Some unspecified behavior is 14909@dfn{implementation-defined}, i.e., documented by the implementation, 14910but since Autoconf tests cannot read the documentation they cannot 14911distinguish between implementation-defined and other unspecified 14912behavior. It is common for Autoconf tests to probe implementations to 14913determine otherwise-unspecified behavior. 14914 14915@dfn{Undefined behavior} is invalid behavior, where the standard allows 14916the implementation to do anything it pleases. For example, 14917dereferencing a null pointer leads to undefined behavior. If possible, 14918test programs should avoid undefined behavior, since a program with 14919undefined behavior might succeed on a test that should fail. 14920 14921The above rules apply to programs that are intended to conform to the 14922standard. However, strictly-conforming programs are quite rare, since 14923the standards are so limiting. A major goal of Autoconf is to support 14924programs that use implementation features not described by the standard, 14925and it is fairly common for test programs to violate the above rules, if 14926the programs work well enough in practice. 14927 14928@node Integer Overflow 14929@section Integer Overflow 14930@cindex overflow, arithmetic 14931 14932In C, signed integer overflow leads to undefined behavior. However, 14933many programs and Autoconf tests assume that signed integer overflow after 14934addition, subtraction, or multiplication silently 14935wraps around modulo a power of two, using two's complement arithmetic, 14936so long as you cast the resulting value 14937to an integer type or store it into an integer variable. Such programs 14938are portable to the vast majority of modern platforms. However, signed 14939integer division is not always harmless: for example, on CPUs of the 14940i386 family, dividing @code{INT_MIN} by @code{-1} yields a SIGFPE signal 14941which by default terminates the program. Worse, taking the remainder 14942of these two values typically yields the same signal on these CPUs, 14943even though the C standard requires @code{INT_MIN % -1} to yield zero 14944because the expression does not overflow. 14945 14946@acronym{GCC} users might consider using the 14947@option{-ftrapv} option if they are worried about porting their code to 14948the rare platforms where signed integer overflow does not wrap around 14949after addition, subtraction, or multiplication. 14950 14951Unsigned integer overflow reliably wraps around modulo the word size. 14952This is guaranteed by the C standard and is portable in practice. 14953 14954@node Null Pointers 14955@section Properties of Null Pointers 14956@cindex null pointers 14957 14958Most modern hosts reliably fail when you attempt to dereference a null 14959pointer. 14960 14961On almost all modern hosts, null pointers use an all-bits-zero internal 14962representation, so you can reliably use @code{memset} with 0 to set all 14963the pointers in an array to null values. 14964 14965If @code{p} is a null pointer to an object type, the C expression 14966@code{p + 0} always evaluates to @code{p} on modern hosts, even though 14967the standard says that it has undefined behavior. 14968 14969@node Buffer Overruns 14970@section Buffer Overruns and Subscript Errors 14971@cindex buffer overruns 14972 14973Buffer overruns and subscript errors are the most common dangerous 14974errors in C programs. They result in undefined behavior because storing 14975outside an array typically modifies storage that is used by some other 14976object, and most modern systems lack runtime checks to catch these 14977errors. Programs should not rely on buffer overruns being caught. 14978 14979There is one exception to the usual rule that a portable program cannot 14980address outside an array. In C, it is valid to compute the address just 14981past an object, e.g., @code{&a[N]} where @code{a} has @code{N} elements, 14982so long as you do not dereference the resulting pointer. But it is not 14983valid to compute the address just before an object, e.g., @code{&a[-1]}; 14984nor is it valid to compute two past the end, e.g., @code{&a[N+1]}. On 14985most platforms @code{&a[-1] < &a[0] && &a[N] < &a[N+1]}, but this is not 14986reliable in general, and it is usually easy enough to avoid the 14987potential portability problem, e.g., by allocating an extra unused array 14988element at the start or end. 14989 14990@uref{http://valgrind.org/, Valgrind} can catch many overruns. 14991@acronym{GCC} 14992users might also consider using the @option{-fmudflap} option to catch 14993overruns. 14994 14995Buffer overruns are usually caused by off-by-one errors, but there are 14996more subtle ways to get them. 14997 14998Using @code{int} values to index into an array or compute array sizes 14999causes problems on typical 64-bit hosts where an array index might 15000be @math{2^31} or larger. Index values of type @code{size_t} avoid this 15001problem, but cannot be negative. Index values of type @code{ptrdiff_t} 15002are signed, and are wide enough in practice. 15003 15004If you add or multiply two numbers to calculate an array size, e.g., 15005@code{malloc (x * sizeof y + z)}, havoc ensues if the addition or 15006multiplication overflows. 15007 15008Many implementations of the @code{alloca} function silently misbehave 15009and can generate buffer overflows if given sizes that are too large. 15010The size limits are implementation dependent, but are at least 4000 15011bytes on all platforms that we know about. 15012 15013The standard functions @code{asctime}, @code{asctime_r}, @code{ctime}, 15014@code{ctime_r}, and @code{gets} are prone to buffer overflows, and 15015portable code should not use them unless the inputs are known to be 15016within certain limits. The time-related functions can overflow their 15017buffers if given timestamps out of range (e.g., a year less than -999 15018or greater than 9999). Time-related buffer overflows cannot happen with 15019recent-enough versions of the @acronym{GNU} C library, but are possible 15020with other 15021implementations. The @code{gets} function is the worst, since it almost 15022invariably overflows its buffer when presented with an input line larger 15023than the buffer. 15024 15025@node Volatile Objects 15026@section Volatile Objects 15027@cindex volatile objects 15028 15029The keyword @code{volatile} is often misunderstood in portable code. 15030Its use inhibits some memory-access optimizations, but programmers often 15031wish that it had a different meaning than it actually does. 15032 15033@code{volatile} was designed for code that accesses special objects like 15034memory-mapped device registers whose contents spontaneously change. 15035Such code is inherently low-level, and it is difficult to specify 15036portably what @code{volatile} means in these cases. The C standard 15037says, ``What constitutes an access to an object that has 15038volatile-qualified type is implementation-defined,'' so in theory each 15039implementation is supposed to fill in the gap by documenting what 15040@code{volatile} means for that implementation. In practice, though, 15041this documentation is usually absent or incomplete. 15042 15043One area of confusion is the distinction between objects defined with 15044volatile types, and volatile lvalues. From the C standard's point of 15045view, an object defined with a volatile type has externally visible 15046behavior. You can think of such objects as having little oscilloscope 15047probes attached to them, so that the user can observe some properties of 15048accesses to them, just as the user can observe data written to output 15049files. However, the standard does not make it clear whether users can 15050observe accesses by volatile lvalues to ordinary objects. For example: 15051 15052@example 15053/* Declare and access a volatile object. 15054 Accesses to X are "visible" to users. */ 15055static int volatile x; 15056x = 1; 15057 15058/* Access two ordinary objects via a volatile lvalue. 15059 It's not clear whether accesses to *P are "visible". */ 15060int y; 15061int *z = malloc (sizeof (int)); 15062int volatile *p; 15063p = &y; 15064*p = 1; 15065p = z; 15066*p = 1; 15067@end example 15068 15069Programmers often wish that @code{volatile} meant ``Perform the memory 15070access here and now, without merging several memory accesses, without 15071changing the memory word size, and without reordering.'' But the C 15072standard does not require this. For objects defined with a volatile 15073type, accesses must be done before the next sequence point; but 15074otherwise merging, reordering, and word-size change is allowed. Worse, 15075it is not clear from the standard whether volatile lvalues provide more 15076guarantees in general than nonvolatile lvalues, if the underlying 15077objects are ordinary. 15078 15079Even when accessing objects defined with a volatile type, 15080the C standard allows only 15081extremely limited signal handlers: the behavior is undefined if a signal 15082handler reads any nonlocal object, or writes to any nonlocal object 15083whose type is not @code{sig_atomic_t volatile}, or calls any standard 15084library function other than @code{abort}, @code{signal}, and (if C99) 15085@code{_Exit}. Hence C compilers need not worry about a signal handler 15086disturbing ordinary computation, unless the computation accesses a 15087@code{sig_atomic_t volatile} lvalue that is not a local variable. 15088(There is an obscure exception for accesses via a pointer to a volatile 15089character, since it may point into part of a @code{sig_atomic_t 15090volatile} object.) Posix 15091adds to the list of library functions callable from a portable signal 15092handler, but otherwise is like the C standard in this area. 15093 15094Some C implementations allow memory-access optimizations within each 15095translation unit, such that actual behavior agrees with the behavior 15096required by the standard only when calling a function in some other 15097translation unit, and a signal handler acts like it was called from a 15098different translation unit. The C standard hints that in these 15099implementations, objects referred to by signal handlers ``would require 15100explicit specification of @code{volatile} storage, as well as other 15101implementation-defined restrictions.'' But unfortunately even for this 15102special case these other restrictions are often not documented well. 15103@xref{Volatiles, , When is a Volatile Object Accessed?, gcc, Using the 15104@acronym{GNU} Compiler Collection (@acronym{GCC})}, for some 15105restrictions imposed by @acronym{GCC}. @xref{Defining Handlers, , 15106Defining Signal Handlers, libc, The @acronym{GNU} C Library}, for some 15107restrictions imposed by the @acronym{GNU} C library. Restrictions 15108differ on other platforms. 15109 15110If possible, it is best to use a signal handler that fits within the 15111limits imposed by the C and Posix standards. 15112 15113If this is not practical, you can try the following rules of thumb. A 15114signal handler should access only volatile lvalues, preferably lvalues 15115that refer to objects defined with a volatile type, and should not 15116assume that the accessed objects have an internally consistent state 15117if they are larger than a machine word. Furthermore, installers 15118should employ compilers and compiler options that are commonly used 15119for building operating system kernels, because kernels often need more 15120from @code{volatile} than the C Standard requires, and installers who 15121compile an application in a similar environment can sometimes benefit 15122from the extra constraints imposed by kernels on compilers. 15123Admittedly we are handwaving somewhat here, as there are few 15124guarantees in this area; the rules of thumb may help to fix some bugs 15125but there is a good chance that they will not fix them all. 15126 15127For @code{volatile}, C++ has the same problems that C does. 15128Multithreaded applications have even more problems with @code{volatile}, 15129but they are beyond the scope of this section. 15130 15131The bottom line is that using @code{volatile} typically hurts 15132performance but should not hurt correctness. In some cases its use 15133does help correctness, but these cases are often so poorly understood 15134that all too often adding @code{volatile} to a data structure merely 15135alleviates some symptoms of a bug while not fixing the bug in general. 15136 15137@node Floating Point Portability 15138@section Floating Point Portability 15139@cindex floating point 15140 15141Almost all modern systems use IEEE-754 floating point, and it is safe to 15142assume IEEE-754 in most portable code these days. For more information, 15143please see David Goldberg's classic paper 15144@uref{http://www.validlab.com/goldberg/paper.pdf, What Every Computer 15145Scientist Should Know About Floating-Point Arithmetic}. 15146 15147@node Exiting Portably 15148@section Exiting Portably 15149@cindex exiting portably 15150 15151A C or C++ program can exit with status @var{N} by returning 15152@var{N} from the @code{main} function. Portable programs are supposed 15153to exit either with status 0 or @code{EXIT_SUCCESS} to succeed, or with 15154status @code{EXIT_FAILURE} to fail, but in practice it is portable to 15155fail by exiting with status 1, and test programs that assume Posix can 15156fail by exiting with status values from 1 through 255. Programs on 15157SunOS 2.0 (1985) through 3.5.2 (1988) incorrectly exited with zero 15158status when @code{main} returned nonzero, but ancient systems like these 15159are no longer of practical concern. 15160 15161A program can also exit with status @var{N} by passing @var{N} to the 15162@code{exit} function, and a program can fail by calling the @code{abort} 15163function. If a program is specialized to just some platforms, it can fail 15164by calling functions specific to those platforms, e.g., @code{_exit} 15165(Posix) and @code{_Exit} (C99). However, like other functions, an exit 15166function should be declared, typically by including a header. For 15167example, if a C program calls @code{exit}, it should include @file{stdlib.h} 15168either directly or via the default includes (@pxref{Default Includes}). 15169 15170A program can fail due to undefined behavior such as dereferencing a null 15171pointer, but this is not recommended as undefined behavior allows an 15172implementation to do whatever it pleases and this includes exiting 15173successfully. 15174 15175 15176@c ================================================== Manual Configuration 15177 15178@node Manual Configuration 15179@chapter Manual Configuration 15180 15181A few kinds of features can't be guessed automatically by running test 15182programs. For example, the details of the object-file format, or 15183special options that need to be passed to the compiler or linker. You 15184can check for such features using ad-hoc means, such as having 15185@command{configure} check the output of the @code{uname} program, or 15186looking for libraries that are unique to particular systems. However, 15187Autoconf provides a uniform method for handling unguessable features. 15188 15189@menu 15190* Specifying Names:: Specifying the system type 15191* Canonicalizing:: Getting the canonical system type 15192* Using System Type:: What to do with the system type 15193@end menu 15194 15195@node Specifying Names 15196@section Specifying the System Type 15197@cindex System type 15198 15199Like other @acronym{GNU} @command{configure} scripts, Autoconf-generated 15200@command{configure} scripts can make decisions based on a canonical name 15201for the system type, which has the form: 15202@samp{@var{cpu}-@var{vendor}-@var{os}}, where @var{os} can be 15203@samp{@var{system}} or @samp{@var{kernel}-@var{system}} 15204 15205@command{configure} can usually guess the canonical name for the type of 15206system it's running on. To do so it runs a script called 15207@command{config.guess}, which infers the name using the @code{uname} 15208command or symbols predefined by the C preprocessor. 15209 15210Alternately, the user can specify the system type with command line 15211arguments to @command{configure}. Doing so is necessary when 15212cross-compiling. In the most complex case of cross-compiling, three 15213system types are involved. The options to specify them are: 15214 15215@table @option 15216@item --build=@var{build-type} 15217the type of system on which the package is being configured and 15218compiled. It defaults to the result of running @command{config.guess}. 15219 15220@item --host=@var{host-type} 15221the type of system on which the package runs. By default it is the 15222same as the build machine. Specifying it enables the cross-compilation 15223mode. 15224 15225@item --target=@var{target-type} 15226the type of system for which any compiler tools in the package 15227produce code (rarely needed). By default, it is the same as host. 15228@end table 15229 15230If you mean to override the result of @command{config.guess}, use 15231@option{--build}, not @option{--host}, since the latter enables 15232cross-compilation. For historical reasons, passing @option{--host} also 15233changes the build type. Therefore, whenever you specify @option{--host}, 15234be sure to specify @option{--build} too; this will be fixed in the 15235future. So, to enter cross-compilation mode, use a command like this 15236 15237@example 15238./configure --build=i686-pc-linux-gnu --host=m68k-coff 15239@end example 15240 15241@noindent 15242Note that if you do not specify @option{--host}, @command{configure} 15243fails if it can't run the code generated by the specified compiler. For 15244example, configuring as follows fails: 15245 15246@example 15247./configure CC=m68k-coff-gcc 15248@end example 15249 15250In the future, when cross-compiling Autoconf will @emph{not} 15251accept tools (compilers, linkers, assemblers) whose name is not 15252prefixed with the host type. The only case when this may be 15253useful is when you really are not cross-compiling, but only 15254building for a least-common-denominator architecture: an example 15255is building for @code{i386-pc-linux-gnu} while running on an 15256@code{i686-pc-linux-gnu} architecture. In this case, some particular 15257pairs might be similar enough to let you get away with the system 15258compilers, but in general the compiler might make bogus assumptions 15259on the host: if you know what you are doing, please create symbolic 15260links from the host compiler to the build compiler. 15261 15262@cindex @command{config.sub} 15263@command{configure} recognizes short aliases for many system types; for 15264example, @samp{decstation} can be used instead of 15265@samp{mips-dec-ultrix4.2}. @command{configure} runs a script called 15266@command{config.sub} to canonicalize system type aliases. 15267 15268This section deliberately omits the description of the obsolete 15269interface; see @ref{Hosts and Cross-Compilation}. 15270 15271 15272@node Canonicalizing 15273@section Getting the Canonical System Type 15274@cindex System type 15275@cindex Canonical system type 15276 15277The following macros make the system type available to @command{configure} 15278scripts. 15279 15280@ovindex build_alias 15281@ovindex host_alias 15282@ovindex target_alias 15283 15284The variables @samp{build_alias}, @samp{host_alias}, and 15285@samp{target_alias} are always exactly the arguments of @option{--build}, 15286@option{--host}, and @option{--target}; in particular, they are left empty 15287if the user did not use them, even if the corresponding 15288@code{AC_CANONICAL} macro was run. Any configure script may use these 15289variables anywhere. These are the variables that should be used when in 15290interaction with the user. 15291 15292If you need to recognize some special environments based on their system 15293type, run the following macros to get canonical system names. These 15294variables are not set before the macro call. 15295 15296If you use these macros, you must distribute @command{config.guess} and 15297@command{config.sub} along with your source code. @xref{Output}, for 15298information about the @code{AC_CONFIG_AUX_DIR} macro which you can use 15299to control in which directory @command{configure} looks for those scripts. 15300 15301 15302@defmac AC_CANONICAL_BUILD 15303@acindex{CANONICAL_BUILD} 15304@ovindex build 15305@ovindex build_cpu 15306@ovindex build_vendor 15307@ovindex build_os 15308Compute the canonical build-system type variable, @code{build}, and its 15309three individual parts @code{build_cpu}, @code{build_vendor}, and 15310@code{build_os}. 15311 15312If @option{--build} was specified, then @code{build} is the 15313canonicalization of @code{build_alias} by @command{config.sub}, 15314otherwise it is determined by the shell script @command{config.guess}. 15315@end defmac 15316 15317@defmac AC_CANONICAL_HOST 15318@acindex{CANONICAL_HOST} 15319@ovindex host 15320@ovindex host_cpu 15321@ovindex host_vendor 15322@ovindex host_os 15323Compute the canonical host-system type variable, @code{host}, and its 15324three individual parts @code{host_cpu}, @code{host_vendor}, and 15325@code{host_os}. 15326 15327If @option{--host} was specified, then @code{host} is the 15328canonicalization of @code{host_alias} by @command{config.sub}, 15329otherwise it defaults to @code{build}. 15330@end defmac 15331 15332@defmac AC_CANONICAL_TARGET 15333@acindex{CANONICAL_TARGET} 15334@ovindex target 15335@ovindex target_cpu 15336@ovindex target_vendor 15337@ovindex target_os 15338Compute the canonical target-system type variable, @code{target}, and its 15339three individual parts @code{target_cpu}, @code{target_vendor}, and 15340@code{target_os}. 15341 15342If @option{--target} was specified, then @code{target} is the 15343canonicalization of @code{target_alias} by @command{config.sub}, 15344otherwise it defaults to @code{host}. 15345@end defmac 15346 15347Note that there can be artifacts due to the backward compatibility 15348code. See @xref{Hosts and Cross-Compilation}, for more. 15349 15350@node Using System Type 15351@section Using the System Type 15352 15353In @file{configure.ac} the system type is generally used by one or more 15354@code{case} statements to select system-specifics. Shell wildcards can 15355be used to match a group of system types. 15356 15357For example, an extra assembler code object file could be chosen, giving 15358access to a CPU cycle counter register. @code{$(CYCLE_OBJ)} in the 15359following would be used in a makefile to add the object to a 15360program or library. 15361 15362@example 15363case $host in 15364 alpha*-*-*) CYCLE_OBJ=rpcc.o ;; 15365 i?86-*-*) CYCLE_OBJ=rdtsc.o ;; 15366 *) CYCLE_OBJ= ;; 15367esac 15368AC_SUBST([CYCLE_OBJ]) 15369@end example 15370 15371@code{AC_CONFIG_LINKS} (@pxref{Configuration Links}) is another good way 15372to select variant source files, for example optimized code for some 15373CPUs. The configured CPU type doesn't always indicate exact CPU types, 15374so some runtime capability checks may be necessary too. 15375 15376@example 15377case $host in 15378 alpha*-*-*) AC_CONFIG_LINKS([dither.c:alpha/dither.c]) ;; 15379 powerpc*-*-*) AC_CONFIG_LINKS([dither.c:powerpc/dither.c]) ;; 15380 *-*-*) AC_CONFIG_LINKS([dither.c:generic/dither.c]) ;; 15381esac 15382@end example 15383 15384The host system type can also be used to find cross-compilation tools 15385with @code{AC_CHECK_TOOL} (@pxref{Generic Programs}). 15386 15387The above examples all show @samp{$host}, since this is where the code 15388is going to run. Only rarely is it necessary to test @samp{$build} 15389(which is where the build is being done). 15390 15391Whenever you're tempted to use @samp{$host} it's worth considering 15392whether some sort of probe would be better. New system types come along 15393periodically or previously missing features are added. Well-written 15394probes can adapt themselves to such things, but hard-coded lists of 15395names can't. Here are some guidelines, 15396 15397@itemize @bullet 15398@item 15399Availability of libraries and library functions should always be checked 15400by probing. 15401@item 15402Variant behavior of system calls is best identified with runtime tests 15403if possible, but bug workarounds or obscure difficulties might have to 15404be driven from @samp{$host}. 15405@item 15406Assembler code is inevitably highly CPU-specific and is best selected 15407according to @samp{$host_cpu}. 15408@item 15409Assembler variations like underscore prefix on globals or ELF versus 15410COFF type directives are however best determined by probing, perhaps 15411even examining the compiler output. 15412@end itemize 15413 15414@samp{$target} is for use by a package creating a compiler or similar. 15415For ordinary packages it's meaningless and should not be used. It 15416indicates what the created compiler should generate code for, if it can 15417cross-compile. @samp{$target} generally selects various hard-coded CPU 15418and system conventions, since usually the compiler or tools under 15419construction themselves determine how the target works. 15420 15421 15422@c ===================================================== Site Configuration. 15423 15424@node Site Configuration 15425@chapter Site Configuration 15426 15427@command{configure} scripts support several kinds of local configuration 15428decisions. There are ways for users to specify where external software 15429packages are, include or exclude optional features, install programs 15430under modified names, and set default values for @command{configure} 15431options. 15432 15433@menu 15434* Help Formatting:: Customizing @samp{configure --help} 15435* External Software:: Working with other optional software 15436* Package Options:: Selecting optional features 15437* Pretty Help Strings:: Formatting help string 15438* Site Details:: Configuring site details 15439* Transforming Names:: Changing program names when installing 15440* Site Defaults:: Giving @command{configure} local defaults 15441@end menu 15442 15443@node Help Formatting 15444@section Controlling Help Output 15445 15446Users consult @samp{configure --help} to learn of configuration 15447decisions specific to your package. By default, @command{configure} 15448breaks this output into sections for each type of option; within each 15449section, help strings appear in the order @file{configure.ac} defines 15450them: 15451 15452@example 15453Optional Features: 15454 @dots{} 15455 --enable-bar include bar 15456 15457Optional Packages: 15458 @dots{} 15459 --with-foo use foo 15460@end example 15461 15462@defmac AC_PRESERVE_HELP_ORDER 15463@acindex{PRESERVE_HELP_ORDER} 15464 15465Request an alternate @option{--help} format, in which options of all 15466types appear together, in the order defined. Call this macro before any 15467@code{AC_ARG_ENABLE} or @code{AC_ARG_WITH}. 15468 15469@example 15470Optional Features and Packages: 15471 @dots{} 15472 --enable-bar include bar 15473 --with-foo use foo 15474@end example 15475 15476@end defmac 15477 15478@node External Software 15479@section Working With External Software 15480@cindex External software 15481 15482Some packages require, or can optionally use, other software packages 15483that are already installed. The user can give @command{configure} 15484command line options to specify which such external software to use. 15485The options have one of these forms: 15486 15487@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 15488@c awful. 15489@example 15490--with-@var{package}[=@var{arg}] 15491--without-@var{package} 15492@end example 15493 15494For example, @option{--with-gnu-ld} means work with the @acronym{GNU} linker 15495instead of some other linker. @option{--with-x} means work with The X 15496Window System. 15497 15498The user can give an argument by following the package name with 15499@samp{=} and the argument. Giving an argument of @samp{no} is for 15500packages that are used by default; it says to @emph{not} use the 15501package. An argument that is neither @samp{yes} nor @samp{no} could 15502include a name or number of a version of the other package, to specify 15503more precisely which other package this program is supposed to work 15504with. If no argument is given, it defaults to @samp{yes}. 15505@option{--without-@var{package}} is equivalent to 15506@option{--with-@var{package}=no}. 15507 15508@command{configure} scripts do not complain about 15509@option{--with-@var{package}} options that they do not support. This 15510behavior permits configuring a source tree containing multiple packages 15511with a top-level @command{configure} script when the packages support 15512different options, without spurious error messages about options that 15513some of the packages support. An unfortunate side effect is that option 15514spelling errors are not diagnosed. No better approach to this problem 15515has been suggested so far. 15516 15517For each external software package that may be used, @file{configure.ac} 15518should call @code{AC_ARG_WITH} to detect whether the @command{configure} 15519user asked to use it. Whether each package is used or not by default, 15520and which arguments are valid, is up to you. 15521 15522@defmac AC_ARG_WITH (@var{package}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given}) 15523@acindex{ARG_WITH} 15524If the user gave @command{configure} the option @option{--with-@var{package}} 15525or @option{--without-@var{package}}, run shell commands 15526@var{action-if-given}. If neither option was given, run shell commands 15527@var{action-if-not-given}. The name @var{package} indicates another 15528software package that this program should work with. It should consist 15529only of alphanumeric characters, dashes, and dots. 15530 15531The option's argument is available to the shell commands 15532@var{action-if-given} in the shell variable @code{withval}, which is 15533actually just the value of the shell variable @code{with_@var{package}}, 15534with any non-alphanumeric characters changed into @samp{_}. You may use that 15535variable instead, if you wish. 15536 15537The argument @var{help-string} is a description of the option that 15538looks like this: 15539@example 15540 --with-readline support fancy command line editing 15541@end example 15542 15543@noindent 15544@var{help-string} may be more than one line long, if more detail is 15545needed. Just make sure the columns line up in @samp{configure 15546--help}. Avoid tabs in the help string. You'll need to enclose the 15547help string in @samp{[} and @samp{]} in order to produce the leading 15548blanks. 15549 15550You should format your @var{help-string} with the macro 15551@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 15552 15553The following example shows how to use the @code{AC_ARG_WITH} macro in 15554a common situation. You want to let the user decide whether to enable 15555support for an external library (e.g., the readline library); if the user 15556specified neither @option{--with-readline} nor @option{--without-readline}, 15557you want to enable support for readline only if the library is available 15558on the system. 15559 15560@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 15561@example 15562AC_ARG_WITH([readline], 15563 [AS_HELP_STRING([--with-readline], 15564 [support fancy command line editing @@<:@@default=check@@:>@@])], 15565 [], 15566 [with_readline=check]) 15567 15568LIBREADLINE= 15569AS_IF([test "x$with_readline" != xno], 15570 [AC_CHECK_LIB([readline], [main], 15571 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 15572 AC_DEFINE([HAVE_LIBREADLINE], [1], 15573 [Define if you have libreadline]) 15574 ], 15575 [if test "x$with_readline" != xcheck; then 15576 AC_MSG_FAILURE( 15577 [--with-readline was given, but test for readline failed]) 15578 fi 15579 ], -lncurses)]) 15580@end example 15581 15582The next example shows how to use @code{AC_ARG_WITH} to give the user the 15583possibility to enable support for the readline library, in case it is still 15584experimental and not well tested, and is therefore disabled by default. 15585 15586@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 15587@example 15588AC_ARG_WITH([readline], 15589 [AS_HELP_STRING([--with-readline], 15590 [enable experimental support for readline])], 15591 [], 15592 [with_readline=no]) 15593 15594LIBREADLINE= 15595AS_IF([test "x$with_readline" != xno], 15596 [AC_CHECK_LIB([readline], [main], 15597 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 15598 AC_DEFINE([HAVE_LIBREADLINE], [1], 15599 [Define if you have libreadline]) 15600 ], 15601 [AC_MSG_FAILURE( 15602 [--with-readline was given, but test for readline failed])], 15603 [-lncurses])]) 15604@end example 15605 15606The last example shows how to use @code{AC_ARG_WITH} to give the user the 15607possibility to disable support for the readline library, given that it is 15608an important feature and that it should be enabled by default. 15609 15610@c FIXME: Remove AS_IF when the problem of AC_REQUIRE within `if' is solved. 15611@example 15612AC_ARG_WITH([readline], 15613 [AS_HELP_STRING([--without-readline], 15614 [disable support for readline])], 15615 [], 15616 [with_readline=yes]) 15617 15618LIBREADLINE= 15619AS_IF([test "x$with_readline" != xno], 15620 [AC_CHECK_LIB([readline], [main], 15621 [AC_SUBST([LIBREADLINE], ["-lreadline -lncurses"]) 15622 AC_DEFINE([HAVE_LIBREADLINE], [1], 15623 [Define if you have libreadline]) 15624 ], 15625 [AC_MSG_FAILURE( 15626 [readline test failed (--without-readline to disable)])], 15627 [-lncurses])]) 15628@end example 15629 15630These three examples can be easily adapted to the case where 15631@code{AC_ARG_ENABLE} should be preferred to @code{AC_ARG_WITH} (see 15632@ref{Package Options}). 15633@end defmac 15634 15635@defmac AC_WITH (@var{package}, @var{action-if-given}, @ovar{action-if-not-given}) 15636@acindex{WITH} 15637This is an obsolete version of @code{AC_ARG_WITH} that does not 15638support providing a help string. 15639@end defmac 15640 15641@node Package Options 15642@section Choosing Package Options 15643@cindex Package options 15644@cindex Options, package 15645 15646If a software package has optional compile-time features, the user can 15647give @command{configure} command line options to specify whether to 15648compile them. The options have one of these forms: 15649 15650@c FIXME: Can't use @ovar here, Texinfo 4.0 goes lunatic and emits something 15651@c awful. 15652@example 15653--enable-@var{feature}[=@var{arg}] 15654--disable-@var{feature} 15655@end example 15656 15657These options allow users to choose which optional features to build and 15658install. @option{--enable-@var{feature}} options should never make a 15659feature behave differently or cause one feature to replace another. 15660They should only cause parts of the program to be built rather than left 15661out. 15662 15663The user can give an argument by following the feature name with 15664@samp{=} and the argument. Giving an argument of @samp{no} requests 15665that the feature @emph{not} be made available. A feature with an 15666argument looks like @option{--enable-debug=stabs}. If no argument is 15667given, it defaults to @samp{yes}. @option{--disable-@var{feature}} is 15668equivalent to @option{--enable-@var{feature}=no}. 15669 15670@command{configure} scripts do not complain about 15671@option{--enable-@var{feature}} options that they do not support. 15672This behavior permits configuring a source tree containing multiple 15673packages with a top-level @command{configure} script when the packages 15674support different options, without spurious error messages about options 15675that some of the packages support. 15676An unfortunate side effect is that option spelling errors are not diagnosed. 15677No better approach to this problem has been suggested so far. 15678 15679For each optional feature, @file{configure.ac} should call 15680@code{AC_ARG_ENABLE} to detect whether the @command{configure} user asked 15681to include it. Whether each feature is included or not by default, and 15682which arguments are valid, is up to you. 15683 15684@defmac AC_ARG_ENABLE (@var{feature}, @var{help-string}, @ovar{action-if-given}, @ovar{action-if-not-given}) 15685@acindex{ARG_ENABLE} 15686If the user gave @command{configure} the option 15687@option{--enable-@var{feature}} or @option{--disable-@var{feature}}, run 15688shell commands @var{action-if-given}. If neither option was given, run 15689shell commands @var{action-if-not-given}. The name @var{feature} 15690indicates an optional user-level facility. It should consist only of 15691alphanumeric characters, dashes, and dots. 15692 15693The option's argument is available to the shell commands 15694@var{action-if-given} in the shell variable @code{enableval}, which is 15695actually just the value of the shell variable 15696@code{enable_@var{feature}}, with any non-alphanumeric characters changed into 15697@samp{_}. You may use that variable instead, if you wish. The 15698@var{help-string} argument is like that of @code{AC_ARG_WITH} 15699(@pxref{External Software}). 15700 15701You should format your @var{help-string} with the macro 15702@code{AS_HELP_STRING} (@pxref{Pretty Help Strings}). 15703 15704See the examples suggested with the definition of @code{AC_ARG_WITH} 15705(@pxref{External Software}) to get an idea of possible applications of 15706@code{AC_ARG_ENABLE}. 15707@end defmac 15708 15709@defmac AC_ENABLE (@var{feature}, @var{action-if-given}, @ovar{action-if-not-given}) 15710@acindex{ENABLE} 15711This is an obsolete version of @code{AC_ARG_ENABLE} that does not 15712support providing a help string. 15713@end defmac 15714 15715 15716@node Pretty Help Strings 15717@section Making Your Help Strings Look Pretty 15718@cindex Help strings 15719 15720Properly formatting the @samp{help strings} which are used in 15721@code{AC_ARG_WITH} (@pxref{External Software}) and @code{AC_ARG_ENABLE} 15722(@pxref{Package Options}) can be challenging. Specifically, you want 15723your own @samp{help strings} to line up in the appropriate columns of 15724@samp{configure --help} just like the standard Autoconf @samp{help 15725strings} do. This is the purpose of the @code{AS_HELP_STRING} macro. 15726 15727@defmac AS_HELP_STRING (@var{left-hand-side}, @var{right-hand-side}) 15728@acindex{HELP_STRING} 15729 15730Expands into an help string that looks pretty when the user executes 15731@samp{configure --help}. It is typically used in @code{AC_ARG_WITH} 15732(@pxref{External Software}) or @code{AC_ARG_ENABLE} (@pxref{Package 15733Options}). The following example makes this clearer. 15734 15735@example 15736AC_ARG_WITH([foo], 15737 [AS_HELP_STRING([--with-foo], 15738 [use foo (default is no)])], 15739 [use_foo=$withval], 15740 [use_foo=no]) 15741@end example 15742 15743The second argument of @code{AS_HELP_STRING} is 15744not a literal, and should not be double quoted. 15745@xref{Autoconf Language}, for a more detailed explanation. 15746Then the last few lines of @samp{configure --help} appear like 15747this: 15748 15749@example 15750--enable and --with options recognized: 15751 --with-foo use foo (default is no) 15752@end example 15753 15754The @code{AS_HELP_STRING} macro is particularly helpful when the 15755@var{left-hand-side} and/or @var{right-hand-side} are composed of macro 15756arguments, as shown in the following example. 15757 15758@example 15759AC_DEFUN([MY_ARG_WITH], 15760 [AC_ARG_WITH([$1], 15761 [AS_HELP_STRING([--with-$1], [use $1 (default is $2)])], 15762 [use_[]$1=$withval], 15763 [use_[]$1=$2])]) 15764@end example 15765@end defmac 15766 15767 15768@node Site Details 15769@section Configuring Site Details 15770@cindex Site details 15771 15772Some software packages require complex site-specific information. Some 15773examples are host names to use for certain services, company names, and 15774email addresses to contact. Since some configuration scripts generated 15775by Metaconfig ask for such information interactively, people sometimes 15776wonder how to get that information in Autoconf-generated configuration 15777scripts, which aren't interactive. 15778 15779Such site configuration information should be put in a file that is 15780edited @emph{only by users}, not by programs. The location of the file 15781can either be based on the @code{prefix} variable, or be a standard 15782location such as the user's home directory. It could even be specified 15783by an environment variable. The programs should examine that file at 15784runtime, rather than at compile time. Runtime configuration is more 15785convenient for users and makes the configuration process simpler than 15786getting the information while configuring. @xref{Directory Variables, , 15787Variables for Installation Directories, standards, @acronym{GNU} Coding 15788Standards}, for more information on where to put data files. 15789 15790@node Transforming Names 15791@section Transforming Program Names When Installing 15792@cindex Transforming program names 15793@cindex Program names, transforming 15794 15795Autoconf supports changing the names of programs when installing them. 15796In order to use these transformations, @file{configure.ac} must call the 15797macro @code{AC_ARG_PROGRAM}. 15798 15799@defmac AC_ARG_PROGRAM 15800@acindex{ARG_PROGRAM} 15801@ovindex program_transform_name 15802Place in output variable @code{program_transform_name} a sequence of 15803@code{sed} commands for changing the names of installed programs. 15804 15805If any of the options described below are given to @command{configure}, 15806program names are transformed accordingly. Otherwise, if 15807@code{AC_CANONICAL_TARGET} has been called and a @option{--target} value 15808is given, the target type followed by a dash is used as a prefix. 15809Otherwise, no program name transformation is done. 15810@end defmac 15811 15812@menu 15813* Transformation Options:: @command{configure} options to transform names 15814* Transformation Examples:: Sample uses of transforming names 15815* Transformation Rules:: Makefile uses of transforming names 15816@end menu 15817 15818@node Transformation Options 15819@subsection Transformation Options 15820 15821You can specify name transformations by giving @command{configure} these 15822command line options: 15823 15824@table @option 15825@item --program-prefix=@var{prefix} 15826prepend @var{prefix} to the names; 15827 15828@item --program-suffix=@var{suffix} 15829append @var{suffix} to the names; 15830 15831@item --program-transform-name=@var{expression} 15832perform @code{sed} substitution @var{expression} on the names. 15833@end table 15834 15835@node Transformation Examples 15836@subsection Transformation Examples 15837 15838These transformations are useful with programs that can be part of a 15839cross-compilation development environment. For example, a 15840cross-assembler running on a Sun 4 configured with 15841@option{--target=i960-vxworks} is normally installed as 15842@file{i960-vxworks-as}, rather than @file{as}, which could be confused 15843with a native Sun 4 assembler. 15844 15845You can force a program name to begin with @file{g}, if you don't want 15846@acronym{GNU} programs installed on your system to shadow other programs with 15847the same name. For example, if you configure @acronym{GNU} @code{diff} with 15848@option{--program-prefix=g}, then when you run @samp{make install} it is 15849installed as @file{/usr/local/bin/gdiff}. 15850 15851As a more sophisticated example, you could use 15852 15853@example 15854--program-transform-name='s/^/g/; s/^gg/g/; s/^gless/less/' 15855@end example 15856@noindent 15857 15858to prepend @samp{g} to most of the program names in a source tree, 15859excepting those like @code{gdb} that already have one and those like 15860@code{less} and @code{lesskey} that aren't @acronym{GNU} programs. (That is 15861assuming that you have a source tree containing those programs that is 15862set up to use this feature.) 15863 15864One way to install multiple versions of some programs simultaneously is 15865to append a version number to the name of one or both. For example, if 15866you want to keep Autoconf version 1 around for awhile, you can configure 15867Autoconf version 2 using @option{--program-suffix=2} to install the 15868programs as @file{/usr/local/bin/autoconf2}, 15869@file{/usr/local/bin/autoheader2}, etc. Nevertheless, pay attention 15870that only the binaries are renamed, therefore you'd have problems with 15871the library files which might overlap. 15872 15873@node Transformation Rules 15874@subsection Transformation Rules 15875 15876Here is how to use the variable @code{program_transform_name} in a 15877@file{Makefile.in}: 15878 15879@example 15880PROGRAMS = cp ls rm 15881transform = @@program_transform_name@@ 15882install: 15883 for p in $(PROGRAMS); do \ 15884 $(INSTALL_PROGRAM) $$p $(DESTDIR)$(bindir)/`echo $$p | \ 15885 sed '$(transform)'`; \ 15886 done 15887 15888uninstall: 15889 for p in $(PROGRAMS); do \ 15890 rm -f $(DESTDIR)$(bindir)/`echo $$p | sed '$(transform)'`; \ 15891 done 15892@end example 15893 15894It is guaranteed that @code{program_transform_name} is never empty, and 15895that there are no useless separators. Therefore you may safely embed 15896@code{program_transform_name} within a sed program using @samp{;}: 15897 15898@example 15899transform = @@program_transform_name@@ 15900transform_exe = s/$(EXEEXT)$$//;$(transform);s/$$/$(EXEEXT)/ 15901@end example 15902 15903Whether to do the transformations on documentation files (Texinfo or 15904@code{man}) is a tricky question; there seems to be no perfect answer, 15905due to the several reasons for name transforming. Documentation is not 15906usually particular to a specific architecture, and Texinfo files do not 15907conflict with system documentation. But they might conflict with 15908earlier versions of the same files, and @code{man} pages sometimes do 15909conflict with system documentation. As a compromise, it is probably 15910best to do name transformations on @code{man} pages but not on Texinfo 15911manuals. 15912 15913@node Site Defaults 15914@section Setting Site Defaults 15915@cindex Site defaults 15916 15917Autoconf-generated @command{configure} scripts allow your site to provide 15918default values for some configuration values. You do this by creating 15919site- and system-wide initialization files. 15920 15921@evindex CONFIG_SITE 15922If the environment variable @code{CONFIG_SITE} is set, @command{configure} 15923uses its value as the name of a shell script to read. Otherwise, it 15924reads the shell script @file{@var{prefix}/share/config.site} if it exists, 15925then @file{@var{prefix}/etc/config.site} if it exists. Thus, 15926settings in machine-specific files override those in machine-independent 15927ones in case of conflict. 15928 15929Site files can be arbitrary shell scripts, but only certain kinds of 15930code are really appropriate to be in them. Because @command{configure} 15931reads any cache file after it has read any site files, a site file can 15932define a default cache file to be shared between all Autoconf-generated 15933@command{configure} scripts run on that system (@pxref{Cache Files}). If 15934you set a default cache file in a site file, it is a good idea to also 15935set the output variable @code{CC} in that site file, because the cache 15936file is only valid for a particular compiler, but many systems have 15937several available. 15938 15939You can examine or override the value set by a command line option to 15940@command{configure} in a site file; options set shell variables that have 15941the same names as the options, with any dashes turned into underscores. 15942The exceptions are that @option{--without-} and @option{--disable-} options 15943are like giving the corresponding @option{--with-} or @option{--enable-} 15944option and the value @samp{no}. Thus, @option{--cache-file=localcache} 15945sets the variable @code{cache_file} to the value @samp{localcache}; 15946@option{--enable-warnings=no} or @option{--disable-warnings} sets the variable 15947@code{enable_warnings} to the value @samp{no}; @option{--prefix=/usr} sets the 15948variable @code{prefix} to the value @samp{/usr}; etc. 15949 15950Site files are also good places to set default values for other output 15951variables, such as @code{CFLAGS}, if you need to give them non-default 15952values: anything you would normally do, repetitively, on the command 15953line. If you use non-default values for @var{prefix} or 15954@var{exec_prefix} (wherever you locate the site file), you can set them 15955in the site file if you specify it with the @code{CONFIG_SITE} 15956environment variable. 15957 15958You can set some cache values in the site file itself. Doing this is 15959useful if you are cross-compiling, where it is impossible to check features 15960that require running a test program. You could ``prime the cache'' by 15961setting those values correctly for that system in 15962@file{@var{prefix}/etc/config.site}. To find out the names of the cache 15963variables you need to set, look for shell variables with @samp{_cv_} in 15964their names in the affected @command{configure} scripts, or in the Autoconf 15965M4 source code for those macros. 15966 15967The cache file is careful to not override any variables set in the site 15968files. Similarly, you should not override command-line options in the 15969site files. Your code should check that variables such as @code{prefix} 15970and @code{cache_file} have their default values (as set near the top of 15971@command{configure}) before changing them. 15972 15973Here is a sample file @file{/usr/share/local/gnu/share/config.site}. The 15974command @samp{configure --prefix=/usr/share/local/gnu} would read this 15975file (if @code{CONFIG_SITE} is not set to a different file). 15976 15977@example 15978# config.site for configure 15979# 15980# Change some defaults. 15981test "$prefix" = NONE && prefix=/usr/share/local/gnu 15982test "$exec_prefix" = NONE && exec_prefix=/usr/local/gnu 15983test "$sharedstatedir" = '$prefix/com' && sharedstatedir=/var 15984test "$localstatedir" = '$prefix/var' && localstatedir=/var 15985 15986# Give Autoconf 2.x generated configure scripts a shared default 15987# cache file for feature test results, architecture-specific. 15988if test "$cache_file" = /dev/null; then 15989 cache_file="$prefix/var/config.cache" 15990 # A cache file is only valid for one C compiler. 15991 CC=gcc 15992fi 15993@end example 15994 15995 15996@c ============================================== Running configure Scripts. 15997 15998@node Running configure Scripts 15999@chapter Running @command{configure} Scripts 16000@cindex @command{configure} 16001 16002Below are instructions on how to configure a package that uses a 16003@command{configure} script, suitable for inclusion as an @file{INSTALL} 16004file in the package. A plain-text version of @file{INSTALL} which you 16005may use comes with Autoconf. 16006 16007@menu 16008* Basic Installation:: Instructions for typical cases 16009* Compilers and Options:: Selecting compilers and optimization 16010* Multiple Architectures:: Compiling for multiple architectures at once 16011* Installation Names:: Installing in different directories 16012* Optional Features:: Selecting optional features 16013* System Type:: Specifying the system type 16014* Sharing Defaults:: Setting site-wide defaults for @command{configure} 16015* Defining Variables:: Specifying the compiler etc. 16016* configure Invocation:: Changing how @command{configure} runs 16017@end menu 16018 16019@set autoconf 16020@include install.texi 16021 16022 16023@c ============================================== Recreating a Configuration 16024 16025@node config.status Invocation 16026@chapter Recreating a Configuration 16027@cindex @command{config.status} 16028 16029The @command{configure} script creates a file named @file{config.status}, 16030which actually configures, @dfn{instantiates}, the template files. It 16031also records the configuration options that were specified when the 16032package was last configured in case reconfiguring is needed. 16033 16034Synopsis: 16035@example 16036./config.status @var{option}@dots{} [@var{file}@dots{}] 16037@end example 16038 16039It configures the @var{files}; if none are specified, all the templates 16040are instantiated. The files must be specified without their 16041dependencies, as in 16042 16043@example 16044./config.status foobar 16045@end example 16046 16047@noindent 16048not 16049 16050@example 16051./config.status foobar:foo.in:bar.in 16052@end example 16053 16054The supported options are: 16055 16056@table @option 16057@item --help 16058@itemx -h 16059Print a summary of the command line options, the list of the template 16060files, and exit. 16061 16062@item --version 16063@itemx -V 16064Print the version number of Autoconf and the configuration settings, 16065and exit. 16066 16067@item --silent 16068@itemx --quiet 16069@itemx -q 16070Do not print progress messages. 16071 16072@item --debug 16073@itemx -d 16074Don't remove the temporary files. 16075 16076@item --file=@var{file}[:@var{template}] 16077Require that @var{file} be instantiated as if 16078@samp{AC_CONFIG_FILES(@var{file}:@var{template})} was used. Both 16079@var{file} and @var{template} may be @samp{-} in which case the standard 16080output and/or standard input, respectively, is used. If a 16081@var{template} file name is relative, it is first looked for in the build 16082tree, and then in the source tree. @xref{Configuration Actions}, for 16083more details. 16084 16085This option and the following ones provide one way for separately 16086distributed packages to share the values computed by @command{configure}. 16087Doing so can be useful if some of the packages need a superset of the 16088features that one of them, perhaps a common library, does. These 16089options allow a @file{config.status} file to create files other than the 16090ones that its @file{configure.ac} specifies, so it can be used for a 16091different package. 16092 16093@item --header=@var{file}[:@var{template}] 16094Same as @option{--file} above, but with @samp{AC_CONFIG_HEADERS}. 16095 16096@item --recheck 16097Ask @file{config.status} to update itself and exit (no instantiation). 16098This option is useful if you change @command{configure}, so that the 16099results of some tests might be different from the previous run. The 16100@option{--recheck} option reruns @command{configure} with the same arguments 16101you used before, plus the @option{--no-create} option, which prevents 16102@command{configure} from running @file{config.status} and creating 16103@file{Makefile} and other files, and the @option{--no-recursion} option, 16104which prevents @command{configure} from running other @command{configure} 16105scripts in subdirectories. (This is so other Make rules can 16106run @file{config.status} when it changes; @pxref{Automatic Remaking}, 16107for an example). 16108@end table 16109 16110@file{config.status} checks several optional environment variables that 16111can alter its behavior: 16112 16113@defvar CONFIG_SHELL 16114@evindex CONFIG_SHELL 16115The shell with which to run @command{configure} for the @option{--recheck} 16116option. It must be Bourne-compatible. The default is a shell that 16117supports @code{LINENO} if available, and @file{/bin/sh} otherwise. 16118Invoking @command{configure} by hand bypasses this setting, so you may 16119need to use a command like @samp{CONFIG_SHELL=/bin/bash /bin/bash ./configure} 16120to insure that the same shell is used everywhere. The absolute name of the 16121shell should be passed. 16122@end defvar 16123 16124@defvar CONFIG_STATUS 16125@evindex CONFIG_STATUS 16126The file name to use for the shell script that records the 16127configuration. The default is @file{./config.status}. This variable is 16128useful when one package uses parts of another and the @command{configure} 16129scripts shouldn't be merged because they are maintained separately. 16130@end defvar 16131 16132You can use @file{./config.status} in your makefiles. For example, in 16133the dependencies given above (@pxref{Automatic Remaking}), 16134@file{config.status} is run twice when @file{configure.ac} has changed. 16135If that bothers you, you can make each run only regenerate the files for 16136that rule: 16137@example 16138@group 16139config.h: stamp-h 16140stamp-h: config.h.in config.status 16141 ./config.status config.h 16142 echo > stamp-h 16143 16144Makefile: Makefile.in config.status 16145 ./config.status Makefile 16146@end group 16147@end example 16148 16149The calling convention of @file{config.status} has changed; see 16150@ref{Obsolete config.status Use}, for details. 16151 16152 16153@c =================================================== Obsolete Constructs 16154 16155@node Obsolete Constructs 16156@chapter Obsolete Constructs 16157@cindex Obsolete constructs 16158 16159Autoconf changes, and throughout the years some constructs have been 16160obsoleted. Most of the changes involve the macros, but in some cases 16161the tools themselves, or even some concepts, are now considered 16162obsolete. 16163 16164You may completely skip this chapter if you are new to Autoconf. Its 16165intention is mainly to help maintainers updating their packages by 16166understanding how to move to more modern constructs. 16167 16168@menu 16169* Obsolete config.status Use:: Different calling convention 16170* acconfig.h:: Additional entries in @file{config.h.in} 16171* autoupdate Invocation:: Automatic update of @file{configure.ac} 16172* Obsolete Macros:: Backward compatibility macros 16173* Autoconf 1:: Tips for upgrading your files 16174* Autoconf 2.13:: Some fresher tips 16175@end menu 16176 16177@node Obsolete config.status Use 16178@section Obsolete @file{config.status} Invocation 16179 16180@file{config.status} now supports arguments to specify the files to 16181instantiate; see @ref{config.status Invocation}, for more details. 16182Before, environment variables had to be used. 16183 16184@defvar CONFIG_COMMANDS 16185@evindex CONFIG_COMMANDS 16186The tags of the commands to execute. The default is the arguments given 16187to @code{AC_OUTPUT} and @code{AC_CONFIG_COMMANDS} in 16188@file{configure.ac}. 16189@end defvar 16190 16191@defvar CONFIG_FILES 16192@evindex CONFIG_FILES 16193The files in which to perform @samp{@@@var{variable}@@} substitutions. 16194The default is the arguments given to @code{AC_OUTPUT} and 16195@code{AC_CONFIG_FILES} in @file{configure.ac}. 16196@end defvar 16197 16198@defvar CONFIG_HEADERS 16199@evindex CONFIG_HEADERS 16200The files in which to substitute C @code{#define} statements. The 16201default is the arguments given to @code{AC_CONFIG_HEADERS}; if that 16202macro was not called, @file{config.status} ignores this variable. 16203@end defvar 16204 16205@defvar CONFIG_LINKS 16206@evindex CONFIG_LINKS 16207The symbolic links to establish. The default is the arguments given to 16208@code{AC_CONFIG_LINKS}; if that macro was not called, 16209@file{config.status} ignores this variable. 16210@end defvar 16211 16212In @ref{config.status Invocation}, using this old interface, the example 16213would be: 16214 16215@example 16216@group 16217config.h: stamp-h 16218stamp-h: config.h.in config.status 16219 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_FILES= \ 16220 CONFIG_HEADERS=config.h ./config.status 16221 echo > stamp-h 16222 16223Makefile: Makefile.in config.status 16224 CONFIG_COMMANDS= CONFIG_LINKS= CONFIG_HEADERS= \ 16225 CONFIG_FILES=Makefile ./config.status 16226@end group 16227@end example 16228 16229@noindent 16230(If @file{configure.ac} does not call @code{AC_CONFIG_HEADERS}, there is 16231no need to set @code{CONFIG_HEADERS} in the @code{make} rules. Equally 16232for @code{CONFIG_COMMANDS}, etc.) 16233 16234 16235@node acconfig.h 16236@section @file{acconfig.h} 16237 16238@cindex @file{acconfig.h} 16239@cindex @file{config.h.top} 16240@cindex @file{config.h.bot} 16241 16242In order to produce @file{config.h.in}, @command{autoheader} needs to 16243build or to find templates for each symbol. Modern releases of Autoconf 16244use @code{AH_VERBATIM} and @code{AH_TEMPLATE} (@pxref{Autoheader 16245Macros}), but in older releases a file, @file{acconfig.h}, contained the 16246list of needed templates. @command{autoheader} copied comments and 16247@code{#define} and @code{#undef} statements from @file{acconfig.h} in 16248the current directory, if present. This file used to be mandatory if 16249you @code{AC_DEFINE} any additional symbols. 16250 16251Modern releases of Autoconf also provide @code{AH_TOP} and 16252@code{AH_BOTTOM} if you need to prepend/append some information to 16253@file{config.h.in}. Ancient versions of Autoconf had a similar feature: 16254if @file{./acconfig.h} contains the string @samp{@@TOP@@}, 16255@command{autoheader} copies the lines before the line containing 16256@samp{@@TOP@@} into the top of the file that it generates. Similarly, 16257if @file{./acconfig.h} contains the string @samp{@@BOTTOM@@}, 16258@command{autoheader} copies the lines after that line to the end of the 16259file it generates. Either or both of those strings may be omitted. An 16260even older alternate way to produce the same effect in ancient versions 16261of Autoconf is to create the files @file{@var{file}.top} (typically 16262@file{config.h.top}) and/or @file{@var{file}.bot} in the current 16263directory. If they exist, @command{autoheader} copies them to the 16264beginning and end, respectively, of its output. 16265 16266In former versions of Autoconf, the files used in preparing a software 16267package for distribution were: 16268@example 16269@group 16270configure.ac --. .------> autoconf* -----> configure 16271 +---+ 16272[aclocal.m4] --+ `---. 16273[acsite.m4] ---' | 16274 +--> [autoheader*] -> [config.h.in] 16275[acconfig.h] ----. | 16276 +-----' 16277[config.h.top] --+ 16278[config.h.bot] --' 16279@end group 16280@end example 16281 16282Using only the @code{AH_} macros, @file{configure.ac} should be 16283self-contained, and should not depend upon @file{acconfig.h} etc. 16284 16285 16286@node autoupdate Invocation 16287@section Using @command{autoupdate} to Modernize @file{configure.ac} 16288@cindex @command{autoupdate} 16289 16290The @command{autoupdate} program updates a @file{configure.ac} file that 16291calls Autoconf macros by their old names to use the current macro names. 16292In version 2 of Autoconf, most of the macros were renamed to use a more 16293uniform and descriptive naming scheme. @xref{Macro Names}, for a 16294description of the new scheme. Although the old names still work 16295(@pxref{Obsolete Macros}, for a list of the old macros and the corresponding 16296new names), you can make your @file{configure.ac} files more readable 16297and make it easier to use the current Autoconf documentation if you 16298update them to use the new macro names. 16299 16300@evindex SIMPLE_BACKUP_SUFFIX 16301If given no arguments, @command{autoupdate} updates @file{configure.ac}, 16302backing up the original version with the suffix @file{~} (or the value 16303of the environment variable @code{SIMPLE_BACKUP_SUFFIX}, if that is 16304set). If you give @command{autoupdate} an argument, it reads that file 16305instead of @file{configure.ac} and writes the updated file to the 16306standard output. 16307 16308@noindent 16309@command{autoupdate} accepts the following options: 16310 16311@table @option 16312@item --help 16313@itemx -h 16314Print a summary of the command line options and exit. 16315 16316@item --version 16317@itemx -V 16318Print the version number of Autoconf and exit. 16319 16320@item --verbose 16321@itemx -v 16322Report processing steps. 16323 16324@item --debug 16325@itemx -d 16326Don't remove the temporary files. 16327 16328@item --force 16329@itemx -f 16330Force the update even if the file has not changed. Disregard the cache. 16331 16332@item --include=@var{dir} 16333@itemx -I @var{dir} 16334Also look for input files in @var{dir}. Multiple invocations accumulate. 16335Directories are browsed from last to first. 16336@end table 16337 16338@node Obsolete Macros 16339@section Obsolete Macros 16340 16341Several macros are obsoleted in Autoconf, for various reasons (typically 16342they failed to quote properly, couldn't be extended for more recent 16343issues, etc.). They are still supported, but deprecated: their use 16344should be avoided. 16345 16346During the jump from Autoconf version 1 to version 2, most of the 16347macros were renamed to use a more uniform and descriptive naming scheme, 16348but their signature did not change. @xref{Macro Names}, for a 16349description of the new naming scheme. Below, if there is just the mapping 16350from old names to new names for these macros, the reader is invited to 16351refer to the definition of the new macro for the signature and the 16352description. 16353 16354@defmac AC_ALLOCA 16355@acindex{ALLOCA} 16356@code{AC_FUNC_ALLOCA} 16357@end defmac 16358 16359@defmac AC_ARG_ARRAY 16360@acindex{ARG_ARRAY} 16361removed because of limited usefulness 16362@end defmac 16363 16364@defmac AC_C_CROSS 16365@acindex{C_CROSS} 16366This macro is obsolete; it does nothing. 16367@end defmac 16368 16369@defmac AC_C_LONG_DOUBLE 16370@acindex{C_LONG_DOUBLE} 16371@cvindex HAVE_LONG_DOUBLE 16372If the C compiler supports a working @code{long double} type with more 16373range or precision than the @code{double} type, define 16374@code{HAVE_LONG_DOUBLE}. 16375 16376You should use @code{AC_TYPE_LONG_DOUBLE} or 16377@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 16378@end defmac 16379 16380@defmac AC_CANONICAL_SYSTEM 16381@acindex{CANONICAL_SYSTEM} 16382Determine the system type and set output variables to the names of the 16383canonical system types. @xref{Canonicalizing}, for details about the 16384variables this macro sets. 16385 16386The user is encouraged to use either @code{AC_CANONICAL_BUILD}, or 16387@code{AC_CANONICAL_HOST}, or @code{AC_CANONICAL_TARGET}, depending on 16388the needs. Using @code{AC_CANONICAL_TARGET} is enough to run the two 16389other macros. 16390@end defmac 16391 16392@defmac AC_CHAR_UNSIGNED 16393@acindex{CHAR_UNSIGNED} 16394@code{AC_C_CHAR_UNSIGNED} 16395@end defmac 16396 16397@defmac AC_CHECK_TYPE (@var{type}, @var{default}) 16398@acindex{CHECK_TYPE} 16399Autoconf, up to 2.13, used to provide this version of 16400@code{AC_CHECK_TYPE}, deprecated because of its flaws. First, although 16401it is a member of the @code{CHECK} clan, it does 16402more than just checking. Secondly, missing types are defined 16403using @code{#define}, not @code{typedef}, and this can lead to 16404problems in the case of pointer types. 16405 16406This use of @code{AC_CHECK_TYPE} is obsolete and discouraged; see 16407@ref{Generic Types}, for the description of the current macro. 16408 16409If the type @var{type} is not defined, define it to be the C (or C++) 16410builtin type @var{default}, e.g., @samp{short int} or @samp{unsigned int}. 16411 16412This macro is equivalent to: 16413 16414@example 16415AC_CHECK_TYPE([@var{type}], [], 16416 [AC_DEFINE_UNQUOTED([@var{type}], [@var{default}], 16417 [Define to `@var{default}' 16418 if <sys/types.h> does not define.])]) 16419@end example 16420 16421In order to keep backward compatibility, the two versions of 16422@code{AC_CHECK_TYPE} are implemented, selected by a simple heuristics: 16423 16424@enumerate 16425@item 16426If there are three or four arguments, the modern version is used. 16427 16428@item 16429If the second argument appears to be a C or C++ type, then the 16430obsolete version is used. This happens if the argument is a C or C++ 16431@emph{builtin} type or a C identifier ending in @samp{_t}, optionally 16432followed by one of @samp{[(* } and then by a string of zero or more 16433characters taken from the set @samp{[]()* _a-zA-Z0-9}. 16434 16435@item 16436If the second argument is spelled with the alphabet of valid C and C++ 16437types, the user is warned and the modern version is used. 16438 16439@item 16440Otherwise, the modern version is used. 16441@end enumerate 16442 16443@noindent 16444You are encouraged either to use a valid builtin type, or to use the 16445equivalent modern code (see above), or better yet, to use 16446@code{AC_CHECK_TYPES} together with 16447 16448@example 16449#ifndef HAVE_LOFF_T 16450typedef loff_t off_t; 16451#endif 16452@end example 16453@end defmac 16454@c end of AC_CHECK_TYPE 16455 16456@defmac AC_CHECKING (@var{feature-description}) 16457@acindex{CHECKING} 16458Same as @samp{AC_MSG_NOTICE([checking @var{feature-description}@dots{}]}. 16459@end defmac 16460 16461@defmac AC_COMPILE_CHECK (@var{echo-text}, @var{includes}, @var{function-body}, @var{action-if-true}, @ovar{action-if-false}) 16462@acindex{COMPILE_CHECK} 16463This is an obsolete version of @code{AC_TRY_COMPILE} itself replaced by 16464@code{AC_COMPILE_IFELSE} (@pxref{Running the Compiler}), with the 16465addition that it prints @samp{checking for @var{echo-text}} to the 16466standard output first, if @var{echo-text} is non-empty. Use 16467@code{AC_MSG_CHECKING} and @code{AC_MSG_RESULT} instead to print 16468messages (@pxref{Printing Messages}). 16469@end defmac 16470 16471@defmac AC_CONST 16472@acindex{CONST} 16473@code{AC_C_CONST} 16474@end defmac 16475 16476@defmac AC_CROSS_CHECK 16477@acindex{CROSS_CHECK} 16478Same as @code{AC_C_CROSS}, which is obsolete too, and does nothing 16479@code{:-)}. 16480@end defmac 16481 16482@defmac AC_CYGWIN 16483@acindex{CYGWIN} 16484Check for the Cygwin environment in which case the shell variable 16485@code{CYGWIN} is set to @samp{yes}. Don't use this macro, the dignified 16486means to check the nature of the host is using 16487@code{AC_CANONICAL_HOST}. As a matter of fact this macro is defined as: 16488 16489@example 16490AC_REQUIRE([AC_CANONICAL_HOST])[]dnl 16491case $host_os in 16492 *cygwin* ) CYGWIN=yes;; 16493 * ) CYGWIN=no;; 16494esac 16495@end example 16496 16497Beware that the variable @code{CYGWIN} has a special meaning when 16498running Cygwin, and should not be changed. That's yet another reason 16499not to use this macro. 16500@end defmac 16501 16502@defmac AC_DECL_SYS_SIGLIST 16503@acindex{DECL_SYS_SIGLIST} 16504@cvindex SYS_SIGLIST_DECLARED 16505Same as: 16506 16507@example 16508AC_CHECK_DECLS([sys_siglist], [], [], 16509[#include <signal.h> 16510/* NetBSD declares sys_siglist in unistd.h. */ 16511#ifdef HAVE_UNISTD_H 16512# include <unistd.h> 16513#endif 16514]) 16515@end example 16516@end defmac 16517 16518@defmac AC_DECL_YYTEXT 16519@acindex{DECL_YYTEXT} 16520Does nothing, now integrated in @code{AC_PROG_LEX}. 16521@end defmac 16522 16523@defmac AC_DIR_HEADER 16524@acindex{DIR_HEADER} 16525@cvindex DIRENT 16526@cvindex SYSNDIR 16527@cvindex SYSDIR 16528@cvindex NDIR 16529Like calling @code{AC_FUNC_CLOSEDIR_VOID} and@code{AC_HEADER_DIRENT}, 16530but defines a different set of C preprocessor macros to indicate which 16531header file is found: 16532 16533@multitable {@file{sys/ndir.h}} {Old Symbol} {@code{HAVE_SYS_NDIR_H}} 16534@item Header @tab Old Symbol @tab New Symbol 16535@item @file{dirent.h} @tab @code{DIRENT} @tab @code{HAVE_DIRENT_H} 16536@item @file{sys/ndir.h} @tab @code{SYSNDIR} @tab @code{HAVE_SYS_NDIR_H} 16537@item @file{sys/dir.h} @tab @code{SYSDIR} @tab @code{HAVE_SYS_DIR_H} 16538@item @file{ndir.h} @tab @code{NDIR} @tab @code{HAVE_NDIR_H} 16539@end multitable 16540@end defmac 16541 16542@defmac AC_DYNIX_SEQ 16543@acindex{DYNIX_SEQ} 16544If on DYNIX/ptx, add @option{-lseq} to output variable 16545@code{LIBS}. This macro used to be defined as 16546 16547@example 16548AC_CHECK_LIB([seq], [getmntent], [LIBS="-lseq $LIBS"]) 16549@end example 16550 16551@noindent 16552now it is just @code{AC_FUNC_GETMNTENT}. 16553@end defmac 16554 16555@defmac AC_EXEEXT 16556@acindex{EXEEXT} 16557@ovindex EXEEXT 16558Defined the output variable @code{EXEEXT} based on the output of the 16559compiler, which is now done automatically. Typically set to empty 16560string if Posix and @samp{.exe} if a @acronym{DOS} variant. 16561@end defmac 16562 16563@defmac AC_EMXOS2 16564@acindex{EMXOS2} 16565Similar to @code{AC_CYGWIN} but checks for the EMX environment on OS/2 16566and sets @code{EMXOS2}. 16567@end defmac 16568 16569@defmac AC_ERROR 16570@acindex{ERROR} 16571@code{AC_MSG_ERROR} 16572@end defmac 16573 16574@defmac AC_FIND_X 16575@acindex{FIND_X} 16576@code{AC_PATH_X} 16577@end defmac 16578 16579@defmac AC_FIND_XTRA 16580@acindex{FIND_XTRA} 16581@code{AC_PATH_XTRA} 16582@end defmac 16583 16584@defmac AC_FOREACH 16585@acindex{FOREACH} 16586@code{m4_foreach_w} 16587@end defmac 16588 16589@defmac AC_FUNC_CHECK 16590@acindex{FUNC_CHECK} 16591@code{AC_CHECK_FUNC} 16592@end defmac 16593 16594@defmac AC_FUNC_WAIT3 16595@acindex{FUNC_WAIT3} 16596@cvindex HAVE_WAIT3 16597If @code{wait3} is found and fills in the contents of its third argument 16598(a @samp{struct rusage *}), which @acronym{HP-UX} does not do, define 16599@code{HAVE_WAIT3}. 16600 16601These days portable programs should use @code{waitpid}, not 16602@code{wait3}, as @code{wait3} has been removed from Posix. 16603@end defmac 16604 16605@defmac AC_GCC_TRADITIONAL 16606@acindex{GCC_TRADITIONAL} 16607@code{AC_PROG_GCC_TRADITIONAL} 16608@end defmac 16609 16610@defmac AC_GETGROUPS_T 16611@acindex{GETGROUPS_T} 16612@code{AC_TYPE_GETGROUPS} 16613@end defmac 16614 16615@defmac AC_GETLOADAVG 16616@acindex{GETLOADAVG} 16617@code{AC_FUNC_GETLOADAVG} 16618@end defmac 16619 16620@defmac AC_HAVE_FUNCS 16621@acindex{HAVE_FUNCS} 16622@code{AC_CHECK_FUNCS} 16623@end defmac 16624 16625@defmac AC_HAVE_HEADERS 16626@acindex{HAVE_HEADERS} 16627@code{AC_CHECK_HEADERS} 16628@end defmac 16629 16630@defmac AC_HAVE_LIBRARY (@var{library}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{other-libraries}) 16631@acindex{HAVE_LIBRARY} 16632This macro is equivalent to calling @code{AC_CHECK_LIB} with a 16633@var{function} argument of @code{main}. In addition, @var{library} can 16634be written as any of @samp{foo}, @option{-lfoo}, or @samp{libfoo.a}. In 16635all of those cases, the compiler is passed @option{-lfoo}. However, 16636@var{library} cannot be a shell variable; it must be a literal name. 16637@end defmac 16638 16639@defmac AC_HAVE_POUNDBANG 16640@acindex{HAVE_POUNDBANG} 16641@code{AC_SYS_INTERPRETER} (different calling convention) 16642@end defmac 16643 16644@defmac AC_HEADER_CHECK 16645@acindex{HEADER_CHECK} 16646@code{AC_CHECK_HEADER} 16647@end defmac 16648 16649@defmac AC_HEADER_EGREP 16650@acindex{HEADER_EGREP} 16651@code{AC_EGREP_HEADER} 16652@end defmac 16653 16654@defmac AC_HELP_STRING 16655@acindex{HELP_STRING} 16656@code{AS_HELP_STRING} 16657@end defmac 16658 16659@defmac AC_INIT (@var{unique-file-in-source-dir}) 16660@acindex{INIT} 16661Formerly @code{AC_INIT} used to have a single argument, and was 16662equivalent to: 16663 16664@example 16665AC_INIT 16666AC_CONFIG_SRCDIR(@var{unique-file-in-source-dir}) 16667@end example 16668@end defmac 16669 16670@defmac AC_INLINE 16671@acindex{INLINE} 16672@code{AC_C_INLINE} 16673@end defmac 16674 16675@defmac AC_INT_16_BITS 16676@acindex{INT_16_BITS} 16677@cvindex INT_16_BITS 16678If the C type @code{int} is 16 bits wide, define @code{INT_16_BITS}. 16679Use @samp{AC_CHECK_SIZEOF(int)} instead. 16680@end defmac 16681 16682@defmac AC_IRIX_SUN 16683@acindex{IRIX_SUN} 16684If on @sc{irix} (Silicon Graphics Unix), add @option{-lsun} to output 16685@code{LIBS}. If you were using it to get @code{getmntent}, use 16686@code{AC_FUNC_GETMNTENT} instead. If you used it for the NIS versions 16687of the password and group functions, use @samp{AC_CHECK_LIB(sun, 16688getpwnam)}. Up to Autoconf 2.13, it used to be 16689 16690@example 16691AC_CHECK_LIB([sun], [getmntent], [LIBS="-lsun $LIBS"]) 16692@end example 16693 16694@noindent 16695now it is defined as 16696 16697@example 16698AC_FUNC_GETMNTENT 16699AC_CHECK_LIB([sun], [getpwnam]) 16700@end example 16701@end defmac 16702 16703@defmac AC_LANG_C 16704@acindex{LANG_C} 16705Same as @samp{AC_LANG([C])}. 16706@end defmac 16707 16708@defmac AC_LANG_CPLUSPLUS 16709@acindex{LANG_CPLUSPLUS} 16710Same as @samp{AC_LANG([C++])}. 16711@end defmac 16712 16713@defmac AC_LANG_FORTRAN77 16714@acindex{LANG_FORTRAN77} 16715Same as @samp{AC_LANG([Fortran 77])}. 16716@end defmac 16717 16718@defmac AC_LANG_RESTORE 16719@acindex{LANG_RESTORE} 16720Select the @var{language} that is saved on the top of the stack, as set 16721by @code{AC_LANG_SAVE}, remove it from the stack, and call 16722@code{AC_LANG(@var{language})}. 16723@end defmac 16724 16725@defmac AC_LANG_SAVE 16726@acindex{LANG_SAVE} 16727Remember the current language (as set by @code{AC_LANG}) on a stack. 16728The current language does not change. @code{AC_LANG_PUSH} is preferred. 16729@end defmac 16730 16731@defmac AC_LINK_FILES (@var{source}@dots{}, @var{dest}@dots{}) 16732@acindex{LINK_FILES} 16733This is an obsolete version of @code{AC_CONFIG_LINKS}. An updated 16734version of: 16735 16736@example 16737AC_LINK_FILES(config/$machine.h config/$obj_format.h, 16738 host.h object.h) 16739@end example 16740 16741@noindent 16742is: 16743 16744@example 16745AC_CONFIG_LINKS([host.h:config/$machine.h 16746 object.h:config/$obj_format.h]) 16747@end example 16748@end defmac 16749 16750@defmac AC_LN_S 16751@acindex{LN_S} 16752@code{AC_PROG_LN_S} 16753@end defmac 16754 16755@defmac AC_LONG_64_BITS 16756@acindex{LONG_64_BITS} 16757@cvindex LONG_64_BITS 16758Define @code{LONG_64_BITS} if the C type @code{long int} is 64 bits wide. 16759Use the generic macro @samp{AC_CHECK_SIZEOF([long int])} instead. 16760@end defmac 16761 16762@defmac AC_LONG_DOUBLE 16763@acindex{LONG_DOUBLE} 16764If the C compiler supports a working @code{long double} type with more 16765range or precision than the @code{double} type, define 16766@code{HAVE_LONG_DOUBLE}. 16767 16768You should use @code{AC_TYPE_LONG_DOUBLE} or 16769@code{AC_TYPE_LONG_DOUBLE_WIDER} instead. @xref{Particular Types}. 16770@end defmac 16771 16772@defmac AC_LONG_FILE_NAMES 16773@acindex{LONG_FILE_NAMES} 16774@code{AC_SYS_LONG_FILE_NAMES} 16775@end defmac 16776 16777@defmac AC_MAJOR_HEADER 16778@acindex{MAJOR_HEADER} 16779@code{AC_HEADER_MAJOR} 16780@end defmac 16781 16782@defmac AC_MEMORY_H 16783@acindex{MEMORY_H} 16784@cvindex NEED_MEMORY_H 16785Used to define @code{NEED_MEMORY_H} if the @code{mem} functions were 16786defined in @file{memory.h}. Today it is equivalent to 16787@samp{AC_CHECK_HEADERS([memory.h])}. Adjust your code to depend upon 16788@code{HAVE_MEMORY_H}, not @code{NEED_MEMORY_H}; see @ref{Standard 16789Symbols}. 16790@end defmac 16791 16792@defmac AC_MINGW32 16793@acindex{MINGW32} 16794Similar to @code{AC_CYGWIN} but checks for the MinGW compiler 16795environment and sets @code{MINGW32}. 16796@end defmac 16797 16798@defmac AC_MINUS_C_MINUS_O 16799@acindex{MINUS_C_MINUS_O} 16800@code{AC_PROG_CC_C_O} 16801@end defmac 16802 16803@defmac AC_MMAP 16804@acindex{MMAP} 16805@code{AC_FUNC_MMAP} 16806@end defmac 16807 16808@defmac AC_MODE_T 16809@acindex{MODE_T} 16810@code{AC_TYPE_MODE_T} 16811@end defmac 16812 16813@defmac AC_OBJEXT 16814@acindex{OBJEXT} 16815@ovindex OBJEXT 16816Defined the output variable @code{OBJEXT} based on the output of the 16817compiler, after .c files have been excluded. Typically set to @samp{o} 16818if Posix, @samp{obj} if a @acronym{DOS} variant. 16819Now the compiler checking macros handle 16820this automatically. 16821@end defmac 16822 16823@defmac AC_OBSOLETE (@var{this-macro-name}, @ovar{suggestion}) 16824@acindex{OBSOLETE} 16825Make M4 print a message to the standard error output warning that 16826@var{this-macro-name} is obsolete, and giving the file and line number 16827where it was called. @var{this-macro-name} should be the name of the 16828macro that is calling @code{AC_OBSOLETE}. If @var{suggestion} is given, 16829it is printed at the end of the warning message; for example, it can be 16830a suggestion for what to use instead of @var{this-macro-name}. 16831 16832For instance 16833 16834@example 16835AC_OBSOLETE([$0], [; use AC_CHECK_HEADERS(unistd.h) instead])dnl 16836@end example 16837 16838You are encouraged to use @code{AU_DEFUN} instead, since it gives better 16839services to the user. 16840@end defmac 16841 16842@defmac AC_OFF_T 16843@acindex{OFF_T} 16844@code{AC_TYPE_OFF_T} 16845@end defmac 16846 16847@defmac AC_OUTPUT (@ovar{file}@dots{}, @ovar{extra-cmds}, @ovar{init-cmds}) 16848@acindex{OUTPUT} 16849The use of @code{AC_OUTPUT} with argument is deprecated. This obsoleted 16850interface is equivalent to: 16851 16852@example 16853@group 16854AC_CONFIG_FILES(@var{file}@dots{}) 16855AC_CONFIG_COMMANDS([default], 16856 @var{extra-cmds}, @var{init-cmds}) 16857AC_OUTPUT 16858@end group 16859@end example 16860@end defmac 16861 16862@defmac AC_OUTPUT_COMMANDS (@var{extra-cmds}, @ovar{init-cmds}) 16863@acindex{OUTPUT_COMMANDS} 16864Specify additional shell commands to run at the end of 16865@file{config.status}, and shell commands to initialize any variables 16866from @command{configure}. This macro may be called multiple times. It is 16867obsolete, replaced by @code{AC_CONFIG_COMMANDS}. 16868 16869Here is an unrealistic example: 16870 16871@example 16872fubar=27 16873AC_OUTPUT_COMMANDS([echo this is extra $fubar, and so on.], 16874 [fubar=$fubar]) 16875AC_OUTPUT_COMMANDS([echo this is another, extra, bit], 16876 [echo init bit]) 16877@end example 16878 16879Aside from the fact that @code{AC_CONFIG_COMMANDS} requires an 16880additional key, an important difference is that 16881@code{AC_OUTPUT_COMMANDS} is quoting its arguments twice, unlike 16882@code{AC_CONFIG_COMMANDS}. This means that @code{AC_CONFIG_COMMANDS} 16883can safely be given macro calls as arguments: 16884 16885@example 16886AC_CONFIG_COMMANDS(foo, [my_FOO()]) 16887@end example 16888 16889@noindent 16890Conversely, where one level of quoting was enough for literal strings 16891with @code{AC_OUTPUT_COMMANDS}, you need two with 16892@code{AC_CONFIG_COMMANDS}. The following lines are equivalent: 16893 16894@example 16895@group 16896AC_OUTPUT_COMMANDS([echo "Square brackets: []"]) 16897AC_CONFIG_COMMANDS([default], [[echo "Square brackets: []"]]) 16898@end group 16899@end example 16900@end defmac 16901 16902@defmac AC_PID_T 16903@acindex{PID_T} 16904@code{AC_TYPE_PID_T} 16905@end defmac 16906 16907@defmac AC_PREFIX 16908@acindex{PREFIX} 16909@code{AC_PREFIX_PROGRAM} 16910@end defmac 16911 16912@defmac AC_PROGRAMS_CHECK 16913@acindex{PROGRAMS_CHECK} 16914@code{AC_CHECK_PROGS} 16915@end defmac 16916 16917@defmac AC_PROGRAMS_PATH 16918@acindex{PROGRAMS_PATH} 16919@code{AC_PATH_PROGS} 16920@end defmac 16921 16922@defmac AC_PROGRAM_CHECK 16923@acindex{PROGRAM_CHECK} 16924@code{AC_CHECK_PROG} 16925@end defmac 16926 16927@defmac AC_PROGRAM_EGREP 16928@acindex{PROGRAM_EGREP} 16929@code{AC_EGREP_CPP} 16930@end defmac 16931 16932@defmac AC_PROGRAM_PATH 16933@acindex{PROGRAM_PATH} 16934@code{AC_PATH_PROG} 16935@end defmac 16936 16937@defmac AC_REMOTE_TAPE 16938@acindex{REMOTE_TAPE} 16939removed because of limited usefulness 16940@end defmac 16941 16942@defmac AC_RESTARTABLE_SYSCALLS 16943@acindex{RESTARTABLE_SYSCALLS} 16944@code{AC_SYS_RESTARTABLE_SYSCALLS} 16945@end defmac 16946 16947@defmac AC_RETSIGTYPE 16948@acindex{RETSIGTYPE} 16949@code{AC_TYPE_SIGNAL} 16950@end defmac 16951 16952@defmac AC_RSH 16953@acindex{RSH} 16954removed because of limited usefulness 16955@end defmac 16956 16957@defmac AC_SCO_INTL 16958@acindex{SCO_INTL} 16959@ovindex LIBS 16960If on SCO Unix, add @option{-lintl} to output variable @code{LIBS}. This 16961macro used to do this: 16962 16963@example 16964AC_CHECK_LIB([intl], [strftime], [LIBS="-lintl $LIBS"]) 16965@end example 16966 16967@noindent 16968Now it just calls @code{AC_FUNC_STRFTIME} instead. 16969@end defmac 16970 16971@defmac AC_SETVBUF_REVERSED 16972@acindex{SETVBUF_REVERSED} 16973@code{AC_FUNC_SETVBUF_REVERSED} 16974@end defmac 16975 16976@defmac AC_SET_MAKE 16977@acindex{SET_MAKE} 16978@code{AC_PROG_MAKE_SET} 16979@end defmac 16980 16981@defmac AC_SIZEOF_TYPE 16982@acindex{SIZEOF_TYPE} 16983@code{AC_CHECK_SIZEOF} 16984@end defmac 16985 16986@defmac AC_SIZE_T 16987@acindex{SIZE_T} 16988@code{AC_TYPE_SIZE_T} 16989@end defmac 16990 16991@defmac AC_STAT_MACROS_BROKEN 16992@acindex{STAT_MACROS_BROKEN} 16993@code{AC_HEADER_STAT} 16994@end defmac 16995 16996@defmac AC_STDC_HEADERS 16997@acindex{STDC_HEADERS} 16998@code{AC_HEADER_STDC} 16999@end defmac 17000 17001@defmac AC_STRCOLL 17002@acindex{STRCOLL} 17003@code{AC_FUNC_STRCOLL} 17004@end defmac 17005 17006@defmac AC_ST_BLKSIZE 17007@acindex{ST_BLKSIZE} 17008@code{AC_CHECK_MEMBERS} 17009@end defmac 17010 17011@defmac AC_ST_BLOCKS 17012@acindex{ST_BLOCKS} 17013@code{AC_STRUCT_ST_BLOCKS} 17014@end defmac 17015 17016@defmac AC_ST_RDEV 17017@acindex{ST_RDEV} 17018@code{AC_CHECK_MEMBERS} 17019@end defmac 17020 17021@defmac AC_SYS_RESTARTABLE_SYSCALLS 17022@acindex{SYS_RESTARTABLE_SYSCALLS} 17023@cvindex HAVE_RESTARTABLE_SYSCALLS 17024If the system automatically restarts a system call that is interrupted 17025by a signal, define @code{HAVE_RESTARTABLE_SYSCALLS}. This macro does 17026not check whether system calls are restarted in general---it checks whether a 17027signal handler installed with @code{signal} (but not @code{sigaction}) 17028causes system calls to be restarted. It does not check whether system calls 17029can be restarted when interrupted by signals that have no handler. 17030 17031These days portable programs should use @code{sigaction} with 17032@code{SA_RESTART} if they want restartable system calls. They should 17033not rely on @code{HAVE_RESTARTABLE_SYSCALLS}, since nowadays whether a 17034system call is restartable is a dynamic issue, not a configuration-time 17035issue. 17036@end defmac 17037 17038@defmac AC_SYS_SIGLIST_DECLARED 17039@acindex{SYS_SIGLIST_DECLARED} 17040@code{AC_DECL_SYS_SIGLIST} 17041@end defmac 17042 17043@defmac AC_TEST_CPP 17044@acindex{TEST_CPP} 17045@code{AC_TRY_CPP}, replaced by @code{AC_PREPROC_IFELSE}. 17046@end defmac 17047 17048@defmac AC_TEST_PROGRAM 17049@acindex{TEST_PROGRAM} 17050@code{AC_TRY_RUN}, replaced by @code{AC_RUN_IFELSE}. 17051@end defmac 17052 17053@defmac AC_TIMEZONE 17054@acindex{TIMEZONE} 17055@code{AC_STRUCT_TIMEZONE} 17056@end defmac 17057 17058@defmac AC_TIME_WITH_SYS_TIME 17059@acindex{TIME_WITH_SYS_TIME} 17060@code{AC_HEADER_TIME} 17061@end defmac 17062 17063@defmac AC_TRY_COMPILE (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false}) 17064@acindex{TRY_COMPILE} 17065Same as: 17066 17067@example 17068AC_COMPILE_IFELSE( 17069 [AC_LANG_PROGRAM([[@var{includes}]], 17070 [[@var{function-body}]])], 17071 [@var{action-if-true}], 17072 [@var{action-if-false}]) 17073@end example 17074 17075@noindent 17076@xref{Running the Compiler}. 17077 17078This macro double quotes both @var{includes} and @var{function-body}. 17079 17080For C and C++, @var{includes} is any @code{#include} statements needed 17081by the code in @var{function-body} (@var{includes} is ignored if 17082the currently selected language is Fortran or Fortran 77). The compiler 17083and compilation flags are determined by the current language 17084(@pxref{Language Choice}). 17085@end defmac 17086 17087@defmac AC_TRY_CPP (@var{input}, @ovar{action-if-true}, @ovar{action-if-false}) 17088@acindex{TRY_CPP} 17089Same as: 17090 17091@example 17092AC_PREPROC_IFELSE( 17093 [AC_LANG_SOURCE([[@var{input}]])], 17094 [@var{action-if-true}], 17095 [@var{action-if-false}]) 17096@end example 17097 17098@noindent 17099@xref{Running the Preprocessor}. 17100 17101This macro double quotes the @var{input}. 17102@end defmac 17103 17104@defmac AC_TRY_LINK (@var{includes}, @var{function-body}, @ovar{action-if-true}, @ovar{action-if-false}) 17105@acindex{TRY_LINK} 17106Same as: 17107 17108@example 17109AC_LINK_IFELSE( 17110 [AC_LANG_PROGRAM([[@var{includes}]], 17111 [[@var{function-body}]])], 17112 [@var{action-if-true}], 17113 [@var{action-if-false}]) 17114@end example 17115 17116@noindent 17117@xref{Running the Compiler}. 17118 17119This macro double quotes both @var{includes} and @var{function-body}. 17120 17121Depending on the current language (@pxref{Language Choice}), create a 17122test program to see whether a function whose body consists of 17123@var{function-body} can be compiled and linked. If the file compiles 17124and links successfully, run shell commands @var{action-if-found}, 17125otherwise run @var{action-if-not-found}. 17126 17127This macro double quotes both @var{includes} and @var{function-body}. 17128 17129For C and C++, @var{includes} is any @code{#include} statements needed 17130by the code in @var{function-body} (@var{includes} is ignored if 17131the currently selected language is Fortran or Fortran 77). The compiler 17132and compilation flags are determined by the current language 17133(@pxref{Language Choice}), and in addition @code{LDFLAGS} and 17134@code{LIBS} are used for linking. 17135@end defmac 17136 17137@defmac AC_TRY_LINK_FUNC (@var{function}, @ovar{action-if-found}, @ovar{action-if-not-found}) 17138@acindex{TRY_LINK_FUNC} 17139This macro is equivalent to 17140@samp{AC_LINK_IFELSE([AC_LANG_CALL([], [@var{function}])], 17141[@var{action-if-found}], [@var{action-if-not-found}])}. 17142@end defmac 17143 17144@defmac AC_TRY_RUN (@var{program}, @ovar{action-if-true}, @ovar{action-if-false}, @ovar{action-if-cross-compiling}) 17145@acindex{TRY_RUN} 17146Same as: 17147 17148@example 17149AC_RUN_IFELSE( 17150 [AC_LANG_SOURCE([[@var{program}]])], 17151 [@var{action-if-true}], 17152 [@var{action-if-false}], 17153 [@var{action-if-cross-compiling}]) 17154@end example 17155 17156@noindent 17157@xref{Runtime}. 17158@end defmac 17159 17160@defmac AC_UID_T 17161@acindex{UID_T} 17162@code{AC_TYPE_UID_T} 17163@end defmac 17164 17165@defmac AC_UNISTD_H 17166@acindex{UNISTD_H} 17167Same as @samp{AC_CHECK_HEADERS([unistd.h])}. 17168@end defmac 17169 17170@defmac AC_USG 17171@acindex{USG} 17172@cvindex USG 17173Define @code{USG} if the @acronym{BSD} string functions are defined in 17174@file{strings.h}. You should no longer depend upon @code{USG}, but on 17175@code{HAVE_STRING_H}; see @ref{Standard Symbols}. 17176@end defmac 17177 17178@defmac AC_UTIME_NULL 17179@acindex{UTIME_NULL} 17180@code{AC_FUNC_UTIME_NULL} 17181@end defmac 17182 17183@defmac AC_VALIDATE_CACHED_SYSTEM_TUPLE (@ovar{cmd}) 17184@acindex{VALIDATE_CACHED_SYSTEM_TUPLE} 17185If the cache file is inconsistent with the current host, target and 17186build system types, it used to execute @var{cmd} or print a default 17187error message. This is now handled by default. 17188@end defmac 17189 17190@defmac AC_VERBOSE (@var{result-description}) 17191@acindex{VERBOSE} 17192@code{AC_MSG_RESULT}. 17193@end defmac 17194 17195@defmac AC_VFORK 17196@acindex{VFORK} 17197@code{AC_FUNC_VFORK} 17198@end defmac 17199 17200@defmac AC_VPRINTF 17201@acindex{VPRINTF} 17202@code{AC_FUNC_VPRINTF} 17203@end defmac 17204 17205@defmac AC_WAIT3 17206@acindex{WAIT3} 17207@code{AC_FUNC_WAIT3} 17208@end defmac 17209 17210@defmac AC_WARN 17211@acindex{WARN} 17212@code{AC_MSG_WARN} 17213@end defmac 17214 17215@defmac AC_WORDS_BIGENDIAN 17216@acindex{WORDS_BIGENDIAN} 17217@code{AC_C_BIGENDIAN} 17218@end defmac 17219 17220@defmac AC_XENIX_DIR 17221@acindex{XENIX_DIR} 17222@ovindex LIBS 17223This macro used to add @option{-lx} to output variable @code{LIBS} if on 17224Xenix. Also, if @file{dirent.h} is being checked for, added 17225@option{-ldir} to @code{LIBS}. Now it is merely an alias of 17226@code{AC_HEADER_DIRENT} instead, plus some code to detect whether 17227running @sc{xenix} on which you should not depend: 17228 17229@example 17230AC_MSG_CHECKING([for Xenix]) 17231AC_EGREP_CPP([yes], 17232[#if defined M_XENIX && !defined M_UNIX 17233 yes 17234#endif], 17235 [AC_MSG_RESULT([yes]); XENIX=yes], 17236 [AC_MSG_RESULT([no]); XENIX=]) 17237@end example 17238@end defmac 17239 17240@defmac AC_YYTEXT_POINTER 17241@acindex{YYTEXT_POINTER} 17242@code{AC_DECL_YYTEXT} 17243@end defmac 17244 17245@node Autoconf 1 17246@section Upgrading From Version 1 17247@cindex Upgrading autoconf 17248@cindex Autoconf upgrading 17249 17250Autoconf version 2 is mostly backward compatible with version 1. 17251However, it introduces better ways to do some things, and doesn't 17252support some of the ugly things in version 1. So, depending on how 17253sophisticated your @file{configure.ac} files are, you might have to do 17254some manual work in order to upgrade to version 2. This chapter points 17255out some problems to watch for when upgrading. Also, perhaps your 17256@command{configure} scripts could benefit from some of the new features in 17257version 2; the changes are summarized in the file @file{NEWS} in the 17258Autoconf distribution. 17259 17260@menu 17261* Changed File Names:: Files you might rename 17262* Changed Makefiles:: New things to put in @file{Makefile.in} 17263* Changed Macros:: Macro calls you might replace 17264* Changed Results:: Changes in how to check test results 17265* Changed Macro Writing:: Better ways to write your own macros 17266@end menu 17267 17268@node Changed File Names 17269@subsection Changed File Names 17270 17271If you have an @file{aclocal.m4} installed with Autoconf (as opposed to 17272in a particular package's source directory), you must rename it to 17273@file{acsite.m4}. @xref{autoconf Invocation}. 17274 17275If you distribute @file{install.sh} with your package, rename it to 17276@file{install-sh} so @code{make} builtin rules don't inadvertently 17277create a file called @file{install} from it. @code{AC_PROG_INSTALL} 17278looks for the script under both names, but it is best to use the new name. 17279 17280If you were using @file{config.h.top}, @file{config.h.bot}, or 17281@file{acconfig.h}, you still can, but you have less clutter if you 17282use the @code{AH_} macros. @xref{Autoheader Macros}. 17283 17284@node Changed Makefiles 17285@subsection Changed Makefiles 17286 17287Add @samp{@@CFLAGS@@}, @samp{@@CPPFLAGS@@}, and @samp{@@LDFLAGS@@} in 17288your @file{Makefile.in} files, so they can take advantage of the values 17289of those variables in the environment when @command{configure} is run. 17290Doing this isn't necessary, but it's a convenience for users. 17291 17292Also add @samp{@@configure_input@@} in a comment to each input file for 17293@code{AC_OUTPUT}, so that the output files contain a comment saying 17294they were produced by @command{configure}. Automatically selecting the 17295right comment syntax for all the kinds of files that people call 17296@code{AC_OUTPUT} on became too much work. 17297 17298Add @file{config.log} and @file{config.cache} to the list of files you 17299remove in @code{distclean} targets. 17300 17301If you have the following in @file{Makefile.in}: 17302 17303@example 17304prefix = /usr/local 17305exec_prefix = $(prefix) 17306@end example 17307 17308@noindent 17309you must change it to: 17310 17311@example 17312prefix = @@prefix@@ 17313exec_prefix = @@exec_prefix@@ 17314@end example 17315 17316@noindent 17317The old behavior of replacing those variables without @samp{@@} 17318characters around them has been removed. 17319 17320@node Changed Macros 17321@subsection Changed Macros 17322 17323Many of the macros were renamed in Autoconf version 2. You can still 17324use the old names, but the new ones are clearer, and it's easier to find 17325the documentation for them. @xref{Obsolete Macros}, for a table showing the 17326new names for the old macros. Use the @command{autoupdate} program to 17327convert your @file{configure.ac} to using the new macro names. 17328@xref{autoupdate Invocation}. 17329 17330Some macros have been superseded by similar ones that do the job better, 17331but are not call-compatible. If you get warnings about calling obsolete 17332macros while running @command{autoconf}, you may safely ignore them, but 17333your @command{configure} script generally works better if you follow 17334the advice that is printed about what to replace the obsolete macros with. In 17335particular, the mechanism for reporting the results of tests has 17336changed. If you were using @command{echo} or @code{AC_VERBOSE} (perhaps 17337via @code{AC_COMPILE_CHECK}), your @command{configure} script's output 17338looks better if you switch to @code{AC_MSG_CHECKING} and 17339@code{AC_MSG_RESULT}. @xref{Printing Messages}. Those macros work best 17340in conjunction with cache variables. @xref{Caching Results}. 17341 17342 17343 17344@node Changed Results 17345@subsection Changed Results 17346 17347If you were checking the results of previous tests by examining the 17348shell variable @code{DEFS}, you need to switch to checking the values of 17349the cache variables for those tests. @code{DEFS} no longer exists while 17350@command{configure} is running; it is only created when generating output 17351files. This difference from version 1 is because properly quoting the 17352contents of that variable turned out to be too cumbersome and 17353inefficient to do every time @code{AC_DEFINE} is called. @xref{Cache 17354Variable Names}. 17355 17356For example, here is a @file{configure.ac} fragment written for Autoconf 17357version 1: 17358 17359@example 17360AC_HAVE_FUNCS(syslog) 17361case "$DEFS" in 17362*-DHAVE_SYSLOG*) ;; 17363*) # syslog is not in the default libraries. See if it's in some other. 17364 saved_LIBS="$LIBS" 17365 for lib in bsd socket inet; do 17366 AC_CHECKING(for syslog in -l$lib) 17367 LIBS="-l$lib $saved_LIBS" 17368 AC_HAVE_FUNCS(syslog) 17369 case "$DEFS" in 17370 *-DHAVE_SYSLOG*) break ;; 17371 *) ;; 17372 esac 17373 LIBS="$saved_LIBS" 17374 done ;; 17375esac 17376@end example 17377 17378Here is a way to write it for version 2: 17379 17380@example 17381AC_CHECK_FUNCS([syslog]) 17382if test $ac_cv_func_syslog = no; then 17383 # syslog is not in the default libraries. See if it's in some other. 17384 for lib in bsd socket inet; do 17385 AC_CHECK_LIB([$lib], [syslog], [AC_DEFINE([HAVE_SYSLOG]) 17386 LIBS="-l$lib $LIBS"; break]) 17387 done 17388fi 17389@end example 17390 17391If you were working around bugs in @code{AC_DEFINE_UNQUOTED} by adding 17392backslashes before quotes, you need to remove them. It now works 17393predictably, and does not treat quotes (except back quotes) specially. 17394@xref{Setting Output Variables}. 17395 17396All of the Boolean shell variables set by Autoconf macros now use 17397@samp{yes} for the true value. Most of them use @samp{no} for false, 17398though for backward compatibility some use the empty string instead. If 17399you were relying on a shell variable being set to something like 1 or 17400@samp{t} for true, you need to change your tests. 17401 17402@node Changed Macro Writing 17403@subsection Changed Macro Writing 17404 17405When defining your own macros, you should now use @code{AC_DEFUN} 17406instead of @code{define}. @code{AC_DEFUN} automatically calls 17407@code{AC_PROVIDE} and ensures that macros called via @code{AC_REQUIRE} 17408do not interrupt other macros, to prevent nested @samp{checking@dots{}} 17409messages on the screen. There's no actual harm in continuing to use the 17410older way, but it's less convenient and attractive. @xref{Macro 17411Definitions}. 17412 17413You probably looked at the macros that came with Autoconf as a guide for 17414how to do things. It would be a good idea to take a look at the new 17415versions of them, as the style is somewhat improved and they take 17416advantage of some new features. 17417 17418If you were doing tricky things with undocumented Autoconf internals 17419(macros, variables, diversions), check whether you need to change 17420anything to account for changes that have been made. Perhaps you can 17421even use an officially supported technique in version 2 instead of 17422kludging. Or perhaps not. 17423 17424To speed up your locally written feature tests, add caching to them. 17425See whether any of your tests are of general enough usefulness to 17426encapsulate them into macros that you can share. 17427 17428 17429@node Autoconf 2.13 17430@section Upgrading From Version 2.13 17431@cindex Upgrading autoconf 17432@cindex Autoconf upgrading 17433 17434The introduction of the previous section (@pxref{Autoconf 1}) perfectly 17435suits this section@enddots{} 17436 17437@quotation 17438Autoconf version 2.50 is mostly backward compatible with version 2.13. 17439However, it introduces better ways to do some things, and doesn't 17440support some of the ugly things in version 2.13. So, depending on how 17441sophisticated your @file{configure.ac} files are, you might have to do 17442some manual work in order to upgrade to version 2.50. This chapter 17443points out some problems to watch for when upgrading. Also, perhaps 17444your @command{configure} scripts could benefit from some of the new 17445features in version 2.50; the changes are summarized in the file 17446@file{NEWS} in the Autoconf distribution. 17447@end quotation 17448 17449@menu 17450* Changed Quotation:: Broken code which used to work 17451* New Macros:: Interaction with foreign macros 17452* Hosts and Cross-Compilation:: Bugward compatibility kludges 17453* AC_LIBOBJ vs LIBOBJS:: LIBOBJS is a forbidden token 17454* AC_FOO_IFELSE vs AC_TRY_FOO:: A more generic scheme for testing sources 17455@end menu 17456 17457@node Changed Quotation 17458@subsection Changed Quotation 17459 17460The most important changes are invisible to you: the implementation of 17461most macros have completely changed. This allowed more factorization of 17462the code, better error messages, a higher uniformity of the user's 17463interface etc. Unfortunately, as a side effect, some construct which 17464used to (miraculously) work might break starting with Autoconf 2.50. 17465The most common culprit is bad quotation. 17466 17467For instance, in the following example, the message is not properly 17468quoted: 17469 17470@example 17471AC_INIT 17472AC_CHECK_HEADERS(foo.h, , 17473 AC_MSG_ERROR(cannot find foo.h, bailing out)) 17474AC_OUTPUT 17475@end example 17476 17477@noindent 17478Autoconf 2.13 simply ignores it: 17479 17480@example 17481$ @kbd{autoconf-2.13; ./configure --silent} 17482creating cache ./config.cache 17483configure: error: cannot find foo.h 17484$ 17485@end example 17486 17487@noindent 17488while Autoconf 2.50 produces a broken @file{configure}: 17489 17490@example 17491$ @kbd{autoconf-2.50; ./configure --silent} 17492configure: error: cannot find foo.h 17493./configure: exit: bad non-numeric arg `bailing' 17494./configure: exit: bad non-numeric arg `bailing' 17495$ 17496@end example 17497 17498The message needs to be quoted, and the @code{AC_MSG_ERROR} invocation 17499too! 17500 17501@example 17502AC_INIT([Example], [1.0], [bug-example@@example.org]) 17503AC_CHECK_HEADERS([foo.h], [], 17504 [AC_MSG_ERROR([cannot find foo.h, bailing out])]) 17505AC_OUTPUT 17506@end example 17507 17508Many many (and many more) Autoconf macros were lacking proper quotation, 17509including no less than@dots{} @code{AC_DEFUN} itself! 17510 17511@example 17512$ @kbd{cat configure.in} 17513AC_DEFUN([AC_PROG_INSTALL], 17514[# My own much better version 17515]) 17516AC_INIT 17517AC_PROG_INSTALL 17518AC_OUTPUT 17519$ @kbd{autoconf-2.13} 17520autoconf: Undefined macros: 17521***BUG in Autoconf--please report*** AC_FD_MSG 17522***BUG in Autoconf--please report*** AC_EPI 17523configure.in:1:AC_DEFUN([AC_PROG_INSTALL], 17524configure.in:5:AC_PROG_INSTALL 17525$ @kbd{autoconf-2.50} 17526$ 17527@end example 17528 17529 17530@node New Macros 17531@subsection New Macros 17532 17533@cindex undefined macro 17534@cindex @code{_m4_divert_diversion} 17535 17536While Autoconf was relatively dormant in the late 1990s, Automake 17537provided Autoconf-like macros for a while. Starting with Autoconf 2.50 17538in 2001, Autoconf provided 17539versions of these macros, integrated in the @code{AC_} namespace, 17540instead of @code{AM_}. But in order to ease the upgrading via 17541@command{autoupdate}, bindings to such @code{AM_} macros are provided. 17542 17543Unfortunately older versions of Automake (e.g., Automake 1.4) 17544did not quote the names of these macros. 17545Therefore, when @command{m4} finds something like 17546@samp{AC_DEFUN(AM_TYPE_PTRDIFF_T, @dots{})} in @file{aclocal.m4}, 17547@code{AM_TYPE_PTRDIFF_T} is 17548expanded, replaced with its Autoconf definition. 17549 17550Fortunately Autoconf catches pre-@code{AC_INIT} expansions, and 17551complains, in its own words: 17552 17553@example 17554$ @kbd{cat configure.ac} 17555AC_INIT([Example], [1.0], [bug-example@@example.org]) 17556AM_TYPE_PTRDIFF_T 17557$ @kbd{aclocal-1.4} 17558$ @kbd{autoconf} 17559aclocal.m4:17: error: m4_defn: undefined macro: _m4_divert_diversion 17560aclocal.m4:17: the top level 17561autom4te: m4 failed with exit status: 1 17562$ 17563@end example 17564 17565Modern versions of Automake no longer define most of these 17566macros, and properly quote the names of the remaining macros. 17567If you must use an old Automake, do not depend upon macros from Automake 17568as it is simply not its job 17569to provide macros (but the one it requires itself): 17570 17571@example 17572$ @kbd{cat configure.ac} 17573AC_INIT([Example], [1.0], [bug-example@@example.org]) 17574AM_TYPE_PTRDIFF_T 17575$ @kbd{rm aclocal.m4} 17576$ @kbd{autoupdate} 17577autoupdate: `configure.ac' is updated 17578$ @kbd{cat configure.ac} 17579AC_INIT([Example], [1.0], [bug-example@@example.org]) 17580AC_CHECK_TYPES([ptrdiff_t]) 17581$ @kbd{aclocal-1.4} 17582$ @kbd{autoconf} 17583$ 17584@end example 17585 17586 17587@node Hosts and Cross-Compilation 17588@subsection Hosts and Cross-Compilation 17589@cindex Cross compilation 17590 17591Based on the experience of compiler writers, and after long public 17592debates, many aspects of the cross-compilation chain have changed: 17593 17594@itemize @minus 17595@item 17596the relationship between the build, host, and target architecture types, 17597 17598@item 17599the command line interface for specifying them to @command{configure}, 17600 17601@item 17602the variables defined in @command{configure}, 17603 17604@item 17605the enabling of cross-compilation mode. 17606@end itemize 17607 17608@sp 1 17609 17610The relationship between build, host, and target have been cleaned up: 17611the chain of default is now simply: target defaults to host, host to 17612build, and build to the result of @command{config.guess}. Nevertheless, 17613in order to ease the transition from 2.13 to 2.50, the following 17614transition scheme is implemented. @emph{Do not rely on it}, as it will 17615be completely disabled in a couple of releases (we cannot keep it, as it 17616proves to cause more problems than it cures). 17617 17618They all default to the result of running @command{config.guess}, unless 17619you specify either @option{--build} or @option{--host}. In this case, 17620the default becomes the system type you specified. If you specify both, 17621and they're different, @command{configure} enters cross compilation 17622mode, so it doesn't run any tests that require execution. 17623 17624Hint: if you mean to override the result of @command{config.guess}, 17625prefer @option{--build} over @option{--host}. In the future, 17626@option{--host} will not override the name of the build system type. 17627Whenever you specify @option{--host}, be sure to specify @option{--build} 17628too. 17629 17630@sp 1 17631 17632For backward compatibility, @command{configure} accepts a system 17633type as an option by itself. Such an option overrides the 17634defaults for build, host, and target system types. The following 17635configure statement configures a cross toolchain that runs on 17636Net@acronym{BSD}/alpha but generates code for @acronym{GNU} Hurd/sparc, 17637which is also the build platform. 17638 17639@example 17640./configure --host=alpha-netbsd sparc-gnu 17641@end example 17642 17643@sp 1 17644 17645In Autoconf 2.13 and before, the variables @code{build}, @code{host}, 17646and @code{target} had a different semantics before and after the 17647invocation of @code{AC_CANONICAL_BUILD} etc. Now, the argument of 17648@option{--build} is strictly copied into @code{build_alias}, and is left 17649empty otherwise. After the @code{AC_CANONICAL_BUILD}, @code{build} is 17650set to the canonicalized build type. To ease the transition, before, 17651its contents is the same as that of @code{build_alias}. Do @emph{not} 17652rely on this broken feature. 17653 17654For consistency with the backward compatibility scheme exposed above, 17655when @option{--host} is specified but @option{--build} isn't, the build 17656system is assumed to be the same as @option{--host}, and 17657@samp{build_alias} is set to that value. Eventually, this 17658historically incorrect behavior will go away. 17659 17660@sp 1 17661 17662The former scheme to enable cross-compilation proved to cause more harm 17663than good, in particular, it used to be triggered too easily, leaving 17664regular end users puzzled in front of cryptic error messages. 17665@command{configure} could even enter cross-compilation mode only 17666because the compiler was not functional. This is mainly because 17667@command{configure} used to try to detect cross-compilation, instead of 17668waiting for an explicit flag from the user. 17669 17670Now, @command{configure} enters cross-compilation mode if and only if 17671@option{--host} is passed. 17672 17673That's the short documentation. To ease the transition between 2.13 and 17674its successors, a more complicated scheme is implemented. @emph{Do not 17675rely on the following}, as it will be removed in the near future. 17676 17677If you specify @option{--host}, but not @option{--build}, when 17678@command{configure} performs the first compiler test it tries to run 17679an executable produced by the compiler. If the execution fails, it 17680enters cross-compilation mode. This is fragile. Moreover, by the time 17681the compiler test is performed, it may be too late to modify the 17682build-system type: other tests may have already been performed. 17683Therefore, whenever you specify @option{--host}, be sure to specify 17684@option{--build} too. 17685 17686@example 17687./configure --build=i686-pc-linux-gnu --host=m68k-coff 17688@end example 17689 17690@noindent 17691enters cross-compilation mode. The former interface, which 17692consisted in setting the compiler to a cross-compiler without informing 17693@command{configure} is obsolete. For instance, @command{configure} 17694fails if it can't run the code generated by the specified compiler if you 17695configure as follows: 17696 17697@example 17698./configure CC=m68k-coff-gcc 17699@end example 17700 17701 17702@node AC_LIBOBJ vs LIBOBJS 17703@subsection @code{AC_LIBOBJ} vs.@: @code{LIBOBJS} 17704 17705Up to Autoconf 2.13, the replacement of functions was triggered via the 17706variable @code{LIBOBJS}. Since Autoconf 2.50, the macro 17707@code{AC_LIBOBJ} should be used instead (@pxref{Generic Functions}). 17708Starting at Autoconf 2.53, the use of @code{LIBOBJS} is an error. 17709 17710This change is mandated by the unification of the @acronym{GNU} Build System 17711components. In particular, the various fragile techniques used to parse 17712a @file{configure.ac} are all replaced with the use of traces. As a 17713consequence, any action must be traceable, which obsoletes critical 17714variable assignments. Fortunately, @code{LIBOBJS} was the only problem, 17715and it can even be handled gracefully (read, ``without your having to 17716change something''). 17717 17718There were two typical uses of @code{LIBOBJS}: asking for a replacement 17719function, and adjusting @code{LIBOBJS} for Automake and/or Libtool. 17720 17721@sp 1 17722 17723As for function replacement, the fix is immediate: use 17724@code{AC_LIBOBJ}. For instance: 17725 17726@example 17727LIBOBJS="$LIBOBJS fnmatch.o" 17728LIBOBJS="$LIBOBJS malloc.$ac_objext" 17729@end example 17730 17731@noindent 17732should be replaced with: 17733 17734@example 17735AC_LIBOBJ([fnmatch]) 17736AC_LIBOBJ([malloc]) 17737@end example 17738 17739@sp 1 17740 17741@ovindex LIBOBJDIR 17742When used with Automake 1.10 or newer, a suitable value for 17743@code{LIBOBJDIR} is set so that the @code{LIBOBJS} and @code{LTLIBOBJS} 17744can be referenced from any @file{Makefile.am}. Even without Automake, 17745arranging for @code{LIBOBJDIR} to be set correctly enables 17746referencing @code{LIBOBJS} and @code{LTLIBOBJS} in another directory. 17747The @code{LIBOJBDIR} feature is experimental. 17748 17749 17750@node AC_FOO_IFELSE vs AC_TRY_FOO 17751@subsection @code{AC_FOO_IFELSE} vs.@: @code{AC_TRY_FOO} 17752 17753Since Autoconf 2.50, internal codes uses @code{AC_PREPROC_IFELSE}, 17754@code{AC_COMPILE_IFELSE}, @code{AC_LINK_IFELSE}, and 17755@code{AC_RUN_IFELSE} on one hand and @code{AC_LANG_SOURCES}, 17756and @code{AC_LANG_PROGRAM} on the other hand instead of the deprecated 17757@code{AC_TRY_CPP}, @code{AC_TRY_COMPILE}, @code{AC_TRY_LINK}, and 17758@code{AC_TRY_RUN}. The motivations where: 17759@itemize @minus 17760@item 17761a more consistent interface: @code{AC_TRY_COMPILE} etc.@: were double 17762quoting their arguments; 17763 17764@item 17765the combinatoric explosion is solved by decomposing on the one hand the 17766generation of sources, and on the other hand executing the program; 17767 17768@item 17769this scheme helps supporting more languages than plain C and C++. 17770@end itemize 17771 17772In addition to the change of syntax, the philosophy has changed too: 17773while emphasis was put on speed at the expense of accuracy, today's 17774Autoconf promotes accuracy of the testing framework at, ahem@dots{}, the 17775expense of speed. 17776 17777 17778As a perfect example of what is @emph{not} to be done, here is how to 17779find out whether a header file contains a particular declaration, such 17780as a typedef, a structure, a structure member, or a function. Use 17781@code{AC_EGREP_HEADER} instead of running @code{grep} directly on the 17782header file; on some systems the symbol might be defined in another 17783header file that the file you are checking includes. 17784 17785As a (bad) example, here is how you should not check for C preprocessor 17786symbols, either defined by header files or predefined by the C 17787preprocessor: using @code{AC_EGREP_CPP}: 17788 17789@example 17790@group 17791AC_EGREP_CPP(yes, 17792[#ifdef _AIX 17793 yes 17794#endif 17795], is_aix=yes, is_aix=no) 17796@end group 17797@end example 17798 17799The above example, properly written would (i) use 17800@code{AC_LANG_PROGRAM}, and (ii) run the compiler: 17801 17802@example 17803@group 17804AC_COMPILE_IFELSE([AC_LANG_PROGRAM( 17805[[#ifndef _AIX 17806 error: This isn't AIX! 17807#endif 17808]])], 17809 [is_aix=yes], 17810 [is_aix=no]) 17811@end group 17812@end example 17813 17814 17815@c ============================= Generating Test Suites with Autotest 17816 17817@node Using Autotest 17818@chapter Generating Test Suites with Autotest 17819 17820@cindex Autotest 17821 17822@display 17823@strong{N.B.: This section describes an experimental feature which will 17824be part of Autoconf in a forthcoming release. Although we believe 17825Autotest is stabilizing, this documentation describes an interface which 17826might change in the future: do not depend upon Autotest without 17827subscribing to the Autoconf mailing lists.} 17828@end display 17829 17830It is paradoxical that portable projects depend on nonportable tools 17831to run their test suite. Autoconf by itself is the paragon of this 17832problem: although it aims at perfectly portability, up to 2.13 its 17833test suite was using Deja@acronym{GNU}, a rich and complex testing 17834framework, but which is far from being standard on Posix systems. 17835Worse yet, it was likely to be missing on the most fragile platforms, 17836the very platforms that are most likely to torture Autoconf and 17837exhibit deficiencies. 17838 17839To circumvent this problem, many package maintainers have developed their 17840own testing framework, based on simple shell scripts whose sole outputs 17841are exit status values describing whether the test succeeded. Most of 17842these tests share common patterns, and this can result in lots of 17843duplicated code and tedious maintenance. 17844 17845Following exactly the same reasoning that yielded to the inception of 17846Autoconf, Autotest provides a test suite generation framework, based on 17847M4 macros building a portable shell script. The suite itself is 17848equipped with automatic logging and tracing facilities which greatly 17849diminish the interaction with bug reporters, and simple timing reports. 17850 17851Autoconf itself has been using Autotest for years, and we do attest that 17852it has considerably improved the strength of the test suite and the 17853quality of bug reports. Other projects are known to use some generation 17854of Autotest, such as Bison, Free Recode, Free Wdiff, @acronym{GNU} Tar, each of 17855them with different needs, and this usage has validated Autotest as a general 17856testing framework. 17857 17858Nonetheless, compared to Deja@acronym{GNU}, Autotest is inadequate for 17859interactive tool testing, which is probably its main limitation. 17860 17861@menu 17862* Using an Autotest Test Suite:: Autotest and the user 17863* Writing testsuite.at:: Autotest macros 17864* testsuite Invocation:: Running @command{testsuite} scripts 17865* Making testsuite Scripts:: Using autom4te to create @command{testsuite} 17866@end menu 17867 17868@node Using an Autotest Test Suite 17869@section Using an Autotest Test Suite 17870 17871@menu 17872* testsuite Scripts:: The concepts of Autotest 17873* Autotest Logs:: Their contents 17874@end menu 17875 17876@node testsuite Scripts 17877@subsection @command{testsuite} Scripts 17878 17879@cindex @command{testsuite} 17880 17881Generating testing or validation suites using Autotest is rather easy. 17882The whole validation suite is held in a file to be processed through 17883@command{autom4te}, itself using @acronym{GNU} M4 under the scene, to 17884produce a stand-alone Bourne shell script which then gets distributed. 17885Neither @command{autom4te} nor @acronym{GNU} M4 are needed at 17886the installer's end. 17887 17888@cindex test group 17889Each test of the validation suite should be part of some test group. A 17890@dfn{test group} is a sequence of interwoven tests that ought to be 17891executed together, usually because one test in the group creates data 17892files than a later test in the same group needs to read. Complex test 17893groups make later debugging more tedious. It is much better to 17894keep only a few tests per test group. Ideally there is only one test 17895per test group. 17896 17897For all but the simplest packages, some file such as @file{testsuite.at} 17898does not fully hold all test sources, as these are often easier to 17899maintain in separate files. Each of these separate files holds a single 17900test group, or a sequence of test groups all addressing some common 17901functionality in the package. In such cases, @file{testsuite.at} 17902merely initializes the validation suite, and sometimes does elementary 17903health checking, before listing include statements for all other test 17904files. The special file @file{package.m4}, containing the 17905identification of the package, is automatically included if found. 17906 17907A convenient alternative consists in moving all the global issues 17908(local Autotest macros, elementary health checking, and @code{AT_INIT} 17909invocation) into the file @code{local.at}, and making 17910@file{testsuite.at} be a simple list of @code{m4_include} of sub test 17911suites. In such case, generating the whole test suite or pieces of it 17912is only a matter of choosing the @command{autom4te} command line 17913arguments. 17914 17915The validation scripts that Autotest produces are by convention called 17916@command{testsuite}. When run, @command{testsuite} executes each test 17917group in turn, producing only one summary line per test to say if that 17918particular test succeeded or failed. At end of all tests, summarizing 17919counters get printed. One debugging directory is left for each test 17920group which failed, if any: such directories are named 17921@file{testsuite.dir/@var{nn}}, where @var{nn} is the sequence number of 17922the test group, and they include: 17923 17924@itemize @bullet 17925@item a debugging script named @file{run} which reruns the test in 17926@dfn{debug mode} (@pxref{testsuite Invocation}). The automatic generation 17927of debugging scripts has the purpose of easing the chase for bugs. 17928 17929@item all the files created with @code{AT_DATA} 17930 17931@item a log of the run, named @file{testsuite.log} 17932@end itemize 17933 17934In the ideal situation, none of the tests fail, and consequently no 17935debugging directory is left behind for validation. 17936 17937It often happens in practice that individual tests in the validation 17938suite need to get information coming out of the configuration process. 17939Some of this information, common for all validation suites, is provided 17940through the file @file{atconfig}, automatically created by 17941@code{AC_CONFIG_TESTDIR}. For configuration informations which your 17942testing environment specifically needs, you might prepare an optional 17943file named @file{atlocal.in}, instantiated by @code{AC_CONFIG_FILES}. 17944The configuration process produces @file{atconfig} and @file{atlocal} 17945out of these two input files, and these two produced files are 17946automatically read by the @file{testsuite} script. 17947 17948Here is a diagram showing the relationship between files. 17949 17950@noindent 17951Files used in preparing a software package for distribution: 17952 17953@example 17954 [package.m4] -->. 17955 \ 17956subfile-1.at ->. [local.at] ---->+ 17957 ... \ \ 17958subfile-i.at ---->-- testsuite.at -->-- autom4te* -->testsuite 17959 ... / 17960subfile-n.at ->' 17961@end example 17962 17963@noindent 17964Files used in configuring a software package: 17965 17966@example 17967 .--> atconfig 17968 / 17969[atlocal.in] --> config.status* --< 17970 \ 17971 `--> [atlocal] 17972@end example 17973 17974@noindent 17975Files created during the test suite execution: 17976 17977@example 17978atconfig -->. .--> testsuite.log 17979 \ / 17980 >-- testsuite* --< 17981 / \ 17982[atlocal] ->' `--> [testsuite.dir] 17983@end example 17984 17985 17986@node Autotest Logs 17987@subsection Autotest Logs 17988 17989When run, the test suite creates a log file named after itself, e.g., a 17990test suite named @command{testsuite} creates @file{testsuite.log}. It 17991contains a lot of information, usually more than maintainers actually 17992need, but therefore most of the time it contains all that is needed: 17993 17994@table @asis 17995@item command line arguments 17996@c akim s/to consist in/to consist of/ 17997A bad but unfortunately widespread habit consists of 17998setting environment variables before the command, such as in 17999@samp{CC=my-home-grown-cc ./testsuite}. The test suite does not 18000know this change, hence (i) it cannot report it to you, and (ii) 18001it cannot preserve the value of @code{CC} for subsequent runs. 18002Autoconf faced exactly the same problem, and solved it by asking 18003users to pass the variable definitions as command line arguments. 18004Autotest requires this rule, too, but has no means to enforce it; the log 18005then contains a trace of the variables that were changed by the user. 18006 18007@item @file{ChangeLog} excerpts 18008The topmost lines of all the @file{ChangeLog} files found in the source 18009hierarchy. This is especially useful when bugs are reported against 18010development versions of the package, since the version string does not 18011provide sufficient information to know the exact state of the sources 18012the user compiled. Of course, this relies on the use of a 18013@file{ChangeLog}. 18014 18015@item build machine 18016Running a test suite in a cross-compile environment is not an easy task, 18017since it would mean having the test suite run on a machine @var{build}, 18018while running programs on a machine @var{host}. It is much simpler to 18019run both the test suite and the programs on @var{host}, but then, from 18020the point of view of the test suite, there remains a single environment, 18021@var{host} = @var{build}. The log contains relevant information on the 18022state of the build machine, including some important environment 18023variables. 18024@c FIXME: How about having an M4sh macro to say `hey, log the value 18025@c of `@dots{}'? This would help both Autoconf and Autotest. 18026 18027@item tested programs 18028The absolute file name and answers to @option{--version} of the tested 18029programs (see @ref{Writing testsuite.at}, @code{AT_TESTED}). 18030 18031@item configuration log 18032The contents of @file{config.log}, as created by @command{configure}, 18033are appended. It contains the configuration flags and a detailed report 18034on the configuration itself. 18035@end table 18036 18037 18038@node Writing testsuite.at 18039@section Writing @file{testsuite.at} 18040 18041The @file{testsuite.at} is a Bourne shell script making use of special 18042Autotest M4 macros. It often contains a call to @code{AT_INIT} near 18043its beginning followed by one call to @code{m4_include} per source file 18044for tests. Each such included file, or the remainder of 18045@file{testsuite.at} if include files are not used, contain a sequence of 18046test groups. Each test group begins with a call to @code{AT_SETUP}, 18047then an arbitrary number of shell commands or calls to @code{AT_CHECK}, 18048and then completes with a call to @code{AT_CLEANUP}. 18049 18050@defmac AT_INIT (@ovar{name}) 18051@atindex{INIT} 18052@c FIXME: Not clear, plus duplication of the information. 18053Initialize Autotest. Giving a @var{name} to the test suite is 18054encouraged if your package includes several test suites. In any case, 18055the test suite always displays the package name and version. It also 18056inherits the package bug report address. 18057@end defmac 18058 18059@defmac AT_COPYRIGHT (@var{copyright-notice}) 18060@atindex{COPYRIGHT} 18061@cindex Copyright Notice 18062State that, in addition to the Free Software Foundation's copyright on 18063the Autotest macros, parts of your test suite are covered by 18064@var{copyright-notice}. 18065 18066The @var{copyright-notice} shows up in both the head of 18067@command{testsuite} and in @samp{testsuite --version}. 18068@end defmac 18069 18070@defmac AT_TESTED (@var{executables}) 18071@atindex{TESTED} 18072Log the file name and answer to @option{--version} of each program in 18073space-separated list @var{executables}. Several invocations register 18074new executables, in other words, don't fear registering one program 18075several times. 18076@end defmac 18077 18078Autotest test suites rely on @env{PATH} to find the tested program. 18079This avoids the need to generate absolute names of the various tools, and 18080makes it possible to test installed programs. Therefore, knowing which 18081programs are being exercised is crucial to understanding problems in 18082the test suite itself, or its occasional misuses. It is a good idea to 18083also subscribe foreign programs you depend upon, to avoid incompatible 18084diagnostics. 18085 18086@sp 1 18087 18088@defmac AT_SETUP (@var{test-group-name}) 18089@atindex{SETUP} 18090This macro starts a group of related tests, all to be executed in the 18091same subshell. It accepts a single argument, which holds a few words 18092(no more than about 30 or 40 characters) quickly describing the purpose 18093of the test group being started. 18094@end defmac 18095 18096@defmac AT_KEYWORDS (@var{keywords}) 18097@atindex{KEYWORDS} 18098Associate the space-separated list of @var{keywords} to the enclosing 18099test group. This makes it possible to run ``slices'' of the test suite. 18100For instance, if some of your test groups exercise some @samp{foo} 18101feature, then using @samp{AT_KEYWORDS(foo)} lets you run 18102@samp{./testsuite -k foo} to run exclusively these test groups. The 18103@var{title} of the test group is automatically recorded to 18104@code{AT_KEYWORDS}. 18105 18106Several invocations within a test group accumulate new keywords. In 18107other words, don't fear registering the same keyword several times in a 18108test group. 18109@end defmac 18110 18111@defmac AT_CAPTURE_FILE (@var{file}) 18112@atindex{CAPTURE_FILE} 18113If the current test group fails, log the contents of @var{file}. 18114Several identical calls within one test group have no additional effect. 18115@end defmac 18116 18117@defmac AT_XFAIL_IF (@var{shell-condition}) 18118@atindex{XFAIL_IF} 18119Determine whether the test is expected to fail because it is a known 18120bug (for unsupported features, you should skip the test). 18121@var{shell-condition} is a shell expression such as a @code{test} 18122command; you can instantiate this macro many times from within the 18123same test group, and one of the conditions is enough to turn 18124the test into an expected failure. 18125@end defmac 18126 18127@defmac AT_CLEANUP 18128@atindex{CLEANUP} 18129End the current test group. 18130@end defmac 18131 18132@sp 1 18133 18134@defmac AT_DATA (@var{file}, @var{contents}) 18135@atindex{DATA} 18136Initialize an input data @var{file} with given @var{contents}. Of 18137course, the @var{contents} have to be properly quoted between square 18138brackets to protect against included commas or spurious M4 18139expansion. The contents ought to end with an end of line. 18140@end defmac 18141 18142@defmac AT_CHECK (@var{commands}, @dvar{status, 0}, @dvar{stdout, }, @dvar{stderr, }, @ovar{run-if-fail}, @ovar{run-if-pass}) 18143@atindex{CHECK} 18144Execute a test by performing given shell @var{commands}. These commands 18145should normally exit with @var{status}, while producing expected 18146@var{stdout} and @var{stderr} contents. If @var{commands} exit with 18147status 77, then the whole test group is skipped. Otherwise, if this test 18148fails, run shell commands @var{run-if-fail} or, if this test passes, run shell 18149commands @var{run-if-pass}. 18150 18151The @var{commands} @emph{must not} redirect the standard output, nor the 18152standard error. 18153 18154If @var{status}, or @var{stdout}, or @var{stderr} is @samp{ignore}, then 18155the corresponding value is not checked. 18156 18157The special value @samp{expout} for @var{stdout} means the expected 18158output of the @var{commands} is the content of the file @file{expout}. 18159If @var{stdout} is @samp{stdout}, then the standard output of the 18160@var{commands} is available for further tests in the file @file{stdout}. 18161Similarly for @var{stderr} with @samp{experr} and @samp{stderr}. 18162@end defmac 18163 18164 18165@node testsuite Invocation 18166@section Running @command{testsuite} Scripts 18167@cindex @command{testsuite} 18168 18169Autotest test suites support the following arguments: 18170 18171@table @option 18172@item --help 18173@itemx -h 18174Display the list of options and exit successfully. 18175 18176@item --version 18177@itemx -V 18178Display the version of the test suite and exit successfully. 18179 18180@item --clean 18181@itemx -c 18182Remove all the files the test suite might have created and exit. Meant 18183for @code{clean} Make targets. 18184 18185@item --list 18186@itemx -l 18187List all the tests (or only the selection), including their possible 18188keywords. 18189@end table 18190 18191@sp 1 18192 18193By default all tests are performed (or described with 18194@option{--list}) in the default environment first silently, then 18195verbosely, but the environment, set of tests, and verbosity level can be 18196tuned: 18197 18198@table @samp 18199@item @var{variable}=@var{value} 18200Set the environment @var{variable} to @var{value}. Use this rather 18201than @samp{FOO=foo ./testsuite} as debugging scripts would then run in a 18202different environment. 18203 18204@cindex @code{AUTOTEST_PATH} 18205The variable @code{AUTOTEST_PATH} specifies the testing path to prepend 18206to @env{PATH}. Relative directory names (not starting with 18207@samp{/}) are considered to be relative to the top level of the 18208package being built. All directories are made absolute, first 18209starting from the top level @emph{build} tree, then from the 18210@emph{source} tree. For instance @samp{./testsuite 18211AUTOTEST_PATH=tests:bin} for a @file{/src/foo-1.0} source package built 18212in @file{/tmp/foo} results in @samp{/tmp/foo/tests:/tmp/foo/bin} and 18213then @samp{/src/foo-1.0/tests:/src/foo-1.0/bin} being prepended to 18214@env{PATH}. 18215 18216@item @var{number} 18217@itemx @var{number}-@var{number} 18218@itemx @var{number}- 18219@itemx -@var{number} 18220Add the corresponding test groups, with obvious semantics, to the 18221selection. 18222 18223@item --keywords=@var{keywords} 18224@itemx -k @var{keywords} 18225Add to the selection the test groups with title or keywords (arguments 18226to @code{AT_SETUP} or @code{AT_KEYWORDS}) that match @emph{all} keywords 18227of the comma separated list @var{keywords}, case-insensitively. Use 18228@samp{!} immediately before the keyword to invert the selection for this 18229keyword. By default, the keywords match whole words; enclose them in 18230@samp{.*} to also match parts of words. 18231 18232For example, running 18233 18234@example 18235@kbd{./testsuite -k 'autoupdate,.*FUNC.*'} 18236@end example 18237 18238@noindent 18239selects all tests tagged @samp{autoupdate} @emph{and} with tags 18240containing @samp{FUNC} (as in @samp{AC_CHECK_FUNC}, @samp{AC_FUNC_ALLOCA}, 18241etc.), while 18242 18243@example 18244@kbd{./testsuite -k '!autoupdate' -k '.*FUNC.*'} 18245@end example 18246 18247@noindent 18248selects all tests not tagged @samp{autoupdate} @emph{or} with tags 18249containing @samp{FUNC}. 18250 18251@item --errexit 18252@itemx -e 18253If any test fails, immediately abort testing. It implies 18254@option{--debug}: post test group clean up, and top-level logging 18255are inhibited. This option is meant for the full test 18256suite, it is not really useful for generated debugging scripts. 18257 18258@item --verbose 18259@itemx -v 18260Force more verbosity in the detailed output of what is being done. This 18261is the default for debugging scripts. 18262 18263@item --debug 18264@itemx -d 18265Do not remove the files after a test group was performed ---but they are 18266still removed @emph{before}, therefore using this option is sane when 18267running several test groups. Create debugging scripts. Do not 18268overwrite the top-level 18269log (in order to preserve supposedly existing full log file). This is 18270the default for debugging scripts, but it can also be useful to debug 18271the testsuite itself. 18272 18273@item --trace 18274@itemx -x 18275Trigger shell tracing of the test groups. 18276@end table 18277 18278 18279@node Making testsuite Scripts 18280@section Making @command{testsuite} Scripts 18281 18282For putting Autotest into movement, you need some configuration and 18283makefile machinery. We recommend, at least if your package uses deep or 18284shallow hierarchies, that you use @file{tests/} as the name of the 18285directory holding all your tests and their makefile. Here is a 18286check list of things to do. 18287 18288@itemize @minus 18289 18290@item 18291@cindex @file{package.m4} 18292Make sure to create the file @file{package.m4}, which defines the 18293identity of the package. It must define @code{AT_PACKAGE_STRING}, the 18294full signature of the package, and @code{AT_PACKAGE_BUGREPORT}, the 18295address to which bug reports should be sent. For sake of completeness, 18296we suggest that you also define @code{AT_PACKAGE_NAME}, 18297@code{AT_PACKAGE_TARNAME}, and @code{AT_PACKAGE_VERSION}. 18298@xref{Initializing configure}, for a description of these variables. We 18299suggest the following makefile excerpt: 18300 18301@smallexample 18302$(srcdir)/package.m4: $(top_srcdir)/configure.ac 18303 @{ \ 18304 echo '# Signature of the current package.'; \ 18305 echo 'm4_define([AT_PACKAGE_NAME], [@@PACKAGE_NAME@@])'; \ 18306 echo 'm4_define([AT_PACKAGE_TARNAME], [@@PACKAGE_TARNAME@@])'; \ 18307 echo 'm4_define([AT_PACKAGE_VERSION], [@@PACKAGE_VERSION@@])'; \ 18308 echo 'm4_define([AT_PACKAGE_STRING], [@@PACKAGE_STRING@@])'; \ 18309 echo 'm4_define([AT_PACKAGE_BUGREPORT], [@@PACKAGE_BUGREPORT@@])'; \ 18310 @} >'$(srcdir)/package.m4' 18311@end smallexample 18312 18313@noindent 18314Be sure to distribute @file{package.m4} and to put it into the source 18315hierarchy: the test suite ought to be shipped! 18316 18317@item 18318Invoke @code{AC_CONFIG_TESTDIR}. 18319 18320@defmac AC_CONFIG_TESTDIR (@var{directory}, @dvar{test-path, directory}) 18321@acindex{CONFIG_TESTDIR} 18322An Autotest test suite is to be configured in @var{directory}. This 18323macro requires the instantiation of @file{@var{directory}/atconfig} from 18324@file{@var{directory}/atconfig.in}, and sets the default 18325@code{AUTOTEST_PATH} to @var{test-path} (@pxref{testsuite Invocation}). 18326@end defmac 18327 18328@item 18329Still within @file{configure.ac}, as appropriate, ensure that some 18330@code{AC_CONFIG_FILES} command includes substitution for 18331@file{tests/atlocal}. 18332 18333@item 18334The @file{tests/Makefile.in} should be modified so the validation in 18335your package is triggered by @samp{make check}. An example is provided 18336below. 18337@end itemize 18338 18339With Automake, here is a minimal example about how to link @samp{make 18340check} with a validation suite. 18341 18342@example 18343EXTRA_DIST = testsuite.at $(TESTSUITE) atlocal.in 18344TESTSUITE = $(srcdir)/testsuite 18345 18346check-local: atconfig atlocal $(TESTSUITE) 18347 $(SHELL) '$(TESTSUITE)' $(TESTSUITEFLAGS) 18348 18349installcheck-local: atconfig atlocal $(TESTSUITE) 18350 $(SHELL) '$(TESTSUITE)' AUTOTEST_PATH='$(bindir)' \ 18351 $(TESTSUITEFLAGS) 18352 18353clean-local: 18354 test ! -f '$(TESTSUITE)' || \ 18355 $(SHELL) '$(TESTSUITE)' --clean 18356 18357AUTOTEST = $(AUTOM4TE) --language=autotest 18358$(TESTSUITE): $(srcdir)/testsuite.at 18359 $(AUTOTEST) -I '$(srcdir)' -o $@@.tmp $@@.at 18360 mv $@@.tmp $@@ 18361@end example 18362 18363You might want to list explicitly the dependencies, i.e., the list of 18364the files @file{testsuite.at} includes. 18365 18366With strict Autoconf, you might need to add lines inspired from the 18367following: 18368 18369@example 18370subdir = tests 18371 18372atconfig: $(top_builddir)/config.status 18373 cd $(top_builddir) && \ 18374 $(SHELL) ./config.status $(subdir)/$@@ 18375 18376atlocal: $(srcdir)/atlocal.in $(top_builddir)/config.status 18377 cd $(top_builddir) && \ 18378 $(SHELL) ./config.status $(subdir)/$@@ 18379@end example 18380 18381@noindent 18382and manage to have @file{atconfig.in} and @code{$(EXTRA_DIST)} 18383distributed. 18384 18385With all this in place, and if you have not initialized @samp{TESTSUITEFLAGS} 18386within your makefile, you can fine-tune test suite execution with this variable, 18387for example: 18388 18389@example 18390make check TESTSUITEFLAGS='-v -d -x 75 -k AC_PROG_CC CFLAGS=-g' 18391@end example 18392 18393 18394 18395@c =============================== Frequent Autoconf Questions, with answers 18396 18397@node FAQ 18398@chapter Frequent Autoconf Questions, with answers 18399 18400Several questions about Autoconf come up occasionally. Here some of them 18401are addressed. 18402 18403@menu 18404* Distributing:: Distributing @command{configure} scripts 18405* Why GNU M4:: Why not use the standard M4? 18406* Bootstrapping:: Autoconf and @acronym{GNU} M4 require each other? 18407* Why Not Imake:: Why @acronym{GNU} uses @command{configure} instead of Imake 18408* Defining Directories:: Passing @code{datadir} to program 18409* autom4te.cache:: What is it? Can I remove it? 18410* Present But Cannot Be Compiled:: Compiler and Preprocessor Disagree 18411@end menu 18412 18413@node Distributing 18414@section Distributing @command{configure} Scripts 18415@cindex License 18416 18417@display 18418What are the restrictions on distributing @command{configure} 18419scripts that Autoconf generates? How does that affect my 18420programs that use them? 18421@end display 18422 18423There are no restrictions on how the configuration scripts that Autoconf 18424produces may be distributed or used. In Autoconf version 1, they were 18425covered by the @acronym{GNU} General Public License. We still encourage 18426software authors to distribute their work under terms like those of the 18427@acronym{GPL}, but doing so is not required to use Autoconf. 18428 18429Of the other files that might be used with @command{configure}, 18430@file{config.h.in} is under whatever copyright you use for your 18431@file{configure.ac}. @file{config.sub} and @file{config.guess} have an 18432exception to the @acronym{GPL} when they are used with an Autoconf-generated 18433@command{configure} script, which permits you to distribute them under the 18434same terms as the rest of your package. @file{install-sh} is from the X 18435Consortium and is not copyrighted. 18436 18437@node Why GNU M4 18438@section Why Require @acronym{GNU} M4? 18439 18440@display 18441Why does Autoconf require @acronym{GNU} M4? 18442@end display 18443 18444Many M4 implementations have hard-coded limitations on the size and 18445number of macros that Autoconf exceeds. They also lack several 18446builtin macros that it would be difficult to get along without in a 18447sophisticated application like Autoconf, including: 18448 18449@example 18450m4_builtin 18451m4_indir 18452m4_bpatsubst 18453__file__ 18454__line__ 18455@end example 18456 18457Autoconf requires version 1.4.7 or later of @acronym{GNU} M4. 18458 18459Since only software maintainers need to use Autoconf, and since @acronym{GNU} 18460M4 is simple to configure and install, it seems reasonable to require 18461@acronym{GNU} M4 to be installed also. Many maintainers of @acronym{GNU} and 18462other free software already have most of the @acronym{GNU} utilities 18463installed, since they prefer them. 18464 18465@node Bootstrapping 18466@section How Can I Bootstrap? 18467@cindex Bootstrap 18468 18469@display 18470If Autoconf requires @acronym{GNU} M4 and @acronym{GNU} M4 has an Autoconf 18471@command{configure} script, how do I bootstrap? It seems like a chicken 18472and egg problem! 18473@end display 18474 18475This is a misunderstanding. Although @acronym{GNU} M4 does come with a 18476@command{configure} script produced by Autoconf, Autoconf is not required 18477in order to run the script and install @acronym{GNU} M4. Autoconf is only 18478required if you want to change the M4 @command{configure} script, which few 18479people have to do (mainly its maintainer). 18480 18481@node Why Not Imake 18482@section Why Not Imake? 18483@cindex Imake 18484 18485@display 18486Why not use Imake instead of @command{configure} scripts? 18487@end display 18488 18489Several people have written addressing this question, so I include 18490adaptations of their explanations here. 18491 18492The following answer is based on one written by Richard Pixley: 18493 18494@quotation 18495Autoconf generated scripts frequently work on machines that it has 18496never been set up to handle before. That is, it does a good job of 18497inferring a configuration for a new system. Imake cannot do this. 18498 18499Imake uses a common database of host specific data. For X11, this makes 18500sense because the distribution is made as a collection of tools, by one 18501central authority who has control over the database. 18502 18503@acronym{GNU} tools are not released this way. Each @acronym{GNU} tool has a 18504maintainer; these maintainers are scattered across the world. Using a 18505common database would be a maintenance nightmare. Autoconf may appear 18506to be this kind of database, but in fact it is not. Instead of listing 18507host dependencies, it lists program requirements. 18508 18509If you view the @acronym{GNU} suite as a collection of native tools, then the 18510problems are similar. But the @acronym{GNU} development tools can be 18511configured as cross tools in almost any host+target permutation. All of 18512these configurations can be installed concurrently. They can even be 18513configured to share host independent files across hosts. Imake doesn't 18514address these issues. 18515 18516Imake templates are a form of standardization. The @acronym{GNU} coding 18517standards address the same issues without necessarily imposing the same 18518restrictions. 18519@end quotation 18520 18521 18522Here is some further explanation, written by Per Bothner: 18523 18524@quotation 18525One of the advantages of Imake is that it easy to generate large 18526makefiles using the @samp{#include} and macro mechanisms of @command{cpp}. 18527However, @code{cpp} is not programmable: it has limited conditional 18528facilities, and no looping. And @code{cpp} cannot inspect its 18529environment. 18530 18531All of these problems are solved by using @code{sh} instead of 18532@code{cpp}. The shell is fully programmable, has macro substitution, 18533can execute (or source) other shell scripts, and can inspect its 18534environment. 18535@end quotation 18536 18537 18538Paul Eggert elaborates more: 18539 18540@quotation 18541With Autoconf, installers need not assume that Imake itself is already 18542installed and working well. This may not seem like much of an advantage 18543to people who are accustomed to Imake. But on many hosts Imake is not 18544installed or the default installation is not working well, and requiring 18545Imake to install a package hinders the acceptance of that package on 18546those hosts. For example, the Imake template and configuration files 18547might not be installed properly on a host, or the Imake build procedure 18548might wrongly assume that all source files are in one big directory 18549tree, or the Imake configuration might assume one compiler whereas the 18550package or the installer needs to use another, or there might be a 18551version mismatch between the Imake expected by the package and the Imake 18552supported by the host. These problems are much rarer with Autoconf, 18553where each package comes with its own independent configuration 18554processor. 18555 18556Also, Imake often suffers from unexpected interactions between 18557@command{make} and the installer's C preprocessor. The fundamental problem 18558here is that the C preprocessor was designed to preprocess C programs, 18559not makefiles. This is much less of a problem with Autoconf, 18560which uses the general-purpose preprocessor M4, and where the 18561package's author (rather than the installer) does the preprocessing in a 18562standard way. 18563@end quotation 18564 18565 18566Finally, Mark Eichin notes: 18567 18568@quotation 18569Imake isn't all that extensible, either. In order to add new features to 18570Imake, you need to provide your own project template, and duplicate most 18571of the features of the existing one. This means that for a sophisticated 18572project, using the vendor-provided Imake templates fails to provide any 18573leverage---since they don't cover anything that your own project needs 18574(unless it is an X11 program). 18575 18576On the other side, though: 18577 18578The one advantage that Imake has over @command{configure}: 18579@file{Imakefile} files tend to be much shorter (likewise, less redundant) 18580than @file{Makefile.in} files. There is a fix to this, however---at least 18581for the Kerberos V5 tree, we've modified things to call in common 18582@file{post.in} and @file{pre.in} makefile fragments for the 18583entire tree. This means that a lot of common things don't have to be 18584duplicated, even though they normally are in @command{configure} setups. 18585@end quotation 18586 18587 18588@node Defining Directories 18589@section How Do I @code{#define} Installation Directories? 18590 18591@display 18592My program needs library files, installed in @code{datadir} and 18593similar. If I use 18594 18595@example 18596AC_DEFINE_UNQUOTED([DATADIR], [$datadir], 18597 [Define to the read-only architecture-independent 18598 data directory.]) 18599@end example 18600 18601@noindent 18602I get 18603 18604@example 18605#define DATADIR "$@{prefix@}/share" 18606@end example 18607@end display 18608 18609As already explained, this behavior is on purpose, mandated by the 18610@acronym{GNU} Coding Standards, see @ref{Installation Directory 18611Variables}. There are several means to achieve a similar goal: 18612 18613@itemize @minus 18614@item 18615Do not use @code{AC_DEFINE} but use your makefile to pass the 18616actual value of @code{datadir} via compilation flags. 18617@xref{Installation Directory Variables}, for the details. 18618 18619@item 18620This solution can be simplified when compiling a program: you may either 18621extend the @code{CPPFLAGS}: 18622 18623@example 18624CPPFLAGS = -DDATADIR='"$(datadir)"' @@CPPFLAGS@@ 18625@end example 18626 18627@noindent 18628or create a dedicated header file: 18629 18630@example 18631DISTCLEANFILES = datadir.h 18632datadir.h: Makefile 18633 echo '#define DATADIR "$(datadir)"' >$@@ 18634@end example 18635 18636@item 18637Use @code{AC_DEFINE} but have @command{configure} compute the literal 18638value of @code{datadir} and others. Many people have wrapped macros to 18639automate this task. For instance, the macro @code{AC_DEFINE_DIR} from 18640the @uref{http://autoconf-archive.cryp.to/, Autoconf Macro 18641Archive}. 18642 18643This solution does not conform to the @acronym{GNU} Coding Standards. 18644 18645@item 18646Note that all the previous solutions hard wire the absolute name of 18647these directories in the executables, which is not a good property. You 18648may try to compute the names relative to @code{prefix}, and try to 18649find @code{prefix} at runtime, this way your package is relocatable. 18650Some macros are already available to address this issue: see 18651@code{adl_COMPUTE_RELATIVE_PATHS} and 18652@code{adl_COMPUTE_STANDARD_RELATIVE_PATHS} on the 18653@uref{http://autoconf-archive.cryp.to/, 18654Autoconf Macro Archive}. 18655@end itemize 18656 18657 18658@node autom4te.cache 18659@section What is @file{autom4te.cache}? 18660 18661@display 18662What is this directory @file{autom4te.cache}? Can I safely remove it? 18663@end display 18664 18665In the @acronym{GNU} Build System, @file{configure.ac} plays a central 18666role and is read by many tools: @command{autoconf} to create 18667@file{configure}, @command{autoheader} to create @file{config.h.in}, 18668@command{automake} to create @file{Makefile.in}, @command{autoscan} to 18669check the completeness of @file{configure.ac}, @command{autoreconf} to 18670check the @acronym{GNU} Build System components that are used. To 18671``read @file{configure.ac}'' actually means to compile it with M4, 18672which can be a long process for complex @file{configure.ac}. 18673 18674This is why all these tools, instead of running directly M4, invoke 18675@command{autom4te} (@pxref{autom4te Invocation}) which, while answering to 18676a specific demand, stores additional information in 18677@file{autom4te.cache} for future runs. For instance, if you run 18678@command{autoconf}, behind the scenes, @command{autom4te} also 18679stores information for the other tools, so that when you invoke 18680@command{autoheader} or @command{automake} etc., reprocessing 18681@file{configure.ac} is not needed. The speed up is frequently of 30%, 18682and is increasing with the size of @file{configure.ac}. 18683 18684But it is and remains being simply a cache: you can safely remove it. 18685 18686@sp 1 18687 18688@display 18689Can I permanently get rid of it? 18690@end display 18691 18692The creation of this cache can be disabled from 18693@file{~/.autom4te.cfg}, see @ref{Customizing autom4te}, for more 18694details. You should be aware that disabling the cache slows down the 18695Autoconf test suite by 40%. The more @acronym{GNU} Build System 18696components are used, the more the cache is useful; for instance 18697running @samp{autoreconf -f} on the Core Utilities is twice slower without 18698the cache @emph{although @option{--force} implies that the cache is 18699not fully exploited}, and eight times slower than without 18700@option{--force}. 18701 18702 18703@node Present But Cannot Be Compiled 18704@section Header Present But Cannot Be Compiled 18705 18706The most important guideline to bear in mind when checking for 18707features is to mimic as much as possible the intended use. 18708Unfortunately, old versions of @code{AC_CHECK_HEADER} and 18709@code{AC_CHECK_HEADERS} failed to follow this idea, and called 18710the preprocessor, instead of the compiler, to check for headers. As a 18711result, incompatibilities between headers went unnoticed during 18712configuration, and maintainers finally had to deal with this issue 18713elsewhere. 18714 18715As of Autoconf 2.56 both checks are performed, and @code{configure} 18716complains loudly if the compiler and the preprocessor do not agree. 18717For the time being the result used is that of the preprocessor, to give 18718maintainers time to adjust their @file{configure.ac}, but in the 18719future, only the compiler will be considered. 18720 18721Consider the following example: 18722 18723@smallexample 18724$ @kbd{cat number.h} 18725typedef int number; 18726$ @kbd{cat pi.h} 18727const number pi = 3; 18728$ @kbd{cat configure.ac} 18729AC_INIT([Example], [1.0], [bug-example@@example.org]) 18730AC_CHECK_HEADERS([pi.h]) 18731$ @kbd{autoconf -Wall} 18732$ @kbd{./configure} 18733checking for gcc... gcc 18734checking for C compiler default output file name... a.out 18735checking whether the C compiler works... yes 18736checking whether we are cross compiling... no 18737checking for suffix of executables... 18738checking for suffix of object files... o 18739checking whether we are using the GNU C compiler... yes 18740checking whether gcc accepts -g... yes 18741checking for gcc option to accept ISO C89... none needed 18742checking how to run the C preprocessor... gcc -E 18743checking for grep that handles long lines and -e... grep 18744checking for egrep... grep -E 18745checking for ANSI C header files... yes 18746checking for sys/types.h... yes 18747checking for sys/stat.h... yes 18748checking for stdlib.h... yes 18749checking for string.h... yes 18750checking for memory.h... yes 18751checking for strings.h... yes 18752checking for inttypes.h... yes 18753checking for stdint.h... yes 18754checking for unistd.h... yes 18755checking pi.h usability... no 18756checking pi.h presence... yes 18757configure: WARNING: pi.h: present but cannot be compiled 18758configure: WARNING: pi.h: check for missing prerequisite headers? 18759configure: WARNING: pi.h: see the Autoconf documentation 18760configure: WARNING: pi.h: section "Present But Cannot Be Compiled" 18761configure: WARNING: pi.h: proceeding with the preprocessor's result 18762configure: WARNING: pi.h: in the future, the compiler will take precedence 18763configure: WARNING: ## -------------------------------------- ## 18764configure: WARNING: ## Report this to bug-example@@example.org ## 18765configure: WARNING: ## -------------------------------------- ## 18766checking for pi.h... yes 18767@end smallexample 18768 18769@noindent 18770The proper way the handle this case is using the fourth argument 18771(@pxref{Generic Headers}): 18772 18773@example 18774$ @kbd{cat configure.ac} 18775AC_INIT([Example], [1.0], [bug-example@@example.org]) 18776AC_CHECK_HEADERS([number.h pi.h], [], [], 18777[[#ifdef HAVE_NUMBER_H 18778# include <number.h> 18779#endif 18780]]) 18781$ @kbd{autoconf -Wall} 18782$ @kbd{./configure} 18783checking for gcc... gcc 18784checking for C compiler default output... a.out 18785checking whether the C compiler works... yes 18786checking whether we are cross compiling... no 18787checking for suffix of executables... 18788checking for suffix of object files... o 18789checking whether we are using the GNU C compiler... yes 18790checking whether gcc accepts -g... yes 18791checking for gcc option to accept ANSI C... none needed 18792checking for number.h... yes 18793checking for pi.h... yes 18794@end example 18795 18796See @ref{Particular Headers}, for a list of headers with their 18797prerequisite. 18798 18799@c ===================================================== History of Autoconf. 18800 18801@node History 18802@chapter History of Autoconf 18803@cindex History of autoconf 18804 18805You may be wondering, Why was Autoconf originally written? How did it 18806get into its present form? (Why does it look like gorilla spit?) If 18807you're not wondering, then this chapter contains no information useful 18808to you, and you might as well skip it. If you @emph{are} wondering, 18809then let there be light@enddots{} 18810 18811@menu 18812* Genesis:: Prehistory and naming of @command{configure} 18813* Exodus:: The plagues of M4 and Perl 18814* Leviticus:: The priestly code of portability arrives 18815* Numbers:: Growth and contributors 18816* Deuteronomy:: Approaching the promises of easy configuration 18817@end menu 18818 18819@node Genesis 18820@section Genesis 18821 18822In June 1991 I was maintaining many of the @acronym{GNU} utilities for the 18823Free Software Foundation. As they were ported to more platforms and 18824more programs were added, the number of @option{-D} options that users 18825had to select in the makefile (around 20) became burdensome. 18826Especially for me---I had to test each new release on a bunch of 18827different systems. So I wrote a little shell script to guess some of 18828the correct settings for the fileutils package, and released it as part 18829of fileutils 2.0. That @command{configure} script worked well enough that 18830the next month I adapted it (by hand) to create similar @command{configure} 18831scripts for several other @acronym{GNU} utilities packages. Brian Berliner 18832also adapted one of my scripts for his @acronym{CVS} revision control system. 18833 18834Later that summer, I learned that Richard Stallman and Richard Pixley 18835were developing similar scripts to use in the @acronym{GNU} compiler tools; 18836so I adapted my @command{configure} scripts to support their evolving 18837interface: using the file name @file{Makefile.in} as the templates; 18838adding @samp{+srcdir}, the first option (of many); and creating 18839@file{config.status} files. 18840 18841@node Exodus 18842@section Exodus 18843 18844As I got feedback from users, I incorporated many improvements, using 18845Emacs to search and replace, cut and paste, similar changes in each of 18846the scripts. As I adapted more @acronym{GNU} utilities packages to use 18847@command{configure} scripts, updating them all by hand became impractical. 18848Rich Murphey, the maintainer of the @acronym{GNU} graphics utilities, sent me 18849mail saying that the @command{configure} scripts were great, and asking if 18850I had a tool for generating them that I could send him. No, I thought, 18851but I should! So I started to work out how to generate them. And the 18852journey from the slavery of hand-written @command{configure} scripts to the 18853abundance and ease of Autoconf began. 18854 18855Cygnus @command{configure}, which was being developed at around that time, 18856is table driven; it is meant to deal mainly with a discrete number of 18857system types with a small number of mainly unguessable features (such as 18858details of the object file format). The automatic configuration system 18859that Brian Fox had developed for Bash takes a similar approach. For 18860general use, it seems to me a hopeless cause to try to maintain an 18861up-to-date database of which features each variant of each operating 18862system has. It's easier and more reliable to check for most features on 18863the fly---especially on hybrid systems that people have hacked on 18864locally or that have patches from vendors installed. 18865 18866I considered using an architecture similar to that of Cygnus 18867@command{configure}, where there is a single @command{configure} script that 18868reads pieces of @file{configure.in} when run. But I didn't want to have 18869to distribute all of the feature tests with every package, so I settled 18870on having a different @command{configure} made from each 18871@file{configure.in} by a preprocessor. That approach also offered more 18872control and flexibility. 18873 18874I looked briefly into using the Metaconfig package, by Larry Wall, 18875Harlan Stenn, and Raphael Manfredi, but I decided not to for several 18876reasons. The @command{Configure} scripts it produces are interactive, 18877which I find quite inconvenient; I didn't like the ways it checked for 18878some features (such as library functions); I didn't know that it was 18879still being maintained, and the @command{Configure} scripts I had 18880seen didn't work on many modern systems (such as System V R4 and NeXT); 18881it wasn't flexible in what it could do in response to a feature's 18882presence or absence; I found it confusing to learn; and it was too big 18883and complex for my needs (I didn't realize then how much Autoconf would 18884eventually have to grow). 18885 18886I considered using Perl to generate my style of @command{configure} 18887scripts, but decided that M4 was better suited to the job of simple 18888textual substitutions: it gets in the way less, because output is 18889implicit. Plus, everyone already has it. (Initially I didn't rely on 18890the @acronym{GNU} extensions to M4.) Also, some of my friends at the 18891University of Maryland had recently been putting M4 front ends on 18892several programs, including @code{tvtwm}, and I was interested in trying 18893out a new language. 18894 18895@node Leviticus 18896@section Leviticus 18897 18898Since my @command{configure} scripts determine the system's capabilities 18899automatically, with no interactive user intervention, I decided to call 18900the program that generates them Autoconfig. But with a version number 18901tacked on, that name would be too long for old Unix file systems, 18902so I shortened it to Autoconf. 18903 18904In the fall of 1991 I called together a group of fellow questers after 18905the Holy Grail of portability (er, that is, alpha testers) to give me 18906feedback as I encapsulated pieces of my handwritten scripts in M4 macros 18907and continued to add features and improve the techniques used in the 18908checks. Prominent among the testers were Fran@,{c}ois Pinard, who came up 18909with the idea of making an Autoconf shell script to run M4 18910and check for unresolved macro calls; Richard Pixley, who suggested 18911running the compiler instead of searching the file system to find 18912include files and symbols, for more accurate results; Karl Berry, who 18913got Autoconf to configure @TeX{} and added the macro index to the 18914documentation; and Ian Lance Taylor, who added support for creating a C 18915header file as an alternative to putting @option{-D} options in a 18916makefile, so he could use Autoconf for his @acronym{UUCP} package. 18917The alpha testers cheerfully adjusted their files again and again as the 18918names and calling conventions of the Autoconf macros changed from 18919release to release. They all contributed many specific checks, great 18920ideas, and bug fixes. 18921 18922@node Numbers 18923@section Numbers 18924 18925In July 1992, after months of alpha testing, I released Autoconf 1.0, 18926and converted many @acronym{GNU} packages to use it. I was surprised by how 18927positive the reaction to it was. More people started using it than I 18928could keep track of, including people working on software that wasn't 18929part of the @acronym{GNU} Project (such as TCL, FSP, and Kerberos V5). 18930Autoconf continued to improve rapidly, as many people using the 18931@command{configure} scripts reported problems they encountered. 18932 18933Autoconf turned out to be a good torture test for M4 implementations. 18934Unix M4 started to dump core because of the length of the 18935macros that Autoconf defined, and several bugs showed up in @acronym{GNU} 18936M4 as well. Eventually, we realized that we needed to use some 18937features that only @acronym{GNU} M4 has. 4.3@acronym{BSD} M4, in 18938particular, has an impoverished set of builtin macros; the System V 18939version is better, but still doesn't provide everything we need. 18940 18941More development occurred as people put Autoconf under more stresses 18942(and to uses I hadn't anticipated). Karl Berry added checks for X11. 18943david zuhn contributed C++ support. Fran@,{c}ois Pinard made it diagnose 18944invalid arguments. Jim Blandy bravely coerced it into configuring 18945@acronym{GNU} Emacs, laying the groundwork for several later improvements. 18946Roland McGrath got it to configure the @acronym{GNU} C Library, wrote the 18947@command{autoheader} script to automate the creation of C header file 18948templates, and added a @option{--verbose} option to @command{configure}. 18949Noah Friedman added the @option{--autoconf-dir} option and 18950@code{AC_MACRODIR} environment variable. (He also coined the term 18951@dfn{autoconfiscate} to mean ``adapt a software package to use 18952Autoconf''.) Roland and Noah improved the quoting protection in 18953@code{AC_DEFINE} and fixed many bugs, especially when I got sick of 18954dealing with portability problems from February through June, 1993. 18955 18956@node Deuteronomy 18957@section Deuteronomy 18958 18959A long wish list for major features had accumulated, and the effect of 18960several years of patching by various people had left some residual 18961cruft. In April 1994, while working for Cygnus Support, I began a major 18962revision of Autoconf. I added most of the features of the Cygnus 18963@command{configure} that Autoconf had lacked, largely by adapting the 18964relevant parts of Cygnus @command{configure} with the help of david zuhn 18965and Ken Raeburn. These features include support for using 18966@file{config.sub}, @file{config.guess}, @option{--host}, and 18967@option{--target}; making links to files; and running @command{configure} 18968scripts in subdirectories. Adding these features enabled Ken to convert 18969@acronym{GNU} @code{as}, and Rob Savoye to convert Deja@acronym{GNU}, to using 18970Autoconf. 18971 18972I added more features in response to other peoples' requests. Many 18973people had asked for @command{configure} scripts to share the results of 18974the checks between runs, because (particularly when configuring a large 18975source tree, like Cygnus does) they were frustratingly slow. Mike 18976Haertel suggested adding site-specific initialization scripts. People 18977distributing software that had to unpack on MS-DOS asked for a way to 18978override the @file{.in} extension on the file names, which produced file 18979names like @file{config.h.in} containing two dots. Jim Avera did an 18980extensive examination of the problems with quoting in @code{AC_DEFINE} 18981and @code{AC_SUBST}; his insights led to significant improvements. 18982Richard Stallman asked that compiler output be sent to @file{config.log} 18983instead of @file{/dev/null}, to help people debug the Emacs 18984@command{configure} script. 18985 18986I made some other changes because of my dissatisfaction with the quality 18987of the program. I made the messages showing results of the checks less 18988ambiguous, always printing a result. I regularized the names of the 18989macros and cleaned up coding style inconsistencies. I added some 18990auxiliary utilities that I had developed to help convert source code 18991packages to use Autoconf. With the help of Fran@,{c}ois Pinard, I made 18992the macros not interrupt each others' messages. (That feature revealed 18993some performance bottlenecks in @acronym{GNU} M4, which he hastily 18994corrected!) I reorganized the documentation around problems people want 18995to solve. And I began a test suite, because experience had shown that 18996Autoconf has a pronounced tendency to regress when we change it. 18997 18998Again, several alpha testers gave invaluable feedback, especially 18999Fran@,{c}ois Pinard, Jim Meyering, Karl Berry, Rob Savoye, Ken Raeburn, 19000and Mark Eichin. 19001 19002Finally, version 2.0 was ready. And there was much rejoicing. (And I 19003have free time again. I think. Yeah, right.) 19004 19005 19006@c ========================================================== Appendices 19007 19008@node Copying This Manual 19009@appendix Copying This Manual 19010@cindex License 19011 19012@menu 19013* GNU Free Documentation License:: License for copying this manual 19014@end menu 19015 19016@include fdl.texi 19017 19018@node Indices 19019@appendix Indices 19020 19021@menu 19022* Environment Variable Index:: Index of environment variables used 19023* Output Variable Index:: Index of variables set in output files 19024* Preprocessor Symbol Index:: Index of C preprocessor symbols defined 19025* Autoconf Macro Index:: Index of Autoconf macros 19026* M4 Macro Index:: Index of M4, M4sugar, and M4sh macros 19027* Autotest Macro Index:: Index of Autotest macros 19028* Program & Function Index:: Index of those with portability problems 19029* Concept Index:: General index 19030@end menu 19031 19032@node Environment Variable Index 19033@appendixsec Environment Variable Index 19034 19035This is an alphabetical list of the environment variables that Autoconf 19036checks. 19037 19038@printindex ev 19039 19040@node Output Variable Index 19041@appendixsec Output Variable Index 19042 19043This is an alphabetical list of the variables that Autoconf can 19044substitute into files that it creates, typically one or more 19045makefiles. @xref{Setting Output Variables}, for more information 19046on how this is done. 19047 19048@printindex ov 19049 19050@node Preprocessor Symbol Index 19051@appendixsec Preprocessor Symbol Index 19052 19053This is an alphabetical list of the C preprocessor symbols that the 19054Autoconf macros define. To work with Autoconf, C source code needs to 19055use these names in @code{#if} or @code{#ifdef} directives. 19056 19057@printindex cv 19058 19059@node Autoconf Macro Index 19060@appendixsec Autoconf Macro Index 19061 19062This is an alphabetical list of the Autoconf macros. 19063@ifset shortindexflag 19064To make the list easier to use, the macros are listed without their 19065preceding @samp{AC_}. 19066@end ifset 19067 19068@printindex AC 19069 19070@node M4 Macro Index 19071@appendixsec M4 Macro Index 19072 19073This is an alphabetical list of the M4, M4sugar, and M4sh macros. 19074@ifset shortindexflag 19075To make the list easier to use, the macros are listed without their 19076preceding @samp{m4_} or @samp{AS_}. 19077@end ifset 19078 19079@printindex MS 19080 19081@node Autotest Macro Index 19082@appendixsec Autotest Macro Index 19083 19084This is an alphabetical list of the Autotest macros. 19085@ifset shortindexflag 19086To make the list easier to use, the macros are listed without their 19087preceding @samp{AT_}. 19088@end ifset 19089 19090@printindex AT 19091 19092@node Program & Function Index 19093@appendixsec Program and Function Index 19094 19095This is an alphabetical list of the programs and functions which 19096portability is discussed in this document. 19097 19098@printindex pr 19099 19100@node Concept Index 19101@appendixsec Concept Index 19102 19103This is an alphabetical list of the files, tools, and concepts 19104introduced in this document. 19105 19106@printindex cp 19107 19108@bye 19109 19110@c LocalWords: texinfo setfilename autoconf texi settitle setchapternewpage 19111@c LocalWords: setcontentsaftertitlepage finalout ARG ovar varname dvar acx 19112@c LocalWords: makeinfo dvi defcodeindex ev ov CPP cv Autotest mv defindex fn 19113@c LocalWords: shortindexflag iftex ifset acindex ACindex ifclear ahindex fu 19114@c LocalWords: asindex MSindex atindex ATindex auindex hdrindex prindex FIXME 19115@c LocalWords: msindex alloca fnindex Aaarg indices FSF's dircategory ifnames 19116@c LocalWords: direntry autoscan autoreconf autoheader autoupdate config FDs 19117@c LocalWords: testsuite titlepage Elliston Demaille vskip filll ifnottex hmm 19118@c LocalWords: insertcopying Autoconf's detailmenu Automake Libtool Posix ois 19119@c LocalWords: Systemology Checkpointing Changequote INTERCAL changequote dfn 19120@c LocalWords: Quadrigraphs builtins Shellology acconfig Bugward LIBOBJ Imake 19121@c LocalWords: LIBOBJS IFELSE cindex flushright Pinard Metaconfig uref Simons 19122@c LocalWords: distclean uninstall noindent versioning Tromey dir 19123@c LocalWords: SAMS samp aclocal acsite underquoted emph itemx prepend SUBST 19124@c LocalWords: evindex automake Gettext autopoint gettext symlink libtoolize 19125@c LocalWords: defmac INIT tarname ovindex cvindex BUGREPORT PREREQ asis PROG 19126@c LocalWords: SRCDIR srcdir globbing afterwards cmds foos fooo foooo init cd 19127@c LocalWords: builddir timestamp src Imakefile chmod defvar CFLAGS CPPFLAGS 19128@c LocalWords: CXXFLAGS DEFS DHAVE defvarx FCFLAGS FFLAGS LDFLAGS bindir GCC 19129@c LocalWords: datadir datarootdir docdir dvidir htmldir libdir ifnothtml kbd 19130@c LocalWords: includedir infodir libexecdir localedir localstatedir mandir 19131@c LocalWords: oldincludedir pdfdir PDF psdir PostScript sbindir sysconfdir 19132@c LocalWords: sharedstatedir DDATADIR sed tmp pkgdatadir VPATH conf unistd 19133@c LocalWords: undef endif builtin FUNCS ifndef STACKSEG getb GETB YMP fubar 19134@c LocalWords: PRE dest SUBDIRS subdirs fi struct STDC stdlib stddef INTTYPES 19135@c LocalWords: inttypes STDINT stdint AWK AIX Solaris NeXT env EGREP FGREP yy 19136@c LocalWords: LEXLIB YYTEXT lfl nonportable Automake's LN RANLIB byacc INETD 19137@c LocalWords: inetd prog PROGS progs ranlib lmp lXt lX nsl gethostbyname UX 19138@c LocalWords: NextStep isinf isnan glibc IRIX sunmath lm lsunmath pre sizeof 19139@c LocalWords: ld inline malloc putenv setenv FreeBSD realloc SunOS MinGW 19140@c LocalWords: snprintf vsnprintf sprintf vsprintf sscanf gcc strerror ifdef 19141@c LocalWords: strnlen sysconf PAGESIZE unsetenv va fallback memcpy dst FUNC 19142@c LocalWords: PowerPC GNUC libPW pragma Olibcalls CHOWN chown CLOSEDIR VFORK 19143@c LocalWords: closedir FNMATCH fnmatch vfork FSEEKO LARGEFILE fseeko SVR sc 19144@c LocalWords: largefile GETGROUPS getgroups GETLOADAVG DGUX UMAX NLIST KMEM 19145@c LocalWords: GETLODAVG SETGID getloadavg nlist GETMNTENT irix 19146@c LocalWords: getmntent UnixWare GETPGRP getpgid getpgrp Posix's pid LSTAT 19147@c LocalWords: lstat rpl MEMCMP memcmp OpenStep MBRTOWC mbrtowc MKTIME mktime 19148@c LocalWords: localtime MMAP mmap OBSTACK obstack obstacks ARGTYPES timeval 19149@c LocalWords: SETPGRP setpgrp defmacx Hurd SETVBUF setvbuf STRCOLL strcoll 19150@c LocalWords: STRTOD strtod DECL STRFTIME strftime SCO UTIME utime VPRINTF 19151@c LocalWords: DOPRNT vprintf doprnt sp unfixable LIBSOURCE LIBSOURCES Eggert 19152@c LocalWords: linux netinet ia Tru XFree DIRENT NDIR dirent ndir multitable 19153@c LocalWords: NAMLEN strlen namlen MKDEV SYSMACROS makedev RESOLV resolv DNS 19154@c LocalWords: inet structs NAMESER arpa NETDB netdb UTekV UTS autom GCC's kB 19155@c LocalWords: STDBOOL BOOL stdbool conformant cplusplus bool Bool stdarg tm 19156@c LocalWords: ctype strchr strrchr rindex bcopy memmove memchr WEXITSTATUS 19157@c LocalWords: WIFEXITED TIOCGWINSZ GWINSZ termios preprocess preprocessable 19158@c LocalWords: DECLS strdup calloc BLKSIZE blksize RDEV rdev TZNAME tzname pw 19159@c LocalWords: passwd gecos pwd MBSTATE mbstate wchar RETSIGTYPE hup UID uid 19160@c LocalWords: gid ptrdiff uintmax EXEEXT OBJEXT Ae Onolimit conftest AXP str 19161@c LocalWords: ALIGNOF WERROR Werror cpp HP's WorkShop egcs un fied stdc CXX 19162@c LocalWords: varargs BIGENDIAN Endianness SPARC endianness grep'ed CONST FC 19163@c LocalWords: const STRINGIZE stringizing PARAMS unprotoize protos KCC cxx 19164@c LocalWords: xlC aCC CXXCPP FREEFORM xlf FLIBS FCLIBS ish SRCEXT XTRA LFS 19165@c LocalWords: ISC lcposix MINIX Minix conditionalized inlines hw dD confdefs 19166@c LocalWords: fputs stdout PREPROC ar UFS HFS QNX realtime fstype STATVFS se 19167@c LocalWords: statvfs STATFS statfs func machfile hdr lelf raboof DEFUN GTK 19168@c LocalWords: GTKMM Grmph ified ine defn baz EOF qar Ahhh changecom algol io 19169@c LocalWords: changeword quadrigraphs quadrigraph dnl SGI atoi overquoting 19170@c LocalWords: Aas Wcross sep args namespace undefine bpatsubst popdef dquote 19171@c LocalWords: bregexp Overquote overquotation meisch maisch meische maische 19172@c LocalWords: miscian DIRNAME dirname MKDIR CATFILE XMKMF TRAVOLTA celsius 19173@c LocalWords: EMX emxos Emacsen Korn DYNIX subshell posix Ksh ksh Pdksh Zsh 19174@c LocalWords: pdksh zsh Allbery Lipe Kubota UWS zorglub stderr eval esac lfn 19175@c LocalWords: drivespec Posixy DJGPP doschk prettybird LPT pfew Zsh's yu yaa 19176@c LocalWords: yM uM aM firebird IP subdir misparses ok Unpatched abc bc zA 19177@c LocalWords: CDPATH DUALCASE LINENO prepass Subshells lineno NULLCMD cmp wc 19178@c LocalWords: MAILPATH scanset arg NetBSD Almquist printf expr cp 19179@c LocalWords: Oliva awk Aaaaarg cmd regex xfoo GNV OpenVMS VM 19180@c LocalWords: sparc Proulx SysV nbar nfoo maxdepth acdilrtu TWG mc 19181@c LocalWords: mkdir exe uname OpenBSD Fileutils mktemp umask TMPDIR guid os 19182@c LocalWords: fooXXXXXX Unicos parenthesization utimes hpux hppa unescaped 19183@c LocalWords: pmake DOS's gmake ifoo DESTDIR autoconfiscated pc coff mips gg 19184@c LocalWords: dec ultrix cpu wildcards rpcc rdtsc powerpc readline 19185@c LocalWords: withval vxworks gless localcache usr LOFF loff CYGWIN Cygwin 19186@c LocalWords: cygwin SIGLIST siglist SYSNDIR SYSDIR ptx lseq rusage elif MSC 19187@c LocalWords: lfoo POUNDBANG lsun NIS getpwnam SYSCALLS RSH INTL lintl aix 19188@c LocalWords: intl lx ldir syslog bsd EPI toolchain netbsd objext de KNR nn 19189@c LocalWords: fication LTLIBOBJS Wdiff TESTDIR atconfig atlocal akim XFAIL 19190@c LocalWords: ChangeLog prepended errexit smallexample TESTSUITEFLAGS GPL er 19191@c LocalWords: installcheck autotest indir Pixley Bothner Eichin Kerberos adl 19192@c LocalWords: DISTCLEANFILES preprocessor's fileutils Stallman Murphey Stenn 19193@c LocalWords: Manfredi Autoconfig TCL FSP david zuhn Blandy MACRODIR Raeburn 19194@c LocalWords: autoconfiscate Savoye Haertel Avera Meyering fdl appendixsec 19195@c LocalWords: printindex american LIBOBJDIR LibdirTest ERLCFLAGS OBJCFLAGS 19196@c LocalWords: VER Gnulib online xyes strcpy TYPEOF typeof OBJC objcc objc ln 19197@c LocalWords: GOBJC OBJCCPP OTP ERLC erl valloc decr dumpdef errprint incr 19198@c LocalWords: esyscmd len maketemp pushdef substr syscmd sysval translit txt 19199@c LocalWords: sinclude foreach myvar tolower toupper uniq BASENAME STDIN 19200@c LocalWords: Dynix descrips basename aname cname macroexpands xno xcheck 19201@c LocalWords: LIBREADLINE lreadline lncurses libreadline 19202 19203@c Local Variables: 19204@c fill-column: 72 19205@c ispell-local-dictionary: "american" 19206@c indent-tabs-mode: nil 19207@c whitespace-check-buffer-indent: nil 19208@c End: 19209